README.md

---
title: DynaCLR
emoji: 🌖
colorFrom: gray
colorTo: purple
sdk: gradio
sdk_version: 6.0.2
app_file: app.py
pinned: false
python_version: 3.13
license: cc-by-nc-4.0
---

# 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

CC-BY-NC-4.0

## Contact

For questions or issues, please open an issue on the [VisCy GitHub repository](https://github.com/mehta-lab/VisCy/issues).