# sjwhitworth/golearn architecture

> Architecture diagram of the GitHub repository sjwhitworth/golearn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sjwhitworth/golearn
- Repository: https://github.com/sjwhitworth/golearn

## Overview

##### Project Type and Purpose
- GoLearn is an open-source, “batteries included” machine-learning library for Go.
- Its purpose is to provide a scikit-learn-style interface (Fit/Predict) for a wide range of ML algorithms, data structures, preprocessing tools, evaluation metrics, and example use cases.

##### Main Components
a. Core/Foundation (“base” package)
- Data structures (Instances, Attributes, DataFrame-like views)
- Parsers (CSV, ARFF)
- Serialization, sorting, grouping, utility functions
b. Preprocessing & Filtering
- filters (binning, discretization, chimerge, etc.)
- metrics (pairwise distance and kernel functions)
- kdtree (spatial indexing)
c. Algorithm Modules
- clustering (DBSCAN, EM, Gaussian mixtures)
- classification/regression
- knn
- naive Bayes
- linear_models (liblinear bindings, logistic, SVM)
- neural networks (layered perceptron)
- perceptron (average perceptron)
- trees (ID3, CART, isolation forest, random structures)
- ensemble (bagging, random forest, multi-svc)
- meta (one-vs-all, bagging wrappers)
- dimension reduction (pca)
- optimisation (general optimiser interface)
d. Evaluation & Utilities
- evaluation (confusion matrix, cross-validation)
- utilities (misc helpers)
e. Examples & Documentation
- examples directory showing common workflows (knn, trees, serialization)
- doc/ (multi-language markdown guides)

##### Relationships and Data Flow
- Data Ingestion: Examples or user code → base.ParseCSVToInstances → Instances object
- Preprocessing: Instances → filters/metrics routines → transformed Instances
- Model Training: Instances → classifier.Fit() (algorithm module)
- Prediction: trained model + test Instances → Predict() → label slice
- Evaluation: true labels + predicted labels → evaluation.GetConfusionMatrix() → summary stats
- Utilities & Optimisation are invoked internally by algorithms when needed (e.g., linear_models calls optimisation routines; clustering calls metrics).

##### Architectural Patterns & Design Principles
- Modular package design: each algorithm lives in its own package, depending only on base and utils
- Interface-based ML API: Fit(Predict) pattern consistent across classifiers
- Separation of concerns: data structures in base, algorithms in algorithm-specific packages, evaluation in its own package
- Extensibility: new filters, distance metrics, or classifiers can be added by implementing prescribed interfaces

##### Essential Elements
- Clear labels for each package component
- A small note or callout listing the main Go interfaces (e.g., “type Estimator interface { Fit(Instances); Predict(Instances) }”)
- A footnote referencing examples and documentation packages as user-facing entry points

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Entry Points
    Examples["Examples"]:::examples
    Doc["Documentation"]:::doc

    %% Core/Foundation
    base["base"]:::core

    %% Preprocessing & Filtering
    subgraph "Preprocessing & Filtering"
        Filters["filters"]:::pre
        Metrics["metrics/pairwise"]:::pre
        KDTree["kdtree"]:::pre
    end

    %% Algorithms
    subgraph "Algorithms"
        clustering["clustering"]:::algo
        knn["knn"]:::algo
        naive["naive"]:::algo
        linear_models["linear_models"]:::algo
        neural["neural"]:::algo
        perceptron["perceptron"]:::algo
        trees["trees"]:::algo
        ensemble["ensemble"]:::algo
        meta["meta"]:::algo
        pca["pca"]:::algo
        Optimisation["optimisation"]:::algo
    end

    %% Evaluation & Utilities
    Evaluation["evaluation"]:::eval
    utilities["utilities"]:::util

    %% Data Flow (dashed)
    Examples -.->|dataflow| base
    base -.->|dataflow| Filters
    base -.->|dataflow| Metrics
    base -.->|dataflow| KDTree
    Filters -.->|transformed data| knn
    Filters -.->|transformed data| trees
    Metrics -.->|distance metrics| clustering
    KDTree -.->|spatial index| knn
    knn -.->|predictions| Evaluation
    trees -.->|predictions| Evaluation
    clustering -.->|cluster labels| Evaluation
    linear_models -.->|predictions| Evaluation
    neural -.->|predictions| Evaluation
    perceptron -.->|predictions| Evaluation
    ensemble -.->|aggregated predictions| Evaluation
    meta -.->|meta predictions| Evaluation
    pca -.->|reduced data| linear_models

    %% Package Dependencies (solid)
    base --> Filters
    base --> Metrics
    base --> KDTree
    base --> clustering
    base --> knn
    base --> naive
    base --> linear_models
    base --> neural
    base --> perceptron
    base --> trees
    base --> ensemble
    base --> meta
    base --> pca
    clustering --> Metrics
    linear_models --> Optimisation
    perceptron --> Optimisation
    clustering --> utilities
    linear_models --> utilities
    naive --> utilities
    trees --> utilities
    ensemble --> utilities
    meta --> utilities
    pca --> utilities
    Evaluation --> base
    Evaluation --> utilities

    %% Click Events
    click Examples "https://github.com/sjwhitworth/golearn/tree/master/examples/"
    click Doc "https://github.com/sjwhitworth/golearn/tree/master/doc/"
    click base "https://github.com/sjwhitworth/golearn/tree/master/base/"
    click Filters "https://github.com/sjwhitworth/golearn/tree/master/filters/"
    click Metrics "https://github.com/sjwhitworth/golearn/tree/master/metrics/pairwise/"
    click KDTree "https://github.com/sjwhitworth/golearn/tree/master/kdtree/"
    click clustering "https://github.com/sjwhitworth/golearn/tree/master/clustering/"
    click knn "https://github.com/sjwhitworth/golearn/tree/master/knn/"
    click naive "https://github.com/sjwhitworth/golearn/tree/master/naive/"
    click linear_models "https://github.com/sjwhitworth/golearn/tree/master/linear_models/"
    click neural "https://github.com/sjwhitworth/golearn/tree/master/neural/"
    click perceptron "https://github.com/sjwhitworth/golearn/tree/master/perceptron/"
    click trees "https://github.com/sjwhitworth/golearn/tree/master/trees/"
    click ensemble "https://github.com/sjwhitworth/golearn/tree/master/ensemble/"
    click meta "https://github.com/sjwhitworth/golearn/tree/master/meta/"
    click pca "https://github.com/sjwhitworth/golearn/tree/master/pca/"
    click Optimisation "https://github.com/sjwhitworth/golearn/blob/master/optimisation/optimisation.go"
    click utilities "https://github.com/sjwhitworth/golearn/blob/master/utilities/utilities.go"
    click Evaluation "https://github.com/sjwhitworth/golearn/tree/master/evaluation/"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,color:#1B2631;
    classDef pre fill:#A9DFBF,stroke:#196F3D,color:#145A32;
    classDef algo fill:#F9E79F,stroke:#B9770E,color:#7D6608;
    classDef eval fill:#D2B4DE,stroke:#6C3483,color:#4A235A;
    classDef util fill:#D5DBDB,stroke:#566573,color:#1C2833;
    classDef examples fill:#E5E8E8,stroke:#85929E,color:#1B2631;
    classDef doc fill:#E5E8E8,stroke:#85929E,color:#1B2631;
```
