A next-generation data analysis library for Golang. Supports parallel processing, data visualization, and seamless integration with Python.

Official Website: https://insyra.hazelnut-paradise.com

Documentation: https://hazelnutparadise.github.io/insyra/

Go.dev Package: https://pkg.go.dev/github.com/HazelnutParadise/insyra

繁體中文版 README

The Insyra library is a dynamic and versatile tool designed for managing and analyzing data in Go. It offers a rich set of features for data manipulation, statistical calculations, data visualization, and more, making it an essential toolkit for developers handling complex data structures.

This repository includes agent skills:

• skills/insyra: helps AI agents use Insyra in Go code (DataList/DataTable workflows, CCL formulas, and common file I/O helpers).
• skills/use-insyra-cli: teaches agents how to use Insyra CLI/REPL and .isr scripts, including environment workflows and full command reference.

Quick picker:

• Use skills/insyra when the task is to write or modify Go code using Insyra APIs.
• Use skills/use-insyra-cli when the task should be done via insyra commands, REPL, or .isr scripts.
• Use both when you need a hybrid flow (CLI prototyping first, then productionize in Go code).

It is platform-agnostic and can be used with OpenClaw, Claude Code, opencode, or any skill-capable agent runtime.

Example prompts:

• "Use insyra to read data.csv, add a derived column with CCL, and export to output.csv."
• "Use insyra DataList to compute mean/std and show a quick preview."

We provide a mini Go IDE, Idensyra, which aims to make data analysis even more easier (though Insyra has already made it very easy).

Idensyra comes with Insyra pre-installed, and allows you to run Go code without installing Go environment!

Know more about Idensyra

If you want a practical, end-to-end way to learn Insyra, start with the guided tutorials.

• Tutorial hub: Docs/tutorials/README.md
• Featured tutorial: Sales Analysis End-to-End
• New tutorial tracks: data quality, parquet streaming, A/B statistics, RFM+CAI segmentation, yfinance trend, interactive plot dashboards, static gplot reports, LP capacity planning, Python + parallel batch.

The featured tutorial walks through a full workflow: CSV setup -> DataTable loading -> CCL enrichment -> sorting -> KPI aggregation -> CSV export.

1. Download and install Golang from here.

2. Set up your editor, we recommend using VSCode. Or even lighter weight, Idensyra.

3. Open or create a folder for your project, and open it in the editor.

4. Create a new project by running the following command:

   go mod init your_project_name

5. Install Insyra:

   go get github.com/HazelnutParadise/insyra/allpkgs

6. Create a new file, e.g., main.go, and write the following code:

   package main
   
   import (
       "fmt"
       "github.com/HazelnutParadise/insyra"
   )
   
   func main() {
       // Your code here
   }

7. Run your project:

   go run main.go

• To start using Insyra, install it with the following command:

  go get github.com/HazelnutParadise/insyra/allpkgs

• Update Insyra to the latest version:

  go get -u github.com/HazelnutParadise/insyra/allpkgs

  or

  go get -u github.com/HazelnutParadise/insyra/allpkgs@latest

package main

import (
    "fmt"
    "github.com/HazelnutParadise/insyra"
)

func main() {
    dl := insyra.NewDataList(1, 2, 3, 4, 5)
    dl.Append(6)
    fmt.Println("DataList:", dl.Data())
    fmt.Println("Mean:", dl.Mean())
}

It is strongly recommended to use syntactic sugar since it is much more power and easier to use. For example, the above code can be written as:

package main

import (
 "fmt"

 "github.com/HazelnutParadise/insyra/isr"
)

func main() {
 dl := isr.DL.Of(1, 2, 3, 4, 5)
 dl.Append(6)
 dl.Show()
 fmt.Println("Mean:", dl.Mean())
}

To use the syntactic sugar, import github.com/HazelnutParadise/insyra/isr.

Need a quick labelled look at any showable structure (like DataTable or DataList)? Use the package-level Show helper, which delegates to ShowRange under the hood and supports the same range arguments:

func main() {
    dt := insyra.NewDataTable(
        insyra.NewDataList("Alice", "Bob", "Charlie").SetName("Name"),
        insyra.NewDataList(28, 34, 29).SetName("Age"),
    ).SetName("Team Members")

    insyra.Show("Preview", dt, 2) // First two rows
}

See Docs/Configuration.md.

Install the CLI (recommended):

go install github.com/HazelnutParadise/insyra/cmd/insyra@latest

The binary is installed to $GOBIN (or $GOPATH/bin if $GOBIN is not set).

Start REPL:

insyra

Run commands directly (non-REPL):

insyra newdl 1 2 3 4 5 as x
insyra mean x

Advanced command examples:

# Regression
insyra regression linear y x1 x2 as reg

# Hypothesis test
insyra ttest two group_a group_b equal

# Plot
insyra plot line sales save sales.html

# Fetch (Yahoo Finance)
insyra fetch yahoo AAPL quote as q

# Partial Parquet load (selected columns + row groups)
insyra load parquet data.parquet cols id,amount,status rowgroups 0,1 as t

For full CLI + DSL documentation, see Docs/cli-dsl.md.

• Defensive copies: Insyra returns defensive copies for all public data accessors. Any method that exposes internal slices, maps, or other mutable structures returns a copy so callers cannot mutate internal state unintentionally.
• Atomic operations: For safe concurrent multi-step operations, use the helper AtomicDo. AtomicDo serializes all operations for an instance via a dedicated actor goroutine and a command channel (see atomic.go), avoiding mutexes.

