GoOD

README

GoOD - Go Outlier Detection

GoOD is a Go implementation of outlier detection algorithms, inspired by the excellent PyOD Python library.

Overview

GoOD provides a comprehensive toolkit for detecting anomalies and outliers in data. It aims to be a Go-native implementation offering similar functionality to PyOD while taking advantage of Go's performance and concurrency features.

Installation

go get github.com/MohammadMdv/GoOD

Quick Start

package main

import (
    "fmt"
    "github.com/MohammadMdv/GoOD/models"
    "github.com/MohammadMdv/GoOD/utils"
)

func main() {
    // Generate sample data
    opts := utils.DefaultGenerateDataOptions()
    opts.NTrain = 200
    opts.NTest = 100
    XTrain, XTest, _, _ := utils.GenerateData(opts)

    // Create and fit an HBOS detector
    detector := models.NewHBOS(nil) // nil uses default options
    detector.Fit(XTrain, nil)

    // Predict outliers
    labels, _ := detector.Predict(XTest)
    scores, _ := detector.DecisionFunction(XTest)

    fmt.Printf("Predictions: %v\n", labels)
    fmt.Printf("Anomaly Scores: %v\n", scores)
}

Implemented Algorithms

GoOD currently supports 13 outlier detection algorithms:

Proximity-Based Models

Algorithm	Full Name	Description
KNN	K-Nearest Neighbors	Uses distance to k-th neighbor or average distance to k neighbors
LOF	Local Outlier Factor	Compares local density of a point to its neighbors
COF	Connectivity-Based Outlier Factor	Uses chaining distance to measure outlierness
ABOD	Angle-Based Outlier Detection	Uses variance of angles between data points
SOD	Subspace Outlier Detection	Detects outliers in axis-parallel subspaces
SOS	Stochastic Outlier Selection	Uses affinity-based probability of being an outlier

Statistical Models

Algorithm	Full Name	Description
HBOS	Histogram-Based Outlier Score	Fast histogram-based approach
ECOD	Empirical Cumulative Distribution	Parameter-free using ECDF
COPOD	Copula-Based Outlier Detection	Parameter-free using empirical copulas
MAD	Median Absolute Deviation	Univariate outlier detection using median

Linear Models

Algorithm	Full Name	Description
PCA	Principal Component Analysis	Uses reconstruction error in principal component space

Ensemble Models

Algorithm	Full Name	Description
IForest	Isolation Forest	Isolates anomalies using random trees
LODA	Lightweight Online Detector	Ensemble of sparse random projections

Design Philosophy

GoOD follows a consistent API design similar to PyOD:

1. Fit: Train the model on data
2. Predict: Get binary labels (0 for inliers, 1 for outliers)
3. DecisionFunction: Get raw anomaly scores
4. PredictProba: Get probability estimates

All detectors implement the common Detector interface for easy interchangeability.

Utilities

GoOD includes utility functions for:

• Data generation for testing (GenerateData, GenerateDataClusters)
• Evaluation metrics (ROC-AUC, Precision@N, Recall, F1)
• Data preprocessing (Train/Test split, standardization)
• Statistical utilities (Percentile, argmax, etc.)

Example Usage

Using Different Detectors

// Isolation Forest
iforest := models.NewIForest(&models.IForestOptions{
    NEstimators:   100,
    MaxSamples:    256,
    Contamination: 0.1,
})

// K-Nearest Neighbors
knn := models.NewKNN(&models.KNNOptions{
    NNeighbors:    5,
    Method:        "largest", // "largest", "mean", or "median"
    Contamination: 0.1,
})

// Local Outlier Factor
lof := models.NewLOF(&models.LOFOptions{
    NNeighbors:    20,
    Contamination: 0.1,
})

// COPOD (parameter-free)
copod := models.NewCOPOD(nil) // Uses default options

Evaluating Performance

// Generate data
opts := utils.DefaultGenerateDataOptions()
XTrain, XTest, yTrain, yTest := utils.GenerateData(opts)

// Fit detector
detector := models.NewHBOS(nil)
detector.Fit(XTrain, nil)

// Evaluate
trainAUC := utils.ROCAUCScore(yTrain, detector.GetDecisionScores())
testScores, _ := detector.DecisionFunction(XTest)
testAUC := utils.ROCAUCScore(yTest, testScores)

fmt.Printf("Train ROC-AUC: %.4f\n", trainAUC)
fmt.Printf("Test ROC-AUC: %.4f\n", testAUC)

Benchmarks

All algorithms have been tested on synthetic data with the following typical ROC-AUC scores:

Algorithm	Train ROC-AUC	Test ROC-AUC
HBOS	1.0000	0.9947
KNN	1.0000	1.0000
LOF	1.0000	0.9800
IForest	1.0000	1.0000
ECOD	0.9753	0.9633
PCA	0.9881	1.0000
LODA	1.0000	1.0000
COPOD	0.9994	0.9989
ABOD	1.0000	1.0000

Credits

This project is inspired by and based on the design of:

• PyOD by Yue Zhao et al.

License

BSD 2-Clause License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.