Insyra - Crafting Your Art of Data

繁體中文 | English

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

Fast, Lovely, Easy To Use

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.

AI / Agent Skills

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."

Idensyra

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

Getting Started

Start Here: Guided Tutorials

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.

For those new to Golang

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
   

Installation

• 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
  

Quick Example

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())
}

Syntactic Sugar

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.

Console Preview with insyra.Show

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
}

Configuration

See Docs/Configuration.md.

CLI Quick Examples

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

# Reproducible sampling and train/test split
insyra sample t frac 0.1 seed 42 as preview
insyra split t train 0.8 seed 42 as train test

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

Thread Safety and Defensive Copies

• 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 sync.Mutex plus a goroutine-id holder (using petermattis/goid) for fast same-goroutine re-entry detection (see atomic.go). Per-call overhead is ~30 ns; same-goroutine re-entry runs inline without re-acquiring the lock.

DataList

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.

DataTable

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.

Error Handling (instance-level)

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.

Column Calculation Language (CCL)

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')")

Parquet Integration

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.

Packages

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

Package	Description
isr	Syntactic sugar over Insyra — the recommended entry point for new code.
stats	Statistical functions for data analysis: skewness, kurtosis, moment calculations, and more.
parallel	Parallel processing for data manipulation; runs any function and auto-waits for all goroutines.
plot	Data visualization wrapping go-echarts.
gplot	Static charts via gonum/plot — fast, no Chrome, supports function plots.
csvxl	Work with Excel and CSV files (e.g. convert CSV to Excel).
parquet	Apache Parquet read/write, deeply integrated with DataTable/DataList; streaming, column-level reads, CCL filtering.
mkt	Marketing analytics: RFM, Customer Activity Index, and market-basket analysis.
finance	High-precision fixed-point finance: TVM, NPV/IRR, depreciation, bond pricing, and amortization schedules.
py	Run Python from Go with no manual environment setup; pass variables both ways.
pd	Pandas-like DataFrame helpers built on gpandas, with DataTable conversion.
datafetch	Easy data fetching: Google Maps store reviews and a Yahoo Finance wrapper.
lpgen	Generate linear programming (LP) models and export them as .lp files.
lp	Fully automatic LP solver using GLPK.
engine	Re-exports selected Insyra internals for reuse in other projects.

Advanced Usage

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

Contributing

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.

Contributors

License

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