Contributing to LoS Estimator

We welcome contributions to the LoS Estimator project! This guide will help you get started with development and submitting contributions.

Getting Started

Setting Up Your Development Environment

  1. Clone the repository:

    git clone git@git.rwth-aachen.de:jrc-combine/los-estimator.git
cd los-estimator

  2. Create a virtual environment:

    python -m venv .venv

# On Windows
.\.venv\Scripts\activate

# On Linux/macOS
source .venv/bin/activate

  3. Install the package in editable mode with development dependencies:

    pip install -e ".[dev,docs]"

Development Workflow

Code Style

We use Black for code formatting and follow PEP 8. Before submitting a PR:

black los_estimator/

Type Hints

We encourage type hints for better code quality. Check your code:

mypy los_estimator/

Running Tests

Run the test suite to ensure your changes work:

pytest tests/

For coverage report:

pytest --cov=los_estimator tests/

Building Documentation

Documentation is built with Sphinx using reStructuredText:

cd docs

# On Windows
.\make.bat html

# On Linux/macOS
make html

View the built documentation in docs/build/html/index.html.

Important Files and Directories

  • los_estimator/ - Main package source code

  • tests/ - Unit and integration tests

  • docs/source/ - Documentation source (RST format)

  • examples/ - Example scripts and data

  • pyproject.toml - Package configuration and dependencies

  • setup.py - Minimal build configuration

Making Changes

Before You Start

  1. Check existing issues and PRs to avoid duplicating work

  2. Create a descriptive issue if one doesn’t exist

  3. For major changes, discuss in an issue before implementing

Creating a Feature Branch

git checkout -b feature/your-feature-name
# or for bug fixes
git checkout -b fix/your-bug-fix-name

Commit Guidelines

  • Use clear, descriptive commit messages

  • Keep commits atomic (one logical change per commit)

  • Reference related issues in commits: Fixes #123 or Related to #456

Example:

git commit -m "Add new distribution model for exponential fitting

- Implement exponential distribution class
- Add unit tests for new model
- Update documentation

Fixes #123"

Documentation Comments

Code should include docstrings following Google style:

def estimate_los(admissions, occupancy):
    """Estimate length of stay distribution from admission and occupancy data.

    This function uses deconvolution methods to estimate the probability
    distribution of patient length of stay.

    Args:
        admissions (np.ndarray): Daily admission counts
        occupancy (np.ndarray): Daily occupancy counts

    Returns:
        dict: Estimated distribution parameters

    Raises:
        ValueError: If input arrays have mismatched lengths
        TypeError: If inputs are not numpy arrays
    """

Submitting a Pull Request

  1. Push your branch to the repository:

    git push origin feature/your-feature-name

  2. Open a Pull Request (PR) on GitLab with:

    • Clear title describing the change

    • Description explaining what and why

    • Reference to related issues

    • Screenshots or examples if applicable

  3. Address review feedback:

    • Respond to comments professionally

    • Make requested changes in new commits

    • Push updates (no need to force push on open PR)

PR Checklist

Before submitting, verify:

  • [ ] Type hints are added where appropriate

  • [ ] Tests are added for new functionality

  • [ ] Tests pass locally (pytest)

  • [ ] Documentation is updated if needed

  • [ ] CHANGELOG.md is updated with your changes

  • [ ] No unnecessary files are committed

Code Review Process

All PRs require review before merging. Reviewers will check:

  • Code quality and adherence to style

  • Test coverage and pass rates

  • Documentation clarity

  • Compatibility with existing code

  • Performance implications

Be patient and constructive during review. Questions are meant to improve the code, not criticize.

Reporting Issues

Bug Reports

Include:

  • Clear, descriptive title

  • Steps to reproduce

  • Expected vs actual behavior

  • Python version, OS, and package version

  • Relevant error messages and traceback

  • (Optional) Minimal reproducible example

Feature Requests

Include:

  • Use case and motivation

  • Proposed solution (if you have one)

  • Alternative approaches considered

  • (Optional) Example code showing the desired API

Support and Questions

For questions or discussions:

  • Use GitLab Issues for technical discussions

  • Check existing documentation and issues first

  • Be specific and provide context

Code of Conduct

We are committed to providing a welcoming and inclusive environment. All contributors are expected to be respectful and constructive in their interactions.

Note

Please report any Code of Conduct violations to the project maintainers.

Licensing

By contributing to LoS Estimator, you agree that your contributions will be licensed under the GPLv3 License. See LICENSE.md for details.

Recognition

Contributors will be recognized in:

  • Project README

  • Release notes

  • GitHub/GitLab contributor list

Thank you for contributing! 🎉