Models retraining functionality added (#169)

Author: gyrdym

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 15.6.0
+- Models retraining functionality added 
+
 ## 15.5.0
 - `KnnClassifier`, `DecisionTreeClassifier`, `LogisticRegressor`, `SoftmaxRegressor`, `KnnRegressor`, `LinearRegressor`
     - hyperparameters added to the interfaces

README.md

@@ -210,8 +210,8 @@ After that we can simply read the model from the file and make predictions:
 import 'dart:io';
 
 final file = File(fileName);
-final encodedData = await file.readAsString();
-final classifier = LogisticRegressor.fromJson(encodedData);
+final encodedModel = await file.readAsString();
+final classifier = LogisticRegressor.fromJson(encodedModel);
 final unlabelledData = await fromCsv('some_unlabelled_data.csv');
 final prediction = classifier.predict(unlabelledData);
 
@@ -226,6 +226,15 @@ print(prediction.rows); // [
                         // ]
 ```
 
+Please note that all the hyperparameters that we used to generate the model are persisted as the model's readonly 
+fields, and we can access it anytime:
+
+```dart
+print(classifier.iterationsLimit);
+print(classifier.probabilityThreshold);
+// and so on
+``` 
+
 All the code above all together:
 
 ````dart
@@ -265,6 +274,25 @@ void main() async {
 }
 ````
 
+Someday our previously shining model can degrade in terms of prediction accuracy - in this case we can retrain it. 
+Retraining means simply re-running the same learning algorithm that was used to generate our current model
+keeping the same hyperparameters but using a new data set with the same features:
+
+```dart
+import 'dart:io';
+
+final encodedModel = await file.readAsString();
+final classifier = LogisticRegressor.fromJson(encodedModel);
+
+// ... 
+// here we do something and realize that our classifier performance is not so good
+// ...
+
+final newData = await fromCsv('path/to/dataset/with/new/data/to/retrain/the/classifier');
+final retrainedClassifier = classifier.retrain(newData);
+
+```
+
 The workflow with other predictors (SoftmaxRegressor, DecisionTreeClassifier and so on) is quite similar to the described
 above for LogisticRegressor, feel free to experiment with other models. 
 

lib/src/classifier/decision_tree_classifier/_helper/create_decision_tree_classifier.dart

@@ -1,3 +1,4 @@
+import 'package:injector/injector.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/_injector.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier_factory.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier_factory_impl.dart';
@@ -22,10 +23,10 @@ import 'package:ml_algo/src/tree_trainer/splitter/splitter_factory_impl.dart';
 import 'package:ml_algo/src/tree_trainer/tree_trainer_factory.dart';
 import 'package:ml_algo/src/tree_trainer/tree_trainer_factory_impl.dart';
 
-void initDecisionTreeModule() {
+Injector initDecisionTreeModule() {
   initCommonModule();
 
-  decisionTreeInjector
+  return decisionTreeInjector
     ..registerSingletonIf<DistributionCalculatorFactory>(
             () => const DistributionCalculatorFactoryImpl())
 

lib/src/classifier/decision_tree_classifier/_helper/create_decision_tree_classifier_from_json.dart

@@ -1,9 +1,9 @@
 import 'package:ml_algo/src/classifier/classifier.dart';
-import 'package:ml_algo/src/classifier/decision_tree_classifier/_helper/create_decision_tree_classifier.dart';
-import 'package:ml_algo/src/classifier/decision_tree_classifier/_helper/create_decision_tree_classifier_from_json.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/_init_module.dart';
+import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier_factory.dart';
 import 'package:ml_algo/src/common/serializable/serializable.dart';
 import 'package:ml_algo/src/model_selection/assessable.dart';
+import 'package:ml_algo/src/predictor/retrainable.dart';
 import 'package:ml_dataframe/ml_dataframe.dart';
 import 'package:ml_linalg/dtype.dart';
 
@@ -16,8 +16,13 @@ import 'package:ml_linalg/dtype.dart';
 /// decision tree learning. Once a decision tree learned, it may be used to
 /// classify new samples with the same features that were used to learn the
 /// tree.
-abstract class DecisionTreeClassifier implements
-    Classifier, Assessable, Serializable {
+abstract class DecisionTreeClassifier
+    implements
+        Assessable,
+        Serializable,
+        Retrainable,
+        Classifier {
+
   /// Parameters:
   ///
   /// [trainData] A [DataFrame] with observations that will be used by the
@@ -45,18 +50,17 @@ abstract class DecisionTreeClassifier implements
     int minSamplesCount,
     int maxDepth,
     DType dtype = DType.float32,
-  }) {
-    initDecisionTreeModule();
-
-    return createDecisionTreeClassifier(
+  }) =>
+    initDecisionTreeModule()
+        .get<DecisionTreeClassifierFactory>()
+        .create(
       trainData,
-      targetName,
       minError,
       minSamplesCount,
       maxDepth,
+      targetName,
       dtype,
     );
-  }
 
   /// Restores previously fitted classifier instance from the given [json]
   ///
@@ -93,11 +97,10 @@ abstract class DecisionTreeClassifier implements
   /// // here you can use previously fitted restored classifier to make
   /// // some prediction, e.g. via `DecisionTreeClassifier.predict(...)`;
   /// ````
-  factory DecisionTreeClassifier.fromJson(String json) {
-    initDecisionTreeModule();
-
-    return createDecisionTreeClassifierFromJson(json);
-  }
+  factory DecisionTreeClassifier.fromJson(String json) =>
+      initDecisionTreeModule()
+          .get<DecisionTreeClassifierFactory>()
+          .fromJson(json);
 
   /// A minimal error on a single decision tree node. It is used as a
   /// stop criteria to avoid farther decision's tree node splitting: if the

lib/src/classifier/decision_tree_classifier/_init_module.dart

@@ -0,0 +1 @@
+const decisionTreeClassifierJsonSchemaVersion = 1;

lib/src/classifier/decision_tree_classifier/decision_tree_classifier.dart

@@ -1,14 +1,16 @@
 import 'package:ml_algo/ml_algo.dart';
-import 'package:ml_algo/src/tree_trainer/tree_node/tree_node.dart';
+import 'package:ml_dataframe/ml_dataframe.dart';
 import 'package:ml_linalg/dtype.dart';
 
 abstract class DecisionTreeClassifierFactory {
   DecisionTreeClassifier create(
+      DataFrame trainData,
       num minError,
       int minSamplesCount,
       int maxDepth,
-      TreeNode root,
       String targetName,
       DType dtype,
   );
+
+  DecisionTreeClassifier fromJson(String json);
 }

lib/src/classifier/decision_tree_classifier/decision_tree_classifier_constants.dart

@@ -1,27 +1,64 @@
+import 'dart:convert';
+
 import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier_factory.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier_impl.dart';
-import 'package:ml_algo/src/tree_trainer/tree_node/tree_node.dart';
+import 'package:ml_algo/src/helpers/validate_train_data.dart';
+import 'package:ml_algo/src/helpers/validate_tree_solver_max_depth.dart';
+import 'package:ml_algo/src/helpers/validate_tree_solver_min_error.dart';
+import 'package:ml_algo/src/helpers/validate_tree_solver_min_samples_count.dart';
+import 'package:ml_algo/src/tree_trainer/_helpers/create_decision_tree_trainer.dart';
+import 'package:ml_dataframe/ml_dataframe.dart';
 import 'package:ml_linalg/dtype.dart';
 
 class DecisionTreeClassifierFactoryImpl implements
     DecisionTreeClassifierFactory {
+
   const DecisionTreeClassifierFactoryImpl();
 
   @override
   DecisionTreeClassifier create(
+      DataFrame trainData,
       num minError,
       int minSamplesCount,
       int maxDepth,
-      TreeNode root,
       String targetName,
       DType dtype,
-  ) => DecisionTreeClassifierImpl(
-    minError,
-    minSamplesCount,
-    maxDepth,
-    root,
-    targetName,
-    dtype,
-  );
+  ) {
+    validateTrainData(trainData, [targetName]);
+    validateTreeSolverMinError(minError);
+    validateTreeSolversMinSamplesCount(minSamplesCount);
+    validateTreeSolverMaxDepth(maxDepth);
+
+    final trainer = createDecisionTreeTrainer(
+      trainData,
+      targetName,
+      minError,
+      minSamplesCount,
+      maxDepth,
+    );
+    final treeRootNode = trainer
+        .train(trainData.toMatrix(dtype));
+
+    return DecisionTreeClassifierImpl(
+      minError,
+      minSamplesCount,
+      maxDepth,
+      treeRootNode,
+      targetName,
+      dtype,
+    );
+  }
+
+  @override
+  DecisionTreeClassifier fromJson(String json) {
+    if (json.isEmpty) {
+      throw Exception('Provided JSON object is empty, please provide a proper '
+          'JSON object');
+    }
+
+    final decodedJson = jsonDecode(json) as Map<String, dynamic>;
+
+    return DecisionTreeClassifierImpl.fromJson(decodedJson);
+  }
 }

lib/src/classifier/decision_tree_classifier/decision_tree_classifier_factory.dart

@@ -1,7 +1,12 @@
 import 'package:json_annotation/json_annotation.dart';
 import 'package:ml_algo/src/classifier/_mixins/assessable_classifier_mixin.dart';
+import 'package:ml_algo/src/classifier/decision_tree_classifier/_injector.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier.dart';
+import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier_constants.dart';
+import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_classifier_factory.dart';
 import 'package:ml_algo/src/classifier/decision_tree_classifier/decision_tree_json_keys.dart';
+import 'package:ml_algo/src/common/constants/common_json_keys.dart';
+import 'package:ml_algo/src/common/exception/outdated_json_schema_exception.dart';
 import 'package:ml_algo/src/common/json_converter/dtype_json_converter.dart';
 import 'package:ml_algo/src/common/serializable/serializable_mixin.dart';
 import 'package:ml_algo/src/tree_trainer/leaf_label/leaf_label.dart';
@@ -31,6 +36,9 @@ class DecisionTreeClassifierImpl
       this.treeRootNode,
       this.targetColumnName,
       this.dtype,
+      {
+        this.schemaVersion = decisionTreeClassifierJsonSchemaVersion,
+      }
   );
 
   factory DecisionTreeClassifierImpl.fromJson(Map<String, dynamic> json) =>
@@ -76,6 +84,12 @@ class DecisionTreeClassifierImpl
   @JsonKey(includeIfNull: false)
   final num negativeLabel = null;
 
+  @override
+  @JsonKey(name: jsonSchemaVersionJsonKey)
+  final schemaVersion;
+
+  final _outdatedSchemaVersions = [null];
+
   @override
   DataFrame predict(DataFrame features) {
     final predictedLabels = features
@@ -134,4 +148,22 @@ class DecisionTreeClassifierImpl
 
     throw Exception('Given sample does not conform any splitting condition');
   }
+
+  @override
+  DecisionTreeClassifier retrain(DataFrame data) {
+    if (_outdatedSchemaVersions.contains(schemaVersion)) {
+      throw OutdatedJsonSchemaException();
+    }
+
+    return decisionTreeInjector
+        .get<DecisionTreeClassifierFactory>()
+        .create(
+      data,
+      minError,
+      minSamplesCount,
+      maxDepth,
+      targetColumnName,
+      dtype,
+    );
+  }
 }