Merge pull request #8 from RubixML/0.4.0-beta

0.4.0 beta

Author: andrewdalpino

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         with:
           php-version: ${{ matrix.php-versions }}
           tools: pecl
-          extensions: bz2, fileinfo
+          extensions: fileinfo
           ini-values: memory_limit=-1    
 
       - name: Validate composer.json

.gitignore

@@ -4,6 +4,7 @@ composer.lock
 .php_cs.cache
 Thumbs.db
 .DS_Store
+debug.log
 /.idea
 /.vscode
 /.vs

CHANGELOG.md

@@ -1,6 +1,10 @@
+- 0.4.0-beta
+    - Added RBXE serializer
+    - Removed Bzip2 serailizer
+
 - 0.3.0-beta
     - Added Vantage Point Tree for spatial queries
-    - Added Bzip2 serializers
+    - Added Bzip2 serializer
     - Added Levenshtein distance kernel
     - Move K Best Selector to main repository
     - Added custom exceptions from the main repo

README.md

@@ -1,5 +1,5 @@
 # Rubix ML Extras
-Experimental features for the Rubix ML library. The code here can see major changes or even removal. If/when features reach 1- sufficient maturity/stability and 2- sufficient community interest, they will be moved to the main package.
+Experimental features for the Rubix ML library. The code here is in permanent beta and may be moved or removed in future releases.
 
 ## Installation
 Install into your project using [Composer](https://getcomposer.org/):
@@ -10,8 +10,5 @@ $ composer require rubix/extras
 ### Requirements
 - [PHP](https://php.net/manual/en/install.php) 7.2 or above
 
-##### Optional
-- [Bzip2 extension](https://www.php.net/manual/en/book.bzip2.php) for Bzip2 compression
-
 ## License
 The code is licensed [MIT](LICENSE) and the documentation is licensed [CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/).

benchmarks/Persisters/Serializers/RBXEBench.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Rubix\ML\Benchmarks\Persisters\Serializers;
+
+use Rubix\ML\Datasets\Generators\Blob;
+use Rubix\ML\Classifiers\KNearestNeighbors;
+use Rubix\ML\Datasets\Generators\Agglomerate;
+use Rubix\ML\Persisters\Serializers\RBXE;
+
+/**
+ * @Groups({"Serializers"})
+ * @BeforeMethods({"setUp"})
+ */
+class RBXEBench
+{
+    protected const TRAINING_SIZE = 2500;
+
+    /**
+     * @var \Rubix\ML\Persisters\Serializers\RBXE
+     */
+    protected $serializer;
+
+    /**
+     * @var \Rubix\ML\Persistable
+     */
+    protected $persistable;
+
+    public function setUp() : void
+    {
+        $generator = new Agglomerate([
+            'Iris-setosa' => new Blob([5.0, 3.42, 1.46, 0.24], [0.35, 0.38, 0.17, 0.1]),
+            'Iris-versicolor' => new Blob([5.94, 2.77, 4.26, 1.33], [0.51, 0.31, 0.47, 0.2]),
+            'Iris-virginica' => new Blob([6.59, 2.97, 5.55, 2.03], [0.63, 0.32, 0.55, 0.27]),
+        ]);
+
+        $training = $generator->generate(self::TRAINING_SIZE);
+
+        $estimator = new KNearestNeighbors(5, true);
+
+        $estimator->train($training);
+
+        $this->persistable = $estimator;
+
+        $this->serializer = new RBXE('secret');
+    }
+
+    /**
+     * @Subject
+     * @revs(10)
+     * @Iterations(5)
+     * @OutputTimeUnit("milliseconds", precision=3)
+     */
+    public function serializeUnserialize() : void
+    {
+        $encoding = $this->serializer->serialize($this->persistable);
+
+        $persistable = $this->serializer->unserialize($encoding);
+    }
+}

composer.json

@@ -22,13 +22,13 @@
     ],
     "require": {
         "php": ">=7.2",
-        "rubix/ml": "0.3.0",
-        "rubix/tensor": "^2.0.4",
+        "rubix/ml": "^0.4.0",
+        "rubix/tensor": "^2.2",
         "wamania/php-stemmer": "^2.0"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "2.18.*",
-        "phpbench/phpbench": "1.0.0-alpha4",
+        "phpbench/phpbench": "1.0.0-alpha6",
         "phpstan/extension-installer": "^1.0",
         "phpstan/phpstan": "0.12.*",
         "phpstan/phpstan-phpunit": "0.12.*",

docs/model-orchestra.md

@@ -0,0 +1,49 @@
+<span style="float:right;"><a href="https://github.com/RubixML/Extras/blob/master/src/CommitteeMachine.php">[source]</a></span>
+
+# Committee Machine
+A voting ensemble that aggregates the predictions of a committee of heterogeneous learners (referred to as *experts*). The committee employs a user-specified influence scheme to weight the final predictions.
+
+> **Note:** Influence values can be on any arbitrary scale as they are automatically normalized upon instantiation.
+
+**Interfaces:** [Estimator](estimator.md), [Learner](learner.md), [Parallel](parallel.md), [Verbose](verbose.md), [Persistable](persistable.md)
+
+**Data Type Compatibility:** Depends on the base learners
+
+## Parameters
+| # | Param | Default | Type | Description |
+|---|---|---|---|---|
+| 1 | experts | | array | An array of learner instances that will comprise the committee. |
+| 2 | influences | null | array | The influence values for each expert in the committee. If null, each expert will be weighted equally. |
+
+## Example
+```php
+use Rubix\ML\CommitteeMachine;
+use Rubix\ML\Classifiers\GaussianNB;
+use Rubix\ML\Classifiers\RandomForest;
+use Rubix\ML\Classifiers\ClassificationTree;
+use Rubix\ML\Classifiers\KDNeighbors;
+use Rubix\ML\Classifiers\SoftmaxClassifier;
+
+$estimator = new CommitteeMachine([
+    new GaussianNB(),
+    new RandomForest(new ClassificationTree(4), 100, 0.3),
+    new KDNeighbors(3),
+    new SoftmaxClassifier(100),
+], [
+    0.2, 0.4, 0.3, 0.1,
+]);
+```
+
+## Additional Methods
+Return the learner instances of the committee:
+```php
+public experts() : array
+```
+
+Return the normalized influence scores of each expert in the committee:
+```php
+public influences() : array
+```
+
+### References
+>- [1] H. Drucker. (1997). Fast Committee Machines for Regression and Classification.

docs/persisters/Serializers/bzip2.md

@@ -0,0 +1,23 @@
+<span style="float:right;"><a href="https://github.com/RubixML/Extras/blob/master/src/Persisters/Serializers/RBXE.php">[source]</a></span>
+
+# RBX Encrypted
+Encrypted Rubix Object File format (RBXE) is a format to securely store and share serialized PHP objects. In addition to ensuring data integrity like RBX format, RBXE also adds layers of security such as tamper protection and data encryption while being resilient to brute-force and evasive to timing attacks.
+
+!!! note
+    Requires the PHP [Open SSL extension](https://www.php.net/manual/en/book.openssl.php) to be installed.
+
+## Parameters
+| # | Param | Default | Type | Description |
+|---|---|---|---|---|
+| 1 | password | '' | string | The password used to sign and encrypt the data. |
+
+## Example
+```php
+use Rubix\ML\Persisters\Serializers\RBXE;
+
+$serializer = new RBXE('secret');
+```
+
+### References
+[^1]: H. Krawczyk et al. (1997). HMAC: Keyed-Hashing for Message Authentication.
+[^2]: M. Bellare et al. (2007). Authenticated Encryption: Relations among notions and analysis of the generic composition paradigm.

docs/persisters/Serializers/rbxe.md

@@ -15,6 +15,7 @@
 use Rubix\ML\Backends\Tasks\TrainLearner;
 use Rubix\ML\Other\Traits\Multiprocessing;
 use Rubix\ML\Classifiers\SoftmaxClassifier;
+use Rubix\ML\Other\Traits\AutotrackRevisions;
 use Rubix\ML\Specifications\DatasetIsNotEmpty;
 use Rubix\ML\Specifications\SpecificationChain;
 use Rubix\ML\Specifications\SamplesAreCompatibleWithEstimator;
@@ -36,7 +37,7 @@
  */
 class ModelOrchestra implements Learner, Parallel, Persistable, Verbose
 {
-    use Multiprocessing, PredictsSingle, LoggerAware;
+    use AutotrackRevisions, Multiprocessing, PredictsSingle, LoggerAware;
 
     /**
      * The members of the orchestra.