README.md

---
title: Spatial Transcriptomics Viewer
emoji: 🧬
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit
---

# Spatial Transcriptomics Viewer

A web-based tool for visualizing spatial gene expression from AnnData (.h5ad) files.

## Features

- **Interactive Visualization**: Explore spatial gene expression with interactive Plotly plots
- **Memory Efficient**: Uses AnnData backed mode for handling large datasets
- **Flexible Input**: Load data from URLs (HuggingFace, Zenodo) or upload files
- **Single-Gene Queries**: Visualize expression of individual genes across spatial coordinates
- **Expression Statistics**: Get detailed statistics for each gene
- **Customizable**: Adjust point size, color scale, and transformations

## Quick Start

### Using the Public Demo

1. Visit the Space URL
2. Load your data:
   - **URL**: Paste a link to your h5ad file
   - **Upload**: Upload your h5ad file directly (< 2GB recommended)
3. Enter a gene name and visualize!

### For Heavy Usage: Duplicate This Space

For large files or frequent use, we recommend duplicating this Space to your account:

1. Click the **⋮** menu at the top right
2. Select **"Duplicate this Space"**
3. Choose your HuggingFace account
4. (Optional) Upgrade to persistent storage for better performance

**Benefits of Duplicating:**
- Independent computing resources
- No queueing with other users
- Private data processing
- Customizable settings
- Optional paid upgrades for more resources

## Data Requirements

Your h5ad file must contain:
- `adata.obsm['spatial']`: 2D spatial coordinates (N × 2 array)
- Gene expression data in `adata.X`
- Gene names in `adata.var_names`

**Supported formats:**
- Visium (10x Genomics)
- MERFISH
- seqFISH
- Any spatial transcriptomics data in AnnData format

## How It Works

### Architecture

```
User Input (URL/Upload)
    ↓
Load h5ad with backed='r' (memory efficient)
    ↓
Validate spatial coordinates
    ↓
Query single gene expression
    ↓
Plotly interactive visualization
```

### Memory Efficiency

This tool uses AnnData's **backed mode** (`backed='r'`), which means:
- Files are read from disk on-demand
- Only requested data is loaded into memory
- Can handle files much larger than available RAM
- Suitable for large-scale spatial transcriptomics datasets

## Technical Details

### Stack
- **Frontend**: Gradio 4.0+
- **Backend**: Python 3.9+
- **Data**: AnnData, scanpy
- **Visualization**: Plotly
- **Platform**: Hugging Face Spaces

### File Size Limits

**Public Space:**
- Recommended: < 2GB
- Maximum: ~10GB (may be slow)

**Duplicated Space (Free):**
- Recommended: < 5GB
- With persistent storage upgrade: 50GB+

### URL Sources

Supported domains for URL input:
- `huggingface.co` - HuggingFace Datasets
- `zenodo.org` - Zenodo repositories
- `s3.amazonaws.com` - S3 buckets

## Usage Examples

### Example 1: Visualize from HuggingFace Dataset

```python
# If you have a h5ad file in a HuggingFace dataset:
URL = "https://huggingface.co/datasets/{username}/{dataset}/resolve/main/data.h5ad"

# Paste this URL in the tool and load
# Then enter gene names like: "GAPDH", "ACTB", "MYC"
```

### Example 2: Prepare Your Own Data

```python
import scanpy as sc
import numpy as np

# Load your data
adata = sc.read_10x_h5("your_data.h5")

# Add spatial coordinates (if not already present)
# Example: load from spatial folder
spatial = sc.read_visium("path/to/spatial_folder")
adata.obsm['spatial'] = spatial.obsm['spatial']

# Save as h5ad
adata.write("your_spatial_data.h5ad")

# Upload to HuggingFace Dataset or use directly
```

## Privacy & Data Security

### Public Space
- Files are processed in **temporary storage**
- No permanent data retention
- Cleared after session ends
- Not suitable for sensitive data

### Duplicated Private Space
- Data stays in your account
- Full control over access
- Suitable for private research data
- Can delete anytime

## Limitations

- **No preprocessing**: Tool does not normalize, scale, or transform data
- **Read-only**: Cannot modify or save h5ad files
- **Single gene**: Visualize one gene at a time
- **2D spatial only**: Requires 2D coordinates in `obsm['spatial']`

## Troubleshooting

### "Spatial coordinates not found"
- Check that your h5ad contains `adata.obsm['spatial']`
- Ensure it's a 2D array (N × 2)

### "Gene not found"
- Check gene name spelling
- Use exact gene names from `adata.var_names`
- Tool will suggest similar gene names

### "File too large" or slow loading
- Try duplicating the Space for more resources
- Consider subsetting your data
- Use URL input instead of upload

### Memory errors
- Ensure backed mode is working (check file size limits)
- Duplicate Space for more RAM
- Consider downsampling your dataset

## Development

### Local Setup

```bash
# Clone the repository
git clone <repo_url>
cd spatial-viewer

# Install dependencies
pip install -r requirements.txt

# Run locally
python app.py
```

### Project Structure

```
spatial-viewer/
├── app.py                  # Main Gradio application
├── utils/
│   ├── __init__.py
│   ├── loader.py           # H5ad loading with backed mode
│   ├── validator.py        # AnnData validation
│   └── plot.py             # Plotly visualization
├── data/
│   └── demo.h5ad           # (Optional) Demo dataset
├── requirements.txt        # Python dependencies
├── README.md               # This file
└── .huggingface/
    └── space_config.yaml   # HF Space configuration
```

## Contributing

Contributions welcome! Areas for improvement:
- Multi-gene visualization
- Additional plot types
- Performance optimizations
- UI enhancements
- Documentation

## Citation

If you use this tool in your research, please cite:

```bibtex
@software{spatial_viewer,
  title = {Spatial Transcriptomics Viewer},
  author = {Your Name},
  year = {2025},
  url = {https://huggingface.co/spaces/...}
}
```

## License

MIT License - see LICENSE file for details

## Acknowledgments

- Built with [Gradio](https://gradio.app/)
- Uses [AnnData](https://anndata.readthedocs.io/) and [Scanpy](https://scanpy.readthedocs.io/)
- Hosted on [Hugging Face Spaces](https://huggingface.co/spaces)

---

## 中文说明

### 功能特点

这是一个基于网页的空间转录组基因表达可视化工具，支持 AnnData (.h5ad) 格式。

**主要特性：**
- 交互式可视化
- 内存高效（支持大文件）
- 灵活的输入方式（URL 或上传）
- 单基因表达查询
- 表达量统计分析

### 使用方法

1. **加载数据**：通过 URL 或上传 h5ad 文件
2. **输入基因名**：输入您想查看的基因
3. **可视化**：查看空间表达图和统计信息

### 大文件或高频使用

对于大型 h5ad 文件（>2GB）或频繁使用，建议 **复制此 Space** 到您的账户：
- 独立计算资源
- 无需排队
- 数据隐私保护
- 可选付费升级

### 数据要求

您的 h5ad 文件必须包含：
- `adata.obsm['spatial']`：空间坐标（N × 2）
- `adata.X`：基因表达数据
- `adata.var_names`：基因名称

支持 Visium、MERFISH、seqFISH 等格式。

### 技术原理

使用 AnnData 的 **backed 模式**（`backed='r'`）：
- 按需从磁盘读取数据
- 内存占用最小化
- 可处理大于内存的文件
- 适合大规模空间转录组数据

---

**为空间转录组研究社区构建** 🧬