CONTRIBUTING.md

Contributing to Spatial Metabolic Atlas

Thank you for your interest in contributing! This document provides guidelines for development, testing, and contributions.

🤝 How to Contribute

Types of Contributions

• Bug Fixes: Report and fix issues
• Features: Add new analysis modules or visualizations
• Documentation: Improve guides and examples
• Tests: Add unit and integration tests
• Performance: Optimize existing code

🔧 Development Setup

1. Clone Repository

git clone <repo-url>
cd streamlit_app

2. Create Development Environment

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies with dev extras
pip install -r requirements.txt
pip install -e .  # If using setup.py

3. Install Pre-commit Hooks

pip install pre-commit
pre-commit install

📝 Code Style

Python Style Guide (PEP 8)

# Format code
black modules/ utils/

# Check linting
flake8 modules/ utils/

# Type checking
mypy modules/ utils/

Docstring Format

def example_function(param1: str, param2: int) -> bool:
    """
    Brief description of function.
    
    Longer description if needed, explaining the purpose,
    algorithm, or important details.
    
    Parameters
    ----------
    param1 : str
        Description of param1
    param2 : int
        Description of param2
    
    Returns
    -------
    bool
        Description of return value
    
    Examples
    --------
    >>> result = example_function("test", 42)
    >>> print(result)
    True
    
    Notes
    -----
    Additional implementation notes or warnings.
    """
    return True

🧪 Testing

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_visualization.py

# Run with coverage
pytest --cov=modules --cov=utils tests/

# Verbose output
pytest -v

Writing Tests

# tests/test_module.py
import pytest
from modules import visualization

def test_spatial_flux_map_basic():
    """Test basic spatial flux map generation."""
    # Setup
    mock_adata = create_mock_adata()
    
    # Action
    fig = visualization.plot_spatial_flux(mock_adata, 'EX_glc_D[e]')
    
    # Assert
    assert fig is not None
    assert fig.axes is not None

def test_visualization_with_invalid_reaction():
    """Test error handling for invalid reactions."""
    mock_adata = create_mock_adata()
    
    with pytest.raises(ValueError):
        visualization.plot_spatial_flux(mock_adata, 'INVALID_RXN')

📦 Adding New Modules

Structure for New Feature

modules/
├── new_feature.py      # Main module
├── __init__.py
└── tests/
    └── test_new_feature.py

Module Template

"""
New Feature Module
==================

Brief description of functionality.
"""

import streamlit as st
import logging

logger = logging.getLogger(__name__)


def render():
    """Render feature UI."""
    st.markdown("## 🆕 New Feature")
    
    # Check prerequisites
    if st.session_state.metabolic_adata is None:
        st.error("Please run flux analysis first.")
        return
    
    metabolic_adata = st.session_state.metabolic_adata
    
    # UI components
    col1, col2 = st.columns(2)
    
    with col1:
        # Input controls
        parameter = st.slider("Parameter:", 1, 100, 50)
    
    with col2:
        # Additional options
        method = st.selectbox("Method:", ["option1", "option2"])
    
    # Main computation
    if st.button("▶️ Run Analysis") :
        try:
            with st.spinner("Computing..."):
                result = perform_analysis(metabolic_adata, parameter, method)
            
            st.success("✓ Analysis complete!")
            st.dataframe(result)
            
        except Exception as e:
            st.error(f"Error: {str(e)}")
            logger.error(f"Analysis failed: {str(e)}", exc_info=True)


def perform_analysis(adata, parameter, method):
    """
    Perform custom analysis.
    
    Parameters
    ----------
    adata : AnnData
        Input data
    parameter : int
        Analysis parameter
    method : str
        Analysis method
    
    Returns
    -------
    pd.DataFrame
        Analysis results
    """
    # Implementation
    results = {}
    return results

Integrating into Main App

# app.py
elif page == "🆕 New Feature":
    from modules import new_feature
    new_feature.render()

📚 Documentation

Adding to README.md

1. Update feature list under "Features"
2. Add usage instructions in "Usage Guide"
3. Include examples and expected outputs

Creating Examples

# examples/basic_workflow.py
"""
Basic workflow example for Spatial Metabolic Atlas.
"""

import scanpy as sc
from streamlit_app.utils import plotting, flux_utils

# Load data
adata = sc.read_h5ad("data/spatial_data.h5ad")

# Preprocess
sc.pp.normalize_total(adata, 1e4)
sc.pp.log1p(adata)

# Visualize
fig = plotting.plot_spatial_flux(adata, "EX_glc_D[e]")

print("Done!")

🐛 Bug Reports

When reporting bugs, include:

• Title: Concise description
• Steps to reproduce: Exact steps to recreate issue
• Expected behavior: What should happen
• Actual behavior: What actually happens
• Screenshots: If applicable
• Environment: Python version, OS, package versions

Bug Report Template

## Bug: [Title]

### Steps to Reproduce
1. Load dataset X
2. Go to Y module
3. Click button Z
4. Get error

### Expected Behavior
Should show visualization

### Actual Behavior
Shows error message: "..."

### Screenshots
[If applicable]

### Environment
- Python: 3.10.5
- Streamlit: 1.28.0
- OS: Ubuntu 22.04

🎨 Feature Requests

Provide:

• Use case: Why is this needed?
• Description: Detailed description
• Example: How would it be used?
• Priority: Low, Medium, High

Feature Request Template

## Feature: [Title]

### Use Case
Researchers want to [use case description]

### Proposed Solution
Implement [feature description]

### Example Usage
[How users would use this feature]

### Additional Context
[Any other relevant information]

📈 Pull Request Process

1. Fork the repository
2. Create Branch: git checkout -b feature/feature-name
3. Make Changes: Follow code style guidelines
4. Write Tests: Add tests for new functionality
5. Document: Update README, docstrings, comments
6. Commit: Clear, descriptive commit messages
7. Push: git push origin feature/feature-name
8. Create PR: Open pull request with description

PR Template

## Description
Brief description of changes

## Type
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation
- [ ] Performance

## Changes
- Change 1
- Change 2

## Testing
- [ ] Tests added/updated
- [ ] All tests passing
- [ ] Manual testing completed

## Screenshots
[If applicable]

## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] Tests added
- [ ] No breaking changes

🏗️ Architecture Decisions

Module Interface Standard

All modules should:

• Implement render() function
• Check st.session_state for prerequisites
• Handle errors gracefully with try/except
• Log important operations
• Provide user feedback (success/error messages)

Caching Strategy

@st.cache_data(ttl=3600)
def expensive_computation(data):
    """This will be cached for 1 hour."""
    return result

@st.cache_resource
def load_model():
    """This will be cached for entire session."""
    return model

🔄 Release Process

1. Update Version:

   • app.py: Update version string
   • setup.py: Update version
   • Create CHANGELOG entry

2. Create Release:

   • Tag commit: git tag v1.0.0
   • Push tag: git push origin v1.0.0
   • Create GitHub release with notes

3. Deploy:

   • Build Docker image
   • Push to registry
   • Deploy to production

📞 Getting Help

• Documentation: Check README.md and DEPLOYMENT.md
• Issues: Search GitHub Issues
• Discussions: Start discussion thread
• Email: contact@example.com

📋 Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment.

Our Standards

• Use welcoming language
• Be respectful of differing opinions
• Accept constructive criticism gracefully
• Focus on what is best for the community
• Show empathy towards other community members

Enforcement

Violations may result in removal from the community.

---

Thank you for contributing! 🎉

Your contributions help make Spatial Metabolic Atlas better for researchers worldwide.

Last Updated: February 2024