The DataList is the core structure in Insyra, enabling the storage, management, and analysis of dynamic data collections. It offers various methods for data manipulation and statistical analysis.

For a complete list of methods and features, please refer to the DataList Documentation.

The DataTable structure provides a tabular data representation, allowing for the storage and manipulation of data in a structured format. It offers methods for data filtering, sorting, and aggregation, making it a powerful tool for data analysis.

You can also convert between DataTables and CSV files with simply one line of code, enabling seamless integration with external data sources.

Both DataList and DataTable support instance-level error tracking for fluent/chained operations. Use Err() to obtain the last error on the instance (returns *ErrorInfo or nil) and ClearErr() to clear it.

Example:

// DataList example
dl := insyra.NewDataList(1,2,3).Sort().Reverse()
if err := dl.Err(); err != nil {
    fmt.Println("Error:", err.Message)
    dl.ClearErr()
}

// DataTable example (pseudo-args shown)
dt := insyra.NewDataTable(insyra.NewDataList(1), insyra.NewDataList(2)).SortBy(/*config*/)
if err := dt.Err(); err != nil {
    fmt.Println("Error:", err.Message)
    dt.ClearErr()
}

For more details, see the DataList Documentation and DataTable Documentation.

Insyra features a powerful Column Calculation Language (CCL) that works just like Excel formulas!

With CCL, you can:

• Create calculated columns using familiar Excel-like syntax
• Reference columns using Excel-style notation (A, B, C...)
• Use conditional logic with IF, AND, OR, and CASE functions
• Perform mathematical operations and string manipulations
• Execute chained comparisons like 1 < A <= 10 for range checks
• Access specific rows using the . operator (e.g., A.0) and reference all columns with @
• Use aggregate functions like SUM, AVG, COUNT, MAX, and MIN

// Add a column that classifies data based on values in column A
dt.AddColUsingCCL("category", "IF(A > 90, 'Excellent', IF(A > 70, 'Good', 'Average'))")

// Perform calculations just like in Excel
dt.AddColUsingCCL("total", "A + B + C")
dt.AddColUsingCCL("average", "AVG(A + B + C)")

// Use aggregate functions on rows or columns
dt.AddColUsingCCL("row_sum", "SUM(@.0)")

// Use range checks with chained comparisons (try this in Excel!)
dt.AddColUsingCCL("in_range", "IF(10 <= A <= 20, 'Yes', 'No')")

CCL can be applied directly during Parquet file reading to filter data at the source:

// Filter rows while reading - only matching rows are loaded into memory
dt, err := parquet.FilterWithCCL(ctx, "sales_data.parquet", "(['amount'] > 1000) && (['status'] = 'Active')")

// Apply CCL transformations directly on parquet files (streaming mode)
err := parquet.ApplyCCL(ctx, "data.parquet", "NEW('total') = A + B + C")

This approach reduces memory usage when working with large datasets by processing data in batches.

For a complete guide to CCL syntax and features, see the CCL Documentation.

For a complete list of DataTable methods and features, please refer to the DataTable Documentation.

Insyra also provides several expansion packages, each focusing on a specific aspect of data analysis.

Provides Syntactic Sugar for Insyra. It is designed to simplify the usage of Insyra and make it more intuitive.

Provides statistical functions for data analysis, including skewness, kurtosis, and moment calculations.

Offers parallel processing capabilities for data manipulation and analysis. Allows you to execute any function and automatically wait for all goroutines to complete.

Provides a wrapper around the powerful github.com/go-echarts/go-echarts library, designed to simplify data visualization.

A visualization package based on github.com/gonum/plot. Fast and no need for Chrome. Even supports function plot.

Work with Excel and CSV files. Such as convert CSV to Excel.

Provides read and write support for the Apache Parquet file format, deeply integrated with Insyra's DataTable and DataList. Supports streaming, column-level reading, and CCL filtering.

Provides marketing-related data analysis functions, such as RFM analysis. No need to worry about how to calculate, one function does it all!

Execute Python code in Go without manually installing Python environment and dependencies. Allows passing variables between Go and Python.

Pandas-like DataFrame helpers built on top of gpandas. Provides conversion helpers between Insyra's DataTable and gpandas.DataFrame, and exposes a pandas-like API in Go. See the package docs at /Docs/pd.md and the upstream gpandas documentation: https://gpandas.apoplexi.com/docs/

Allows you to fetch data easily. It currently includes a Google Maps store review crawler and a Yahoo Finance wrapper (powered by go-yfinance). Network access is required for remote fetchers and some features depend on third-party backends which may change.

Provides a super simple and intuitive way to generate linear programming (LP) models and save them as .lp files. It supports setting objectives, adding constraints, defining variable bounds, and specifying binary or integer variables.

Fully automatic linear programming (LP) solver using GLPK.

Exports selected internal implementations from Insyra for developers to reuse in other projects.

Beyond basic usage, Insyra provides extensive capabilities for handling different data types and performing complex statistical operations. Explore more in the detailed documentation.

Contributions are welcome! You can contribute to Insyra by:

• Issues: Reporting issues or suggesting new features.
• Pull Requests: Submitting pull requests to enhance the library.
• Discussions: Sharing your feedback and ideas to improve the project.

Insyra is licensed under the MIT License. See the LICENSE file for more information.