CONTRIBUTING.md

Contributing to CortexLab

Thanks for your interest in contributing to CortexLab! This guide will help you get started.

Getting Started

1. Fork and clone

git clone https://github.com/YOUR_USERNAME/cortexlab.git
cd cortexlab

2. Set up the development environment

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev,analysis]"

3. Verify everything works

pytest tests/ -v
ruff check src/ tests/

Development Workflow

1. Create a branch from master for your work:

   git checkout -b feature/your-feature-name
   

2. Make your changes - keep commits focused and atomic.

3. Run tests and lint before committing:

   pytest tests/ -v
   ruff check src/ tests/
   

4. Open a pull request with a clear description of what you changed and why.

Project Structure

src/cortexlab/
  core/          Model architecture, attention extraction, subject adaptation
  data/          Dataset loading, transforms, HCP ROI utilities
  training/      PyTorch Lightning training pipeline
  inference/     Predictor, streaming, modality attribution
  analysis/      Brain-alignment benchmark, cognitive load scorer
  viz/           Brain surface visualization
tests/           Unit tests (pytest)
examples/        Usage examples

What to Work On

• Check issues labeled good first issue for beginner-friendly tasks
• Check issues labeled help wanted for tasks where we need help
• Look at the experiment issues if you want to run evaluations

Code Style

• Linting: We use ruff with a 100-character line limit
• Tests: Write pytest tests for new functionality. Use synthetic data (no real fMRI needed)
• Docstrings: Use NumPy-style docstrings for public functions
• Imports: Let ruff sort imports automatically (ruff check --fix)

Writing Tests

Tests use synthetic data and mock objects so you don't need real fMRI datasets or GPU access:

import torch
from neuralset.dataloader import SegmentData
import neuralset.segments as seg

# Create dummy segments matching batch size
segments = [seg.Segment(start=float(i), duration=1.0, timeline="test") for i in range(batch_size)]

# Create synthetic batch
data = {"text": torch.randn(batch_size, 2, 32, seq_len), "subject_id": torch.zeros(batch_size, dtype=torch.long)}
batch = SegmentData(data=data, segments=segments)

Adding New Features

If you're adding a new analysis method or inference capability:

1. Add the implementation in the appropriate subpackage
2. Export it from the subpackage's __init__.py
3. Write tests in tests/test_yourfeature.py
4. Add a usage example in the README or examples/

Reporting Bugs

When filing a bug report, please include:

• Python version and OS
• PyTorch version
• Steps to reproduce
• Full error traceback
• What you expected to happen

Questions?

Open an issue with the question label and we'll help out.