lingo

README

lingo

A package for quickly deploying Scikit-Learn Linear Models as Go applications.

It was developed to explore use-cases requiring fast inference for very large numbers of models, and to do this cost-effectively.

The package has been tested with the following Scikit-Learn Linear Model variants:

• LinearRegression
• LogisticRegression
• Ridge
• RidgeClassifier
• Lasso
• SGDRegressor
• SGDClassifier

While the package is designed for some of the most common Scikit-Learn linear models, it was designed to demonstrate a concept that can easily be applied to other model variants too -- and not just models in Scikit-Learn.

Quickstart

Before you begin, you'll need to save your Scikit-Learn model with the py-lingo Python package. When you've got that saved, you can move to deploy your model...

If you're familiar with the setting up servers in Go, then this should all feel familiar. All you need to do is:

1. Load either your LinearClassifier or LinearRegressor model with LoadClassifier or LoadRegressor functions respectively.
2. Create a handler for your model with the NewRegressorHandler or NewClassifierHandler function.
3. Setup your server as normal, passing your newly created handler to whichever router you choose!

Here's a code example of the above for one of the sample models:

package main 

import (
    "github.com/markdouthwaite/lingo"
    "github.com/gorilla/mux"
	"net/http" 
    "time"
	"log"
)


func main(){    
    model := lingo.LoadRegressor("artifacts/boston.h5")
    handler := lingo.NewRegressorHandler(model)
    
    router := mux.NewRouter()
    router.HandleFunc("/predict", handler)
    server := &http.Server{
		Handler:      router,
		Addr:         "127.0.0.1:8000",
		// Good practice: enforce timeouts for servers you create!
		WriteTimeout: 15 * time.Second,
		ReadTimeout:  15 * time.Second,
	}
	
    log.Fatal(server.ListenAndServe())

}

Tailored to run inference on individual feature vectors (i.e. single observations).

Bundled models

There's a few models bundled with this package for testing purposes. They are:

• data/classifiers/iris.h5 - A Scikit-Learn LogisticRegression model trained on the Iris plant dataset.
• data/regressors/boston.h5 - A Scikit-Learn LinearRegression model trained on a reduced version of the Boston housing dataset.
• data/regressors/multi-boston.h5 - A Scikit-Learn LinearRegression model trained on a reduced version of the Boston housing dataset, but with two output variables (both identical).

Documentation

Index

• Constants
• func Argmax(a mat.Vector) (int, int)
• func LinearDecisionFunction(x *mat.Dense, coef *mat.Dense, intercept *mat.VecDense) *mat.Dense
• func NewClassifierHandler(model *LinearClassifier) http.HandlerFunc
• func NewRegressorHandler(model *LinearRegressor) http.HandlerFunc
• func Softmax(x *mat.Dense) *mat.Dense
• func VecToArrayFloat64(v mat.Vector) []float64
• type Classifier
• type ClassifierResponse
• type LinearClassifier
  • func LoadClassifier(fileName string) (model *LinearClassifier)
  • func NewLinearClassifier(coef []float64, intercept []float64, nVars int) *LinearClassifier
  • func (m *LinearClassifier) Predict(x []float64) (c []int, err error)
  • func (m *LinearClassifier) PredictProba(x []float64) (p []float64, err error)
• type LinearModel
  • func Load(fileName string) (modelType string, model *LinearModel)
  • func NewLinearModel(coef []float64, intercept []float64, nVars int) *LinearModel
  • func (m *LinearModel) DecisionFunction(x []float64) (h *mat.Dense, err error)
  • func (m *LinearModel) Validate(x []float64) error
• type LinearRegressor
  • func LoadRegressor(fileName string) (model *LinearRegressor)
  • func NewLinearRegressor(theta []float64, intercept []float64, nVars int) *LinearRegressor
  • func (m *LinearRegressor) Predict(x []float64) ([]float64, error)
• type Model
• type ModelError
• type ModelQuery
• type ProbabilisticClassifier
• type Regressor
• type RegressorResponse
• type Validator

