Contributing

zea is an open-source project and we welcome contributions from the ultrasound community. Whether you want to report a bug, suggest a new feature, or contribute code, your input is valuable. This document outlines how you can contribute to the project.

How to contribute

First, take some time to read through this whole guide. Then follow the following steps to contribute:

1. Make an issue

Take a look at the current issues on GitHub to see if there are any open issues that you can help with. If your issue is not listed, please create a new issue describing the motivation behind the problem or feature you want to work on. That way we can discuss it and make sure that your contribution is aligned with the project’s goals.

Example Issue Template

**Title:** [Bug/Feature/Question]: Brief summary

**Description:**
- For problems or bugs
    - What is the problem?
    - Steps to reproduce
    - Expected behavior
    - Actual behavior
- For feature requests
    - What is the feature and why is it needed?
    - Possible interface or implementation details
- References (if applicable)
  - Link to relevant documentation, discussions, or related issues.

2. Fork the repository

Most contributors will not have write access to the main repository. Instead, you will need to fork the repository to your own GitHub account. You can fork the repository on GitHub by clicking the “Fork” button at the top right of the page. This will create a copy of the repository under your GitHub account. One can also use:

gh repo fork tue-bmd/zea --clone

3. Setup environment

Check out a new branch for your changes.

cd zea
git checkout -b <your_feature_branch_name>

Set up your development environment. We recommend using Docker as described in the Installation guide. This ensures consistency and avoids dependency issues. If you prefer to work without Docker, you can set up a local environment using conda or pip. For example, to set up a conda environment, you can run:

conda create -n zea python=3.12
conda activate zea
conda install pip
pip install -e .[dev]
pre-commit install

Now install the backend(s). If you use the Docker image, the backends are already installed. If you use a local environment, you need to install one of the supported machine learning backends: JAX, PyTorch or TensorFlow. For more information on how to install the backends, see the backend installation.` guide.

4. Make your changes

In general, we recommend a test-driven development approach:

1. Write a test for the functionality you want to add.

2. Write the code to make the test pass.

You can run tests for your installed environment using pytest:

pytest

A few things to keep in mind when making changes:

• Make sure to write backend-agnostic code. This means that your code should work with all supported backends. This can be achieved by using the keras.ops API (see the Keras ops documentation), instead of using backend-specific functions. For example, use keras.ops.squeeze instead of jax.numpy.squeeze or torch.squeeze. Also, when converting tensors to numpy arrays, use the keras.ops.convert_to_numpy function (instead of my_tensor.numpy()) to ensure compatibility with all backends.

• The code is autoformatted using ruff. You can run the pre-commit hooks to automatically format and check your code using:

pre-commit run --all-files

5. Document your changes

The documentation uses Sphinx and generally is written in reStructuredText format. You can find the documentation files in the docs/source directory. Docstrings are written in Google style, which you can see examples of in the example_google_docstrings.py file. If you add new functionality, please make sure to document it in the documentation files.

The overall structure of the documentation is manually designed, but the API documentation is auto-generated based on the docstrings in the code. To generate the docs locally you can run:

# if you didn't install the dependencies earlier
pip install -e .[docs]
cd docs
make docs-clean && make docs-build
# you can also serve the docs locally
make docs-clean && make docs-serve
# and open them in your browser at http://localhost:8000

See the README.md for more information.

6. Make a pull request

Once your changes are ready and all tests pass, push your branch to your forked repository:

git add .
git commit -m "Description of your changes"
git push origin <your_feature_branch_name>

Then, go to the original repository on GitHub and open a Pull Request (PR) from your branch. In your PR description, clearly explain what changes you made and reference any related issues.

Example Pull Request Template

**Title:** [Bug/Feature]: Brief summary of changes

**Description:**
- What changes were made?
- Why were these changes made?
- How do these changes address the issue or feature request?
- Any additional context or references.
- How to test the changes.

The maintainers will review your PR and may request changes or ask questions. Please respond to feedback and update your PR as needed. Once everything looks good, your changes will be merged!

Note

Anyone can review pull requests, we encourage others to review each other’s work, however, only the maintainers can approve a pull request. Pull Requests require at least one approval and all tests passing before being able to merge it.

Thank you for contributing to zea!

Contributing topics

Adding notebooks

New tutorial or example notebooks are always welcome! Please add them to the docs/source/notebooks directory. Make sure to follow the naming conventions and structure of existing notebooks. If you are adding a new tutorial, please also update the examples.rst file in the docs/source directory to check if your notebook is included.

Adding to zea.models

Please see the Models section for more information on how to add new models to zea.

Adding to zea.ops

Please see the Pipeline section for more information on how to add new ops to zea.