CellMapFlow Hub

A community-driven hub for CellMapFlow components: models, normalizers, postprocessors, and pre-built pipelines.

🎯 Quick Start

Browse Components

Access the hub at: http://localhost:PORT/hub in your CellMapFlow dashboard

Install a Component

1. Browse the hub and find a component you want
2. Click "Install"
3. Dependencies are installed automatically
4. Component is available in pipeline builder

📁 Repository Structure

Each component type has its own folder with self-documenting config files:

cellmap_flow_hub/
├── models/              # ML models for inference
├── normalizers/         # Input normalization components (6 available)
├── postprocessors/      # Output post-processing components (8 available)
└── pipelines/           # Pre-built pipeline templates

What's Inside Each Component

Every component folder contains:

• config.yaml - Metadata (name, description, author, version, tags, dependencies)
• requirements.txt - Python package dependencies
• README.md - Implementation details, usage examples, and parameters

Example:

normalizers/zscore_normalizer/
├── config.yaml          # Metadata
├── requirements.txt     # numpy>=1.20
└── README.md           # Usage examples and parameters

🚀 Contributing Components

Add a New Model

mkdir cellmap_flow_hub/models/my_model
cd cellmap_flow_hub/models/my_model

Create config.yaml:

name: My Awesome Model
description: A powerful segmentation model for your data
author: Your Name
version: 1.0.0
tags: [segmentation, deep-learning, neurons]
dependencies:
  - torch>=1.10
  - torchvision>=0.11
min_cellmap_flow_version: "1.2.0"
min_python_version: "3.8"

Add your implementation files:

• model_script.py - Main model code
• requirements.txt - Python dependencies
• README.md - Detailed documentation (optional)
• thumbnail.png - Preview image (optional)

Add a Normalizer

mkdir cellmap_flow_hub/normalizers/my_normalizer
cd cellmap_flow_hub/normalizers/my_normalizer

Create config.yaml:

name: My Custom Normalizer
description: Normalizes images with special handling for artifacts
author: Your Name
version: 1.0.0
tags: [normalization, preprocessing]

Add implementation and requirements.

Add a Postprocessor

mkdir cellmap_flow_hub/postprocessors/my_postprocessor
cd cellmap_flow_hub/postprocessors/my_postprocessor

Create config.yaml with similar structure.

Add a Pipeline Template

mkdir cellmap_flow_hub/pipelines/my_pipeline
cd cellmap_flow_hub/pipelines/my_pipeline

Create pipeline.yaml:

input_normalizers:
  - name: StandardNormalizer
    params: { clip_min: -1, clip_max: 1 }

models:
  - name: my_model
    params: { checkpoint: "model.pt" }

postprocessors:
  - name: InstanceSegmentation
    params: { threshold: 0.5 }

Create config.yaml with metadata about the pipeline:

name: Mitochondria Segmentation Pipeline
description: Complete pipeline for segmenting mitochondria
author: Your Name
version: 1.0.0
tags: [mitochondria, segmentation, organelles]

📋 Config.yaml Format

Every component must have a config.yaml with metadata:

name: Component Display Name           # Required: Human-readable name
description: What this component does  # Required: Brief description
author: Your Name                       # Required: Creator
version: 1.0.0                         # Required: Semantic version
tags: [tag1, tag2]                     # Required: Category tags

# Optional fields
dependencies:                          # Python package dependencies
  - package>=1.0
  - another-package

min_cellmap_flow_version: "1.2.0"     # Minimum CellMapFlow version
min_python_version: "3.8"             # Minimum Python version
max_python_version: "3.11"            # Maximum Python version

thumbnail_url: ./thumbnail.png        # Path to preview image (relative)
documentation_url: ./README.md        # Path to detailed docs

✅ Component Checklist

Before contributing, ensure:

• config.yaml has all required fields
• requirements.txt lists all dependencies with versions
• Code is well-commented and documented
• Component has been tested locally
• README.md included (optional but recommended)
• Thumbnail included (optional, improves discoverability)
• No hardcoded paths or credentials
• Follows CellMapFlow conventions

🔄 How Hub Discovery Works

1. CellMapFlow scans cellmap_flow_hub/ folder structure
2. For each subfolder in models/, normalizers/, etc., it reads config.yaml
3. Builds a manifest of all available components
4. Caches manifest locally for fast loading
5. User can click "Refresh Hub" to fetch latest from repository

No central registry needed - just add a folder!

📦 Installation

For Users

1. Access /hub in CellMapFlow dashboard
2. Click "Refresh Hub" to fetch latest components
3. Click "Install" on any component
4. Use in pipeline builder

For Developers

1. Clone the hub repo
2. Create component folder in appropriate directory
3. Add config.yaml and implementation files
4. Push changes
5. Component automatically appears in hub

🐛 Troubleshooting

Component not appearing in hub?

• Ensure config.yaml exists in component folder
• Check YAML syntax is valid
• Try "Refresh Hub" button

Installation fails?

• Check requirements.txt has correct package names
• Verify min_cellmap_flow_version matches your version
• Check Python version compatibility

Dependencies conflict?

• Use virtual environments (conda/venv)
• Pin exact versions in requirements.txt

📞 Support

For issues or questions:

• Check existing components for examples
• Review CellMapFlow documentation
• Open an issue on GitHub

📜 License

Each component is independently licensed. Check individual component READMEs for license information.

---

Happy Contributing! 🚀