Merge branch 'main' of https://github.com/hmgomes/CapyMOA into main

adaptive-machine-learning · Apr 18, 2024 · 841c225 · 841c225
2 parents eb36e60 + 205b23c
commit 841c225
Show file tree

Hide file tree

Showing 70 changed files with 3,484 additions and 4,430 deletions.
diff --git a/README.md b/README.md
@@ -2,9 +2,10 @@
 Python wrapper for MOA to allow efficient use of existing algorithms with a more modern API
 
 > [!IMPORTANT]
-> * **[How to Install CapyMOA](docs/installation.md)**
-> * **[How to Contribute Tests](docs/testing.md)**
-> * **[How to Contribute Documentation](docs/README.md)**
+> * **[How to install CapyMOA](docs/installation.md)**
+> * **[How to add documentation](docs/contributing/docs.md)**
+> * **[How to add tests](docs/contributing/tests.md)**
+> * **[How to add new algorithms or methods](docs/contributing/learners.md)**
 
 
 # Functionality

diff --git a/docs/api/classifiers.rst b/docs/api/classifiers.rst
@@ -1,9 +1,8 @@
 Classifiers
 ===========
-Classifiers implement the :class:`capymoa.learner.learners.Classifier` interface.
+Classifiers implement the :class:`capymoa.base.Classifier` interface.
 
-.. automodule:: capymoa.learner.classifier
+.. automodule:: capymoa.classifier
     :members:
     :undoc-members:
     :show-inheritance:
-    :inherited-members:
diff --git a/docs/api/datasets.rst b/docs/api/datasets.rst
@@ -8,3 +8,9 @@ and used being downloaded the first time you use them.
     :undoc-members:
     :show-inheritance:
     :inherited-members:
+
+.. automodule:: capymoa.datasets.downloader
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :inherited-members:
diff --git a/docs/api/api.rst → docs/api/index.rst b/docs/api/api.rst → docs/api/index.rst
@@ -16,12 +16,18 @@ with the :ref:`tutorials<tutorials>`.
     datasets
     instance
 
+..  toctree::
+    :maxdepth: 1
+    :caption: Interfaces
+
+    learner
+    moa_learner
+
 ..  toctree::
     :maxdepth: 1
     :caption: Learners
 
     regressor
-    learners
     ssl
     classifiers
 
@@ -30,3 +36,10 @@ with the :ref:`tutorials<tutorials>`.
     :caption: Evaluation
 
     evaluation
+
+
+..  toctree::
+    :maxdepth: 1
+    :caption: Other
+
+    splitcriteria
diff --git a/docs/api/instance.rst b/docs/api/instance.rst
@@ -2,7 +2,7 @@ Instance
 ========
 Instances are the basic unit of data in CapyMOA.
 
-..  automodule:: capymoa.stream.instance
+..  automodule:: capymoa.instance
     :members:
     :undoc-members:
     :show-inheritance:

diff --git a/docs/api/learners.rst → docs/api/learner.rst b/docs/api/learners.rst → docs/api/learner.rst
@@ -3,17 +3,17 @@ Learners
 CapyMOA defines different interfaces for learners performing different machine
 learning tasks.
 
-..  autoclass:: capymoa.learner.learners.Classifier
+..  autoclass:: capymoa.base.Classifier
     :members:
     :undoc-members:
     :inherited-members:
 
-..  autoclass:: capymoa.learner.learners.Regressor
+..  autoclass:: capymoa.base.Regressor
     :members:
     :undoc-members:
     :inherited-members:
 
-.. autoclass:: capymoa.learner.learners.ClassifierSSL
+.. autoclass:: capymoa.base.ClassifierSSL
     :members:
     :undoc-members:
     :inherited-members:
diff --git a/docs/api/moa_learner.rst b/docs/api/moa_learner.rst
@@ -0,0 +1,14 @@
+MOA Learners
+============
+Interfaces for objects that wrap MOA functionality.
+
+..  autoclass:: capymoa.base.MOAClassifier
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+..  autoclass:: capymoa.base.MOARegressor
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
diff --git a/docs/api/regressor.rst b/docs/api/regressor.rst
@@ -1,10 +1,9 @@
 Regressors
 ==========
