# TensorScript - Machine Learning and Neural Networks with Tensorflow

## Introduction

This library is a compilation of model building modules with a consistent API for quickly implementing Tensorflow at edge(browser) or any JavaScript environment (Node JS / GPU).

### Read the manual

## List of Tensorflow models

### Classification

- Deep Learning Classification: `DeepLearningClassification`
- Logistic Regression: `LogisticRegression`

### Regression

- Deep Learning Regression: `DeepLearningRegression`
- Multivariate Linear Regression: `MultipleLinearRegression`

### Artificial neural networks (ANN)

- Multi-Layered Perceptrons: `BaseNeuralNetwork`

### LSTM Time Series

- Long Short Term Memory Time Series: `LSTMTimeSeries`
- Long Short Term Memory Multivariate Time Series: `LSTMMultivariateTimeSeries`

## Basic Usage

TensorScript is and ECMA Script module designed to be used in an `ES2015+` environment, if you need compiled modules for older versions of node use the compiled modules in the bundle folder.

Please read more on tensorflow configuration options, specifying epochs, and using custom layers in configuration.

### Regression Examples

    import { MultipleLinearRegression, DeepLearningRegression, } from 'tensorscript';
    import ms from 'modelscript';

    async function main(){
      const independentVariables = [ 'sqft', 'bedrooms',];
      const dependentVariables = [ 'price', ];
      const housingdataCSV = await ms.csv.loadCSV('./test/mock/data/portland_housing_data.csv');
      const DataSet = new ms.DataSet(housingdataCSV);
      const x_matrix = DataSet.columnMatrix(independentVariables);
      const y_matrix = DataSet.columnMatrix(dependentVariables);
      const MLR = new MultipleLinearRegression();
      await MLR.train(x_matrix, y_matrix);
      const DLR = new DeepLearningRegression();
      await DLR.train(x_matrix, y_matrix);
      //1600 sqft, 3 bedrooms
      await MLR.predict([1650,3]); //=>[293081.46]
      await DLR.predict([1650,3]); //=>[293081.46]
    }
    main();

### Classification Examples

    import { DeepLearningClassification, } from 'tensorscript';
    import ms from 'modelscript';

    async function main(){
      const independentVariables = [
        'sepal_length_cm',
        'sepal_width_cm',
        'petal_length_cm',
        'petal_width_cm',
      ];
      const dependentVariables = [
        'plant_Iris-setosa',
        'plant_Iris-versicolor',
        'plant_Iris-virginica',
      ];
      const housingdataCSV = await ms.csv.loadCSV('./test/mock/data/iris_data.csv');
      const DataSet = new ms.DataSet(housingdataCSV).fitColumns({ columns: {plant:'onehot'}, });
      const x_matrix = DataSet.columnMatrix(independentVariables);
      const y_matrix = DataSet.columnMatrix(dependentVariables);
      const nnClassification = new DeepLearningClassification();
      await nnClassification.train(x_matrix, y_matrix);
      const input_x = [
        [5.1, 3.5, 1.4, 0.2, ],
        [6.3, 3.3, 6.0, 2.5, ],
        [5.6, 3.0, 4.5, 1.5, ],
        [5.0, 3.2, 1.2, 0.2, ],
        [4.5, 2.3, 1.3, 0.3, ],
      ];
      const predictions = await nnClassification.predict(input_x);
      const answers = await nnClassification.predict(input_x, { probability:false, });
      /*
        predictions = [
          [ 0.989512026309967, 0.010471616871654987, 0.00001649192017794121, ],
          [ 0.0000016141033256644732, 0.054614484310150146, 0.9453839063644409, ],
          [ 0.001930746017023921, 0.6456733345985413, 0.3523959517478943, ],
          [ 0.9875779747962952, 0.01239941269159317, 0.00002274810685776174, ],
          [ 0.9545140862464905, 0.04520365223288536, 0.0002823179238475859, ],
        ];
        answers = [
          [ 1, 0, 0, ], //setosa
          [ 0, 0, 1, ], //virginica
          [ 0, 1, 0, ], //versicolor
          [ 1, 0, 0, ], //setosa
          [ 1, 0, 0, ], //setosa
        ];
       */
    }
    main();

    import { LogisticRegression, } from 'tensorscript';
    import ms from 'modelscript';

    async function main(){
      const independentVariables = [
        'Age',
        'EstimatedSalary',
      ];
      const dependentVariables = [
        'Purchased',
      ];
      const housingdataCSV = await ms.csv.loadCSV('./test/mock/data/social_network_ads.csv');
      const DataSet = new ms.DataSet(housingdataCSV).fitColumns({ columns: {Age:['scale','standard'],
      EstimatedSalary:['scale','standard'],}, });
      const x_matrix = DataSet.columnMatrix(independentVariables);
      const y_matrix = DataSet.columnMatrix(dependentVariables);
      const LR = new LogisticRegression();
      await LR.train(x_matrix, y_matrix);
      const input_x = [
        [-0.062482849427819266, 0.30083326827486173,], //0
        [0.7960601198093905, -1.1069168538010206,], //1
        [0.7960601198093905, 0.12486450301537644,], //0
        [0.4144854668150751, -0.49102617539282206,], //0
        [0.3190918035664962, 0.5061301610775946,], //1
      ];
      const predictions = await LR.predict(input_x); // => [ [ 0 ], [ 0 ], [ 1 ], [ 0 ], [ 1 ] ];
    }
    main();

