Contributing to electroMICA
Thank you for your interest in contributing to electroMICA! This document provides guidelines for contributing code, documentation, and feedback.
Code of Conduct
We are committed to providing a welcoming and inclusive environment. Please treat all contributors with respect and professionalism.
Getting Started
Fork the repository on GitHub
Clone your fork locally:
git clone https://github.com/your-username/electroMICA.git cd electroMICA
Create a virtual environment and install development dependencies:
python -m venv .venv source .venv/bin/activate # or .\.venv\Scripts\Activate.ps1 on Windows pip install -r requirements.txt
Create a feature branch:
git checkout -b feature/your-feature-name
Make your changes, following the guidelines below.
Commit and push:
git add . git commit -m "Descriptive commit message" git push origin feature/your-feature-name
Open a pull request on GitHub and describe your changes.
Coding Guidelines
- Python Style
Follow PEP 8 conventions
Use 4 spaces for indentation
Limit lines to ~100 characters where practical
Use descriptive variable and function names
- Docstrings
All functions should have docstrings in NumPy or Google style
Include parameter descriptions, return types, and examples
Example:
def compute_feature_map(leadfield, features): """ Compute the projected feature map from a leadfield matrix. Parameters ---------- leadfield : array_like Shape (n_vertices, n_channels). Leadfield matrix. features : array_like Shape (n_channels,). Feature values at each channel. Returns ------- map : ndarray Shape (n_vertices,). Projected feature map. Examples -------- >>> lf = np.random.randn(1000, 32) >>> feat = np.random.randn(32) >>> proj = compute_feature_map(lf, feat) """ ...
- Comments
Write clear, concise comments explaining the “why” not the “what”
Avoid redundant comments; let readable code speak for itself
- Testing
Add unit tests for new functions in a tests/ folder (when tests are formalized)
Verify your code works with the existing example scripts
Test on multiple Python versions (3.7+) if possible
- Performance
Avoid unnecessary loops; use NumPy vectorization
Profile critical sections if performance matters
Use sparse matrices (scipy.sparse) for large matrices
Types of Contributions
- Bug Reports
Open an issue on GitHub with a clear description
Include Python version, OS, and a minimal reproducible example
Attach relevant error messages and tracebacks
- Feature Requests
Describe the feature and why it would be useful
Provide use cases or examples
Discuss design implications (e.g., API changes)
- Code Contributions
Bug fixes: Target the main branch
Features: Discuss first via an issue to ensure alignment
Refactoring: Ensure no behavioral changes and all tests pass
- Documentation Improvements
Clarify ambiguous sections
Add missing examples or references
Correct typos and grammatical issues
Improve algorithm descriptions or API docs
- Example Scripts
Add new example scripts for specific use cases
Ensure scripts are well-commented and runnable
Include both simple and advanced examples
Workflow & Pull Requests
- Before submitting:
Ensure your branch is up-to-date:
git fetch origin git merge origin/main
Test your changes:
python example_electroMICA_iEEG.py # or relevant test
Check code style (if linter is available):
# Optional: run flake8 or similar flake8 electroMICA.py
Pull Request Template
## Description Brief description of the change. ## Type of Change - [ ] Bug fix - [ ] New feature - [ ] Documentation - [ ] Refactoring ## Related Issues Closes #(issue number) ## Testing Describe how you tested the changes. ## Checklist - [ ] Code follows PEP 8 guidelines - [ ] Docstrings added/updated - [ ] Comments added where necessary - [ ] Examples tested and working - [ ] No new warnings or errors
- Review Process
A maintainer will review your PR
Address feedback and suggestions
Once approved, the PR will be merged
Documentation
- Building Docs Locally
The documentation uses Sphinx and the RTD theme:
cd docs make html
Open
docs/_build/html/index.htmlin your browser to preview.- Editing Docs
Source files are in
docs/(RST format)Update relevant sections when making code changes
Add new doc pages for new features
Use consistent RST formatting and cross-references
- Documentation Standards
All public functions should be documented in the API reference
Provide examples for non-trivial features
Include mathematical background (see Algorithms and Mathematical Background) for complex methods
Reference external papers and related work
Reporting Issues
- Security Issues
Please do not open a public issue for security vulnerabilities. Email the maintainers directly with details.
- Bug Reports
Include: - Python version and OS - Full error traceback - Minimal reproducible example - Steps to reproduce - Expected vs. actual behavior
- Feature Requests
Describe: - The feature and its purpose - Why it would be useful - Proposed API or interface - Any implementation concerns
Development Environment
- Recommended Tools
Editor: VS Code, PyCharm, or similar
Linter: flake8, pylint, or ruff
Formatter: black or autopep8
Type checker: mypy (optional)
Documentation: Sphinx, rst2html
- Optional Setup
Add to requirements.txt for development:
pip install flake8 black pytest pytest-cov mypy sphinx-autodoc-typehints
- Pre-commit Hook (optional)
Create .git/hooks/pre-commit:
#!/bin/bash flake8 electroMICA.py || exit 1 black --check electroMICA.py || exit 1
Acknowledgments
Contributors to electroMICA are listed in the repository and documentation. Thank you for improving the tool!
Contact
For questions or discussions: - Open a GitHub discussion - Email the MICA Lab (see README) - Check the documentation and FAQ
—
Last updated: 2025. See the repository for the latest guidelines.