Contributing to tstrait

Contributing to tstrait#

All contributions, bug reports, documentation improvements and ideas are welcome. If you think there is anything missing, please open an issue or pull request on Github.

Quick start#

Initializing environment#

  • Go to tstrait Github repo and click the “fork” button to create your own copy of the project.

  • Clone the project to your own computer:

git clone https://github.com/your-user-name/tstrait.git
cd tstrait
git remote add upstream https://github.com/tskit-dev/tstrait.git
git fetch upstream

This creates the directory tstrait and connects your repository to the upstream (main project) tstrait repository.

  • Install the requirements.

  • Run the tests to ensure everything has worked: python3 -m pytest. These should all pass.

Develop your contribution#

  • Make your changes in a local branch. On each commit, a pre-commit hook will check for code styles and common problems. You can also use pre-commit run to run the checks without committing.

Submit your contribution#

  • You can submit your contribution by pushing your changes back to your fork on Github:

git push origin branch-name

Afterwards, go to Github and open a pull request by pressing a green Pull Request button.

  • Please also refer to tskit documentation for more details on the recommended Github workflow.

Requirements#

The list of packages needed for development are listed in requirements.development.txt. Install these by using either:

conda install --file requirements/development.txt

or

python -m pip install -r requirements/development.txt

Documentation#

The documentation is written in markdown, and Jupyter Book is used to build a HTML documentation. The Jupyter Book documentation offers Tutorial, so please refer to it if you are new to the concept.

All files that are used in the documentation are included in the docs directory. To build the documentation, run the following code in the doc directory:

jupyter-book build .

API Reference#

The API reference is created by using the docstring written in each code. We follow the Numpy Docstring standard, and please refer to the documentation for details.

The API reference is built aumotically from docstring by using sphinx.ext.autosummary.

Codes#

Almost all codes in the documentation are written by using the IPython directive Sphinx extension. The code examples in the documentation are run during the doc building, so the code examples will always be up to date.

Continuous integration tests#

Continuous integration tests are implemented in Github actions, and it runs a variety of code style and quality checks using pre-commit along with Python tests on Linux.

All tests are located in the tests directory, and run using pytest. All new code must have high test coverage, which will be checked as part of the continuous integration tests by CodeCov.

Statistical tests#

We run many statistical tests to ensure that tstrait is simulating the correct process with the desired statistical properties. Since these tests are quite expensive to run and difficult to automatically validate, they are not run as part of continuous integration (CI) but instead as a pre-release sanity check.

The statistical tests are all run via the verification.py script in the project root. The script has some extra dependencies listed in the requirements/verification.txt, which can be installed using pip install -r or conda install --file. You should also need to install R into your environment. Run this script using:

$ python3 verification.py

The statistical tests use scripts in scripts directory to compare the tstrait simulation output against AlphaSimR and simplePHENOTYPES simulation algorithms.

Please read the comments at the top of the verification.py script for details on how to write and run these tests.

Contents