.. _developer_guide: 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 :class:`.CSMSimulation` and :class:`.CSMFrame` objects. A :class:`.CSMSimulation` contains a list of :class:`.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. .. image:: /diagrams/packages_cytocalc.png :alt: 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. .. image:: /diagrams/classes_cytocalc.png :alt: Classes and Data structures (The above UML diagrams are automatically generated by Pylint's pyreverse) .. code-block:: bash pyreverse -o png -p cytocalc ./src/cytocalc/ .. image:: /diagrams/CSMSimulation_architecture.png :alt: 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: #. Check if the function is meaningful for a frame or the entire simulation: - Radius of the Network (:meth:`.compute_radius`) is a method of :class:`.CSMFrame`. - Rate of Contraction (:meth:`.contraction_rate`) is a method of :class:`.CSMSimulation`. #. Functions like :func:`.theoretical_cont_rate` which do not directly use Cytosim data can be placed in ``helper.py``. #. The data in a :class:`.CSMFrame` is accessible as either a Pandas dataframe (``pandas_obj``) or a Numpy array (``np_obj``). Development Workflow -------------------- .. image:: /diagrams/git_workflow.png :alt: 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: .. code-block:: bash black . isort . Testing ~~~~~~~ We use ``pytest`` for our test suite. Tests are located in the ``tests/`` directory. To run tests: .. code-block:: bash pytest For test coverage: .. code-block:: bash pytest --cov=src tests/ Making Changes ~~~~~~~~~~~~~~ #. Switch to ``dev`` branch or an offshooting branch #. Create a new branch for your changes #. Make your changes #. Write or update tests as needed #. Run the full test suite #. 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 #. Push your branch #. If branch work done, create a Merge Request (see below) Merge Request Process --------------------- #. Update documentation for any new features or changes #. Ensure all tests pass and code quality checks succeed #. Add a description of your changes to ``CHANGELOG.md`` #. Open a Merge Request to ``dev`` branch (or to offshooting branch) and request review from at least one team member #. Address any review comments #. Ask another member (with member privileges) to Merge .. image:: /diagrams/git-branch-strategy.png :alt: 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.