-Regressors implement the :class:`capymoa.learner.learners.Regressor` interface.
+Regressors implement the :class:`capymoa.base.Regressor` interface.
 
-.. automodule:: capymoa.learner.regressor
+.. automodule:: capymoa.regressor
     :members:
     :undoc-members:
     :show-inheritance:
-    :inherited-members:
 
diff --git a/docs/api/splitcriteria.rst b/docs/api/splitcriteria.rst
@@ -0,0 +1,10 @@
+Split Criterions
+================
+Decision trees are built by splitting the data into groups based on a split
+criterion. The split criterion is a function that measures the quality of a
+split.
+
+..  automodule:: capymoa.splitcriteria
+    :members:
+    :undoc-members:
+    :inherited-members:
diff --git a/docs/api/ssl.rst b/docs/api/ssl.rst
@@ -1,8 +1,8 @@
-Semi-Supervised Classifiers
-===========================
-Semi-Supervised classifiers implement the :class:`capymoa.learner.learners.ClassifierSSL` interface.
+Semi-Supervised Learners (SSL)
+==============================
+Semi-Supervised classifiers implement the :class:`capymoa.base.ClassifierSSL` interface.
 
-.. automodule:: capymoa.learner.ssl.classifier
+.. automodule:: capymoa.ssl.classifier
     :members:
     :undoc-members:
     :show-inheritance:

diff --git a/docs/conf.py b/docs/conf.py
@@ -25,6 +25,18 @@
     "myst_parser",
 ]
 
+nitpick_ignore_regex = [
+    ('py:class', r'sklearn\..*'),
+    ('py:class', r'numpy\..*'),
+    ('py:class', r'pathlib\..*'),
+    ('py:class', r'abc\..*'),
+    ('py:class', r'moa\..*'),
+    ('py:class', r'com\..*'),
+    ('py:class', r'java\..*'),
+    ('py:class', r'org\..*'),
+    ('py:class', r'torch\..*'),
+
+]
 bibtex_bibfiles = ['references.bib']
 
 autoclass_content = 'class'
@@ -45,11 +57,13 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "sphinx_book_theme"
+html_theme = "pydata_sphinx_theme"
 html_static_path = ['_static']
 
 # Setup symbolic links for notebooks
 
+python_maximum_signature_line_length = 88
+
 notebooks = Path("../notebooks")
 notebook_doc_source = Path("notebooks")
 if not notebook_doc_source.exists():

