Developer’s Guide

Welcome to the project! This guide will help you set up your development environment and provide guidelines for contributing to the project.

Development Environment

Prerequisites

See pyproject.toml and requirements.txt (requirements.txt will be verified as part of install process)

Getting Started

The Cytocalc documentation provides detailed instructions on installing and using Cytocalc.

Code architecture

Cytocalc provides CSMSimulation and CSMFrame objects. A CSMSimulation contains a list of CSMFrame objects, which can be accessed using the frames attribute.

The following figure provides an overview of the code architecture for the project. It illustrates the main packages and modules, their relationships, and how they interact with each other.

Code Architecture

The following figure provides an overview of the classes and data structures used in the project. It shows the relationships between different classes, their attributes, and methods.

Classes and Data structures

(The above UML diagrams are automatically generated by Pylint’s pyreverse)

pyreverse -o png -p cytocalc ./src/cytocalc/
The CSMSimulation structure

Class context for parsing cytosim report files

  • The CSMFrame class is used either to conduct a measurement on a single frame, or can be called by CSMSimulation to construct a time series of frames. An object of the CSMFrame class contains a pandas dataframe data holding the data from a single cytosim saved frame, and an added attribute time.

  • The CSMSimulation class is used to conduct a measurement on a time series of frames. An object of CSMSimulation class has an attribute frames which is a list whose elements are supposed to contain objects of CSMFrame class. It also has a params attribute.

Cytocalc can parse both the cytosim single file report of a full simulation and the multiple file reportF which produces a file per saved cytosim frame.

When implementing new functionality:

  1. Check if the function is meaningful for a frame or the entire simulation: - Radius of the Network (compute_radius()) is a method of CSMFrame. - Rate of Contraction (contraction_rate()) is a method of CSMSimulation.

  2. Functions like theoretical_cont_rate() which do not directly use Cytosim data can be placed in helper.py.

  3. The data in a CSMFrame is accessible as either a Pandas dataframe (pandas_obj) or a Numpy array (np_obj).

Development Workflow

Git workflow and CI

Branch Naming Convention

  • Feature branches: feature/descriptive-name

  • Bug fixes: fix/issue-description

  • Documentation: docs/what-changed

  • Release branches: release/version-number

Code Standards and Style

This project follows PEP 8 style guidelines. We use the following tools to maintain code quality:

  • Use meaningful variable and function names.

  • Write docstrings for all functions and classes.

  • black for code formatting

  • isort for import sorting

Run the following commands before committing:

black .
isort .

Testing

We use pytest for our test suite. Tests are located in the tests/ directory.

To run tests:

pytest

For test coverage:

pytest --cov=src tests/

Making Changes

  1. Switch to dev branch or an offshooting branch

  2. Create a new branch for your changes

  3. Make your changes

  4. Write or update tests as needed

  5. Run the full test suite

  6. Commit your changes using conventional commit messages: .. code-block:: text

    feat: add new feature fix: resolve bug docs: update documentation test: add tests refactor: improve code structure

  7. Push your branch

  8. If branch work done, create a Merge Request (see below)

Merge Request Process

  1. Update documentation for any new features or changes

  2. Ensure all tests pass and code quality checks succeed

  3. Add a description of your changes to CHANGELOG.md

  4. Open a Merge Request to dev branch (or to offshooting branch) and request review from at least one team member

  5. Address any review comments

  6. Ask another member (with member privileges) to Merge

Git workflow and CI

Documentation

  • Keep docstrings up to date using Google-style format

  • Update README.md for user-facing changes

  • Update API documentation for public interfaces

  • Cytocalc uses Sphinx to automatically generate code documentation. Hence, we strongly suggest using docstrings.

Getting Help

  • Check existing issues and pull requests

  • Create a new issue for bugs or feature requests

  • Contact project maintainers through appropriate channels

License

Ensure all new code complies with the project’s license terms.