Initial commit with HF dataset integration

- Gradio app loads data from HF dataset repository
- No large files in repo (uses chanzuckerberg/DynaCLR-data)
- Requires HF_TOKEN for private dataset access

.gitattributes

@@ -0,0 +1,44 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Zarr datasets in data directory
+# OME-Zarr binary chunks
+data/dataset.zarr/[A-Z]/*/[0-9]*/0/c/0/0/0/0/0 filter=lfs diff=lfs merge=lfs -text
+# AnnData zarr - exclude metadata files (.z*), track binary chunks
+data/annotations.zarr/**/* filter=lfs diff=lfs merge=lfs -text
+data/annotations.zarr/**/.z* !filter !diff !merge text
+data/annotations.zarr/**/*.json !filter !diff !merge text
+# CSV files
+data/*.csv filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Jupyter
+.ipynb_checkpoints
+*.ipynb
+
+
+# Logs
+*.log
+logs/
+
+# Gradio
+gradio_queue.db
+flagged/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Environment variables
+.env
+.env.local
+
+# Other
+claudedocs/
+.claude/
+concatenate_dataset.yml
+.hf_cache/

README.md

@@ -0,0 +1,129 @@
+---
+title: DynaCLR
+emoji: 🔬
+colorFrom: gray
+colorTo: purple
+sdk: gradio
+sdk_version: 6.0.2
+app_file: app.py
+pinned: false
+license: bsd-3-clause
+---
+
+# DynaCLR Visualization
+
+Interactive visualization of cell embeddings and infection status with microscopy image viewing.
+
+## Overview
+
+This application provides an interactive interface for exploring:
+
+- Cell embeddings (PCA, projections, and other dimensionality reductions)
+- Infection status annotations
+- Multi-channel microscopy images
+- Time-series cell tracking
+
+## Features
+
+### Interactive Embedding Plot
+
+- Visualize cells in 2D embedding space
+- Color-coded by infection status (infected, uninfected, unknown)
+- Select any embedding dimensions for X and Y axes
+- Click on cells to view detailed microscopy images
+
+### Microscopy Image Viewer
+
+- View multi-channel images for selected cells
+- Toggle between Phase3D, GFP, and mCherry channels
+- Adjustable channel opacity for image composition
+- Track time-series visualization
+
+### Infection Status Tracking
+
+- Annotated infection status for cells
+- Visual highlighting of selected tracks
+- FOV-specific track identification
+
+## Configuration
+
+### HuggingFace Dataset Integration
+
+This application automatically loads data from the private HuggingFace dataset repository `chanzuckerberg/DynaCLR-data`. To deploy on HuggingFace Spaces:
+
+1. **Set the HF_TOKEN secret** in your Space settings:
+   - Go to your Space settings → Repository secrets
+   - Add a new secret named `HF_TOKEN`
+   - Set the value to a HuggingFace access token with read permissions for the dataset repository
+   - Get a token from: https://huggingface.co/settings/tokens
+
+2. **Environment Variables** (optional):
+   - `USE_HF_DATASET`: Set to "true" (default) to load from HF dataset, or "false" to use local data
+   - `HF_TOKEN`: HuggingFace access token (required for private dataset repositories)
+
+### Local Development
+
+For local development without HuggingFace dataset:
+
+```bash
+# Disable HF dataset loading
+export USE_HF_DATASET=false
+
+# Ensure local data files are present in data/ directory:
+# - data/dataset.zarr/
+# - data/annotations_filtered.zarr/
+# - data/track_infection_annotation.csv
+```
+
+## Usage
+
+### Exploring Embeddings
+
+1. Select embedding dimensions from the X-axis and Y-axis dropdowns (e.g., PC1, PC2)
+2. The plot will update to show all cells in that embedding space
+3. Cells are colored by infection status:
+   - 🔴 Red: Infected
+   - 🟢 Green: Uninfected
+   - ⚪ Gray: Unknown
+
+### Viewing Cell Images
+
+2. Select a track from the dropdown menu
+3. The image gallery will display microscopy images for that cell
+4. Use the channel checkboxes to toggle different imaging channels
+5. Adjust opacity sliders to control channel visibility
+
+### Channel Information
+
+- **Phase3D**: Phase contrast imaging showing cell morphology
+- **GFP**: Green fluorescent protein channel
+- **mCherry**: Fluorescent protein channel
+
+## Citation
+
+If you use this visualization tool in your research, please cite:
+
+```bibtex
+@misc{hiratamiyasaki2025dynaclrcontrastivelearningcellular,
+      title={DynaCLR: Contrastive Learning of Cellular Dynamics with Temporal Regularization}, 
+      author={Eduardo Hirata-Miyasaki and Soorya Pradeep and Ziwen Liu and Alishba Imran and Taylla Milena Theodoro and Ivan E. Ivanov and Sudip Khadka and See-Chi Lee and Michelle Grunberg and Hunter Woosley and Madhura Bhave and Carolina Arias and Shalin B. Mehta},
+      year={2025},
+      eprint={2410.11281},
+      archivePrefix={arXiv},
+      primaryClass={cs.CV},
+      url={https://arxiv.org/abs/2410.11281}, 
+}
+```
+
+## Related Projects
+
+- [VisCy](https://github.com/mehta-lab/VisCy): Computer vision models for single-cell phenotyping
+- [iohub](https://github.com/czbiohub-sf/iohub): Pythonic and parallelizable I/O for N-dimensional imaging data with OME metadata
+
+## License
+
+BSD-3-Clause
+
+## Contact
+
+For questions or issues, please open an issue on the [VisCy GitHub repository](https://github.com/mehta-lab/VisCy/issues).

app.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+"""
+DynaCLR Visualization - Hugging Face Spaces Deployment
+
+Interactive visualization of cell embeddings and infection status
+with microscopy image viewing.
+
+This is a self-contained deployment package for Hugging Face Spaces.
+"""
+
+from dynaclr_viz import create_app
+import gradio as gr
+
+if __name__ == "__main__":
+    print("=" * 60)
+    print("DynaCLR Visualization - Hugging Face Spaces")
+    print("=" * 60)
+    print("Starting application...")
+    print("=" * 60)
+
+    # Create and launch the Gradio app
+    demo = create_app()
+
+    # Launch with HF Spaces configuration
+    demo.launch()

dynaclr_viz/README.md

@@ -0,0 +1,133 @@
+# DynaCLR Visualization Package
+
+Modular package for visualizing cell embeddings and infection status with interactive microscopy image viewing.
+
+## Structure
+
+```
+dynaclr_viz/
+├── __init__.py          # Package exports and public API
+├── config.py            # Configuration, paths, and constants
+├── data.py              # Data loading and state management
+├── image.py             # Image processing and extraction
+├── plot.py              # Plotly visualization functions
+├── handlers.py          # Gradio event handlers
+└── ui.py                # Gradio UI layout and components
+```
+
+## Module Responsibilities
+
+### `config.py` - Configuration (~30 lines)
+- Data file paths
+- Visualization constants (colors, sizes, defaults)
+- Plot settings
+
+### `data.py` - Data Management (~130 lines)
+- `load_ome_dataset()`: Load and cache OME-Zarr data
+- `load_anndata()`: Load AnnData with infection annotation merging
+- `initialize_data()`: Initialize all data and embeddings
+- `get_embedding_data()`: Extract specific embedding dimensions
+- `parse_track_selection()`: Parse dropdown selections
+- Global state: `adata_demo`, `embedding_info`, `current_plot_data`
+
+### `image.py` - Image Processing (~160 lines)
+- `normalize_channel_image()`: Percentile-based contrast normalization
+- `extract_track_images()`: Multi-channel image extraction and compositing
+- Supports Phase3D, GFP, mCherry with opacity control
+
+### `plot.py` - Visualization (~180 lines)
+- `create_embedding_plot()`: Generate Plotly scatter plots
+- Infection status coloring with discrete categories
+- Track highlighting with FOV-specific filtering
+- Interactive hover tooltips
+
+### `handlers.py` - Event Logic (~230 lines)
+- `update_plot_and_selector()`: Handle embedding axis changes
+- `on_cell_selected()`: Handle track selection (full update)
+- `update_channel_images()`: Handle channel changes (lightweight update)
+
+### `ui.py` - User Interface (~220 lines)
+- `create_app()`: Build complete Gradio interface
+- Embedding controls and plot
+- Track selector with accordion for channel settings
+- Image gallery and track info display
+- Event wiring for all interactions
+
+## Usage
+
+### Run the Application
+```python
+python app.py
+```
+
+### Import as Library
+```python
+from dynaclr_viz import load_anndata, extract_track_images, create_embedding_plot
+
+# Load data
+adata, embeddings = load_anndata()
+
+# Generate images for specific track
+images = extract_track_images(
+    track_id=19,
+    fov_name="A/1/000000",
+    show_phase=True,
+    show_gfp=True
+)
+
+# Create plot
+fig = create_embedding_plot("PC1", "PC2", highlight_track_id=19)
+```
+
+## Key Features
+
+### Unique Cell Identification
+- Cells uniquely identified by `(track_id, fov_name)` pair
+- Dropdown shows: "Track 19 (A/1/000000)"
+- Prevents ambiguity when same track_id appears in multiple FOVs
+
+### Performance Optimized
+- Separate event handlers for different update types
+- Channel changes only update gallery (not plot)
+- Eliminates redundant plot re-renders
+
+### Clean Separation of Concerns
+- Data layer independent of visualization
+- Image processing reusable in batch scripts
+- UI and handlers separated for testability
+
+## Migration Notes
+
+### Original File
+- `new_dynaclr_demo.py`: 899 lines, monolithic
+- All code in single file
+
+### Refactored Structure
+- 7 modules averaging ~150 lines each
+- Clear boundaries and responsibilities
+- Entry point: 16 lines
+
+### Backward Compatibility
+- Original file kept as `new_dynaclr_demo.py`
+- New entry point: `app.py`
+- Both work identically
+
+## Development
+
+### Adding New Features
+1. **New embedding type**: Modify `data.load_anndata()`
+2. **New channel**: Update `image.extract_track_images()`
+3. **New visualization**: Add function to `plot.py`
+4. **New UI control**: Add to `ui.create_app()`
+
+### Testing Individual Modules
+```python
+# Test data loading
+python -c "from dynaclr_viz.data import initialize_data; initialize_data()"
+
+# Test image extraction
+python -c "from dynaclr_viz.image import extract_track_images; ..."
+
+# Test plotting
+python -c "from dynaclr_viz.plot import create_embedding_plot; ..."
+```

dynaclr_viz/__init__.py

@@ -0,0 +1,67 @@
+"""
+DynaCLR Visualization Package
+
+A modular package for visualizing cell embeddings and infection status
+with interactive microscopy image viewing.
+"""
+
+from .config import (
+    DATA_PATH,
+    OME_ZARR_PATH,
+    ANNDATA_PATH,
+    INFECTION_ANNOTATIONS_PATH,
+    INFECTION_COLOR_MAP,
+    DEFAULT_CROP_SIZE,
+    DEFAULT_CONTRAST,
+    DEFAULT_OPACITY,
+)
+from .data import (
+    load_ome_dataset,
+    load_anndata,
+    get_embedding_data,
+    get_all_embeddings,
+    get_fov_choices,
+    get_tracks_for_fov,
+    is_track_annotated,
+)
+from .image import extract_track_images, normalize_channel_image
+from .plot import create_embedding_plot
+from .handlers import (
+    update_plot_and_selector,
+    update_track_selector,
+    on_cell_selected,
+    update_channel_images,
+)
+from .ui import create_app
+
+__all__ = [
+    # Config
+    "DATA_PATH",
+    "OME_ZARR_PATH",
+    "ANNDATA_PATH",
+    "INFECTION_ANNOTATIONS_PATH",
+    "INFECTION_COLOR_MAP",
+    "DEFAULT_CROP_SIZE",
+    "DEFAULT_CONTRAST",
+    "DEFAULT_OPACITY",
+    # Data
+    "load_ome_dataset",
+    "load_anndata",
+    "get_embedding_data",
+    "get_all_embeddings",
+    "get_fov_choices",
+    "get_tracks_for_fov",
+    "is_track_annotated",
+    # Image
+    "extract_track_images",
+    "normalize_channel_image",
+    # Plot
+    "create_embedding_plot",
+    # Handlers
+    "update_plot_and_selector",
+    "update_track_selector",
+    "on_cell_selected",
+    "update_channel_images",
+    # UI
+    "create_app",
+]

dynaclr_viz/config.py

@@ -0,0 +1,37 @@
+"""Configuration and constants for DynaCLR visualization."""
+
+import os
+from pathlib import Path
+
+# Data paths - relative to repository root
+REPO_ROOT = Path(__file__).parent.parent
+DATA_PATH = REPO_ROOT / "data"
+
+# HuggingFace dataset configuration
+HF_DATASET_REPO = "chanzuckerberg/DynaCLR-data"
+USE_HF_DATASET = os.getenv("USE_HF_DATASET", "true").lower() == "true"
+
+# Data file paths (will use HF dataset if USE_HF_DATASET=true)
+OME_ZARR_PATH = DATA_PATH / "dataset.zarr"
+ANNDATA_PATH = DATA_PATH / "annotations_filtered.zarr"
+INFECTION_ANNOTATIONS_PATH = DATA_PATH / "track_infection_annotation.csv"
+
+# Visualization constants - colorblind-accessible palette
+INFECTION_COLOR_MAP = {
+    "infected": "#FF6B00",  # Bright orange (colorblind-accessible)
+    "uninfected": "#00D9FF",  # Bright cyan-blue (colorblind-accessible)
+    "unknown": "#9CA3AF",  # Gray
+}
+
+# Image processing defaults
+DEFAULT_CROP_SIZE = 160
+DEFAULT_CONTRAST = (10, 90)
+DEFAULT_OPACITY = 1.0
+
+# Plot settings
+PLOT_HEIGHT = 700
+MARKER_SIZE_NORMAL = 6
+MARKER_SIZE_HIGHLIGHTED = 10
+MARKER_OPACITY_NORMAL = 0.9
+MARKER_OPACITY_HIGHLIGHTED = 0.9
+MARKER_OPACITY_UNKNOWN = 0.2

dynaclr_viz/data.py

@@ -0,0 +1,263 @@
+"""Data loading and management for DynaCLR visualization."""
+
+import pandas as pd
+import anndata as ad
+from iohub import open_ome_zarr
+from huggingface_hub import snapshot_download
+from pathlib import Path
+
+from .config import (
+    OME_ZARR_PATH,
+    ANNDATA_PATH,
+    INFECTION_ANNOTATIONS_PATH,
+    HF_DATASET_REPO,
+    USE_HF_DATASET,
+    DATA_PATH,
+)
+
+# Global state for cached data
+ome_dataset = None
+adata_demo = None
+embedding_info = None
+all_embeddings = None
+embedding_to_key_idx = None
+current_plot_data = None
+# Track selection caching
+cached_fov_choices = None  # List of all FOV names
+cached_tracks_by_fov = None  # Dict: {fov_name: [track_ids]}
+cached_annotated_tracks = (
+    None  # Set of (track_id, fov_name) with infected/uninfected cells
+)
+
+
+def download_dataset_from_hf():
+    """Download dataset files from HuggingFace dataset repository.
+
+    This function downloads the entire dataset repository to a local cache
+    and returns paths to the downloaded files.
+
+    Returns:
+        tuple: (ome_zarr_path, anndata_path, infection_csv_path)
+    """
+    print(f"Downloading dataset from HuggingFace: {HF_DATASET_REPO}")
+
+    # Get HF token from environment (required for private repos)
+    # token = os.getenv("HF_TOKEN")
+    # if not token:
+    #     raise ValueError(
+    #         "HF_TOKEN environment variable not set. "
+    #         "Please set it to access the private dataset repository."
+    #     )
+
+    # Download the entire dataset repository
+    # This will cache files locally and reuse them on subsequent runs
+    cache_dir = snapshot_download(
+        repo_id=HF_DATASET_REPO,
+        repo_type="dataset",
+        # token=token,
+        cache_dir=str(DATA_PATH.parent / ".hf_cache"),
+    )
+
+    cache_path = Path(cache_dir)
+    print(f"Dataset cached to: {cache_path}")
+
+    # Return paths to the downloaded files
+    ome_zarr_path = cache_path / "dataset.zarr"
+    anndata_path = cache_path / "annotations_filtered.zarr"
+    infection_csv_path = cache_path / "track_infection_annotation.csv"
+
+    # Verify all files exist
+    for path, name in [
+        (ome_zarr_path, "dataset.zarr"),
+        (anndata_path, "annotations_filtered.zarr"),
+        (infection_csv_path, "track_infection_annotation.csv"),
+    ]:
+        if not path.exists():
+            raise FileNotFoundError(f"Expected file not found in dataset: {name}")
+
+    return ome_zarr_path, anndata_path, infection_csv_path
+
+
+def get_data_paths():
+    """Get data file paths, downloading from HF if USE_HF_DATASET is enabled.
+
+    Returns:
+        tuple: (ome_zarr_path, anndata_path, infection_csv_path)
+    """
+    if USE_HF_DATASET:
+        return download_dataset_from_hf()
+    else:
+        return OME_ZARR_PATH, ANNDATA_PATH, INFECTION_ANNOTATIONS_PATH
+
+
+def load_ome_dataset():
+    """Load OME-Zarr dataset once and reuse the handle."""
+    global ome_dataset
+    if ome_dataset is None:
+        ome_zarr_path, _, _ = get_data_paths()
+        print(f"Loading OME-Zarr dataset from: {ome_zarr_path}")
+        ome_dataset = open_ome_zarr(ome_zarr_path, mode="r")
+    return ome_dataset
+
+
+def load_anndata():
+    """Load AnnData and extract embedding information with infection annotations."""
+    _, anndata_path, infection_csv_path = get_data_paths()
+
+    print(f"Loading AnnData from: {anndata_path}")
+    adata = ad.read_zarr(anndata_path)
+
+    # Check if infection_status is already in obs (e.g., from filtered dataset)
+    if "infection_status" not in adata.obs.columns:
+        # Load infection annotations and merge with AnnData.obs
+        print(f"Loading infection annotations from: {infection_csv_path}")
+        infection_annotations = pd.read_csv(infection_csv_path)
+
+        # Merge infection status using (fov_name, id) as the composite unique key
+        # This is necessary because 'id' is only unique within each FOV
+        print("Merging infection annotations with AnnData.obs...")
+        adata.obs = adata.obs.merge(
+            infection_annotations[["fov_name", "id", "infection_status"]],
+            on=["fov_name", "id"],
+            how="left",
+        )
+
+        # Fill missing infection_status with 'unknown'
+        adata.obs["infection_status"] = adata.obs["infection_status"].fillna("unknown")
+
+    # Report infection status statistics
+    n_with_annot = (adata.obs["infection_status"] != "unknown").sum()
+    n_without_annot = (adata.obs["infection_status"] == "unknown").sum()
+    print(
+        f"  - Cells with infection annotations: {n_with_annot} "
+        f"({n_with_annot / len(adata.obs) * 100:.1f}%)"
+    )
+    print(
+        f"  - Cells without annotations: {n_without_annot} "
+        f"({n_without_annot / len(adata.obs) * 100:.1f}%)"
+    )
+
+    # Detect all embeddings from obsm
+    embeddings = {}
+    for key in adata.obsm.keys():
+        n_components = adata.obsm[key].shape[1]
+
+        if key == "X_pca":
+            # PCA components: PC1, PC2, ..., PC8
+            embeddings[key] = [f"PC{i + 1}" for i in range(n_components)]
+        elif key == "X_projections":
+            # Projection dimensions: Proj1, Proj2, ..., Proj32
+            embeddings[key] = [f"Proj{i + 1}" for i in range(n_components)]
+        else:
+            # Generic naming for any other embeddings
+            embeddings[key] = [f"{key}_{i + 1}" for i in range(n_components)]
+
+    print(f"Loaded {adata.shape[0]} cells with {adata.shape[1]} features")
+    print(f"Available embeddings: {list(embeddings.keys())}")
+
+    return adata, embeddings
+
+
+def initialize_data():
+    """Initialize all data and create embedding index."""
+    global adata_demo, embedding_info, all_embeddings, embedding_to_key_idx
+    global cached_fov_choices, cached_tracks_by_fov, cached_annotated_tracks
+
+    adata_demo, embedding_info = load_anndata()
+
+    # Create flat list of all embedding names for dropdowns
+    all_embeddings = []
+    embedding_to_key_idx = {}
+
+    for obsm_key, component_names in embedding_info.items():
+        for idx, component_name in enumerate(component_names):
+            all_embeddings.append(component_name)
+            embedding_to_key_idx[component_name] = (obsm_key, idx)
+
+    print(f"Total embedding dimensions available: {len(all_embeddings)}")
+
+    # Pre-compute FOV and track selections with filtering
+    print("Pre-computing FOV and track selections...")
+
+    # Filter tracks: keep only those with at least one infected or uninfected cell
+    print("Filtering tracks with infection annotations...")
+    track_groups = adata_demo.obs.groupby(["track_id", "fov_name"])["infection_status"]
+
+    cached_annotated_tracks = set()
+    for (track_id, fov_name), statuses in track_groups:
+        # Include track if it has at least one infected or uninfected cell
+        if any(status in ["infected", "uninfected"] for status in statuses):
+            cached_annotated_tracks.add((int(track_id), fov_name))
+
+    total_tracks = len(track_groups)
+    annotated_count = len(cached_annotated_tracks)
+    print(
+        f"Filtered tracks: {annotated_count} / {total_tracks} have infection annotations "
+        f"({annotated_count / total_tracks * 100:.1f}%)"
+    )
+
+    # Build FOV → Tracks mapping (only annotated tracks)
+    cached_tracks_by_fov = {}
+    for track_id, fov_name in cached_annotated_tracks:
+        if fov_name not in cached_tracks_by_fov:
+            cached_tracks_by_fov[fov_name] = []
+        cached_tracks_by_fov[fov_name].append(track_id)
+
+    # Sort track lists within each FOV
+    for fov_name in cached_tracks_by_fov:
+        cached_tracks_by_fov[fov_name].sort()
+
+    # Only show FOVs that have annotated tracks
+    cached_fov_choices = sorted(cached_tracks_by_fov.keys())
+
+    total_fovs = len(adata_demo.obs["fov_name"].unique())
+    print(
+        f"Cached annotated tracks for {len(cached_tracks_by_fov)} FOVs (out of {total_fovs} total FOVs)"
+    )
+
+    return adata_demo, embedding_info, all_embeddings
+
+
+def get_embedding_data(embedding_name):
+    """Extract embedding data for a given component name."""
+    obsm_key, component_idx = embedding_to_key_idx[embedding_name]
+    return adata_demo.obsm[obsm_key][:, component_idx]
+
+
+def get_all_embeddings():
+    """Get list of all available embedding names."""
+    return all_embeddings
+
+
+def get_fov_choices():
+    """Get pre-computed list of FOV choices for dropdown."""
+    return cached_fov_choices or []
+
+
+def get_tracks_for_fov(fov_name):
+    """Get list of annotated track IDs for a specific FOV.
+
+    Args:
+        fov_name: FOV name (e.g., "A/1/000000")
+
+    Returns:
+        list: Sorted list of track IDs with infection annotations in this FOV
+    """
+    if cached_tracks_by_fov is None:
+        return []
+    return cached_tracks_by_fov.get(fov_name, [])
+
+
+def is_track_annotated(track_id, fov_name):
+    """Check if a track has infection annotations.
+
+    Args:
+        track_id: Track ID
+        fov_name: FOV name
+
+    Returns:
+        bool: True if track has at least one infected or uninfected cell
+    """
+    if cached_annotated_tracks is None:
+        return False
+    return (int(track_id), fov_name) in cached_annotated_tracks

dynaclr_viz/handlers.py

@@ -0,0 +1,370 @@
+"""Event handlers for Gradio interface."""
+
+import gradio as gr
+import traceback
+
+from . import data
+from .image import extract_track_images
+from .plot import create_embedding_plot
+
+
+# Preset tracks showing infection transitions
+PRESET_TRACKS = [
+    {
+        "name": "Track 152 (64 timepoints)",
+        "track_id": 152,
+        "fov_name": "A/2/000001",
+        "description": "38 uninfected → 26 infected cells, transition at t=40",
+    },
+    {
+        "name": "Track 114 (49 timepoints)",
+        "track_id": 114,
+        "fov_name": "A/2/001000",
+        "description": "29 uninfected → 20 infected cells, transition at t=40",
+    },
+    {
+        "name": "Track 182 (55 timepoints)",
+        "track_id": 182,
+        "fov_name": "A/2/000000",
+        "description": "33 uninfected → 22 infected cells, transition at t=40",
+    },
+    {
+        "name": "Track 135 (46 timepoints)",
+        "track_id": 135,
+        "fov_name": "A/2/000000",
+        "description": "36 uninfected → 10 infected cells, starts at t=4",
+    },
+    {
+        "name": "Track 107 (46 timepoints)",
+        "track_id": 107,
+        "fov_name": "A/2/000001",
+        "description": "19 uninfected → 27 infected cells, transition at t=39",
+    },
+]
+
+
+def update_plot_and_selector(emb_x, emb_y):
+    """Update plot and populate FOV/track selectors.
+
+    Args:
+        emb_x: X-axis embedding name
+        emb_y: Y-axis embedding name
+
+    Returns:
+        tuple: (plotly.Figure, FOV dropdown, Track dropdown)
+    """
+    fig = create_embedding_plot(emb_x, emb_y)
+
+    # Get FOV choices
+    fov_choices = data.get_fov_choices()
+
+    # Initialize with first FOV's tracks (if available)
+    if fov_choices:
+        first_fov = fov_choices[0]
+        track_choices = data.get_tracks_for_fov(first_fov)
+    else:
+        first_fov = None
+        track_choices = []
+
+    return (
+        fig,
+        gr.Dropdown(choices=fov_choices, value=first_fov),
+        gr.Dropdown(choices=track_choices),
+    )
+
+
+def update_track_selector(fov_name):
+    """Update track dropdown based on FOV selection.
+
+    Args:
+        fov_name: Selected FOV name
+
+    Returns:
+        gr.Dropdown: Updated track dropdown with filtered choices
+    """
+    if not fov_name:
+        return gr.Dropdown(choices=[], value=None)
+
+    # Get annotated tracks for this FOV
+    track_choices = data.get_tracks_for_fov(fov_name)
+
+    return gr.Dropdown(choices=track_choices, value=None)
+
+
+def apply_preset(preset_name):
+    """Apply a preset track selection.
+
+    Args:
+        preset_name: Name of the preset to apply
+
+    Returns:
+        tuple: (fov_value, track_value, track_choices)
+    """
+    if not preset_name:
+        return gr.Dropdown(), gr.Dropdown()
+
+    # Find the preset
+    preset = None
+    for p in PRESET_TRACKS:
+        if p["name"] == preset_name:
+            preset = p
+            break
+
+    if not preset:
+        return gr.Dropdown(), gr.Dropdown()
+
+    # Get tracks for the FOV
+    track_choices = data.get_tracks_for_fov(preset["fov_name"])
+
+    return (
+        gr.Dropdown(value=preset["fov_name"]),
+        gr.Dropdown(choices=track_choices, value=preset["track_id"]),
+    )
+
+
+def build_channel_status_text(show_phase, show_gfp, show_mcherry):
+    """Build the channel status display text.
+
+    Args:
+        show_phase: Phase3D enabled flag
+        show_gfp: GFP enabled flag
+        show_mcherry: mCherry enabled flag
+
+    Returns:
+        str: Formatted channel status markdown
+    """
+    active_channels = []
+
+    if show_phase:
+        active_channels.append("🔬 **Phase3D** (structure/morphology)")
+    if show_gfp:
+        active_channels.append("🟢 **GFP** (green fluorescence)")
+    if show_mcherry:
+        active_channels.append("🟣 **mCherry** (red/magenta fluorescence)")
+
+    if not active_channels:
+        return "⚠️ **No channels enabled** - Please enable at least one channel in Channel Settings"
+
+    return " · ".join(active_channels)
+
+
+def update_channel_images(
+    fov_name,
+    track_id,
+    show_phase,
+    show_gfp,
+    show_mcherry,
+    phase_min,
+    phase_max,
+    phase_opacity,
+    gfp_min,
+    gfp_max,
+    gfp_opacity,
+    mcherry_min,
+    mcherry_max,
+    mcherry_opacity,
+):
+    """Update image gallery and channel status when channel settings change.
+
+    Args:
+        fov_name: Selected FOV name
+        track_id: Selected track ID
+        show_phase, show_gfp, show_mcherry: Channel enable flags
+        phase_min, phase_max: Phase contrast limits
+        phase_opacity: Phase opacity
+        gfp_min, gfp_max: GFP contrast limits
+        gfp_opacity: GFP opacity
+        mcherry_min, mcherry_max: mCherry contrast limits
+        mcherry_opacity: mCherry opacity
+
+    Returns:
+        tuple: (gallery_images, channel_status_text)
+    """
+    # Build channel status text
+    status_text = build_channel_status_text(show_phase, show_gfp, show_mcherry)
+
+    if not fov_name or track_id is None:
+        return [], status_text
+
+    try:
+        # Check if at least one channel is enabled
+        if not (show_phase or show_gfp or show_mcherry):
+            return [], status_text
+
+        # Extract images with current channel settings
+        images = extract_track_images(
+            track_id,
+            fov_name,
+            crop_size=160,
+            show_phase=show_phase,
+            show_gfp=show_gfp,
+            show_mcherry=show_mcherry,
+            phase_min=phase_min,
+            phase_max=phase_max,
+            phase_opacity=phase_opacity,
+            gfp_min=gfp_min,
+            gfp_max=gfp_max,
+            gfp_opacity=gfp_opacity,
+            mcherry_min=mcherry_min,
+            mcherry_max=mcherry_max,
+            mcherry_opacity=mcherry_opacity,
+        )
+
+        return images, status_text
+
+    except Exception as e:
+        print(f"Error in update_channel_images: {e}")
+        return [], status_text
+
+
+def on_cell_selected(
+    fov_name,
+    track_id,
+    show_phase,
+    show_gfp,
+    show_mcherry,
+    phase_min,
+    phase_max,
+    phase_opacity,
+    gfp_min,
+    gfp_max,
+    gfp_opacity,
+    mcherry_min,
+    mcherry_max,
+    mcherry_opacity,
+    embedding_x,
+    embedding_y,
+):
+    """Handle cell selection - updates gallery, info, and highlighted plot.
+
+    Args:
+        fov_name: Selected FOV name
+        track_id: Selected track ID
+        show_phase, show_gfp, show_mcherry: Channel flags
+        phase_min, phase_max, phase_opacity: Phase settings
+        gfp_min, gfp_max, gfp_opacity: GFP settings
+        mcherry_min, mcherry_max, mcherry_opacity: mCherry settings
+        embedding_x, embedding_y: Current embedding axes
+
+    Returns:
+        tuple: (gallery_images, info_text, highlighted_plot)
+    """
+    if not fov_name or track_id is None or data.current_plot_data is None:
+        # No selection - return to normal plot without highlighting
+        normal_fig = create_embedding_plot(
+            embedding_x, embedding_y, highlight_track_id=None
+        )
+        return (
+            [],
+            "Select a FOV and track to view the timeline",
+            normal_fig,
+        )
+
+    try:
+        # Get all cells in this specific track within this specific FOV
+        track_cells = data.adata_demo.obs[
+            (data.adata_demo.obs["track_id"] == track_id)
+            & (data.adata_demo.obs["fov_name"] == fov_name)
+        ]
+
+        if len(track_cells) == 0:
+            normal_fig = create_embedding_plot(
+                embedding_x, embedding_y, highlight_track_id=None
+            )
+            return (
+                [],
+                f"No cells found for track {track_id} in FOV {fov_name}",
+                normal_fig,
+            )
+
+        # Build channel list for display
+        active_channels = []
+        if show_phase:
+            active_channels.append("Phase3D")
+        if show_gfp:
+            active_channels.append("GFP (green)")
+        if show_mcherry:
+            active_channels.append("mCherry (periwinkle)")
+
+        if not active_channels:
+            # Create highlighted plot without images
+            highlighted_fig = create_embedding_plot(
+                embedding_x,
+                embedding_y,
+                highlight_track_id=track_id,
+                highlight_fov_name=fov_name,
+            )
+            return (
+                [],
+                "⚠️ Please select at least one channel to display",
+                highlighted_fig,
+            )
+
+        # Extract multi-channel images for all timepoints
+        print(
+            f"Extracting images for track {track_id} in FOV {fov_name} "
+            f"({len(track_cells)} timepoints) with channels: {active_channels}..."
+        )
+        images = extract_track_images(
+            track_id,
+            fov_name,
+            crop_size=160,
+            show_phase=show_phase,
+            show_gfp=show_gfp,
+            show_mcherry=show_mcherry,
+            phase_min=phase_min,
+            phase_max=phase_max,
+            phase_opacity=phase_opacity,
+            gfp_min=gfp_min,
+            gfp_max=gfp_max,
+            gfp_opacity=gfp_opacity,
+            mcherry_min=mcherry_min,
+            mcherry_max=mcherry_max,
+            mcherry_opacity=mcherry_opacity,
+        )
+
+        if len(images) == 0:
+            highlighted_fig = create_embedding_plot(
+                embedding_x,
+                embedding_y,
+                highlight_track_id=track_id,
+                highlight_fov_name=fov_name,
+            )
+            return [], f"Failed to load images for track {track_id}", highlighted_fig
+
+        # Create updated plot with highlighted track in specific FOV
+        highlighted_fig = create_embedding_plot(
+            embedding_x,
+            embedding_y,
+            highlight_track_id=track_id,
+            highlight_fov_name=fov_name,
+        )
+
+        # Create metadata info text
+        t_min, t_max = track_cells["t"].min(), track_cells["t"].max()
+        channels_text = ", ".join(active_channels)
+
+        # Get infection status for this track
+        track_infection_statuses = track_cells["infection_status"].unique()
+        infection_text = (
+            ", ".join(track_infection_statuses)
+            if len(track_infection_statuses) > 0
+            else "unknown"
+        )
+
+        info_text = f"""
+**Track:** {track_id} | **FOV:** {fov_name}
+**Duration:** T{t_min}→T{t_max} ({len(track_cells)} obs) | **Infection:** {infection_text}
+**Channels:** {channels_text}
+        """
+
+        print(f"Successfully loaded {len(images)} images for track {track_id}")
+        return images, info_text, highlighted_fig
+
+    except Exception as e:
+        print(f"Error in on_cell_selected: {e}")
+        traceback.print_exc()
+        normal_fig = create_embedding_plot(
+            embedding_x, embedding_y, highlight_track_id=None
+        )
+        return [], f"Error loading track images: {str(e)}", normal_fig

dynaclr_viz/image.py

@@ -0,0 +1,154 @@
+"""Image processing and extraction for microscopy data."""
+
+import numpy as np
+from PIL import Image
+from skimage.exposure import rescale_intensity
+
+from .config import DEFAULT_CROP_SIZE
+from . import data
+
+
+def normalize_channel_image(channel_array, contrast_min=1, contrast_max=99):
+    """Normalize channel image for display using percentile-based clipping.
+
+    Args:
+        channel_array: Raw channel data
+        contrast_min: Minimum percentile for clipping (0-100)
+        contrast_max: Maximum percentile for clipping (0-100)
+
+    Returns:
+        Normalized uint8 array (0-255)
+    """
+    p_min = np.percentile(channel_array, contrast_min)
+    p_max = np.percentile(channel_array, contrast_max)
+    clipped = np.clip(channel_array, p_min, p_max)
+    normalized = rescale_intensity(clipped, out_range=(0, 255))
+    return normalized.astype(np.uint8)
+
+
+def extract_track_images(
+    track_id,
+    fov_name,
+    crop_size=DEFAULT_CROP_SIZE,
+    show_phase=True,
+    show_gfp=False,
+    show_mcherry=False,
+    phase_min=10,
+    phase_max=90,
+    gfp_min=10,
+    gfp_max=90,
+    mcherry_min=10,
+    mcherry_max=90,
+    phase_opacity=1.0,
+    gfp_opacity=1.0,
+    mcherry_opacity=1.0,
+):
+    """Extract multi-channel crops for all timepoints in a track within a specific FOV.
+
+    Args:
+        track_id: Track ID to extract images for
+        fov_name: Field of view name to filter by
+        crop_size: Size of the square crop around cell centroid
+        show_phase: Show Phase3D channel (grayscale)
+        show_gfp: Show GFP channel (green)
+        show_mcherry: Show mCherry channel (periwinkle)
+        phase_min, phase_max: Contrast limits for Phase (percentile 0-100)
+        gfp_min, gfp_max: Contrast limits for GFP (percentile 0-100)
+        mcherry_min, mcherry_max: Contrast limits for mCherry (percentile 0-100)
+        phase_opacity: Opacity for Phase channel (0-1)
+        gfp_opacity: Opacity for GFP channel (0-1)
+        mcherry_opacity: Opacity for mCherry channel (0-1)
+
+    Returns:
+        List of tuples (PIL.Image, label_text)
+    """
+    # Query AnnData for all cells in this track within this specific FOV
+    track_cells = data.adata_demo.obs[
+        (data.adata_demo.obs["track_id"] == track_id)
+        & (data.adata_demo.obs["fov_name"] == fov_name)
+    ]
+    track_cells = track_cells.sort_values("t")  # Sort chronologically
+
+    # Load OME-Zarr dataset (cached after first call)
+    dataset = data.load_ome_dataset()
+
+    images = []
+    for _, cell in track_cells.iterrows():
+        try:
+            fov = cell["fov_name"]
+            t = int(cell["t"])
+            y_center = int(cell["y"])
+            x_center = int(cell["x"])
+
+            # Access position
+            position = dataset[fov]
+
+            # Crop boundaries with boundary handling
+            half_crop = crop_size // 2
+            y_min = max(0, y_center - half_crop)
+            y_max = min(position["0"].shape[3], y_center + half_crop)  # Shape is TCZYX
+            x_min = max(0, x_center - half_crop)
+            x_max = min(position["0"].shape[4], x_center + half_crop)
+
+            # Initialize composite as black RGB image
+            composite = np.zeros((y_max - y_min, x_max - x_min, 3), dtype=np.float32)
+
+            # Extract and composite channels with opacity control
+            if show_phase:
+                # Phase channel (C=0) - display as grayscale base
+                phase_data = position["0"][t, 0, 0, y_min:y_max, x_min:x_max]
+                normalized_phase = normalize_channel_image(
+                    phase_data, phase_min, phase_max
+                ).astype(np.float32)
+
+                # Apply opacity
+                normalized_phase = normalized_phase * phase_opacity
+
+                # If showing fluorescence channels, dim the phase to not overwhelm
+                if show_gfp or show_mcherry:
+                    normalized_phase = normalized_phase * 0.4
+
+                # Convert grayscale to RGB by setting all channels equal
+                composite[:, :, 0] += normalized_phase
+                composite[:, :, 1] += normalized_phase
+                composite[:, :, 2] += normalized_phase
+
+            if show_gfp:
+                # GFP channel (C=1) - green overlay with opacity
+                gfp_data = position["0"][t, 1, 0, y_min:y_max, x_min:x_max]
+                normalized_gfp = normalize_channel_image(
+                    gfp_data, gfp_min, gfp_max
+                ).astype(np.float32)
+
+                # Apply green color with opacity
+                composite[:, :, 1] += normalized_gfp * gfp_opacity
+
+            if show_mcherry:
+                # mCherry channel (C=2) - periwinkle overlay with opacity
+                mcherry_data = position["0"][t, 2, 0, y_min:y_max, x_min:x_max]
+                normalized_mcherry = normalize_channel_image(
+                    mcherry_data, mcherry_min, mcherry_max
+                ).astype(np.float32)
+
+                # Apply periwinkle color with opacity (R=43%, G=31%, B=98%)
+                composite[:, :, 0] += normalized_mcherry * 0.43 * mcherry_opacity
+                composite[:, :, 1] += normalized_mcherry * 0.31 * mcherry_opacity
+                composite[:, :, 2] += normalized_mcherry * 0.98 * mcherry_opacity
+
+            # Clip and convert to uint8
+            composite = np.clip(composite, 0, 255).astype(np.uint8)
+
+            # Convert to PIL Image
+            img = Image.fromarray(composite, mode="RGB")
+
+            # Create label with timepoint info
+            label = f"T={t}"
+            images.append((img, label))
+
+        except Exception as e:
+            print(
+                f"Warning: Failed to load image for track {track_id}, t={cell['t']}: {e}"
+            )
+            continue
+
+    return images

dynaclr_viz/plot.py

@@ -0,0 +1,197 @@
+"""Plotly visualization functions for cell embedding plots."""
+
+import numpy as np
+import pandas as pd
+import plotly.graph_objects as go
+
+from .config import (
+    INFECTION_COLOR_MAP,
+    PLOT_HEIGHT,
+    MARKER_SIZE_NORMAL,
+    MARKER_SIZE_HIGHLIGHTED,
+    MARKER_OPACITY_NORMAL,
+    MARKER_OPACITY_UNKNOWN,
+)
+from . import data
+
+
+def create_embedding_plot(
+    embedding_x="PC1",
+    embedding_y="PC2",
+    highlight_track_id=None,
+    highlight_fov_name=None,
+):
+    """Create interactive Plotly scatter plot of embeddings with infection status coloring.
+
+    Args:
+        embedding_x: X-axis embedding name
+        embedding_y: Y-axis embedding name
+        highlight_track_id: If provided, highlight this specific track
+        highlight_fov_name: If provided with track_id, highlight only this FOV
+
+    Returns:
+        plotly.graph_objects.Figure: Interactive Plotly figure
+    """
+    # Get embedding coordinates
+    x_data = data.get_embedding_data(embedding_x)
+    y_data = data.get_embedding_data(embedding_y)
+
+    # Get metadata for coloring and hover
+    obs_data = data.adata_demo.obs
+
+    # Map each observation to its color
+    color_values = obs_data["infection_status"].map(INFECTION_COLOR_MAP).values
+
+    # Map infection status to opacity (unknown cells more transparent)
+    opacity_values = (
+        obs_data["infection_status"]
+        .map(
+            {
+                "infected": MARKER_OPACITY_NORMAL,
+                "uninfected": MARKER_OPACITY_NORMAL,
+                "unknown": MARKER_OPACITY_UNKNOWN,
+            }
+        )
+        .values
+    )
+
+    # Create DataFrame for plotting
+    plot_data = pd.DataFrame(
+        {
+            "x": x_data,
+            "y": y_data,
+            "color": color_values,
+            "opacity": opacity_values,
+            "id": obs_data["id"].values,
+            "track_id": obs_data["track_id"].values,
+            "timepoint": obs_data["t"].values,
+            "fov_name": obs_data["fov_name"].values,
+            "x_pos": obs_data["x"].values,
+            "y_pos": obs_data["y"].values,
+            "infection_status": obs_data["infection_status"].values,
+        }
+    )
+
+    # Store for potential future interactions
+    data.current_plot_data = plot_data
+
+    # Create Plotly figure
+    fig = go.Figure()
+
+    # If highlighting a specific track, split into background and foreground
+    if highlight_track_id is not None:
+        # Create filter for the specific track (and FOV if specified)
+        if highlight_fov_name is not None:
+            # Highlight only cells from this specific track in this specific FOV
+            highlight_mask = (plot_data["track_id"] == highlight_track_id) & (
+                plot_data["fov_name"] == highlight_fov_name
+            )
+        else:
+            # Highlight all cells with this track_id (across all FOVs)
+            highlight_mask = plot_data["track_id"] == highlight_track_id
+
+        # Background: all cells NOT in the highlighted set
+        bg_data = plot_data[~highlight_mask]
+        if len(bg_data) > 0:
+            fig.add_trace(
+                go.Scattergl(
+                    x=bg_data["x"],
+                    y=bg_data["y"],
+                    mode="markers",
+                    marker=dict(
+                        size=3,
+                        color="lightgray",
+                        opacity=0.2,
+                        line=dict(width=0),
+                    ),
+                    hoverinfo="skip",
+                    showlegend=False,
+                )
+            )
+
+        # Foreground: selected track in selected FOV (highlighted)
+        fg_data = plot_data[highlight_mask].copy()
+        if len(fg_data) > 0:
+            # Sort by timepoint to ensure correct trajectory order
+            fg_data = fg_data.sort_values("timepoint").reset_index(drop=True)
+            n_points = len(fg_data)
+
+            # Add the main trajectory trace with markers and line
+            fig.add_trace(
+                go.Scattergl(
+                    x=fg_data["x"],
+                    y=fg_data["y"],
+                    mode="markers+lines",
+                    marker=dict(
+                        size=MARKER_SIZE_HIGHLIGHTED,
+                        color=fg_data["color"],
+                        opacity=0.9,
+                        line=dict(width=1, color="white"),
+                    ),
+                    line=dict(width=2, color="rgba(255, 255, 255, 0.5)"),
+                    text=[
+                        f"ID: {row['id']}<br>"
+                        f"Track: {row['track_id']}<br>"
+                        f"Time: {row['timepoint']}<br>"
+                        f"FOV: {row['fov_name']}<br>"
+                        f"Infection: {row['infection_status']}<br>"
+                        f"Position: ({row['x_pos']}, {row['y_pos']})<br>"
+                        f"{embedding_x}: {row['x']:.2f}<br>"
+                        f"{embedding_y}: {row['y']:.2f}"
+                        for _, row in fg_data.iterrows()
+                    ],
+                    hovertemplate="%{text}<extra></extra>",
+                    showlegend=False,
+                )
+            )
+    else:
+        # Standard view: all cells with normal coloring and variable opacity
+        fig.add_trace(
+            go.Scattergl(
+                x=plot_data["x"],
+                y=plot_data["y"],
+                mode="markers",
+                marker=dict(
+                    size=MARKER_SIZE_NORMAL,
+                    color=plot_data["color"],
+                    opacity=plot_data["opacity"],  # Use variable opacity per point
+                    line=dict(width=0),
+                ),
+                text=[
+                    f"ID: {row['id']}<br>"
+                    f"Track: {row['track_id']}<br>"
+                    f"Time: {row['timepoint']}<br>"
+                    f"FOV: {row['fov_name']}<br>"
+                    f"Infection: {row['infection_status']}<br>"
+                    f"Position: ({row['x_pos']}, {row['y_pos']})<br>"
+                    f"{embedding_x}: {row['x']:.2f}<br>"
+                    f"{embedding_y}: {row['y']:.2f}"
+                    for _, row in plot_data.iterrows()
+                ],
+                hovertemplate="%{text}<extra></extra>",
+            )
+        )
+
+    # Create title
+    title_text = f"Cell Embedding Visualization: {embedding_x} vs {embedding_y}"
+    if highlight_track_id is not None:
+        if highlight_fov_name is not None:
+            title_text += (
+                f" (Highlighting Track {highlight_track_id} - {highlight_fov_name})"
+            )
+        else:
+            title_text += f" (Highlighting Track {highlight_track_id})"
+
+    fig.update_layout(
+        title=title_text,
+        xaxis_title=embedding_x,
+        yaxis_title=embedding_y,
+        hovermode="closest",
+        height=PLOT_HEIGHT,
+        showlegend=False,
+        template="plotly_dark",
+    )
+
+    print(f"Created plot with {len(plot_data)} cells, colored by infection status")
+
+    return fig

dynaclr_viz/ui.py

@@ -0,0 +1,267 @@
+"""Gradio UI components and layout for DynaCLR visualization."""
+
+import gradio as gr
+
+from . import data
+from .handlers import (
+    on_cell_selected,
+    update_channel_images,
+    update_plot_and_selector,
+    update_track_selector,
+    apply_preset,
+    build_channel_status_text,
+    PRESET_TRACKS,
+)
+
+
+def create_app():
+    """Create and configure the Gradio application.
+
+    Returns:
+        gr.Blocks: Configured Gradio demo
+    """
+    # Initialize data first
+    adata, embeddings, all_emb = data.initialize_data()
+
+    with gr.Blocks(title="Cell Embedding Visualization") as demo:
+        gr.Markdown("# 🔬 DynaCLR: Cell Embedding Visualization")
+        gr.Markdown(
+            f"Exploring **{adata.shape[0]:,} cells** colored by infection status"
+        )
+        gr.Markdown(
+            '**Paper:** Hirata-Miyasaki E., Pradeep S., Liu Z., et al. "DynaCLR: Contrastive Learning of Cellular Dynamics with Temporal Regularization." '
+            "[arXiv:2410.11281](https://arxiv.org/abs/2410.11281) (2025)\n\n"
+            "**GitHub Repository:** [mehta-lab/VisCy](https://github.com/mehta-lab/viscy)"
+        )
+        gr.Markdown("---")
+
+        # Embedding plot section
+        gr.Markdown("## Embedding Plot")
+        with gr.Row():
+            embedding_x = gr.Dropdown(
+                choices=all_emb, value="PC1", label="X-axis", scale=1
+            )
+            embedding_y = gr.Dropdown(
+                choices=all_emb, value="PC2", label="Y-axis", scale=1
+            )
+
+        scatter_plot = gr.Plot(label="Embedding Scatter Plot")
+
+        gr.Markdown("**Legend:** 🟠 Infected · 🔵 Uninfected · ⚪ Unknown")
+
+        # Track viewer section
+        gr.Markdown("---")
+        gr.Markdown("## Track Inspector")
+        gr.Markdown("Select a FOV and track to view timeline and microscopy images")
+
+        # Presets section
+        gr.Markdown("### 🎯 Featured Tracks: Infection Transitions")
+        gr.Markdown("*Quick access to tracks showing dynamic infection state changes*")
+
+        preset_selector = gr.Dropdown(
+            choices=[p["name"] for p in PRESET_TRACKS],
+            label="Select a Preset Track",
+            info="These tracks show cells transitioning from uninfected to infected states",
+            value=None,
+            scale=2,
+        )
+
+        with gr.Accordion("📖 Preset Details", open=False):
+            preset_info_md = "\n\n".join(
+                [
+                    f"**{p['name']}**\n- {p['description']}\n- FOV: `{p['fov_name']}`"
+                    for p in PRESET_TRACKS
+                ]
+            )
+            gr.Markdown(preset_info_md)
+
+        gr.Markdown("### Manual Selection")
+
+        # Two-level selector: FOV → Track
+        with gr.Row():
+            fov_selector = gr.Dropdown(
+                choices=[],
+                label="Field of View (FOV)",
+                info="Select imaging field of view",
+                filterable=True,
+                scale=1,
+            )
+            track_selector = gr.Dropdown(
+                choices=[],
+                label="Track ID",
+                info="Annotated tracks only (filtered: has infected/uninfected cells)",
+                filterable=True,
+                scale=1,
+            )
+
+        # Channel Settings Accordion
+        with gr.Accordion("Channel Settings", open=False):
+            gr.Markdown("*Adjust contrast and opacity for each microscopy channel*")
+
+            # Phase3D channel
+            with gr.Group():
+                gr.Markdown("**Phase3D**")
+                show_phase = gr.Checkbox(label="Enable Phase3D", value=True)
+                with gr.Row():
+                    phase_contrast = gr.Slider(
+                        minimum=0, maximum=100, value=10, step=0.1, label="Min %"
+                    )
+                    phase_max_slider = gr.Slider(
+                        minimum=0, maximum=100, value=90, step=0.1, label="Max %"
+                    )
+                phase_opacity = gr.Slider(
+                    minimum=0, maximum=1, value=1.0, step=0.05, label="Opacity"
+                )
+
+            # GFP channel
+            with gr.Group():
+                gr.Markdown("**GFP (Green)**")
+                show_gfp = gr.Checkbox(label="Enable GFP", value=True)
+                with gr.Row():
+                    gfp_contrast = gr.Slider(
+                        minimum=0, maximum=100, value=10, step=0.1, label="Min %"
+                    )
+                    gfp_max_slider = gr.Slider(
+                        minimum=0, maximum=100, value=90, step=0.1, label="Max %"
+                    )
+                gfp_opacity = gr.Slider(
+                    minimum=0, maximum=1, value=1.0, step=0.05, label="Opacity"
+                )
+
+            # mCherry channel
+            with gr.Group():
+                gr.Markdown("**mCherry (Periwinkle)**")
+                show_mcherry = gr.Checkbox(label="Enable mCherry", value=True)
+                with gr.Row():
+                    mcherry_contrast = gr.Slider(
+                        minimum=0, maximum=100, value=10, step=0.1, label="Min %"
+                    )
+                    mcherry_max_slider = gr.Slider(
+                        minimum=0, maximum=100, value=90, step=0.1, label="Max %"
+                    )
+                mcherry_opacity = gr.Slider(
+                    minimum=0, maximum=1, value=1.0, step=0.05, label="Opacity"
+                )
+
+        # Channel Status Display - always visible
+        gr.Markdown("### Currently Displayed Channels")
+        channel_status = gr.Markdown(
+            value="🔬 **Phase3D** (structure/morphology) · 🟢 **GFP** (green fluorescence) · 🟣 **mCherry** (red/magenta fluorescence)",
+            elem_classes=["channel-status-info"],
+        )
+
+        # Image gallery
+        lineage_gallery = gr.Gallery(
+            label="Track Timeline",
+            show_label=True,
+            columns=8,
+            rows=2,
+            object_fit="contain",
+            height=400,
+        )
+
+        # Event wiring
+        # Connect embedding controls to plot and selector initialization
+        for component in [embedding_x, embedding_y]:
+            component.change(
+                fn=update_plot_and_selector,
+                inputs=[embedding_x, embedding_y],
+                outputs=[scatter_plot, fov_selector, track_selector],
+            )
+
+        # Connect preset selector to FOV and track selectors
+        # Using .then() to set both FOV and track without triggering intermediate events
+        preset_selector.select(
+            fn=apply_preset,
+            inputs=[preset_selector],
+            outputs=[fov_selector, track_selector],
+        )
+
+        # Connect FOV selector to track selector (cascading)
+        # Only triggers on manual FOV selection, not on preset updates
+        fov_selector.select(
+            fn=update_track_selector,
+            inputs=[fov_selector],
+            outputs=[track_selector],
+        )
+
+        # Inputs for cell selection (full update)
+        cell_selection_inputs = [
+            fov_selector,
+            track_selector,
+            show_phase,
+            show_gfp,
+            show_mcherry,
+            phase_contrast,
+            phase_max_slider,
+            phase_opacity,
+            gfp_contrast,
+            gfp_max_slider,
+            gfp_opacity,
+            mcherry_contrast,
+            mcherry_max_slider,
+            mcherry_opacity,
+            embedding_x,
+            embedding_y,
+        ]
+
+        # Inputs for channel updates (lightweight)
+        channel_only_inputs = [
+            fov_selector,
+            track_selector,
+            show_phase,
+            show_gfp,
+            show_mcherry,
+            phase_contrast,
+            phase_max_slider,
+            phase_opacity,
+            gfp_contrast,
+            gfp_max_slider,
+            gfp_opacity,
+            mcherry_contrast,
+            mcherry_max_slider,
+            mcherry_opacity,
+        ]
+
+        # Info display for track metadata
+        lineage_info = gr.Markdown(
+            value="Select a FOV and track to view the timeline",
+            elem_classes=["track-info"],
+        )
+
+        # Connect track selector to full update
+        track_selector.change(
+            fn=on_cell_selected,
+            inputs=cell_selection_inputs,
+            outputs=[lineage_gallery, lineage_info, scatter_plot],
+        )
+
+        # Connect channel controls to update gallery and status display
+        for control in [
+            show_phase,
+            show_gfp,
+            show_mcherry,
+            phase_contrast,
+            phase_max_slider,
+            phase_opacity,
+            gfp_contrast,
+            gfp_max_slider,
+            gfp_opacity,
+            mcherry_contrast,
+            mcherry_max_slider,
+            mcherry_opacity,
+        ]:
+            control.change(
+                fn=update_channel_images,
+                inputs=channel_only_inputs,
+                outputs=[lineage_gallery, channel_status],
+            )
+
+        # Initialize plot and selectors on load
+        demo.load(
+            fn=update_plot_and_selector,
+            inputs=[embedding_x, embedding_y],
+            outputs=[scatter_plot, fov_selector, track_selector],
+        )
+
+    return demo

requirements.txt

@@ -0,0 +1,29 @@
+# Core dependencies for DynaCLR Visualization on Hugging Face Spaces
+
+# Gradio for the web interface
+gradio==6.0.2
+
+# Data handling and visualization
+plotly>=6.3.0
+pandas>=2.0.0
+numpy>=1.24.0
+
+# AnnData for single-cell analysis
+anndata>=0.10.0
+
+# OME-Zarr and image I/O
+iohub[tensorstore]>=0.3.0a2
+
+# Image processing
+scikit-image>=0.22.0
+
+# Zarr for data storage
+zarr>=2.17.0
+
+# HuggingFace Hub for dataset loading
+huggingface_hub>=1.1.7
+
+# Additional dependencies for data handling
+xarray<=2025.9.0
+datashader>=0.18.2
+matplotlib>=3.10.0