Insyra

繁體中文 | English

Go 語言次世代資料分析庫。支援 平行處理、資料視覺化，並 與 Python 無縫整合。

官方網站: https://insyra.hazelnut-paradise.com

說明文件: https://hazelnutparadise.github.io/insyra/

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

[!NOTE] 本專案正在快速迭代中，請為此專案加星並關注，以便隨時了解最新變化！

太快、太美、太簡單

Insyra 庫是一個動態且多功能的 Go 語言資料分析工具。提供了豐富的功能集，可用於數據操作、統計計算、資料視覺化等，對於處理複雜數據結構的開發者來說，是一個必不可少的工具包。

[!TIP] isr 套件提供 語法糖！

建議任何新專案使用 isr 套件取代直接呼叫 insyra 主套件包的寫法。

更多詳細資訊，請參閱 說明文件。

[!NOTE] 如果文檔中的某些功能無法使用，可能是該功能還未包含在最新發布的版本中。請至 Releases 查看對應版本源碼中的文檔。

[!IMPORTANT] 對於 Insyra 文檔中未明確列出的任何函數或方法，表示該功能仍在積極開發中。這些實驗性功能可能會提供不穩定的結果。

請參閱我們 文檔 資料夾中的最新更新以獲取更多詳細資訊。

AI / Agent Skills

這個 repo 內含兩份 agent skill：

• skills/insyra：協助 AI agent 在 Go 程式碼中使用 Insyra（DataList / DataTable 工作流、CCL 公式、常見檔案 I/O）。
• skills/use-insyra-cli：教 agent 使用 Insyra CLI / REPL 與 .isr 腳本，包含環境工作流與完整指令參考。

快速選擇：

• 任務是撰寫或修改使用 Insyra API 的 Go 程式碼：用 skills/insyra。
• 任務是透過 insyra 指令、REPL 或 .isr 腳本執行：用 skills/use-insyra-cli。
• 需要混合流程（先用 CLI 驗證，再落地成 Go 程式）：兩個 skill 一起用。

這份 skill 不綁特定平台，可用於 OpenClaw、Claude Code、opencode，或任何支援載入 skills 的 agent runtime。

範例提示詞：

• 「用 insyra 讀取 data.csv，用 CCL 新增衍生欄位，然後輸出成 output.csv。」
• 「用 insyra 的 DataList 計算 mean/std，並快速 preview。」

Idensyra

我們提供了一個迷你 Go IDE，Idensyra，旨在使數據分析變得更簡單（儘管 Insyra 已經使其非常簡單）。

Idensyra 預裝了 Insyra，不需要安裝 Go 環境即可運行 Go 程式碼！

了解更多關於 Idensyra

開始使用

先從主題引導式文件開始

如果你想用實作導向、端到端的方式快速上手 Insyra，建議先從主題引導式文件開始。

• 教學總覽：Docs/tutorials/README.md
• 特色教學：Sales Analysis End-to-End
• 新增主題軌道：資料品質清理、Parquet 串流、A/B 統計決策、RFM+CAI 分群、Yahoo Finance 趨勢、互動式 plot 儀表板、靜態 gplot 報表、LP 容量規劃、Python + parallel 批次處理。

特色教學會帶你完整走過流程：
CSV 準備 -> DataTable 載入 -> CCL 衍生欄位 -> 排序 -> KPI 彙總 -> 匯出 CSV。

致初學者

[!TIP] 如果您已熟悉 Go，請跳至 安裝 或 快速範例。

1. 從 這裡 下載並安裝 Golang。
2. 設置您的編輯器，我們推薦使用 VSCode。

3. 在您的專案中開啟或建立一個資料夾，並在編輯器中開啟它。

4. 使用以下命令建立新專案：

sh go mod init your_project_name

1. 在您的專案中安裝 Insyra：

sh go get github.com/HazelnutParadise/insyra/allpkgs

1. 建立一個新文件，例如 main.go，並寫入以下代碼：

```go package main

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

func main() { // 將您的代碼寫在這裡 } ```

1. 運行您的專案：

sh go run main.go

安裝

• 要開始使用 Insyra，請使用以下命令進行安裝：

sh go get github.com/HazelnutParadise/insyra/allpkgs

• 更新 Insyra 到最新版本：

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

或者

sh go get 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())
}

語法糖

強烈建議使用 語法糖，因為它更強大且更易於使用。例如，上面的程式碼可以寫成：

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

若要使用語法糖，請引用 github.com/HazelnutParadise/insyra/isr。

使用 insyra.Show 快速預覽

需要在終端機上快速、帶標籤地預覽 DataTable 或 DataList 嗎？使用套件層級的 Show 函式即可，它底層會呼叫 ShowRange，因此也支援相同的範圍參數：

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) // 顯示前兩列
}

配置

有關配置的詳細資訊請見 Docs/Configuration.md。

CLI 快速範例

安裝 CLI（建議）：

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

安裝後可執行檔預設在 $GOBIN（未設定時為 $GOPATH/bin）。

