'LinearRegressor.BGD' constructor added (#232)

Author: gyrdym

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 16.15.0
+- `LinearRegressor.BGD` constructor added
+
 ## 16.14.0
 - `LinearRegressor.SGD` constructor added
 

README.md

@@ -45,8 +45,12 @@ it in web applications.
     A class that performs linear binary classification of data. To use this kind of classifier your data has to be 
     [linearly separable](https://en.wikipedia.org/wiki/Linear_separability).
 
-    - [LogisticRegressor.SGD](https://pub.dev/documentation/ml_algo/latest/ml_algo/LogisticRegressor/LogisticRegressor.SGD.html). 
+        - [LogisticRegressor.SGD](https://pub.dev/documentation/ml_algo/latest/ml_algo/LogisticRegressor/LogisticRegressor.SGD.html). 
     Implementation of the logistic regression algorithm based on stochastic gradient descent with L2 regularisation. 
+    To use this kind of classifier your data has to be [linearly separable](https://en.wikipedia.org/wiki/Linear_separability).
+    
+        - [LogisticRegressor.BGD](https://pub.dev/documentation/ml_algo/latest/ml_algo/LogisticRegressor/LogisticRegressor.BGD.html). 
+    Implementation of the logistic regression algorithm based on batch gradient descent with L2 regularisation. 
     To use this kind of classifier your data has to be [linearly separable](https://en.wikipedia.org/wiki/Linear_separability).
 
     - [SoftmaxRegressor](https://pub.dev/documentation/ml_algo/latest/ml_algo/SoftmaxRegressor-class.html). 
@@ -64,10 +68,10 @@ it in web applications.
     - [LinearRegressor](https://pub.dev/documentation/ml_algo/latest/ml_algo/LinearRegressor-class.html). 
     A general class for finding a linear pattern in training data and predicting outcomes as real numbers.
 
-    - [LinearRegressor.lasso](https://pub.dev/documentation/ml_algo/latest/ml_algo/LinearRegressor/LinearRegressor.lasso.html)
+        - [LinearRegressor.lasso](https://pub.dev/documentation/ml_algo/latest/ml_algo/LinearRegressor/LinearRegressor.lasso.html)
     Implementation of the linear regression algorithm based on coordinate descent with lasso regularisation
 
-    - [LinearRegressor.SGD](https://pub.dev/documentation/ml_algo/latest/ml_algo/LinearRegressor/LinearRegressor.SGD.html)
+        - [LinearRegressor.SGD](https://pub.dev/documentation/ml_algo/latest/ml_algo/LinearRegressor/LinearRegressor.SGD.html)
     Implementation of the linear regression algorithm based on stochastic gradient descent with L2 regularisation
 
     - [KnnRegressor](https://pub.dev/documentation/ml_algo/latest/ml_algo/KnnRegressor-class.html)

e2e/logistic_regressor/logistic_regressor_bgd_test.dart

@@ -0,0 +1,84 @@
+import 'package:ml_algo/ml_algo.dart';
+import 'package:ml_dataframe/ml_dataframe.dart';
+import 'package:ml_linalg/vector.dart';
+import 'package:test/test.dart';
+
+Future<Vector> evaluateLogisticRegressor(MetricType metric, DType dtype) {
+  final samples = getPimaIndiansDiabetesDataFrame().shuffle(seed: 12);
+  final numberOfFolds = 5;
+  final validator = CrossValidator.kFold(
+    samples,
+    numberOfFolds: numberOfFolds,
+  );
+  final createClassifier = (DataFrame trainSamples) => LogisticRegressor.BGD(
+        trainSamples,
+        'Outcome',
+        iterationsLimit: 50,
+        initialLearningRate: 1e-4,
+        learningRateType: LearningRateType.constant,
+        dtype: dtype,
+      );
+
+  return validator.evaluate(
+    createClassifier,
+    metric,
+  );
+}
+
+Future main() async {
+  group('LogisticRegressor.BGD', () {
+    test(
+        'should return adequate score on pima indians diabetes dataset using '
+        'accuracy metric, dtype=DType.float32', () async {
+      final scores =
+          await evaluateLogisticRegressor(MetricType.accuracy, DType.float32);
+
+      expect(scores.mean(), greaterThan(0.5));
+    });
+
+    test(
+        'should return adequate score on pima indians diabetes dataset using '
+        'accuracy metric, dtype=DType.float64', () async {
+      final scores =
+          await evaluateLogisticRegressor(MetricType.accuracy, DType.float32);
+
+      expect(scores.mean(), greaterThan(0.5));
+    });
+
+    test(
+        'should return adequate score on pima indians diabetes dataset using '
+        'precision metric, dtype=DType.float32', () async {
+      final scores =
+          await evaluateLogisticRegressor(MetricType.precision, DType.float32);
+
+      expect(scores.mean(), greaterThan(0.5));
+    });
+
+    test(
+        'should return adequate score on pima indians diabetes dataset using '
+        'precision metric, dtype=DType.float64', () async {
+      final scores =
+          await evaluateLogisticRegressor(MetricType.precision, DType.float32);
+
+      expect(scores.mean(), greaterThan(0.5));
+    });
+
+    test(
+        'should return adequate score on pima indians diabetes dataset using '
+        'recall metric, dtype=DType.float32', () async {
+      final scores =
+          await evaluateLogisticRegressor(MetricType.recall, DType.float32);
+
+      expect(scores.mean(), greaterThan(0.5));
+    });
+
+    test(
+        'should return adequate score on pima indians diabetes dataset using '
+        'recall metric, dtype=DType.float64', () async {
+      final scores =
+          await evaluateLogisticRegressor(MetricType.recall, DType.float32);
+
+      expect(scores.mean(), greaterThan(0.5));
+    });
+  });
+}

lib/src/classifier/logistic_regressor/logistic_regressor.dart

@@ -188,6 +188,9 @@ abstract class LogisticRegressor
             dtype: dtype,
           );
 
+  /// Creates a [LogisticRegressor] instance based on Stochastic
+  /// Gradient Descent algorithm
+  ///
   /// Parameters:
   ///
   /// [trainingData] Observations that will be used by the classifier to learn
@@ -346,6 +349,160 @@ abstract class LogisticRegressor
             dtype: dtype,
           );
 
+  /// Creates a [LogisticRegressor] instance based on Batch Gradient Descent
+  /// algorithm
+  ///
+  /// Parameters:
+  ///
+  /// [trainingData] Observations that will be used by the classifier to learn
+  /// the coefficients. Must contain [targetName] column.
+  ///
+  /// [targetName] A string that serves as a name of the target column (a
+  /// column that contains class labels or outcomes for the associated
+  /// features).
+  ///
+  /// [learningRateType] A value defining a strategy for the learning rate
+  /// behaviour throughout the whole fitting process.
+  ///
+  /// [iterationsLimit] A number of fitting iterations. Uses as a condition of
+  /// convergence in the optimization algorithm. Default value is `100`.
+  ///
+  /// [initialLearningRate] The initial value defining velocity of the convergence of the
+  /// gradient descent optimizer. Default value is `1e-3`.
+  ///
+  /// [decay] The value meaning "speed" of learning rate decrease. Applicable only
+  /// for [LearningRateType.timeBased], [LearningRateType.stepBased], and
+  /// [LearningRateType.exponential] strategies
+  ///
+  /// [dropRate] The value that is used as a number of learning iterations after
+  /// which the learning rate will be decreased. The value is applicable only for
+  /// [LearningRateType.stepBased] learning rate; it will be omitted for other
+  /// learning rate strategies
+  ///
+  /// [minCoefficientsUpdate] A minimum distance between coefficient vectors in
+  /// two contiguous iterations. Uses as a condition of convergence in the
+  /// optimization algorithm. If a difference between the two vectors is small
+  /// enough, there is no reason to continue fitting. Default value is `1e-12`
+  ///
+  /// [probabilityThreshold] A probability on the basis of which it is decided,
+  /// whether an observation relates to positive class label (see
+  /// [positiveLabel] parameter) or to negative class label (see [negativeLabel]
+  /// parameter). The greater the probability, the more strict the classifier
+  /// is. Default value is `0.5`.
+  ///
+  /// [lambda] A coefficient of regularization. Uses to prevent the regressor's
+  /// overfitting. The more the value of [lambda], the more regular the
+  /// coefficients of the equation of the predicting hyperplane are. Extremely
+  /// large [lambda] may decrease the coefficients to nothing, otherwise too
+  /// small [lambda] may be a cause of too large absolute values of the
+  /// coefficients, that is also bad.
+  ///
+  /// [fitIntercept] Whether or not to fit intercept term. Default value is
+  /// `false`. Intercept in 2-dimensional space is a bias of the line (relative
+  /// to X-axis).
+  ///
+  /// [interceptScale] A value, defining a size of the intercept.
+  ///
+  /// [initialCoefficientsType] Defines the coefficients that will be
+  /// autogenerated at the first optimization iteration. By default
+  /// all the autogenerated coefficients are equal to zeroes. If
+  /// [initialCoefficients] are provided, the parameter will be ignored
+  ///
+  /// [initialCoefficients] Coefficients to be used in the first iteration of
+  /// optimization algorithm. [initialCoefficients] is a vector, length of which
+  /// must be equal to the number of features in [trainingData] : in case of
+  /// logistic regression only one column from [trainingData] is used as a
+  /// prediction target column, thus the number of features is equal to
+  /// the number of columns in [trainingData] minus 1 (target column). Keep in
+  /// mind, that if your model considers intercept term, [initialCoefficients]
+  /// should contain an extra element in the beginning of the vector and it
+  /// denotes the intercept term coefficient
+  ///
+  /// [positiveLabel] A value that will be used for the positive class.
+  /// By default, `1`.
+  ///
+  /// [negativeLabel] A value that will be used for the negative class.
+  /// By default, `0`.
+  ///
+  /// [collectLearningData] Whether or not to collect learning data, for
+  /// instance cost function value per each iteration. Affects performance much.
+  /// If [collectLearningData] is true, one may access [costPerIteration]
+  /// getter in order to evaluate learning process more thoroughly. Default value
+  /// is `false`
+  ///
+  /// [dtype] A data type for all the numeric values, used by the algorithm. Can
+  /// affect performance or accuracy of the computations. Default value is
+  /// [DType.float32]
+  ///
+  /// Example:
+  ///
+  /// ```dart
+  /// import 'package:ml_algo/ml_algo.dart';
+  /// import 'package:ml_dataframe/ml_dataframe.dart';
+  ///
+  /// void main() {
+  ///   final samples = getPimaIndiansDiabetesDataFrame().shuffle(seed: 12);
+  ///   final model = LogisticRegressor.BGD(
+  ///     samples,
+  ///     'Outcome',
+  ///     iterationsLimit: 50,
+  ///     initialLearningRate: 1e-4,
+  ///     learningRateType: LearningRateType.constant,
+  ///     dtype: dtype,
+  ///    );
+  /// }
+  /// ```
+  ///
+  /// Keep in mind that you need to select a proper learning rate strategy for
+  /// every particular model. For more details, refer to [LearningRateType],
+  /// also consider [decay] and [dropRate] parameters.
+  factory LogisticRegressor.BGD(
+    DataFrame trainingData,
+    String targetName, {
+    required LearningRateType learningRateType,
+    int iterationsLimit = iterationLimitDefaultValue,
+    double initialLearningRate = initialLearningRateDefaultValue,
+    double decay = decayDefaultValue,
+    int dropRate = dropRateDefaultValue,
+    double minCoefficientsUpdate = minCoefficientsUpdateDefaultValue,
+    double probabilityThreshold = probabilityThresholdDefaultValue,
+    double lambda = lambdaDefaultValue,
+    bool fitIntercept = fitInterceptDefaultValue,
+    double interceptScale = interceptScaleDefaultValue,
+    InitialCoefficientsType initialCoefficientsType =
+        initialCoefficientsTypeDefaultValue,
+    num positiveLabel = positiveLabelDefaultValue,
+    num negativeLabel = negativeLabelDefaultValue,
+    bool collectLearningData = collectLearningDataDefaultValue,
+    DType dtype = dTypeDefaultValue,
+    Vector? initialCoefficients,
+  }) =>
+      initLogisticRegressorModule().get<LogisticRegressorFactory>().create(
+            trainData: trainingData,
+            targetName: targetName,
+            optimizerType: LinearOptimizerType.gradient,
+            iterationsLimit: iterationsLimit,
+            initialLearningRate: initialLearningRate,
+            decay: decay,
+            dropRate: dropRate,
+            minCoefficientsUpdate: minCoefficientsUpdate,
+            probabilityThreshold: probabilityThreshold,
+            lambda: lambda,
+            regularizationType: RegularizationType.L2,
+            batchSize: trainingData.shape.first,
+            fitIntercept: fitIntercept,
+            interceptScale: interceptScale,
+            isFittingDataNormalized: false,
+            learningRateType: learningRateType,
+            initialCoefficientsType: initialCoefficientsType,
+            initialCoefficients:
+                initialCoefficients ?? Vector.empty(dtype: dtype),
+            positiveLabel: positiveLabel,
+            negativeLabel: negativeLabel,
+            collectLearningData: collectLearningData,
+            dtype: dtype,
+          );
+
   /// Restores previously fitted classifier instance from the [json]
   ///
   /// ````dart

pubspec.yaml

@@ -1,6 +1,6 @@
 name: ml_algo
 description: Machine learning algorithms, Machine learning models performance evaluation functionality
-version: 16.14.0
+version: 16.15.0
 homepage: https://github.com/gyrdym/ml_algo
 
 environment: