Contributing to dtaianomaly

The goal of dtaianomaly is to be community-driven. All types of contributions are welcome. This includes code, but also bug reports, improvements to the documentation, additional tests and more. Below we give an overview of how to contribute to dtaianomaly.

Reporting issues

We use GitHub Issues to track bugs and feature requests. Feel free to open a new issue if you found a bug or wish to see a new feature in dtaianomaly. Please verify that the issue is not already addressed by another issue or pull request before submitting a new issue.

Resolving issues

Alternatively, you can also resolve an open issue. Below, we describe the required steps for this.

Find your contribution

The first step is to find an issue you wish to resolve on GitHub Issues. These are feature requests, bug reports, or anything else that can improve dtaianomaly. If you find an issue that seems interesting to you, you can click on it to see its current status. You can then either join the ongoing discussion on this issue, or start the discussion if you only see the initial issue. In this case, you can leave a message with your proposed solution. We will analyze your solution and review alternative solutions together with you, to find the best way to fix the issue. Once we decided on the best fix, the issue will be assigned to you, after which you will be able to implement your solution.

Checklist

Find an issue you wish to work on.

Join the discussion with your proposed solution.

Create a fork

To start working on your issue, you need to create a fork of dtaianomaly, on which you can work to resolve the issue.

Next, you have to clone your fork to your own machine, as follows:

git clone https://github.com/<link-to-your-fork>

Next, you should create a new branch in your fork. You can find more information about git branches on this webpage. In the end, you will merge this branch into dtaianomaly such that everyone can benefit from your contribution. You can create a branch with the following command:

git checkout -b <branch-name>

Here you should replace <branch-name> by something descriptive to make clear what you are working on. For example, if you are implementing a new anomaly detector MyAmazingAnomalyDetector, you can name your branch implement_my_amazing_anomaly_detector.

Checklist

Create a fork of dtaianomaly on your own account.

Clone the fork to your local machine.

Create a branch for you to work on.

Setup the environment

Next, you can set up your environment to start working on the issue. For this, we highly recommend to virtual environment to isolate the dependencies. To install the dependencies of dtaianomaly, including all optional dependencies, navigate to the directory where you downloaded the code and run the following command:

pip install --editable .[all]

You should include the --editable flag to ensure that your changes to the code are actually reflected in the installed version.

Next, make sure to install pre-commit to the project, using the following command:

pre-commit install

To check if the environment is correct, you verify if all tests succeed by running the following command (which also checks the coverage of the unit tests):

pytest .\tests\ --cov=dtaianomaly --cov-report term-missing

In addition, you should also check if the documentation generates without any errors or warnings. This can be done as follows:

docs/make html
docs/make doctest

Checklist

Install the dependencies in requirements.txt.

Install the dependencies in requirements-dev.txt.

Check if all tests run successfully.

Check if the documentation generates successfully.

Resolve the issue

Once everything has been set up, it is time to resolve the issue. This can include writing code, fixing bugs, writing documentation, … depending on the issue you selected.

If this is your first contribution, also make sure you added your name to CONTRIBUTORS.

Be sure to go through the checklist below if your issue involves implementing a new BaseDetector, LazyDataLoader, Preprocessor, Thresholding, or Metric.

Once you have resolved the issue, you commit the changes to your remote fork via:

git add .
git commit -m <commit-message>
git push

Checklist

Add the resolution to the issue.

Add your update to the changelog

Check if all tests still run successfully.

Check if the documentation still generates successfully.

Commit your changes to your fork.

Synchronize your fork

Since you started working on the issue, it is likely that new changes have been added to dtaianomaly. Some of these changes might conflict with your resolution of the issue. Therefore, it is necessary to first sync your fork with dtaianomaly and pull all the changes in your personal branch. If this does not lead to merge conflicts: great! Otherwise, you will have to fix the conflicts and make sure the unit tests still successfully run.

Checklist

Synchronize your project with dtaianomaly

Fix the merge conflicts, if there are any.

Check if the documentation still generates successfully.

Commit your changes to your fork.

Create a pull request

Now that you have resolved the issue and made sure your fork is up to date with dtaianomaly, you can create a pull request! For this, you can go to the GitHub page of your fork, on which there should be a button to automatically create a pull request. Otherwise, you will have to manually create a pull request.

Make sure to add a descriptive title to your pull request. Also add a description of the issue you tackled and how exactly you solved it. Also add a reference to the issue you solved in the body of the pull request.

Creating a pull request will automatically run various checks, such as running the unit tests, doctests, and checking if certain notebooks remain executable. These checks must succeed before a pull request can be accepted.

Checklist

Create a pull request.

Add an informative description to the pull request.

Add the issue number to the pull request.

Work on your pull request

We will likely have some questions, suggestions or comments on your solution. This is our opportunity to collaborate and further improve the resolution. If we see a further improvement to your solution, you can simply continue working on the same branch you have been working on.

Checklist

Engage in the discussion on your pull request.

Add the suggestions given in the documentation.

Merge!

Once your contribution has been finalized and polished, we will merge your pull request into dtaianomaly! Thanks for your contribution!

Checklist

Celebrate your successful addition to dtaianomaly!

Checklist for implementing new components

It is highly recommended to follow below checklist if you are implementing a new BaseDetector, LazyDataLoader, Preprocessor, Thresholding, or Metric. This ensures a flawless integration of the new component into dtaianomaly.

BaseDetector

Implement the anomaly detector

Have you added a .py in dtaianomaly/anomaly_detection named identical to the anomaly detector?

Does the file contain a class named as the anomaly detector, which inherits BaseDetector?

Does the constructor call super().__init__(Supervision) with the correct supervision type?

Are all hyperparameters checked to be of the correct type and belong to the domain?

