neuralnet

README

neuralnet

Implements a basic L-Layer neural network. Current features are

• Inputs are images only (classification is based on folder location)
• Binary classification only
• Supports only relu, tanh and sigmoid activation functions
• Auto-initialize weights
• Augment data by flipping images horizontally
• Normalize data sets
• Use L2 regularization
• Use dropout
• Split training set into mini batches
• Use gradient descent with momentum

How to use

Define the hyper parameters

Define the L layer net by using the neuralnet.NewHyperParametersBuilder() with the following options

• AddLayers(a ActivationFuncName, neurons ...uint) - adds layers with the specified neurons and activation function
• AddNLayer(a ActivationFuncName, neurons uint, n uint) - adds n indentical layers to the net
• SetLearningRate(learningRate float64) - The learning rate to use, defaults to 0.01
• SetIterations(iterations uint) - number of iterations used to train the model, defaults to 1000
• SetRegularizationFactor(regularizationFactor float64) - the regularization factor to use. 0 indicates not to regularize.
• SetDropoutKeepProbability - enables dropout by specifying the probability neurons should be kept (i.e. not dropped). 0 indicates not to dropout.
• SetMiniBatchSize - splits the training set into mini batches for large data sets
• UseGradientDescentWithMomentum(beta float64) - uses a exponential moving average of gradients when minimizing, allowing the learning rate to be higher as it dampens out oscillations.

The last layer must be a single neuron using the sigmoid activation function for binary classification.

e.g.

hyperParams, err := neuralnet.NewHyperParametersBuilder().
    AddLayers(neuralnet.ActivationFuncNameReLU, 3, 2).
    AddLayer(neuralnet.ActivationFuncNameSigmoid, 1)
    SetLearningRate(0.15).
    SetIterations(5000).
    SetRegularizationFactor(0.5).
    SetDropoutKeepProbability(0.75).
    SetMiniBatchSize(1024).
    UseGradientDescentWithMomentum(0.9).
    Build()

Load the training set

Once defined, create a training set using the neuralnet.NewImageSetBuilder() with the following options

• WithPathPrefix(pathPrefix string) - defines a root folder to use
• AddFolder(pathToFolder string, classification bool) - adds a folder to the training set, with the classification to use
• AddImage(pathToImage string, classification bool) - adds a single image, with the classification to use
• ResizeImages(width, height uint) - resize all the images
• AugmentFlipHorizontal() - doubles the data set by considering the images flipped horizontally
• Normalize() - normalizes the data. Note that if the training set is normalized, the test set will also need to be normalized.

If the images are not being resized, they need to be all of the same height and width.

e.g.

trainingDataSet, err := neuralnet.NewImageSetBuilder().
    AugmentFlipHorizontal().
    WithPathPrefix("datasets/Vegetable Images/train").
    AddFolder("Cabbage", false).
    AddFolder("Carrot", true).
    ResizeImages(32, 32).
    Normalize().
    Build()

Train the model with dataset

model, err := hyperParams.TrainModel(trainingDataSet)

Verify accuracy of training set

model.Predict(trainingDataSet)

Load the testing set

e.g.

testDataSet, err := neuralnet.NewImageSetBuilder().
    WithPathPrefix("../datasets/Vegetable Images/test").
    AddFolder("Cabbage", false).
    AddFolder("Carrot", true).
    ResizeImages(32, 32).
    Normalize().
    Build()

Verify accuracy of test set

model.Predict(testDataSet)

Documentation

Index

• type ActivationFuncName
• type HyperParameters
  • func (h HyperParameters) Layer(i int) layerDefinition
  • func (h HyperParameters) String() string
  • func (h HyperParameters) TrainModel(trainingDataSet *ImageSet) (*TrainedModel, error)
• type HyperParametersBuilder
  • func NewHyperParametersBuilder() HyperParametersBuilder
  • func (builder HyperParametersBuilder) AddLayers(a ActivationFuncName, neurons ...uint) HyperParametersBuilder
  • func (builder HyperParametersBuilder) AddNLayers(a ActivationFuncName, neurons uint, n uint) HyperParametersBuilder
  • func (builder HyperParametersBuilder) Build() (HyperParameters, error)
  • func (builder HyperParametersBuilder) SetDropoutKeepProbability(keepProb float64) HyperParametersBuilder
  • func (builder HyperParametersBuilder) SetIterations(iterations uint) HyperParametersBuilder
  • func (builder HyperParametersBuilder) SetLearningRate(learningRate float64) HyperParametersBuilder
  • func (builder HyperParametersBuilder) SetMiniBatchSize(size uint) HyperParametersBuilder
  • func (builder HyperParametersBuilder) SetRegularizationFactor(regularizationFactor float64) HyperParametersBuilder
  • func (builder HyperParametersBuilder) UseGradientDescentWithMomentum(beta float64) HyperParametersBuilder
