CONTRIBUTING.md

Contributing Guide

Thank you for your interest in contributing to the Multimodal Skin Lesion Explainability project! This guide will help you get started.

Code of Conduct

Please follow HuggingFace's Code of Conduct in all interactions.

Getting Started

1. Fork & Clone

# Fork the repository at HuggingFace or GitHub
git clone https://huggingface.co/spaces/<your-username>/<your-fork>
cd GradCAMPlusPlus_SkinLesion

2. Set Up Environment

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

# Install dependencies with dev tools
pip install -r requirements.txt
pip install black flake8 pytest  # Optional: for code style

3. Verify Installation

python app.py  # Should launch Gradio without errors

Development Workflow

Making Changes

1. Create a feature branch

   git checkout -b feature/your-feature-name
   

2. Make your changes

   • Follow existing code style
   • Add type hints to new functions
   • Include docstrings for complex logic

3. Test locally

   python app.py
   # Test the UI thoroughly before pushing
   

4. Format code (optional but recommended)

   black src/ app.py
   flake8 src/ app.py
   

5. Commit with clear messages

   git add .
   git commit -m "feat: add new feature description"
   

6. Push and create Pull Request

   git push origin feature/your-feature-name
   

Types of Contributions

🐛 Bug Reports

Found an issue? Check Issues first, then report with:

• Describe the bug clearly
• Steps to reproduce
• Expected vs. actual behavior
• Screenshots if relevant
• Environment details (OS, Python version, GPU/CPU)

✨ Feature Requests

Have an idea? Create an issue with:

• Clear description of the feature
• Why it's useful
• Suggested implementation (if you have one)
• Examples of similar solutions

📚 Documentation

Improve docs? Edit:

• README.md - Main documentation
• DEPLOYMENT.md - Deployment guide
• Code docstrings - Inline documentation
• Create tutorials or examples

🔧 Code Improvements

Areas for Contribution:

• Model Improvements: Optimize attention mechanisms, add new architectures
• UI/UX: Enhance Gradio interface, add new visualizations
• Performance: Reduce inference time, optimize memory usage
• Testing: Add test cases, improve code coverage
• Documentation: Add docstrings, improve clarity

Code Standards:

# Type hints required
from typing import Optional, Tuple, List

def process_metadata(values: dict, enabled_groups: List[str]) -> str:
    """
    Process metadata values and generate CSV format.
    
    Args:
        values: Dictionary of patient/lesion fields
        enabled_groups: List of active metadata groups
        
    Returns:
        CSV-formatted string
        
    Raises:
        ValueError: If required fields are missing
    """
    # Implementation...

Project Structure Reference

src/
├── main.py                    # Gradio UI - Safe to modify
├── models/
│   ├── inference.py          # Model loading - Core logic
│   ├── model_loader.py       # PyTorch model setup
│   ├── cam.py                # GradCAM++ implementation
│   ├── preprocessing.py      # Image/metadata processing
│   ├── metadata_*.py         # Metadata handling
│   └── ...                   # Attention mechanism files
utils/
├── transforms.py             # Image transformations
└── load_local_variables.py   # Configuration loading

data/
├── weights/TO_BE_USED/       # Model files (do not commit large files)
└── preprocess_data/          # Encoders, scalers

Areas to Avoid (Breaking Changes)

• Do not modify: Input/output format of run_inference() without coordination
• Do not change: Metadata CSV schema without updating documentation
• Do not remove: Core model classes without providing migration path
• Do not alter: Pre-trained model weights (they're frozen)

Testing

Manual Testing

# Run the app locally
python app.py

# Test scenarios:
1. Upload test image (try different formats)
2. Toggle metadata groups
3. Test all model options
4. Verify heatmap generation
5. Check metadata CSV output

Automated Testing (Optional)

# Create tests/test_inference.py
import pytest
from src.models.inference import get_available_model_choices

def test_model_loading():
    choices = get_available_model_choices()
    assert len(choices) > 0, "No models available"
    assert all(isinstance(c, tuple) for c in choices)

# Run tests
pytest tests/

Deployment Considerations

Before submitting PR with changes:

• Changes work locally with python app.py
• No new dependencies added without updating requirements.txt
• No hardcoded local paths
• All imports are available in requirements
• Code produces no warnings when run

GPU/Performance Notes

• Models are cached after first load - don't reload unnecessarily
• Use torch.no_grad() for inference (already implemented)
• Profile code for bottlenecks: python -m cProfile app.py

Documentation Standards

For New Features

1. Update README.md with feature description
2. Add docstrings to functions
3. Include usage examples in docstrings
4. Update relevant guide (DEPLOYMENT.md, etc.)

Example Docstring

def generate_heatmap(image_tensor: torch.Tensor, metadata_tensor: torch.Tensor) -> np.ndarray:
    """
    Generate GradCAM++ heatmap for given inputs.
    
    This method computes class-weighted gradients and generates attention maps.
    The output can be overlaid on the original image for visualization.
    
    Args:
        image_tensor: Preprocessed image (1, 3, H, W)
        metadata_tensor: Encoded metadata (1, 20)
        
    Returns:
        Normalized heatmap (H, W) with values in [0, 1]
        
    Example:
        >>> image = torch.randn(1, 3, 224, 224)
        >>> metadata = torch.randn(1, 20)
        >>> heatmap = generate_heatmap(image, metadata)
        >>> assert heatmap.shape == (224, 224)
    """

Commit Message Style

Follow conventional commits:

feat: add new attention mechanism
fix: resolve heatmap generation bug
docs: update README with new feature
style: format code with black
refactor: optimize inference pipeline
test: add unit tests for metadata builder
chore: update dependencies

Getting Help

• Questions: Post in Discussions
• Documentation: Check README.md and DEPLOYMENT.md
• Issues: Search existing issues first
• Code Review: Tag maintainers in your PR

Recognition

Contributors will be:

• Listed in project README
• Credited in git commits
• Thanked in release notes
• Considered for maintainer roles (for significant contributions)

Legal

• By contributing, you agree your work may be used under the MIT License
• Ensure you have rights to any code you submit
• Respect intellectual property and attribution

Review Process

1. Automated Checks: CI/CD runs automatically

   • Code format check
   • Import validation
   • Model loading verification

2. Manual Review: Maintainers review for:

   • Code quality and style
   • Alignment with project goals
   • Documentation completeness
   • Performance impact

3. Merge: Once approved, changes are merged to main

Questions?

• Check existing Issues
• Read DEPLOYMENT.md for deployment questions
• Open a Discussion for questions

---

Thank you for contributing! 🙏

Together we make skin lesion analysis more transparent and interpretable.

Last Updated: March 2026