Insyra - Crafting Your Art of Data

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

[!NOTE] This project is evolving rapidly—please star and watch the repository to stay up to date with the latest changes!

繁體中文版 README

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.

[!TIP] isr package provides Sytax Sugar!<br/> Any new project is recommended to use isr package instead of calling insyra main package directly.<br/> For more details, please refer to the Documentation.

[!NOTE] If some functions or methods in the documentation are not working, it may be because the feature is not yet included in the latest release. Please refer to the documentation in the source code of the corresponding version in Releases.

[!IMPORTANT] For any functions or methods not explicitly listed in Insyra documents, it indicates that the feature is still under active development. These experimental features might provide unstable results. <br/> Please refer to our latest updates in Docs folder for more details.

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

[!TIP] Jump to Installation or Quick Example if you are familiar with Go.

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

[!TIP] On Windows, if insyra is not found, add %USERPROFILE%\\go\\bin (or your %GOBIN%) to PATH, then reopen your terminal.

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

[!TIP] Use --env <name> to isolate analysis contexts, e.g. insyra --env exp1.

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 dedicated actor goroutine and a command channel (see atomic.go), avoiding mutexes.

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