FAQ#

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.

  • Anomaly detectors go in src/capymoa/anomaly.

  • 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:

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:

from capymoa.classifier import MyNewLearner

What does a learner implement?#

A learner should implement the appropriate interface:

If your method is a wrapper around a MOA learner, you should use the appropriate base class:

How do I test my new learner?#

You should add a test to ensure your learner achieves and continues to achieve the expected performance in future versions. CapyMOA provides parameterised 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_ssl_classifiers.py for semi-supervised classifiers.

  • tests/ocl/test_learners.py for online continual learning learners.

  • tests/test_regressors.py for regressors.

  • tests/test_anomaly.py for anomaly detectors.

To run your tests, use the following command:

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 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 documentation guide for more information and an example.

How do I fix failing automated checks?#

When a pull request is opened, automated checks are triggered to prevent breaking changes and maintain code quality. These checks are configured in the .github/workflows/pr.yml file using GitHub Actions. The workflow runs tests, linters, and documentation builds automatically.

If a check fails, review the error messages and try to reproduce the issue locally. If you need help, ask in the pull request or join the Discord server.

Automated Checks:

  • Tests:

    • PyTest (invoke test.pytest): Runs all unit tests in the /tests directory. See the PyTest guide.

    • Doctest (invoke test.doctest): Runs documentation tests. See the doctest guide.

    • Notebooks (invoke test.nb): Executes all notebooks in /notebooks to ensure they run without errors. See the notebook guide.

  • Code Style:

    • Formatting (invoke fmt): Checks code formatting and style.

  • Documentation:

    • Build (invoke docs.build): Verifies that the documentation builds successfully. See the documentation guide.

How do I format my code?#

invoke fmt will format and check your code using ruff. Ruff is installed as part of the development dependencies. Formatting helps make diff reviews easier and keeps the codebase consistent.

How do I write a commit message?#

Don’t worry about this too much as reviewers will squash and merge your PR with a meaningful commit message using the conventional commit style. We use this style to automate versioning and changelog generation.