Are all hyperparameters set as an attribute of the object (necessary for __str__() method)?

Have you implemented the fit() method?

Have you implemented the decision_function() method?

Did you add the anomaly detector in __all__ of the dtaianomaly/anomaly_detection/__init__.py file?

Can you load the anomaly detector via interpret_config() (specifically, in the detector_entry() function)?

Test the anomaly detector

Have you added a new file test_<class>.py in under tests/anomaly_detection?

Is a test coverage of at least 95% reached?

Have you included the anomaly detector in the tests in tests/anomaly_detection/test_detectors.py?

Have you tested loading the new anomaly detector in tests/workflow/test_workflow_from_config.py?

Document the anomaly detector

Have you added class documentation to your implementation?

Does the class documentation contain an explanation of the anomaly detector?

Are all hyperparameters and attributes discussed in the class documentation, including their meaning, type and default values?

Does the class documentation contain a code-example?

Has a reference to the relevant paper(s) been added in the class documentation?

Is a separate file for the anomaly detector created in docs/api/anomaly_detection_algorithms/ with the same name as the anomaly detector?

LazyDataLoader

Implement the data loader

Have you added a .py in dtaianomaly/data named identical to the data loader?

Does the file contain a class named as the data loader, which inherits LazyDataLoader?

Are all hyperparameters checked to be of the correct type and belong to the domain?

Are all hyperparameters set as an attribute of the object (necessary for __str__() method)?

Have you implemented the _load() method?

Did you add the data loader in __all__ of the dtaianomaly/data/__init__.py file?

Can you load the data loader via interpret_config() (specifically, in the data_entry() function)?

Test the data loader

Have you added a new file test_<class>.py in under tests/data?

Is a test coverage of at least 95% reached?

Have you tested loading the new data loader in tests/workflow/test_workflow_from_config.py?

Document the data loader

Have you added class documentation to your implementation?

Does the class documentation contain an explanation of expected format of the data?

Are all hyperparameters and attributes discussed in the class documentation, including their meaning, type and default values?

Has a reference to the relevant paper(s) been added in the class documentation?

Have you added the data loader to docs/api/data.rst?

Did you update data/README.rst?

Preprocessor

Implement the preprocessor

Have you added a .py in dtaianomaly/preprocessing named identical to the preprocessor?

Does the file contain a class named as the preprocessor, which inherits Preprocessor?

Are all hyperparameters checked to be of the correct type and belong to the domain?

Are all hyperparameters set as an attribute of the object (necessary for __str__() method)?

Have you implemented the _fit() method?

Have you implemented the _transform() method?

Did you add the preprocessor in __all__ of the dtaianomaly/preprocessing/__init__.py file?

Can you load the preprocessor via interpret_config() (specifically, in the preprocessor_entry() function)?

Test the preprocessor

Have you added a new file test_<class>.py in under tests/preprocessing?

Is a test coverage of at least 95% reached?

Has the preprocessor been included in the tests in tests/preprocessing/test_preprocessors.py?

Have you tested loading the new preprocessor in tests/workflow/test_workflow_from_config.py?

Document the preprocessor

Have you added class documentation to your implementation?

Does the class documentation contain an explanation of the preprocessor?

Are all hyperparameters and attributes discussed in the class documentation, including their meaning, type and default values?

Has a reference to the relevant paper(s) been added in the class documentation?

Have you added the preprocessor to docs/api/preprocessing.rst?

Thresholding

Implement the thresholder

Have you added a .py in dtaianomaly/thresholding named identical to the thresholder?

Does the file contain a class named as the thresholder, which inherits Thresholder?

Are all hyperparameters checked to be of the correct type and belong to the domain?

Are all hyperparameters set as an attribute of the object (necessary for __str__() method)?

Have you implemented the threshold() method?

Did you add the thresholder in __all__ of the dtaianomaly/thresholding/__init__.py file?

Can you load the thresholder via interpret_config() (specifically, in the threshold_entry()` function)?

Test the thresholder

Have you added a new file test_<class>.py in under tests/thresholding?

Is a test coverage of at least 95% reached?

Have you tested loading the new thresholder in tests/workflow/test_workflow_from_config.py?

Document the thresholder

Have you added class documentation to your implementation?

Does the class documentation contain an explanation of the thresholder?

Are all hyperparameters and attributes discussed in the class documentation, including their meaning, type and default values?

Has a reference to the relevant paper(s) been added in the class documentation?

Have you added the thresholder to docs/api/thresholding.rst?

Evaluation Metric

Implement the evaluation metric

Have you added a .py in dtaianomaly/evaluation named identical to the evaluation metric?

Does the file contain a class named as the evaluation metric, which inherits BinaryMetric or ProbaMetric, depending on if the metric accepts binary anomaly labels or continuous anomaly probabilities?

Are all hyperparameters checked to be of the correct type and belong to the domain?

Are all hyperparameters set as an attribute of the object (necessary for __str__() method)?

Have you implemented the _compute() method?

Did you add the metric in __all__ of the dtaianomaly/evaluation/__init__.py file?

Can you load the metric via interpret_config() (specifically, in the metric_entry()` function)?

Test the evaluation metric

Have you added a new file test_<class>.py in under tests/evaluation?

Is a test coverage of at least 95% reached?

Has the evaluation metric been included in the tests in tests/evaluation/test_metrics.py?

Have you tested loading the new evaluation metric in tests/workflow/test_workflow_from_config.py?

Document the evaluation metric

Have you added class documentation to your implementation?

Does the class documentation contain an explanation of the evaluation metric?

Are all hyperparameters and attributes discussed in the class documentation, including their meaning, type and default values?

Has a reference to the relevant paper(s) been added in the class documentation?

Have you added the evaluation metric to docs/api/evaluation.rst?