• type ImageSet
  • func (i *ImageSet) NumberOfExamples() uint
  • func (i *ImageSet) X() mx.Matrix
  • func (i *ImageSet) Y() mx.Matrix
• type ImageSetBuilder
  • func NewImageSetBuilder() ImageSetBuilder
  • func (builder ImageSetBuilder) AddFolder(pathToFolder string, classification bool) ImageSetBuilder
  • func (builder ImageSetBuilder) AddImage(pathToImage string, classification bool) ImageSetBuilder
  • func (builder ImageSetBuilder) AugmentFlipHorizontal() ImageSetBuilder
  • func (builder ImageSetBuilder) Build() (*ImageSet, error)
  • func (builder ImageSetBuilder) Normalize() ImageSetBuilder
  • func (builder ImageSetBuilder) ResizeImages(width, height uint) ImageSetBuilder
  • func (builder ImageSetBuilder) WithLogging() ImageSetBuilder
  • func (builder ImageSetBuilder) WithPathPrefix(pathPrefix string) ImageSetBuilder
• type TrainedModel
  • func (t *TrainedModel) Predict(set *ImageSet)

Types

type ActivationFuncName

type ActivationFuncName string

const (
	ActivationFuncNameReLU    ActivationFuncName = "relu"
	ActivationFuncNameSigmoid ActivationFuncName = "sigmoid"
	ActivationFuncNameTanh    ActivationFuncName = "tanh"
)

type HyperParameters

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

func (HyperParameters) Layer

func (h HyperParameters) Layer(i int) layerDefinition

func (HyperParameters) String

func (h HyperParameters) String() string

func (HyperParameters) TrainModel

func (h HyperParameters) TrainModel(trainingDataSet *ImageSet) (*TrainedModel, error)

type HyperParametersBuilder

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

func NewHyperParametersBuilder

func NewHyperParametersBuilder() HyperParametersBuilder

func (HyperParametersBuilder) AddLayers

func (builder HyperParametersBuilder) AddLayers(a ActivationFuncName, neurons ...uint) HyperParametersBuilder

func (HyperParametersBuilder) AddNLayers

func (builder HyperParametersBuilder) AddNLayers(a ActivationFuncName, neurons uint, n uint) HyperParametersBuilder

func (HyperParametersBuilder) Build

func (builder HyperParametersBuilder) Build() (HyperParameters, error)

func (HyperParametersBuilder) SetDropoutKeepProbability

func (builder HyperParametersBuilder) SetDropoutKeepProbability(keepProb float64) HyperParametersBuilder

func (HyperParametersBuilder) SetIterations

func (builder HyperParametersBuilder) SetIterations(iterations uint) HyperParametersBuilder

func (HyperParametersBuilder) SetLearningRate

func (builder HyperParametersBuilder) SetLearningRate(learningRate float64) HyperParametersBuilder

func (HyperParametersBuilder) SetMiniBatchSize

func (builder HyperParametersBuilder) SetMiniBatchSize(size uint) HyperParametersBuilder

func (HyperParametersBuilder) SetRegularizationFactor

func (builder HyperParametersBuilder) SetRegularizationFactor(regularizationFactor float64) HyperParametersBuilder

func (HyperParametersBuilder) UseGradientDescentWithMomentum

func (builder HyperParametersBuilder) UseGradientDescentWithMomentum(beta float64) HyperParametersBuilder

type ImageSet

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

func (*ImageSet) NumberOfExamples

func (i *ImageSet) NumberOfExamples() uint

func (*ImageSet) X

func (i *ImageSet) X() mx.Matrix

func (*ImageSet) Y

func (i *ImageSet) Y() mx.Matrix

type ImageSetBuilder

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

func NewImageSetBuilder

func NewImageSetBuilder() ImageSetBuilder

func (ImageSetBuilder) AddFolder

func (builder ImageSetBuilder) AddFolder(pathToFolder string, classification bool) ImageSetBuilder

func (ImageSetBuilder) AddImage

func (builder ImageSetBuilder) AddImage(pathToImage string, classification bool) ImageSetBuilder

func (ImageSetBuilder) AugmentFlipHorizontal

func (builder ImageSetBuilder) AugmentFlipHorizontal() ImageSetBuilder

func (ImageSetBuilder) Build

func (builder ImageSetBuilder) Build() (*ImageSet, error)

func (ImageSetBuilder) Normalize

func (builder ImageSetBuilder) Normalize() ImageSetBuilder

func (ImageSetBuilder) ResizeImages

func (builder ImageSetBuilder) ResizeImages(width, height uint) ImageSetBuilder

func (ImageSetBuilder) WithLogging

func (builder ImageSetBuilder) WithLogging() ImageSetBuilder

func (ImageSetBuilder) WithPathPrefix

func (builder ImageSetBuilder) WithPathPrefix(pathPrefix string) ImageSetBuilder

type TrainedModel

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

func (*TrainedModel) Predict

func (t *TrainedModel) Predict(set *ImageSet)