### Time Series Example

    import { LSTMTimeSeries, } from 'tensorscript';
    import ms from 'modelscript';

    async function main(){
      const dependentVariables = [
        'Passengers',
      ];
      const airlineCSV = await ms.csv.loadCSV('./test/mock/data/airline-sales.csv');
      const DataSet = new ms.DataSet(airlineCSV);
      const x_matrix = DataSet.columnMatrix(independentVariables);
      const TS = new LSTMTimeSeries();
      await TS.train(x_matrix);
      const forecastData = TS.getTimeseriesDataSet([ [100 ], [200], [300], ])
      await TS.predict(forecastData.x_matrix); //=>[200,300,400]
    }
    main();

### Testing

    $ npm i
    $ npm test

### Contributing

Fork, write tests and create a pull request!

### Misc

As of Node 8, ES modules are still used behind a flag, when running natively as an ES module

    $ node --experimental-modules manual/examples/ex_regression-boston.mjs
    # Also there are native bindings that require Python 2.x, make sure if you're using Anaconda, you build with your Python 2.x bin
    $ npm i --python=/usr/bin/python

### Special Thanks

- Machine Learning Mastery
- Super Data Science
- Python Programming
- Towards Data Science
- ml.js

## License

MIT

# Overview

All of the model building classes are structured similarly to ml.js models. Each model has three shared components regardless if it's a regression, classification or time series model.

This library was built to quickly implement Tensorflow and Keras models in JavaScript.

## Configuration

All of the model configuration is managed during creating an instance of the class. All models have `fit` and `compile` properties that are assigned to the instance `settings` property.

You can also pass the Tensorflow reference to be used, as a configuration property if you want to use the compiled C++ or GPU via CUDA versions on the `tf` property;

- `this.settings.compile` is passed to `tensorflow.model.compile` and contains the configuration for optimizers (`read more`).
- `this.settings.fit` is passed to `tensorflow.model.fit` and contains the configuration for model fitting (`read more`)

### Model constructor example

    import { MultipleLinearRegression, } from 'tensorscript';
    import tf from '@tensorflow/tfjs-node-gpu';

    const MLR = new MultipleLinearRegression({
      fit:{
        epochs:500,
        batchSize:5,
      },
      compile:{
        loss: 'meanSquaredError',
        optimizer: 'adam',
      },
    },{
      tf,
    });

Each constructor takes two parameters `settings` and `properties`. As in the example above, settings are used to configure tensorflow objects and properties are used to configure tensorscript (like which version of tensorflow to use).

## Training

All tensorflow models train asynchronously, therefore all tensorscript model train functions are all asynchronous. Always pass dependent and independent variables as matrix inputs.

Time series models can be trained with only one input matrix.

### Training example

    import { MultipleLinearRegression, } from 'tensorscript';

    async function main(){
      const MLR = new MultipleLinearRegression();
      const x = [ [1], [2] ];
      const y = [ [3], [4] ];
      await MLR.train(x,y);
    }

## Predicting

All prediction inputs must be the same shape as training inputs. TensorScript provides an asynchronous predict method that converts tensor values to javascript objects. If you want the tensor from tensorflow, use the calculate method instead.

### Predicting example

    import { MultipleLinearRegression, } from 'tensorscript';

    async function main(){
      const MLR = new MultipleLinearRegression();
      const x = [ [1], [2] ];
      const y = [ [3], [4] ];
      await MLR.train(x,y);

      await MLR.predict([[3]]) //=> [[5]];
      const tensorPrediction = await MLR.calculate([[3]]) //=> [[5]];
      tensorPrediction.data()
        .then(tensors=> /*Typed Array*/)
    }

## Examples

For more examples on how to do feature scaling and more, check out the Examples folder.

# Usage

Usage examples are below

## Classification

- Deep Learning Classification with Iris data set. link
- Logistic Regression Classification with social media ads. link

## Regression

- Deep Learning Regression with Boston housing data set. link
- Multiple Linear Regression with Portland housing data set. link

## Time Series

- Long Short Term Memory with Airline prices. link

## Neural Network

- MLP with dense layers and the Portland housing data. link

# Frequently Asked Questions

## Scaling

- How do I scale and descale my inputs?
  - The library is only for model create, data engineering and modeling is typically handled elsewhere
  - Check out the regression examples (hint: use ModelScript).
- How do I cross validate, test/train split, K-fold, etc?
  - (See above) The library is only for model create, data engineering and modeling is typically handled elsewhere
  - Check out the code examples (hint: use ModelScript).

# Changelog

## 1.0.0 (2018-07-30)

- Feat
  - First Initial Release
- Fix
  - N/A
- Chore
  - Allow for multistep future forecasts in multivariate timeseries.
  - Add basic clustering example.