scigo

SciGo 🚀

SciGo's official mascot - Ready, Set, SciGo!

The blazing-fast scikit-learn compatible ML library for Go

Say "Goodbye" to slow ML, "Sci-Go" to fast learning!

🌟 Why SciGo?

SciGo = Statistical Computing In Go

SciGo brings the power and familiarity of scikit-learn to the Go ecosystem, offering:

• 🔥 Blazing Fast: Native Go implementation with built-in parallelization
• 🎯 scikit-learn Compatible: Familiar Fit/Predict API for easy migration
• 📖 Well Documented: Complete API documentation with examples on pkg.go.dev
• 🌊 Streaming Support: Online learning algorithms for real-time data
• 🚀 Zero Heavy Dependencies: Pure Go implementation (only scientific essentials)
• 📊 Comprehensive: Regression, classification, clustering, and more
• 🧪 Production Ready: Extensive tests, benchmarks, and error handling

📦 Installation

go get github.com/YuminosukeSato/scigo

🚀 Quick Start

💡 Tip: For complete API documentation with examples, visit pkg.go.dev/scigo

package main

import (
    "fmt"
    "log"
    
    "github.com/YuminosukeSato/scigo/linear"
    "gonum.org/v1/gonum/mat"
)

func main() {
    // Create and train model - just like scikit-learn!
    model := linear.NewLinearRegression()
    
    // Training data
    X := mat.NewDense(4, 2, []float64{
        1, 1,
        1, 2,
        2, 2,
        2, 3,
    })
    y := mat.NewDense(4, 1, []float64{
        2, 3, 3, 4,
    })
    
    // Fit the model
    if err := model.Fit(X, y); err != nil {
        log.Fatal(err)
    }
    
    // Make predictions
    XTest := mat.NewDense(2, 2, []float64{
        1.5, 1.5,
        2.5, 3.5,
    })
    predictions, _ := model.Predict(XTest)
    
    fmt.Println("Ready, Set, SciGo! Predictions:", predictions)
}

📚 API Documentation

📖 Package Documentation

Package	Description	Go Doc
preprocessing	Data preprocessing utilities (StandardScaler, MinMaxScaler, OneHotEncoder)
linear	Linear machine learning algorithms (LinearRegression)
metrics	Model evaluation metrics (MSE, RMSE, MAE, R², MAPE)
core/model	Base model abstractions and interfaces

📋 Complete API Examples

The documentation includes comprehensive examples for all major APIs. Visit the Go Doc links above or use go doc locally:

# View package documentation
go doc github.com/YuminosukeSato/scigo/preprocessing
go doc github.com/YuminosukeSato/scigo/linear
go doc github.com/YuminosukeSato/scigo/metrics

# View specific function documentation
go doc github.com/YuminosukeSato/scigo/preprocessing.StandardScaler.Fit
go doc github.com/YuminosukeSato/scigo/linear.LinearRegression.Predict
go doc github.com/YuminosukeSato/scigo/metrics.MSE

# Run example tests
go test -v ./preprocessing -run Example
go test -v ./linear -run Example
go test -v ./metrics -run Example

📚 Algorithms

Supervised Learning

Linear Models

• ✅ Linear Regression - Classic OLS regression with parallel processing
• ✅ SGD Regressor - Stochastic Gradient Descent for large-scale learning
• ✅ SGD Classifier - Linear classifiers with SGD training
• ✅ Passive-Aggressive - Online learning for classification and regression

Data Preprocessing

• ✅ StandardScaler - Standardizes features by removing mean and scaling to unit variance
• ✅ MinMaxScaler - Scales features to a given range (e.g., [0,1] or [-1,1])
• ✅ OneHotEncoder - Encodes categorical features as one-hot numeric arrays

Tree-based Models

• 🚧 Random Forest (Coming Soon)
• 🚧 Gradient Boosting (Coming Soon)
• 🚧 XGBoost compatibility (Coming Soon)

Unsupervised Learning

Clustering

• ✅ MiniBatch K-Means - Scalable K-Means for large datasets
• 🚧 DBSCAN (Coming Soon)
• 🚧 Hierarchical Clustering (Coming Soon)

Special Features

Online Learning & Streaming

