Contributing¶

This guide will help you get started with contributing to the project.

Getting Started¶

Fork the Repository

Fork the repository on GitHub and clone your fork locally:
```
git clone https://github.com/YOUR_USERNAME/CellMIL.git
cd CellMIL
```

Set Up Development Environment

Follow the installation instructions in Installation, then install development dependencies:

# Create and activate environment
conda env create -f environments/environment_cellmil.yml
conda activate cellmil

# Install
poetry install

Create a Branch

Create a new branch for your feature or bug fix:
```
git checkout -b feature/your-feature-name
```

Development Guidelines¶

Code Style¶

Follow PEP 8-ish style guidelines
Use type hints for all function parameters and return values
Use descriptive variable and function names

Documentation¶

Add docstrings to all public functions and classes
Use Google-style docstrings
Update documentation when adding new features
Build docs locally to test:

cd src/doc/
make html

Code Architecture¶

Understanding the codebase structure:

src/cellmil/
├── cli/                    # Command-line interfaces
├── models/                 # Deep learning models
│   ├── segmentation/       # Cell segmentation models
│   └── mil/               # MIL models
├── data/                  # Data processing
├── features/              # Feature extraction
├── graph/                 # Graph creation
├── segmentation/          # Cell segmentation
├── visualization/         # Plotting and visualization
├── interfaces/            # Configuration classes
├── explainability/        # Explainability methods
├── statistics/            # Statistical analysis
├── utils/                 # Utility functions
└── __tests__/                 # Test suite

Design Principles¶

Modularity: Each component should be self-contained
Configuration: Use Pydantic models for configuration
Type Safety: Use type hints throughout
Error Handling: Provide clear error messages
Logging: Use structured logging for debugging

Adding New Models¶

To add a new segmentation model:

Create a new file in cellmil/models/segmentation/
Add model to __init__.py
Update CLI to include new model
Add documentation

To add a new MIL model:

Create a new file in cellmil/models/mil/
Follow existing model patterns
Add model to __init__.py
Update CLI options

Documentation Guidelines¶

Docstring Format:

def extract_features(self, image: np.ndarray, mask: np.ndarray) -> Dict[str, float]:
    """Extract features from segmented cells.

    Args:
        image: Input histological image
        mask: Binary segmentation mask

    Returns:
        Dictionary mapping feature names to values

    Raises:
        ValueError: If image and mask shapes don't match

    Example:
        >>> extractor = FeatureExtractor()
        >>> features = extractor.extract_features(image, mask)
        >>> print(features.keys())
    """

API Documentation:

Document all public APIs
Include usage examples
Explain parameter choices
Document return value formats