Contributing

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

Development Setup

Fork and clone the repository:

git clone https://github.com/adityapt/deepcausalmmm.git
cd deepcausalmmm

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install in development mode:

pip install -e .
pip install -e .[test]

Run tests to verify setup:

python -m pytest tests/ -v

Contributing Guidelines

Zero Hardcoding Philosophy

All parameters must be configurable via config.py
No magic numbers in model code
Dataset agnostic - works on any MMM dataset
Learnable parameters preferred over fixed constants

Code Quality Standards

Type hints for all function parameters and returns
Comprehensive docstrings with examples (Google/NumPy style)
Error handling with informative messages
Modular design with clear separation of concerns

Performance Standards

Benchmark against baseline before and after changes
Maintain generalization with proper train/holdout validation
Document performance impact in pull requests
Training stability - no coefficient explosion or divergence
Business logic - contributions should be realistic and interpretable

Submitting Changes

Create a feature branch:

git checkout -b feature/your-feature-name

Make your changes following the guidelines above
Add tests for new functionality
Run the test suite:

python -m pytest tests/ -v --cov=deepcausalmmm

Update documentation if needed
Submit a pull request with: - Clear description of changes - Performance impact analysis - Test results - Documentation updates

Documentation

We use Sphinx with Read the Docs for documentation. To build docs locally:

cd docs/
make html
open build/html/index.html

All public APIs should have comprehensive docstrings in Google/NumPy style:

def example_function(param1: int, param2: str = "default") -> Dict[str, Any]:
    """
    Brief description of the function.

    Longer description explaining the purpose and behavior.

    Parameters
    ----------
    param1 : int
        Description of param1
    param2 : str, default="default"
        Description of param2

    Returns
    -------
    Dict[str, Any]
        Description of return value

    Examples
    --------
    >>> result = example_function(42, "test")
    >>> print(result)
    {'status': 'success'}
    """

Testing

We use pytest for testing. Tests should cover:

Unit tests for individual functions/classes
Integration tests for complete workflows
Performance tests for critical paths
Edge cases and error conditions

Run specific test categories:

# Unit tests only
python -m pytest tests/unit/ -v

# Integration tests
python -m pytest tests/integration/ -v

# With coverage report
python -m pytest tests/ --cov=deepcausalmmm --cov-report=html

Code Style

We follow PEP 8 with some modifications:

100-character line limit
Type hints for all function signatures
Descriptive variable names (no abbreviations)
Consistent formatting using black formatter

Format your code before submitting:

black deepcausalmmm/
isort deepcausalmmm/

Naming Conventions

Functions/variables: snake_case
Classes: PascalCase
Constants: UPPER_SNAKE_CASE
Private methods: _leading_underscore

Import Organization

# Standard library imports
import os
import sys
from typing import Dict, List, Optional, Tuple

# Third-party imports
import torch
import torch.nn as nn
import pandas as pd
import numpy as np

# Local imports
from deepcausalmmm.core.config import get_default_config
from deepcausalmmm.utils.device import get_device

Recognition

Contributors will be recognized in:

CHANGELOG.md for each release
README.md contributors section
GitHub releases with contributor highlights

Community Guidelines

Be respectful and constructive in discussions
Help others learn and contribute
Share knowledge through documentation and examples
Celebrate successes and learn from failures

Getting Help

GitHub Issues: For bug reports and feature requests
GitHub Discussions: For questions and general discussion
Documentation: Check the docs first for common questions

Thank you for contributing to DeepCausalMMM!