• ✅ Incremental Learning - Update models with new data batches
• ✅ Partial Fit - scikit-learn compatible online learning
• ✅ Concept Drift Detection - DDM and ADWIN algorithms
• ✅ Streaming Pipelines - Real-time data processing with channels

🎯 scikit-learn Compatibility

SciGo implements the familiar scikit-learn API:

// Just like scikit-learn!
model.Fit(X, y)              // Train the model
model.Predict(X)              // Make predictions  
model.Score(X, y)             // Evaluate the model
model.PartialFit(X, y)        // Incremental learning

// Streaming - unique to Go!
model.FitStream(ctx, dataChan) // Streaming training

📊 Performance Benchmarks

SciGo leverages Go's concurrency for exceptional performance:

Benchmarks on MacBook Pro M2, 16GB RAM

Memory Efficiency

🏗️ Architecture

scigo/
├── linear/           # Linear models
├── sklearn/          # scikit-learn compatible implementations
│   ├── linear_model/ # SGD, Passive-Aggressive
│   ├── cluster/      # Clustering algorithms
│   └── drift/        # Concept drift detection
├── metrics/          # Evaluation metrics
├── core/            # Core abstractions
│   ├── model/       # Base model interfaces
│   ├── tensor/      # Tensor operations
│   └── parallel/    # Parallel processing
├── datasets/        # Dataset utilities
└── examples/        # Usage examples

📊 Metrics

Comprehensive evaluation metrics with full documentation:

• Regression Metrics:
  • MSE (Mean Squared Error) - pkg.go.dev/metrics.MSE
  • RMSE (Root Mean Squared Error) - pkg.go.dev/metrics.RMSE
  • MAE (Mean Absolute Error) - pkg.go.dev/metrics.MAE
  • R² (Coefficient of Determination) - pkg.go.dev/metrics.R2Score
  • MAPE (Mean Absolute Percentage Error) - pkg.go.dev/metrics.MAPE
  • Explained Variance Score - pkg.go.dev/metrics.ExplainedVarianceScore
• Classification: Accuracy, Precision, Recall, F1-Score, ROC-AUC (coming)
• Clustering: Silhouette Score, Davies-Bouldin Index (coming)

🧪 Testing & Quality

# Run tests
go test ./...

# Run benchmarks
go test -bench=. -benchmem ./...

# Check coverage (76.7% overall coverage)
go test -cover ./...

# Run linter (errcheck, govet, ineffassign, staticcheck, unused, misspell)
make lint-full

# Run examples to see API usage
go test -v ./preprocessing -run Example
go test -v ./linear -run Example
go test -v ./metrics -run Example
go test -v ./core/model -run Example

Quality Gates

• ✅ Test Coverage: 76.7% (target: 70%+)
• ✅ Linting: golangci-lint with comprehensive checks
• ✅ Documentation: Complete godoc for all public APIs
• ✅ Examples: Comprehensive example functions for all major APIs

📚 Examples

Check out the examples directory:

• Linear Regression - Basic regression
• Streaming Learning - Online learning demo
• Iris Classification - Classic dataset
• Error Handling - Robust error management

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Setup

# Clone the repository
git clone https://github.com/YuminosukeSato/scigo.git
cd scigo

# Install dependencies
go mod download

# Run tests
go test ./...

# Run linter
golangci-lint run

🗺️ Roadmap

Phase 1: Core ML (Current)

• ✅ Linear models
• ✅ Online learning
• ✅ Basic clustering
• 🚧 Tree-based models

Phase 2: Advanced Features

• Neural Networks (MLP)
• Deep Learning integration
• Model serialization (ONNX export)
• GPU acceleration

Phase 3: Enterprise Features

• Distributed training
• AutoML capabilities
• Model versioning
• A/B testing framework

📖 Documentation

Core Documentation

• API Documentation - Complete API reference with examples
• Package Index - Browse all packages

API Quick Reference

Guides (Coming Soon)

• Migration from scikit-learn
• Streaming Guide
• Performance Tuning

🙏 Acknowledgments

• Inspired by scikit-learn
• Built with Gonum
• Error handling by CockroachDB errors

📄 License

SciGo is licensed under the MIT License. See LICENSE for details.

📧 Contact

• Author: Yuminosuke Sato
• GitHub: @YuminosukeSato
• Repository: https://github.com/YuminosukeSato/scigo
• Issues: GitHub Issues