{"id":20173547,"url":"https://github.com/ronasit/tfjs-node-helpers","last_synced_at":"2026-01-03T17:30:53.434Z","repository":{"id":58566210,"uuid":"524042394","full_name":"RonasIT/tfjs-node-helpers","owner":"RonasIT","description":"A library simplifying the work with TensorFlow.js in Node.","archived":false,"fork":false,"pushed_at":"2023-02-10T11:45:41.000Z","size":431,"stargazers_count":3,"open_issues_count":19,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-01-24T07:45:06.015Z","etag":null,"topics":["deep-learning","deeplearning","machine-learning","machinelearning","node","node-js","node-module","nodejs","tensorflow","tensorflow-js","tensorflowjs","tfjs","tfjs-node","ts","typescript"],"latest_commit_sha":null,"homepage":"https://ronasit.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RonasIT.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-08-12T10:17:48.000Z","updated_at":"2024-01-12T18:35:02.000Z","dependencies_parsed_at":"2023-02-14T17:01:39.126Z","dependency_job_id":null,"html_url":"https://github.com/RonasIT/tfjs-node-helpers","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Ftfjs-node-helpers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Ftfjs-node-helpers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Ftfjs-node-helpers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RonasIT%2Ftfjs-node-helpers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RonasIT","download_url":"https://codeload.github.com/RonasIT/tfjs-node-helpers/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244110086,"owners_count":20399561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning","deeplearning","machine-learning","machinelearning","node","node-js","node-module","nodejs","tensorflow","tensorflow-js","tensorflowjs","tfjs","tfjs-node","ts","typescript"],"created_at":"2024-11-14T01:36:35.573Z","updated_at":"2026-01-03T17:30:53.377Z","avatar_url":"https://github.com/RonasIT.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# tfjs-node-helpers\n\n## Introduction\n\nThis library was created to simplify the work with [TensorFlow.js][1] in\n[Node][2].\n\nCurrently, this library provides the helpers for the\n[binary classification task][3].  \nThe long-term plan is to implement helpers for other tasks, for example,\n[regression][4] and [multiclass classification][5]), as well as to cover\ndifferent [machine learning approaches][6].\n\n## Installation\n\nBefore you start using the helpers in your project, you need to install the\n[@ronas-it/tfjs-node-helpers][7] package:\n\n```bash\nnpm install @ronas-it/tfjs-node-helpers --save\n```\n\n## Usage\n\n### Feature extraction\n\nBefore training any model, you need to extract the valuable information\nfrom your dataset. This information is usually called *features*.\nThis library provides a few helpers to streamline the process of feature extraction.\n\nFirst, you need to define the feature extractors. In the example below we\nextract the `gender` feature from the dataset item. For that we create a\n`GenderFeatureExtractor` class extending the `FeatureExtractor` base class\nprovided by the library. Please note that feature extractors also encode the\nextracted information as a number in the range between `0` and `1`, so that it\ncan be consumed when training the model.\n\n```typescript\ntype DatasetItem = {\n  id: number;\n  gender: string;\n  age: number;\n  annual_salary: number;\n  owns_the_car: number;\n};\n\nclass GenderFeatureExtractor extends FeatureExtractor\u003cDatasetItem, FeatureType\u003e {\n  public featureType = FeatureType.GENDER;\n\n  public extract(item: DatasetItem): Feature\u003cFeatureType\u003e {\n    return new Feature({\n      type: this.featureType,\n      label: item.gender,\n      value: (item.gender === 'Male') ? 1 : 0\n    });\n  }\n}\n```\n\nThat's it! Now we can use the defined feature extractor to extract valuable\ninformation from our dataset.\n\n### Metrics\n\nAfter your model has been trained it's important to evaluate it.\nOne way to do this is by analyzing *metrics*.\nThe library helps measure model performance by passing a list of\nmetric calculators to the model trainer.\n\nWe have a list of built-in metric calculators for popular metrics:\n- AccuracyMetricCalculator\n- PrecisionMetricCalculator\n- RecallMetricCalculator\n- SpecificityMetricCalculator\n- FNRMetricCalculator\n- FPRMetricCalculator\n- NPVMetricCalculator\n- MCCMetricCalculator\n- FBetaScoreMetricCalculator\n- ROCAUCMetricCalculator\n- PRAUCMetricCalculator\n- BrierLossMetricCalculator\n- BinaryCrossentropyMetricCalculator\n- CohenKappaMetricCalculator\n\nYou can implement your own `MetricCalculator`. In the example below, we define\na metric calculator for `precision`. For that we create a `PrecisionMetricCalculator`\nclass extending the `MetricCalculator` base class provided by the library and\nimplementing `calculate` method.\n\n```typescript\nexport class PrecisionMetricCalculator extends MetricCalculator {\n  public calculate({ trueValues, predictedValues }: TestingResult): Metric {\n    const { tp, fp } = new ConfusionMatrix(trueValues, predictedValues);\n\n    return new Metric({\n      title: 'Precision',\n      value: tp / (tp + fp)\n    });\n  }\n}\n```\n\n### Binary classification\n\nThis library provides two classes to train and evaluate binary classification\nmodels:\n\n1. `BinaryClassificationTrainer` – used for training and testing.\n1. `BinaryClassifier` – used for evaluation.\n\n#### Creating the trainer\n\nBefore training the model, you need to create an instance of the\n`BinaryClassificationTrainer` class first and provide a few parameters:\n\n- `batchSize` – the number of training samples in each batch.\n- `epochs` – the maximum number of iterations that we should train the model.\n- `patience` – the number of iterations after which the trainer will stop if\n  there is no improvement.\n- `hiddenLayers` – a list of hidden layers. You can also provide the custom\n  model by using the optional `model` parameter instead.\n- `inputFeatureExtractors` – a list of feature extractors to extract information\n  that should be fed into the model as inputs.\n- `outputFeatureExtractor` – the feature extractor to extract information that\n  we want to predict.\n- `metricCalculators` – a list of metric calculators that will be used during test stage.\n\nAn example can be found below:\n\n```typescript\nconst trainer = new BinaryClassificationTrainer({\n  batchSize: BATCH_SIZE,\n  epochs: EPOCHS,\n  patience: PATIENCE,\n  hiddenLayers: [\n    layers.dense({ units: 128, activation: 'mish' }),\n    layers.dense({ units: 128, activation: 'mish' })\n  ],\n  inputFeatureExtractors: [\n    new AgeFeatureExtractor(),\n    new AnnualSalaryFeatureExtractor(),\n    new GenderFeatureExtractor()\n  ],\n  outputFeatureExtractor: new OwnsTheCarFeatureExtractor(),\n  metricCalculators: [\n    new AccuracyMetricCalculator(),\n    new PrecisionMetricCalculator(),\n    new SpecificityMetricCalculator(),\n    new FPRMetricCalculator()\n  ]\n});\n```\n\n#### Training and testing\n\nTo train the model, you need to call the `trainAndTest` method of the\ninstantiated `BinaryClassificationTrainer`.\n\nYou can pass the `data` parameter, and in this case trainer will extract\nfeatures from the provided dataset first. If you want something more customized,\nthen you can create the datasets for training, validation and testing manually,\nand pass them as the `trainingDataset`, `validationDataset` and `testingDataset`\nparameters.\n\nYou can also print the testing results by setting the `printTestingResults` to\n`true`.\n\nAn example can be found below:\n\n```typescript\nawait trainer.trainAndTest({\n  data,\n  printTestingResults: true\n});\n```\n\n##### Loading data asynchronously\n\nWhen working with large dataset, you might find out that the whole dataset\ncan't fit in memory. In this situation you might want to load the data in\nchunks. To do this, you can define the asynchronous generators for\n`trainingDataset`, `validationDataset` and `testingDataset`.\n\nThis library provides the `makeChunkedDataset` helper to make it easier to\ncreate chunked datasets where chunks are controlled with `skip` and `take`\nparameters.\n\n`makeChunkedDataset` helper accepts the following parameters:\n\n- `loadChunk` – an asynchronous function accepting the numeric `skip` and `take`\n  parameters and returning an array of samples.\n- `chunkSize` – the number of samples loaded per chunk.\n- `batchSize` – the number of samples in each batch.\n\n```typescript\nconst loadTrainingSamplesChunk = async (skip: number, take: number): Promise\u003cArray\u003cSample\u003e\u003e =\u003e {\n  // Your samples chunk loading logic goes here. For example, you may want to\n  //   load samples from database, or from a remote data source.\n};\n\nconst makeTrainingDataset = (): data.Dataset\u003cTensorContainer\u003e =\u003e makeChunkedDataset({\n  loadChunk: loadTrainingSamplesChunk,\n  chunkSize: 32,\n  batchSize: 32\n});\n\n// You should also define similar functions for validationDataset and\n//   trainingDataset. We omit this for the sake of brevity.\n\nconst trainingDataset = makeTrainingDataset();\nconst validationDataset = makeValidationDataset();\nconst testingDataset = makeTestingDataset();\n\nawait trainer.trainAndTest({\n  trainingDataset,\n  validationDataset,\n  testingDataset,\n  printTestingResults: true\n});\n```\n\n#### Saving the model\n\nTo save the trained model, you need to call the `save` method of the\ninstantiated `BinaryClassificationTrainer` and pass the path where the model\nshould be saved:\n\n```typescript\nawait trainer.save(join(__dirname, './trained_model'));\n```\n\n#### Creating the classifier\n\nBefore evaluating the model, you need to create an instance of the\n`BinaryClassifier` class:\n\n```typescript\nconst classifier = new BinaryClassifier();\n```\n\n#### Loading the trained model\n\nTo load the trained model, you need to call the `load` method of the\ninstantiated `BinaryClassifier` class and pass the path where the model json\nfile is located:\n\n```typescript\nawait classifier.load(join(__dirname, './trained_model/model.json'));\n```\n\n#### Evaluation\n\nTo evaluate the trained model, you need to load it first, and then call the\n`predict` method of the instantiated `BinaryClassifier` class and pass an array\nof encoded inputs which will be fed into the model:\n\n```typescript\nconst ownsTheCar = await classifier.predict([0.2, 0.76, 0]);\n```\n\n## Roadmap\n\n- [x] Binary classification ([#1](https://github.com/RonasIT/tfjs-node-helpers/pull/1))\n- [x] Asynchronously loaded datasets ([#14](https://github.com/RonasIT/tfjs-node-helpers/issues/14))\n- [x] Feature normalization ([#5](https://github.com/RonasIT/tfjs-node-helpers/issues/5))\n- [x] Custom metrics ([#18](https://github.com/RonasIT/tfjs-node-helpers/issues/18))\n- [x] Add more metrics ([#17](https://github.com/RonasIT/tfjs-node-helpers/issues/17))\n- [ ] Allow using GPU ([#29](https://github.com/RonasIT/tfjs-node-helpers/issues/29))\n- [ ] Task-oriented architecture ([#26](https://github.com/RonasIT/tfjs-node-helpers/issues/26))\n- [ ] Categorical features ([#19](https://github.com/RonasIT/tfjs-node-helpers/issues/19))\n- [ ] Multiclass classification ([#3](https://github.com/RonasIT/tfjs-node-helpers/issues/3))\n- [ ] Image classification ([#4](https://github.com/RonasIT/tfjs-node-helpers/issues/4))\n- [ ] Regression ([#2](https://github.com/RonasIT/tfjs-node-helpers/issues/2))\n- [ ] Object detection ([#27](https://github.com/RonasIT/tfjs-node-helpers/issues/27))\n- [ ] Uncertainty ([#15](https://github.com/RonasIT/tfjs-node-helpers/issues/15))\n- [ ] Handle class imbalance problem ([#10](https://github.com/RonasIT/tfjs-node-helpers/issues/10))\n- [ ] Automated tests ([#6](https://github.com/RonasIT/tfjs-node-helpers/issues/6))\n- [ ] Continuous Integration ([#11](https://github.com/RonasIT/tfjs-node-helpers/issues/11))\n- [ ] Add an example of queued feature extraction and evaluation ([#12](https://github.com/RonasIT/tfjs-node-helpers/issues/12))\n- [ ] Add an example of storing the extracted features ([#13](https://github.com/RonasIT/tfjs-node-helpers/issues/13))\n- [ ] Add more examples ([#8](https://github.com/RonasIT/tfjs-node-helpers/issues/8))\n- [ ] API reference ([#9](https://github.com/RonasIT/tfjs-node-helpers/issues/9))\n- [ ] Dashboard to visualize metrics over time ([#7](https://github.com/RonasIT/tfjs-node-helpers/issues/7))\n\n## Contributing\n\nThank you for considering contributing to `tfjs-node-helpers` library! The\ncontribution guide can be found in the [Contributing guide][8].\n\n## License\n\n`tfjs-node-helpers` is licensed under the [MIT license][9].\n\n[1]:https://www.tensorflow.org/js\n[2]:https://nodejs.org\n[3]:https://en.wikipedia.org/wiki/Binary_classification\n[4]:https://en.wikipedia.org/wiki/Regression_analysis\n[5]:https://en.wikipedia.org/wiki/Multiclass_classification\n[6]:https://en.wikipedia.org/wiki/Machine_learning#Approaches\n[7]:https://www.npmjs.com/package/@ronas-it/tfjs-node-helpers\n[8]:CONTRIBUTING.md\n[9]:LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronasit%2Ftfjs-node-helpers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fronasit%2Ftfjs-node-helpers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fronasit%2Ftfjs-node-helpers/lists"}