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
```bash
git clone <repo-url>
cd streamlit_app
```

### 2. Create Development Environment
```bash
# 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
```bash
pip install pre-commit
pre-commit install
```

## 📝 Code Style

### Python Style Guide (PEP 8)
```bash
# Format code
black modules/ utils/

# Check linting
flake8 modules/ utils/

# Type checking
mypy modules/ utils/
```

### Docstring Format
```python
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
```bash
# 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
```python
# 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
```python
"""
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
```python
# 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
```python
# 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
```markdown
## 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
```markdown
## 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
```markdown
## 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
```python
@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