[!TIP] Windows 使用者若找不到 insyra 指令，請確認將 %USERPROFILE%\\go\\bin（或你的 %GOBIN%）加入 PATH，重新開啟終端機後再執行。

進入 REPL：

insyra

批次執行（非 REPL）：

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

進階命令範例：

# 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

# 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

[!TIP] 可搭配 --env <name> 管理多個分析環境，例如：insyra --env exp1。 完整 CLI + DSL 說明請參閱 Docs/cli-dsl.md。

執行緒安全與防禦性複製

• 防禦性複製： Insyra 對所有公開資料存取器回傳防禦性複製（defensive copies）。任何會暴露內部 slice、map 或其他可變結構的方法，會回傳該結構的複製，避免呼叫端無意間修改內部狀態。
• 原子操作： 若需在並發環境中執行多步驟操作，請使用 AtomicDo。AtomicDo 透過每個實例的 sync.Mutex 加上 goroutine-id holder（使用 petermattis/goid）序列化執行；同一 goroutine 的 re-entry 會 inline 跑、不重新取鎖，每次呼叫成本約 30 ns。參考實作：atomic.go。

DataList

DataList 是 Insyra 的核心結構，能夠存儲、管理和分析動態數據集合。它提供了各種用於數據操作和統計分析的方法。

有關方法和功能的完整列表，請參閱 DataList 文檔。

DataTable

DataTable 結構提供了表格數據的表示方式，允許以結構化格式存儲和操作數據。它提供了數據過濾、排序和聚合的方法，使其成為數據分析的強大工具。

您還可以僅用一行代碼在 DataTables 和 CSV 文件之間進行轉換，實現與外部數據源的無縫整合。

錯誤處理（實例級）

DataList 與 DataTable 均支援用於鏈式操作的實例級錯誤追蹤。使用 Err() 可取得該實例最後發生的錯誤（回傳 *ErrorInfo 或 nil），使用 ClearErr() 可清除該錯誤。

範例：

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

// DataTable 範例（簡示參數）
dt := insyra.NewDataTable(insyra.NewDataList(1), insyra.NewDataList(2)).SortBy(/*config*/)
if err := dt.Err(); err != nil {
    fmt.Println("Error:", err.Message)
    dt.ClearErr()
}

更多細節請參閱 DataList 文檔 與 DataTable 文檔。

Column Calculation Language (CCL)

Insyra 提供強大的 Column Calculation Language (CCL) 功能，其使用方式就像 Excel 公式一樣直觀！

使用 CCL，您可以：

• 使用熟悉的 Excel 式語法建立計算欄位
• 使用 Excel 風格的欄位引用方式 (A, B, C...)
• 使用 IF、AND、OR 和 CASE 等函數實現條件邏輯
• 執行數學運算和字串操作
• 執行連鎖比較，如 1 < A <= 10，用於範圍檢查
• 使用 . 運算符存取特定列 (例如 A.0)，並使用 @ 引用所有欄位
• 使用聚合函數，如 SUM、AVG、COUNT、MAX 和 MIN

// 根據 A 欄位的值分類資料
dt.AddColUsingCCL("category", "IF(A > 90, 'Excellent', IF(A > 70, 'Good', 'Average'))")

// 像在 Excel 中一樣執行計算
dt.AddColUsingCCL("total", "A + B + C")
dt.AddColUsingCCL("average", "AVG(A + B + C)")

// 對列或欄位使用聚合函數
dt.AddColUsingCCL("row_sum", "SUM(@.0)")

// 使用連鎖比較進行範圍檢查 (在 Excel 中也可使用！)
dt.AddColUsingCCL("in_range", "IF(10 <= A <= 20, 'Yes', 'No')")

Parquet 整合

CCL 可以直接在 Parquet 檔案讀取時應用，在資料源頭進行篩選：

// 讀取時即時篩選資料列 - 僅將符合條件的資料載入記憶體
dt, err := parquet.FilterWithCCL(ctx, "sales_data.parquet", "(['amount'] > 1000) && (['status'] = 'Active')")

// 直接在 parquet 檔案上套用 CCL 轉換（串流模式）
err := parquet.ApplyCCL(ctx, "data.parquet", "NEW('total') = A + B + C")

這種方式透過批次處理資料，可減少處理大型資料集時的記憶體使用量。 關於 CCL 語法和功能的完整指南，請參閱 CCL 文檔。

有關 DataTable 方法和功能的完整列表，請參閱 DataTable 文檔。

套件

Insyra 還提供了多個擴展套件，每個都專注於數據分析的特定方面。

進階使用

除了基本用法外，Insyra 還提供了處理不同數據類型和執行複雜統計操作的強大功能。請在 詳細文檔 中探索更多內容。

貢獻

歡迎各種形式的貢獻！您可以通過以下方式貢獻 Insyra：

• Issues: 提出問題、建議或功能請求。
• Pull Requests: 提交代碼更改或新功能。
• Discussions: 參與討論，分享您的想法和建議。

貢獻者

授權

Insyra 採用 MIT 許可證授權。請參閱 LICENSE 文件以獲取更多資訊。