Contributing

We welcome contributions to BellmanFilterDFSV! This guide will help you get started.

Development Setup

1. Clone the Repository

git clone https://github.com/givani30/BellmanFilterDFSV.git
cd BellmanFilterDFSV

2. Install Development Dependencies

Using uv (recommended):

uv sync
uv run pytest  # Run tests to verify setup

Using pip:

pip install -e .[dev,all]
pytest

3. Set up Pre-commit Hooks (optional)

pre-commit install

Code Style

We follow these coding standards:

  • PEP 8 for Python code style

  • Google style for docstrings

  • Functional programming style using Equinox and JAX

  • Type safety using jaxtyping and basedpyright

Linting and Formatting Tools

We use ruff for both linting and formatting, and basedpyright for type checking.

# Format and lint code
uv run ruff check --fix .
uv run ruff format .

# Type checking
uv run basedpyright src/

Testing

Running Tests

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_filters.py

# Run with coverage
uv run pytest --cov=bellman_filter_dfsv

Writing Tests

  • Place tests in the tests/ directory

  • Use descriptive test names: test_bellman_filter_convergence

  • Include docstrings explaining what the test validates

  • Use fixtures from tests/conftest.py for common setup

  • Use Hypothesis for property-based testing of mathematical identities

Documentation

Building Documentation

cd docs/
make html
# Open docs/build/html/index.html

Documentation Standards

  • Use Google style docstrings for all public functions

  • Include mathematical notation using LaTeX: .. math::

  • Provide usage examples in docstrings

  • Update API documentation when adding new modules

Example Docstring

def run_filter(filter_module: BellmanFilter, returns: jnp.ndarray) -> FilterResult:
    """Run Bellman filter on DFSV model.

    This function implements the Bellman filter for Dynamic Factor
    Stochastic Volatility models using JAX for efficient computation.

    Args:
        filter_module: Initialized BellmanFilter Equinox module.
        returns: Observed return data of shape (T, N) where T is
            the number of time periods and N is the number of series.

    Returns:
        A FilterResult namedtuple containing filtered means,
        information matrices, and the log-likelihood.

    Example:
        >>> params = DFSVParams(...)
        >>> bf = BellmanFilter(params)
        >>> result = bf.filter(returns)
        >>> print(f"Log-likelihood: {result.log_likelihood:.2f}")
    """

Contributing Guidelines

1. Issue Reporting

Before submitting a bug report or feature request:

  • Check existing issues to avoid duplicates

  • Provide minimal reproducible examples

  • Include system information (Python version, JAX version, OS)

2. Pull Requests

  • Fork the repository and create a feature branch

  • Write tests for new functionality

  • Ensure all tests pass

  • Update documentation as needed

  • Follow the code style guidelines

Pull Request Process

# 1. Create feature branch
git checkout -b feature/new-filter-algorithm

# 2. Make changes and commit
git add .
git commit -m "feat: add new filter algorithm with tests"

# 3. Run tests
uv run pytest

# 4. Push and create PR
git push origin feature/new-filter-algorithm

3. Code Review

All contributions go through code review:

  • Ensure code follows style guidelines (Ruff/Pyright)

  • Verify tests provide adequate coverage

  • Check documentation is complete and accurate

  • Validate numerical correctness for mathematical code

Areas for Contribution

High Priority

  • Performance optimizations for high-dimensional factor models

  • Real-world examples with financial datasets

  • GPU acceleration benchmarks and improvements

Medium Priority

  • Alternative optimization algorithms for the EM M-step

  • Model diagnostics and validation tools (e.g., residual analysis)

  • Visualization utilities for particle clouds

Getting Help

  • GitHub Issues: For bug reports and feature requests

  • Discussions: For questions and general discussion

  • Email: givaniboek@hotmail.com for direct contact

Recognition

Contributors will be acknowledged in the release notes for significant contributions.

Thank you for contributing to BellmanFilterDFSV!