Constants

const (
	// ErrorThreshold is used in tests as the default error expected between predicted and expected values.
	ErrorThreshold = 0.00001
)

Functions

func Argmax

func Argmax(a mat.Vector) (int, int)

Argmax gets the i, j associated with the largest value in a dense matrix.

func LinearDecisionFunction

func LinearDecisionFunction(x *mat.Dense, coef *mat.Dense, intercept *mat.VecDense) *mat.Dense

LinearDecisionFunction computes the decision function over the provided model and feature/s.

func NewClassifierHandler

func NewClassifierHandler(model *LinearClassifier) http.HandlerFunc

NewClassifierHandler creates a handler for LinearClassifiers

func NewRegressorHandler

func NewRegressorHandler(model *LinearRegressor) http.HandlerFunc

NewRegressorHandler creates a handler for LinearRegressors

func Softmax

func Softmax(x *mat.Dense) *mat.Dense

An implementation of a softmax function applied to a dense matrix.

func VecToArrayFloat64

func VecToArrayFloat64(v mat.Vector) []float64

VecToArrayFloat64 converts a vector into an array of floats.

Types

type Classifier

type Classifier interface {
	Predict([]float64) ([]int, error)
}

type ClassifierResponse

type ClassifierResponse struct {
	Response []int `json:"response"`
}

ModelResponse is the default response format from model queries.

type LinearClassifier

type LinearClassifier struct {
	// contains filtered or unexported fields
}

LinearClassifier model

func LoadClassifier

func LoadClassifier(fileName string) (model *LinearClassifier)

func NewLinearClassifier

func NewLinearClassifier(coef []float64, intercept []float64, nVars int) *LinearClassifier

NewLinearClassifier initializes a new Linear LinearClassifier model

func (*LinearClassifier) Predict

func (m *LinearClassifier) Predict(x []float64) (c []int, err error)

// Predict the class for a single observation

func (*LinearClassifier) PredictProba

func (m *LinearClassifier) PredictProba(x []float64) (p []float64, err error)

Predict the probability of classes for a single observation

type LinearModel

type LinearModel struct {
	Coef      *mat.Dense
	Intercept *mat.VecDense
}

func Load

func Load(fileName string) (modelType string, model *LinearModel)

Load loads a linear model from a HDF5 file.

func NewLinearModel

func NewLinearModel(coef []float64, intercept []float64, nVars int) *LinearModel

func (*LinearModel) DecisionFunction

func (m *LinearModel) DecisionFunction(x []float64) (h *mat.Dense, err error)

func (*LinearModel) Validate

func (m *LinearModel) Validate(x []float64) error

type LinearRegressor

type LinearRegressor struct {
	// contains filtered or unexported fields
}

LinearRegressor

func LoadRegressor

func LoadRegressor(fileName string) (model *LinearRegressor)

func NewLinearRegressor

func NewLinearRegressor(theta []float64, intercept []float64, nVars int) *LinearRegressor

NewLinearRegressor creates a new Linear Regression model.

func (*LinearRegressor) Predict

func (m *LinearRegressor) Predict(x []float64) ([]float64, error)

Predict runs inference for a single observation

type Model

type Model interface {
	Predict([]float64) ([]float64, error)
}

type ModelError

type ModelError struct {
	Title   string `json:"title"`
	Message string `json:"message"`
}

type ModelQuery

type ModelQuery struct {
	Features []float64 `json:"features"`
}

ModelResponse is the default query format for model requests.

type ProbabilisticClassifier

type ProbabilisticClassifier interface {
	PredictProba([]float64) ([]float64, error)
}

type Regressor

type Regressor interface {
	Predict([]float64) ([]float64, error)
}

type RegressorResponse

type RegressorResponse struct {
	Response []float64 `json:"response"`
}

ModelResponse is the default response format from model queries.

type Validator

type Validator interface {
	// contains filtered or unexported methods
}