|
1 | | -# tfjs-node-helpers |
| 1 | +# tfjs-node-helpers |
| 2 | + |
| 3 | +## Introduction |
| 4 | + |
| 5 | +This library was created to simplify the work with [TensorFlow.js][1] in |
| 6 | +[Node][2]. |
| 7 | + |
| 8 | +Currently, this library provides the helpers for the |
| 9 | +[binary classification task][3]. |
| 10 | +The long-term plan is to implement helpers for other tasks, for example, |
| 11 | +[regression][4] and [multiclass classification][5]), as well as to cover |
| 12 | +different [machine learning approaches][6]. |
| 13 | + |
| 14 | +## Installation |
| 15 | + |
| 16 | +Before you start using the helpers in your project, you need to install the |
| 17 | +[@ronas-it/tfjs-node-helpers][7] package: |
| 18 | + |
| 19 | +```bash |
| 20 | +> npm install @ronas-it/tfjs-node-helpers --save |
| 21 | +``` |
| 22 | + |
| 23 | +## Usage |
| 24 | + |
| 25 | +### Feature extraction |
| 26 | + |
| 27 | +Before training any model, you need to extract the valuable information |
| 28 | +from your dataset. This information is usually called *features*. |
| 29 | +This library provides a few helpers to streamline the process of feature extraction. |
| 30 | + |
| 31 | +First, you need to define the feature extractors. In the example below we |
| 32 | +extract the `gender` feature from the dataset item. For that we create a |
| 33 | +`GenderFeatureExtractor` class extending the `FeatureExtractor` base class |
| 34 | +provided by the library. Please note that feature extractors also encode the |
| 35 | +extracted information as a number in the range between `0` and `1`, so that it |
| 36 | +can be consumed when training the model. |
| 37 | + |
| 38 | +```typescript |
| 39 | +type DatasetItem = { |
| 40 | + id: number; |
| 41 | + gender: string; |
| 42 | + age: number; |
| 43 | + annual_salary: number; |
| 44 | + owns_the_car: number; |
| 45 | +}; |
| 46 | + |
| 47 | +class GenderFeatureExtractor extends FeatureExtractor<DatasetItem, FeatureType> { |
| 48 | + public featureType = FeatureType.GENDER; |
| 49 | + |
| 50 | + public extract(item: DatasetItem): Feature<FeatureType> { |
| 51 | + return new Feature({ |
| 52 | + type: this.featureType, |
| 53 | + label: item.gender, |
| 54 | + value: (item.gender === 'Male') ? 1 : 0 |
| 55 | + }); |
| 56 | + } |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +That's it! Now we can use the defined feature extractor to extract valuable |
| 61 | +information from our dataset. |
| 62 | + |
| 63 | +### Binary classification |
| 64 | + |
| 65 | +This library provides two classes to train and evaluate binary classification |
| 66 | +models: |
| 67 | + |
| 68 | +1. `BinaryClassificationTrainer` – used for training and testing. |
| 69 | +1. `BinaryClassifier` – used for evaluation. |
| 70 | + |
| 71 | +#### Creating the trainer |
| 72 | + |
| 73 | +Before training the model, you need to create an instance of the |
| 74 | +`BinaryClassificationTrainer` class first and provide a few parameters: |
| 75 | + |
| 76 | +- `batchSize` – the number of training samples in each batch. |
| 77 | +- `epochs` – the maximum number of iterations that we should train the model. |
| 78 | +- `patience` – the number of iterations after which the trainer will stop if |
| 79 | + there is no improvement. |
| 80 | +- `hiddenLayers` – a list of hidden layers. You can also provide the custom |
| 81 | + model by using the optional `model` parameter instead. |
| 82 | +- `inputFeatureExtractors` – a list of feature extractors to extract information |
| 83 | + that should be fed into the model as inputs. |
| 84 | +- `outputFeatureExtractor` – the feature extractor to extract information that |
| 85 | + we want to predict. |
| 86 | + |
| 87 | +An example can be found below: |
| 88 | + |
| 89 | +```typescript |
| 90 | +const trainer = new BinaryClassificationTrainer({ |
| 91 | + batchSize: BATCH_SIZE, |
| 92 | + epochs: EPOCHS, |
| 93 | + patience: PATIENCE, |
| 94 | + hiddenLayers: [ |
| 95 | + layers.dense({ units: 128, activation: 'mish' }), |
| 96 | + layers.dense({ units: 128, activation: 'mish' }) |
| 97 | + ], |
| 98 | + inputFeatureExtractors: [ |
| 99 | + new AgeFeatureExtractor(), |
| 100 | + new AnnualSalaryFeatureExtractor(), |
| 101 | + new GenderFeatureExtractor() |
| 102 | + ], |
| 103 | + outputFeatureExtractor: new OwnsTheCarFeatureExtractor() |
| 104 | +}); |
| 105 | +``` |
| 106 | + |
| 107 | +#### Training and testing |
| 108 | + |
| 109 | +To train the model, you need to call the `trainAndTest` method of the |
| 110 | +instantiated `BinaryClassificationTrainer`. |
| 111 | + |
| 112 | +You can pass the `data` parameter, and in this case trainer will extract |
| 113 | +features from the provided dataset first. If you want something more customized, |
| 114 | +then you can create the datasets for training, validation and testing manually, |
| 115 | +and pass them as the `trainingDataset`, `validationDataset` and `testingDataset` |
| 116 | +parameters. |
| 117 | + |
| 118 | +You can also print the testing results by setting the `printResults` to `true`. |
| 119 | + |
| 120 | +An example can be found below: |
| 121 | + |
| 122 | +```typescript |
| 123 | +await trainer.trainAndTest({ |
| 124 | + data, |
| 125 | + printResults: true |
| 126 | +}); |
| 127 | +``` |
| 128 | + |
| 129 | +#### Saving the model |
| 130 | + |
| 131 | +To save the trained model, you need to call the `save` method of the |
| 132 | +instantiated `BinaryClassificationTrainer` and pass the path where the model |
| 133 | +should be saved: |
| 134 | + |
| 135 | +```typescript |
| 136 | +await trainer.save(join(__dirname, './trained_model')); |
| 137 | +``` |
| 138 | + |
| 139 | +#### Creating the classifier |
| 140 | + |
| 141 | +Before evaluating the model, you need to create an instance of the |
| 142 | +`BinaryClassifier` class: |
| 143 | + |
| 144 | +```typescript |
| 145 | +const classifier = new BinaryClassifier(); |
| 146 | +``` |
| 147 | + |
| 148 | +#### Loading the trained model |
| 149 | + |
| 150 | +To load the trained model, you need to call the `load` method of the |
| 151 | +instantiated `BinaryClassifier` class and pass the path where the model json |
| 152 | +file is located: |
| 153 | + |
| 154 | +```typescript |
| 155 | +await classifier.load(join(__dirname, './trained_model/model.json')); |
| 156 | +``` |
| 157 | + |
| 158 | +#### Evaluation |
| 159 | + |
| 160 | +To evaluate the trained model, you need to load it first, and then call the |
| 161 | +`predict` method of the instantiated `BinaryClassifier` class and pass an array |
| 162 | +of encoded inputs which will be fed into the model: |
| 163 | + |
| 164 | +```typescript |
| 165 | +const ownsTheCar = await classifier.predict([0.2, 0.76, 0]); |
| 166 | +``` |
| 167 | + |
| 168 | +## Contributing |
| 169 | + |
| 170 | +Thank you for considering contributing to `tfjs-node-helpers` library! The |
| 171 | +contribution guide can be found in the [Contributing guide][8]. |
| 172 | + |
| 173 | +## License |
| 174 | + |
| 175 | +`tfjs-node-helpers` is licensed under the [MIT license][9]. |
| 176 | + |
| 177 | +[1]:https://www.tensorflow.org/js |
| 178 | +[2]:https://nodejs.org |
| 179 | +[3]:https://en.wikipedia.org/wiki/Binary_classification |
| 180 | +[4]:https://en.wikipedia.org/wiki/Regression_analysis |
| 181 | +[5]:https://en.wikipedia.org/wiki/Multiclass_classification |
| 182 | +[6]:https://en.wikipedia.org/wiki/Machine_learning#Approaches |
| 183 | +[7]:https://www.npmjs.com/package/@ronas-it/tfjs-node-helpers |
| 184 | +[8]:CONTRIBUTING.md |
| 185 | +[9]:LICENSE |
0 commit comments