diff --git a/docs/README.md → docs/contributing/docs.md b/docs/README.md → docs/contributing/docs.md
diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst
@@ -0,0 +1,10 @@
+Contributing
+============
+This part of the documentation is for developers and contributors.
+
+.. toctree::
+   :maxdepth: 2
+
+   learners
+   tests
+   docs
diff --git a/docs/contributing/learners.md b/docs/contributing/learners.md
@@ -0,0 +1,76 @@
+# Adding Learners
+This document describes adding a new classifier, regressor, or 
+another learner to CapyMOA. Before doing this, you should have read the
+[installation guide](../installation.md) to set up your development environment.
+
+## Where does my new learner go?
+You should add your new learner to the appropriate directory:
+- Classifiers go in `src/capymoa/classifier`.
+- Regressors go in `src/capymoa/regressor`.
+- Semi-supervised classifiers go in `src/capymoa/ssl/classifier`.
+
+Each standalone learner should be in its own file, prefixed with `_` to indicate that they are not meant to be imported directly. Instead, they are imported by an `__init__.py` file. The `__init__.py` file is a special file that tells Python to treat the directory as a package.
+
+For example, to add a new classifier class called `MyNewLearner`, you should implement it in `src/capymoa/classifier/_my_new_learner.py` and add it to the `src/capymoa/classifier/__init__.py` file. The `__init__.py` will look like this:
+```python
+from ._my_new_learner import MyNewLearner
+...
+__all__ = [
+    'MyNewLearner',
+    ...
+]
+```
+
+The prefix and init files allow users to import all classifiers, regressors, 
+or semi-supervised from one package while splitting the code into multiple files. You can, for example, import your new learner with the following:
+```python
+from capymoa.classifier import MyNewLearner
+```
+
+## What does a learner implement?
+<!-- TODO: Link to capymoa documentation -->
+A learner should implement the appropriate interface:
+* `capymoa.base.Classifier` for classifiers.
+* `capymoa.base.Regressor` for regressors.
+* `capymoa.base.ClassifierSSL` for semi-supervised classifiers.
+
+If your method is a wrapper around a MOA learner, you should use the appropriate
+base class:
+* `capymoa.base.MOAClassifier` for classifiers.
+* `capymoa.base.MOARegressor` for regressors.
+
+## How do I test my new learner?
+You should add a test to ensure your learner achieves and continues to achieves
+the expected performance in future versions. CapyMOA provides parametrized
+tests for classifiers, regressors, and semi-supervised classifiers. You should
+not need to write any new test code. Instead, you should add your test's
+parameters to the appropriate test file:
+- `tests/test_classifiers.py` for classifiers.
+- `tests/test_regressors.py` for regressors.
+- `tests/test_ssl_classifiers.py` for semi-supervised classifiers.
+
+To run your tests, use the following command:
+```bash
+python -m pytest -k MyNewLearner
+```
+The `-k MyNewLearner` flag tells PyTest to run tests containing `MyNewLearner` in the test ID.
+
+* If you want to add documented exemplar usage of your learner, you can add doctests.
+See the [testing guide](tests.md) for more information.
+
+* If you need custom test code for your learner, you can add a new test file in
+`tests`.
+
+## How do I document my new learner?
+You should add a docstring to your learner that describes the learner and its
+parameters. The docstring should be in the Sphinx format. Check the 
+[documenation guide](docs.md) for more information and an example.
+
+## How to debug failed GitHub Actions?
+Before submitting your pull request, you may wish to run all tests to
+ensure your changes will succeed in GitHub Actions. You can run all tests with:
+```bash
+invoke test
+```
+If you run into issues with GitHub actions failing to build documentation. Follow
+the instructions in the [documentation guide](docs.md) to build the documentation locally. The documentation build settings are intentionally strict to ensure the documentation builds correctly.
diff --git a/docs/testing.md → docs/contributing/tests.md b/docs/testing.md → docs/contributing/tests.md
@@ -1,6 +1,6 @@
 # Adding Tests
 Ensure you have installed the development dependencies by following the instructions
-in the [installation guide](installation.md). To run all tests, use the following command:
+in the [installation guide](../installation.md). To run all tests, use the following command:
 ```bash
 invoke test
 ```

diff --git a/docs/index.rst b/docs/index.rst
@@ -33,18 +33,16 @@ and modules.
 .. toctree::
    :maxdepth: 2
 
-   api/api
+   api/index
 
 Contributing
 ------------
 This part of the documentation is for developers and contributors.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contributing
 
-   testing
-   README
+   contributing/index
 
 Indices and tables
 ==================

diff --git a/invoke.yml b/invoke.yml
@@ -5,8 +5,14 @@ moa_url: "https://homepages.ecs.vuw.ac.nz/~antonlee/capymoa/versions/240412_moa.
 
 # What notebooks to skip when running them as tests.
 test_skip_notebooks:
-  - notebooks/04_drift_streams.ipynb
-  - notebooks/02_learners_api_examples.ipynb
-  - notebooks/Basic_Classification_Examples.ipynb
   - notebooks/00_getting_started.ipynb
+  - notebooks/01_evaluation_and_data_reading.ipynb
+  - notebooks/02_learners_api_examples.ipynb
   - notebooks/03_using_sklearn_pytorch.ipynb
+  - notebooks/04_drift_streams.ipynb
+  - notebooks/Basic_Classification_Examples.ipynb
+  - notebooks/Creating_new_classifier.ipynb
+  - notebooks/Data_Reading.ipynb
+  - notebooks/Preprocessing.ipynb
+  - notebooks/SSL_example.ipynb
+