h5ad_viewer

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* 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
+data/Mouse_Adult_Brain_M9_70_15um_adata_brain_15um.h5ad filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Spatial Transcriptomics Viewer Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,14 +1,303 @@
 ---
-title: Spatial Omics Viewer
-emoji: 📚
-colorFrom: red
-colorTo: green
+title: Spatial Transcriptomics Viewer
+emoji: 🧬
+colorFrom: blue
+colorTo: purple
 sdk: gradio
-sdk_version: 6.2.0
+sdk_version: 4.0.0
 app_file: app.py
 pinned: false
 license: mit
-short_description: Visualize spatial expression from .h5ad files (AnnData forma
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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'`）：
+- 按需从磁盘读取数据
+- 内存占用最小化
+- 可处理大于内存的文件
+- 适合大规模空间转录组数据
+
+---
+
+**为空间转录组研究社区构建** 🧬

app.py

@@ -0,0 +1,1494 @@
+import gradio as gr
+import os
+import io
+import zipfile
+import tempfile
+import csv
+import datetime
+from pathlib import Path
+from typing import Optional, Tuple, List, Dict
+import numpy as np
+import plotly.graph_objects as go
+
+from utils.loader import H5adLoader
+from utils.validator import AnnDataValidator
+from utils.plot import SpatialPlotter, SpatialImageExtractor
+from utils.data_source_manager import DataSourceManager
+
+
+class SpatialViewer:
+    """Main application class for spatial transcriptomics viewer"""
+
+    # Default demo dataset to load on startup
+    DEFAULT_DEMO = "Cerebellum-MALDI-MSI.h5ad"
+
+    def __init__(self):
+        self.data_manager = DataSourceManager()
+        self.current_source = None
+
+    def load_default_demo(self) -> Tuple[str, Optional[gr.Plot], gr.update, gr.update, str]:
+        """
+        Load default demo dataset on app startup
+
+        Returns:
+            Tuple of (status, overview_plot, selector_update, row_visibility, dataset_info)
+        """
+        demo_path = Path("data") / self.DEFAULT_DEMO
+        if not demo_path.exists():
+            return (
+                "Demo dataset not found. Please load data manually.",
+                None,
+                gr.update(),
+                gr.update(visible=False),
+                "No dataset loaded"
+            )
+
+        try:
+            adata = H5adLoader.load_from_source(str(demo_path))
+
+            # Validate data
+            is_valid, errors = AnnDataValidator.validate(adata)
+            if not is_valid:
+                return (
+                    "Demo dataset validation failed: " + "; ".join(errors),
+                    None,
+                    gr.update(),
+                    gr.update(visible=False),
+                    "No dataset loaded"
+                )
+
+            # Add to data manager
+            source_id = self.data_manager.add_source(
+                name=self.DEFAULT_DEMO,
+                source_type="demo",
+                source_path=str(demo_path),
+                adata=adata
+            )
+
+            # Create overview plot
+            spatial_coords = adata.obsm["spatial"]
+            overview_fig = SpatialPlotter.create_overview_plot(spatial_coords)
+
+            status = (
+                f"✅ Auto-loaded demo dataset!\n"
+                f"- Dataset: {self.DEFAULT_DEMO}\n"
+                f"- Observations (spots/cells): {adata.n_obs:,}\n"
+                f"- Variables (genes): {adata.n_vars:,}\n"
+                f"- Spatial coordinates: {spatial_coords.shape}\n"
+                f"\nReady to visualize gene expression. Switch to 'Visualize Gene' tab."
+            )
+
+            # Dataset selector update
+            choices = self.data_manager.get_source_choices()
+            selector_update = gr.update(
+                choices=choices,
+                value=self.data_manager.current_id,
+                visible=True
+            )
+
+            # Dataset info for Visualize tab
+            current_source = self.data_manager.get_current_source()
+            dataset_info = f"📊 Current: {current_source.name}\n({current_source.n_obs:,} cells, {current_source.n_vars:,} genes)"
+
+            return status, overview_fig, selector_update, gr.update(visible=True), dataset_info
+
+        except Exception as e:
+            return (
+                f"Failed to load demo dataset: {str(e)}",
+                None,
+                gr.update(),
+                gr.update(visible=False),
+                "No dataset loaded"
+            )
+
+    def load_data(
+        self, source_type: str, demo_dataset: Optional[str] = None, url: Optional[str] = None, file_path: Optional[str] = None
+    ) -> Tuple[str, Optional[gr.Plot], gr.update]:
+        """
+        Load h5ad data from various sources
+        Now supports ZIP files containing multiple h5ad files
+
+        Args:
+            source_type: Type of source ('demo', 'url', 'upload')
+            demo_dataset: Selected demo dataset name (if source_type is 'demo')
+            url: URL to h5ad file (if source_type is 'url')
+            file_path: Path to uploaded file (if source_type is 'upload')
+
+        Returns:
+            Tuple of (status_message, overview_plot, dataset_selector_update)
+        """
+        try:
+            # Determine source
+            if source_type == "demo":
+                if not demo_dataset:
+                    return "Please select a demo dataset.", None, gr.update()
+                demo_path = Path("data") / demo_dataset
+                if not demo_path.exists():
+                    return f"Demo dataset not found: {demo_dataset}", None, gr.update()
+                source = str(demo_path)
+                display_name = demo_dataset
+
+            elif source_type == "url":
+                if not url or url.strip() == "":
+                    return "Please provide a valid URL.", None, gr.update()
+                source = url.strip()
+                display_name = source.split("/")[-1] or "URL Dataset"
+
+            elif source_type == "upload":
+                if not file_path:
+                    return "Please upload a file.", None, gr.update()
+                source = file_path
+                display_name = Path(file_path).name
+
+            else:
+                return f"Unknown source type: {source_type}", None, gr.update()
+
+            # Load data
+            loaded_data = H5adLoader.load_from_source(source)
+
+            # Handle multiple datasets (from ZIP file)
+            if isinstance(loaded_data, list):
+                # Multiple h5ad files loaded from ZIP
+                status_messages = []
+                loaded_count = 0
+
+                for idx, adata in enumerate(loaded_data):
+                    # Validate each dataset
+                    is_valid, errors = AnnDataValidator.validate(adata)
+                    if not is_valid:
+                        status_messages.append(
+                            f"Dataset {idx + 1} validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+                        )
+                        continue
+
+                    # Add to data manager
+                    file_name = f"{display_name} - Part {idx + 1}"
+                    source_id = self.data_manager.add_source(
+                        name=file_name,
+                        source_type=source_type,
+                        source_path=source,
+                        adata=adata
+                    )
+                    loaded_count += 1
+
+                if loaded_count == 0:
+                    return "No valid datasets found in ZIP file.\n" + "\n".join(status_messages), None, gr.update()
+
+                # Get current (latest loaded) dataset
+                current_source = self.data_manager.get_current_source()
+                spatial_coords = current_source.adata.obsm["spatial"]
+                overview_fig = SpatialPlotter.create_overview_plot(spatial_coords)
+
+                status = (
+                    f"Successfully loaded {loaded_count} dataset(s) from ZIP file!\n\n"
+                    f"Current dataset: {current_source.name}\n"
+                    f"- Observations (spots/cells): {current_source.n_obs:,}\n"
+                    f"- Variables (genes): {current_source.n_vars:,}\n"
+                    f"- Spatial coordinates: {spatial_coords.shape}\n"
+                    f"\nUse the dataset selector above to switch between datasets.\n"
+                    f"Ready to visualize gene expression."
+                )
+
+            else:
+                # Single h5ad file
+                adata = loaded_data
+
+                # Validate data
+                is_valid, errors = AnnDataValidator.validate(adata)
+                if not is_valid:
+                    error_msg = "Validation errors:\n" + "\n".join(f"- {e}" for e in errors)
+                    return error_msg, None, gr.update()
+
+                # Add to data manager
+                source_id = self.data_manager.add_source(
+                    name=display_name,
+                    source_type=source_type,
+                    source_path=source,
+                    adata=adata
+                )
+
+                # Create overview plot
+                spatial_coords = adata.obsm["spatial"]
+                overview_fig = SpatialPlotter.create_overview_plot(spatial_coords)
+
+                status = (
+                    f"Successfully loaded data!\n"
+                    f"- Dataset: {display_name}\n"
+                    f"- Observations (spots/cells): {adata.n_obs:,}\n"
+                    f"- Variables (genes): {adata.n_vars:,}\n"
+                    f"- Spatial coordinates: {spatial_coords.shape}\n"
+                    f"\nReady to visualize gene expression."
+                )
+
+            # Update dataset selector
+            choices = self.data_manager.get_source_choices()
+            selector_update = gr.update(
+                choices=choices,
+                value=self.data_manager.current_id,
+                visible=True
+            )
+
+            return status, overview_fig, selector_update
+
+        except Exception as e:
+            return f"Error loading data: {str(e)}", None, gr.update()
+
+    def switch_dataset(self, source_id: str) -> Tuple[str, Optional[gr.Plot]]:
+        """
+        Switch to a different loaded dataset
+
+        Args:
+            source_id: ID of the dataset to switch to
+
+        Returns:
+            Tuple of (info_message, overview_plot)
+        """
+        if not source_id:
+            return "No dataset selected.", None
+
+        success = self.data_manager.set_current(source_id)
+        if not success:
+            return f"Dataset not found: {source_id}", None
+
+        current_source = self.data_manager.get_current_source()
+        spatial_coords = current_source.adata.obsm["spatial"]
+        overview_fig = SpatialPlotter.create_overview_plot(spatial_coords)
+
+        info = current_source.get_info()
+        return info, overview_fig
+
+    def visualize_gene(
+        self,
+        gene_name: str,
+        point_size: int = 5,
+        use_log: bool = True,
+        colorscale: str = "Viridis",
+        show_background: bool = False,
+        background_opacity: float = 0.5,
+    ) -> Tuple[str, Optional[gr.Plot], str, str]:
+        """
+        Visualize gene expression in spatial context
+        """
+        current_source = self.data_manager.get_current_source()
+
+        if current_source is None:
+            return "❌ Please load data first.", None, "", ""
+            
+        if current_source.adata is None:
+            return "❌ Dataset registered but not yet loaded. Please select it in the 'Select Dataset' tab first.", None, "", ""
+
+        if not gene_name or gene_name.strip() == "":
+            return "❓ Please enter a gene name.", None, "", ""
+
+        gene_name = gene_name.strip()
+
+        try:
+            adata = current_source.adata
+
+            # Get gene expression
+            expression = AnnDataValidator.get_gene_expression(adata, gene_name)
+
+            # Get spatial coordinates
+            spatial_coords = adata.obsm["spatial"]
+
+            # Extract background image from h5ad if requested
+            background_image = None
+            scalefactors = None
+            bg_status = ""
+            
+            if show_background:
+                result = SpatialImageExtractor.get_spatial_image(adata, prefer_lowres=True)
+                if result is not None:
+                    background_image, scalefactors, image_key = result
+                    # Pass image_key to scalefactors so plot knows which scale to use
+                    scalefactors = dict(scalefactors)  # Make a copy
+                    scalefactors['_image_key'] = image_key
+                    bg_status = f" (with {image_key} tissue background)"
+                else:
+                    bg_status = " (no background image in h5ad)"
+
+            # Create plot
+            fig = SpatialPlotter.plot_spatial_gene(
+                spatial_coords=spatial_coords,
+                expression=expression,
+                gene_name=gene_name,
+                point_size=point_size,
+                use_log=use_log,
+                colorscale=colorscale,
+                background_image=background_image,
+                scalefactors=scalefactors,
+                background_opacity=background_opacity,
+            )
+
+            # Get statistics
+            stats = SpatialPlotter.get_expression_stats(expression)
+            stats_text = (
+                f"Expression Statistics for {gene_name}:\n"
+                f"- Min: {stats['min']:.4f}\n"
+                f"- Max: {stats['max']:.4f}\n"
+                f"- Mean: {stats['mean']:.4f}\n"
+                f"- Median: {stats['median']:.4f}\n"
+                f"- Std Dev: {stats['std']:.4f}\n"
+                f"- Non-zero: {stats['non_zero_count']:,} ({stats['non_zero_percent']:.1f}%)"
+            )
+
+            # Current dataset info
+            dataset_info = f"Current dataset: {current_source.name}\n({current_source.n_obs:,} cells, {current_source.n_vars:,} genes)"
+
+            return f"Successfully visualized gene: {gene_name}{bg_status}", fig, stats_text, dataset_info
+
+        except ValueError as e:
+            return str(e), None, "", ""
+        except Exception as e:
+            return f"Error visualizing gene: {str(e)}", None, "", ""
+
+    def check_spatial_image_available(self) -> bool:
+        """Check if current dataset has spatial background image"""
+        current_source = self.data_manager.get_current_source()
+        if current_source is None or current_source.adata is None:
+            return False
+        return SpatialImageExtractor.has_spatial_image(current_source.adata)
+
+    def get_gene_suggestions(self, limit: int = 100) -> list:
+        """Get list of available genes for autocomplete"""
+        current_source = self.data_manager.get_current_source()
+        if current_source is None or current_source.adata is None:
+            return []
+        return AnnDataValidator.get_gene_list(current_source.adata, limit=limit)
+
+    def get_current_dataset_info(self) -> str:
+        """Get formatted info string for current dataset"""
+        current_source = self.data_manager.get_current_source()
+        if current_source is None:
+            return "No dataset loaded. Please load data first."
+        if current_source.adata is None:
+            return f"📊 Current: {current_source.name}\n(Not yet loaded)"
+        return f"📊 Current: {current_source.name}\n({current_source.n_obs:,} cells, {current_source.n_vars:,} genes)"
+
+    def get_all_genes(self) -> List[str]:
+        """Get full list of genes for autocomplete dropdown"""
+        current_source = self.data_manager.get_current_source()
+        if current_source is None or current_source.adata is None:
+            return []
+        return list(current_source.adata.var_names)
+
+    def search_genes(self, query: str, limit: int = 50) -> List[str]:
+        """
+        Search genes by prefix or substring match
+        """
+        current_source = self.data_manager.get_current_source()
+        if current_source is None or current_source.adata is None:
+            return []
+
+        if not query or query.strip() == "":
+            # Return first N genes if no query
+            return list(current_source.adata.var_names[:limit])
+
+        query = query.strip().upper()
+        all_genes = list(current_source.adata.var_names)
+
+        # First: exact prefix matches (prioritized)
+        prefix_matches = [g for g in all_genes if g.upper().startswith(query)]
+
+        # Second: substring matches (lower priority)
+        substring_matches = [g for g in all_genes if query in g.upper() and g not in prefix_matches]
+
+        # Combine and limit
+        results = prefix_matches + substring_matches
+        return results[:limit]
+
+    def get_adata_summary(self) -> str:
+        """
+        Get detailed summary of current AnnData object
+        
+        Returns:
+            Formatted string with h5ad file details
+        """
+        current_source = self.data_manager.get_current_source()
+        if current_source is None:
+            return "No dataset loaded"
+            
+        if current_source.adata is None:
+            return f"📊 **{current_source.name}**\n\n*Dataset registered but not yet loaded. Select it in the list to load.*"
+        
+        adata = current_source.adata
+        
+        lines = []
+        lines.append(f"📊 **{current_source.name}**")
+        lines.append("")
+        
+        # Basic info
+        lines.append("### 📈 Dimensions")
+        lines.append(f"- Observations (cells/spots): **{adata.n_obs:,}**")
+        lines.append(f"- Variables (features): **{adata.n_vars:,}**")
+        
+        # Spatial coordinates
+        if "spatial" in adata.obsm:
+            spatial_shape = adata.obsm["spatial"].shape
+            lines.append(f"- Spatial coordinates: **{spatial_shape}**")
+        
+        lines.append("")
+        
+        # Variables info (first 5)
+        lines.append("### 🧬 Variables (first 5)")
+        var_names = list(adata.var_names[:5])
+        lines.append(f"`{', '.join(var_names)}`")
+        if adata.n_vars > 5:
+            lines.append(f"... and {adata.n_vars - 5:,} more")
+        
+        lines.append("")
+        
+        # obsm keys
+        if len(adata.obsm.keys()) > 0:
+            lines.append("### 📍 obsm (embeddings)")
+            for key in list(adata.obsm.keys())[:5]:
+                shape = adata.obsm[key].shape
+                lines.append(f"- `{key}`: {shape}")
+        
+        # obsp keys
+        if hasattr(adata, 'obsp') and len(adata.obsp.keys()) > 0:
+            lines.append("")
+            lines.append("### 🔗 obsp (pairwise)")
+            for key in list(adata.obsp.keys())[:3]:
+                lines.append(f"- `{key}`")
+        
+        # uns keys
+        if len(adata.uns.keys()) > 0:
+            lines.append("")
+            lines.append("### 📦 uns (unstructured)")
+            uns_keys = list(adata.uns.keys())[:6]
+            lines.append(f"`{', '.join(uns_keys)}`")
+            if len(adata.uns.keys()) > 6:
+                lines.append(f"... and {len(adata.uns.keys()) - 6} more")
+        
+        # Check for spatial image
+        lines.append("")
+        lines.append("### 🖼️ Spatial Image")
+        if SpatialImageExtractor.has_spatial_image(adata):
+            libs = SpatialImageExtractor.get_available_libraries(adata)
+            lines.append(f"✅ Available (libraries: {', '.join(libs)})")
+        else:
+            lines.append("❌ Not available")
+        
+        return "\n".join(lines)
+
+    def get_local_h5ad_files(self) -> List[str]:
+        """Get list of h5ad files in the data folder"""
+        data_dir = Path("data")
+        if not data_dir.exists():
+            return []
+        return [f.name for f in data_dir.glob("*.h5ad")]
+
+    def create_overview_with_background(self) -> Optional[go.Figure]:
+        """Create spatial overview plot with tissue background if available"""
+        current_source = self.data_manager.get_current_source()
+        if current_source is None or current_source.adata is None:
+            return None
+        
+        adata = current_source.adata
+        spatial_coords = adata.obsm["spatial"]
+        
+        # Try to get background image
+        background_image = None
+        scalefactors = None
+        
+        result = SpatialImageExtractor.get_spatial_image(adata, prefer_lowres=True)
+        if result is not None:
+            background_image, scalefactors, image_key = result
+            scalefactors = dict(scalefactors)
+            scalefactors['_image_key'] = image_key
+        
+        # Create overview plot with background
+        return SpatialPlotter.create_overview_plot_with_background(
+            spatial_coords=spatial_coords,
+            background_image=background_image,
+            scalefactors=scalefactors,
+        )
+
+    def parse_variables_list(self, input_text: str) -> Tuple[List[str], List[str], List[str]]:
+        """
+        Parse comma/space/newline separated variables list
+        
+        Args:
+            input_text: Raw input text with variable names
+            
+        Returns:
+            Tuple of (found_features, not_found_features, all_parsed)
+        """
+        current_source = self.data_manager.get_current_source()
+        if current_source is None:
+            return [], [], []
+        
+        if not input_text or input_text.strip() == "":
+            return [], [], []
+        
+        # Parse: split by comma, space, newline, tab
+        import re
+        raw_items = re.split(r'[,\s\n\t]+', input_text.strip())
+        all_parsed = [item.strip() for item in raw_items if item.strip()]
+        
+        # Check which features exist in dataset
+        available_genes = set(current_source.adata.var_names)
+        found_features = [g for g in all_parsed if g in available_genes]
+        not_found_features = [g for g in all_parsed if g not in available_genes]
+        
+        return found_features, not_found_features, all_parsed
+
+    def batch_visualize(
+        self,
+        variables_text: str,
+        point_size: int = 5,
+        use_log: bool = True,
+        colorscale: str = "Viridis",
+        show_background: bool = False,
+        background_opacity: float = 0.5,
+        progress=gr.Progress(track_tqdm=True),
+    ) -> Tuple[str, Optional[str], str, str]:
+        """
+        Perform batch visualization for multiple features
+        
+        Args:
+            variables_text: Comma/space/newline separated feature names
+            point_size, use_log, colorscale, show_background, background_opacity: Plot settings
+            progress: Gradio progress tracker
+            
+        Returns:
+            Tuple of (status, zip_file_path, summary_report, stats_csv)
+        """
+        current_source = self.data_manager.get_current_source()
+        if current_source is None:
+            return "❌ No dataset loaded. Please load data first.", None, "", ""
+        
+        found_features, not_found_features, all_parsed = self.parse_variables_list(variables_text)
+        
+        if not found_features:
+            return f"❌ No valid features found in dataset.\nParsed: {', '.join(all_parsed)}", None, "", ""
+        
+        # Prepare output
+        adata = current_source.adata
+        spatial_coords = adata.obsm["spatial"]
+        
+        # Get background image if needed
+        background_image = None
+        scalefactors = None
+        if show_background:
+            result = SpatialImageExtractor.get_spatial_image(adata, prefer_lowres=True)
+            if result is not None:
+                background_image, scalefactors, image_key = result
+                scalefactors = dict(scalefactors)
+                scalefactors['_image_key'] = image_key
+        
+        # Create temp directory for outputs
+        temp_dir = tempfile.mkdtemp(prefix="batch_viz_")
+        
+        # Track results
+        stats_records = []
+        successful_plots = []
+        failed_features = []
+        
+        # Generate plots
+        total = len(found_features)
+        for idx, gene_name in enumerate(found_features):
+            progress((idx + 1) / total, desc=f"Processing {gene_name} ({idx + 1}/{total})")
+            
+            try:
+                # Get expression
+                expression = AnnDataValidator.get_gene_expression(adata, gene_name)
+                
+                # Create plot
+                fig = SpatialPlotter.plot_spatial_gene(
+                    spatial_coords=spatial_coords,
+                    expression=expression,
+                    gene_name=gene_name,
+                    point_size=point_size,
+                    use_log=use_log,
+                    colorscale=colorscale,
+                    background_image=background_image,
+                    scalefactors=scalefactors,
+                    background_opacity=background_opacity,
+                )
+                
+                # Save as PNG
+                png_path = os.path.join(temp_dir, f"{gene_name}.png")
+                fig.write_image(png_path, scale=2)
+                successful_plots.append((gene_name, png_path))
+                
+                # Get statistics
+                stats = SpatialPlotter.get_expression_stats(expression)
+                stats['feature'] = gene_name
+                stats_records.append(stats)
+                
+            except Exception as e:
+                failed_features.append((gene_name, str(e)))
+        
+        # Generate summary report
+        report_lines = [
+            "# Batch Visualization Report",
+            f"Dataset: {current_source.name}",
+            f"Total cells/spots: {current_source.n_obs:,}",
+            f"Total features: {current_source.n_vars:,}",
+            "",
+            "## Settings",
+            f"- Point Size: {point_size}",
+            f"- Log Transform: {use_log}",
+            f"- Color Scale: {colorscale}",
+            f"- Background: {show_background}",
+            "",
+            "## Results Summary",
+            f"- Total requested: {len(all_parsed)}",
+            f"- Found in dataset: {len(found_features)}",
+            f"- Successfully visualized: {len(successful_plots)}",
+            f"- Failed: {len(failed_features)}",
+            "",
+        ]
+        
+        if not_found_features:
+            report_lines.append("## Not Found Features")
+            for feat in not_found_features:
+                report_lines.append(f"- {feat}")
+            report_lines.append("")
+        
+        if failed_features:
+            report_lines.append("## Failed Features")
+            for feat, err in failed_features:
+                report_lines.append(f"- {feat}: {err}")
+            report_lines.append("")
+        
+        report_lines.append("## Successfully Visualized Features")
+        for feat, _ in successful_plots:
+            report_lines.append(f"- {feat}")
+        
+        report_text = "\n".join(report_lines)
+        
+        # Save report
+        report_path = os.path.join(temp_dir, "report.md")
+        with open(report_path, "w") as f:
+            f.write(report_text)
+        
+        # Save statistics CSV
+        stats_csv_path = os.path.join(temp_dir, "expression_statistics.csv")
+        if stats_records:
+            with open(stats_csv_path, "w", newline="") as f:
+                fieldnames = ['feature', 'min', 'max', 'mean', 'median', 'std', 'non_zero_count', 'non_zero_percent']
+                writer = csv.DictWriter(f, fieldnames=fieldnames)
+                writer.writeheader()
+                writer.writerows(stats_records)
+        
+        # Create ZIP file
+        zip_path = os.path.join(temp_dir, "batch_visualization.zip")
+        with zipfile.ZipFile(zip_path, 'w', zipfile.ZIP_DEFLATED) as zf:
+            # Add images
+            for gene_name, png_path in successful_plots:
+                zf.write(png_path, f"images/{gene_name}.png")
+            
+            # Add report
+            zf.write(report_path, "report.md")
+            
+            # Add stats CSV
+            if stats_records:
+                zf.write(stats_csv_path, "expression_statistics.csv")
+        
+        # Format stats for display
+        stats_display = "Feature | Min | Max | Mean | Non-zero %\n"
+        stats_display += "--- | --- | --- | --- | ---\n"
+        for rec in stats_records:
+            stats_display += f"{rec['feature']} | {rec['min']:.4f} | {rec['max']:.4f} | {rec['mean']:.4f} | {rec['non_zero_percent']:.1f}%\n"
+        
+        status = f"✅ Batch visualization complete!\n- Generated: {len(successful_plots)} plots\n- Failed: {len(failed_features)}"
+        
+        return status, zip_path, report_text, stats_display
+
+
+def create_interface():
+    """Create Gradio interface"""
+
+    viewer = SpatialViewer()
+
+    # Custom CSS
+    custom_css = """
+    .duplicate-notice {
+        background: linear-gradient(135deg, #fff8e1 0%, #ffecb3 100%);
+        color: #3e2723;
+        border: 1px solid #ffc107;
+        border-radius: 8px;
+        padding: 12px 16px;
+        margin: 12px 0;
+        font-size: 0.95rem;
+        line-height: 1.5;
+    }
+    .duplicate-notice b { color: #e65100; }
+    
+    @media (prefers-color-scheme: dark) {
+        .duplicate-notice {
+            background: linear-gradient(135deg, rgba(50,40,20,0.9) 0%, rgba(40,30,10,0.9) 100%);
+            color: #ffffff;
+            border-color: #ffc107;
+        }
+        .duplicate-notice b { color: #ffd54f; }
+    }
+
+    .file-browser {
+        background: linear-gradient(180deg, #f8f9fa 0%, #e9ecef 100%);
+        border: 1px solid #dee2e6;
+        border-radius: 8px;
+        padding: 12px;
+    }
+    @media (prefers-color-scheme: dark) {
+        .file-browser {
+            background: linear-gradient(180deg, #2d2d2d 0%, #1a1a1a 100%);
+            border-color: #444;
+        }
+    }
+    
+    .data-info-panel {
+        background: linear-gradient(180deg, #e3f2fd 0%, #bbdefb 100%);
+        border: 1px solid #90caf9;
+        border-radius: 8px;
+        padding: 12px;
+    }
+    @media (prefers-color-scheme: dark) {
+        .data-info-panel {
+            background: linear-gradient(180deg, rgba(33,150,243,0.15) 0%, rgba(33,150,243,0.05) 100%);
+            border-color: #1976d2;
+        }
+    }
+    
+    .control-panel {
+        background: linear-gradient(180deg, #f5f5f5 0%, #eeeeee 100%);
+        border: 1px solid #e0e0e0;
+        border-radius: 8px;
+        padding: 16px;
+    }
+    @media (prefers-color-scheme: dark) {
+        .control-panel {
+            background: linear-gradient(180deg, #2a2a2a 0%, #1f1f1f 100%);
+            border-color: #444;
+        }
+    }
+    """
+
+    with gr.Blocks(
+        title="Spatial Omics Viewer",
+        theme=gr.themes.Soft(),
+        css=custom_css,
+    ) as app:
+        gr.Markdown(
+            """
+            # 🔬 Spatial Omics Viewer
+            Visualize spatial expression from .h5ad files (AnnData format)
+            
+            <div class="duplicate-notice">
+            <b>Notice:</b> This is a public demo Space. For large h5ad files or heavy usage,
+            please <b>Duplicate this Space</b> to your account for better performance and privacy.
+            </div>
+            """
+        )
+
+        # ==================== Select Dataset Tab ====================
+        with gr.Tab("📂 Select Dataset"):
+            with gr.Row():
+                # Column 1: Dataset Browser
+                with gr.Column(scale=1, elem_classes="file-browser"):
+                    gr.Markdown("### 📁 Available Datasets")
+                    gr.Markdown("*Click to select and view*")
+                    
+                    # All available datasets (loaded ones)
+                    dataset_selector = gr.Radio(
+                        choices=[],
+                        label="📦 Datasets",
+                        value=None,
+                        info="Click to select",
+                    )
+                    
+                    gr.Markdown("---")
+                    gr.Markdown("#### 📥 Import New Data")
+                    
+                    import_type = gr.Radio(
+                        choices=["URL", "Upload"],
+                        value="URL",
+                        label="Import Method",
+                        info="Download from URL or upload file",
+                    )
+                    
+                    with gr.Group() as url_group:
+                        url_input = gr.Textbox(
+                            label="🔗 URL",
+                            placeholder="https://... or Google Drive link",
+                            info="HuggingFace, Zenodo, S3, Google Drive",
+                            lines=1,
+                        )
+                        import_url_btn = gr.Button("📥 Import from URL", variant="secondary")
+                    
+                    with gr.Group(visible=False) as upload_group:
+                        file_input = gr.File(
+                            label="📤 Upload File",
+                            file_types=[".h5ad", ".zip"],
+                            type="filepath",
+                        )
+                    
+                    load_status = gr.Textbox(
+                        label="Status",
+                        lines=2,
+                        interactive=False,
+                    )
+
+                # Column 2: Spatial Overview with background
+                with gr.Column(scale=2):
+                    gr.Markdown("### 🗺️ Spatial Overview")
+                    overview_plot = gr.Plot(label="Spatial Overview")
+
+                # Column 3: Dataset Info
+                with gr.Column(scale=1, elem_classes="data-info-panel"):
+                    gr.Markdown("### 📊 Dataset Information")
+                    dataset_summary = gr.Markdown(
+                        value="*Select a dataset to see information*",
+                        elem_id="dataset-summary",
+                    )
+
+        # ==================== Visualize Tab ====================
+        with gr.Tab("🎨 Visualize") as visualize_tab:
+            with gr.Row():
+                # Column 1: Controls
+                with gr.Column(scale=1, elem_classes="control-panel"):
+                    gr.Markdown("### ⚙️ Controls")
+                    gr.Markdown("*Auto-renders when parameters change*", elem_id="auto-render-hint")
+                    
+                    # Current dataset
+                    current_dataset_display = gr.Textbox(
+                        label="📊 Current Dataset",
+                        value="No dataset loaded",
+                        interactive=False,
+                        lines=2,
+                    )
+                    
+                    # Gene input
+                    gene_input = gr.Textbox(
+                        label="🧬 Feature Name",
+                        placeholder="Type to search (e.g., Pcp, Gab, Act)",
+                        info="Start typing to see matching features",
+                    )
+                    
+                    gene_quick_picks = gr.Radio(
+                        label="🔍 Quick Pick",
+                        choices=[],
+                        visible=False,
+                        interactive=True,
+                    )
+                    
+                    # Plot Settings - default open
+                    with gr.Accordion("🎛️ Plot Settings", open=True):
+                        point_size = gr.Slider(
+                            minimum=1,
+                            maximum=20,
+                            value=5,
+                            step=1,
+                            label="Point Size",
+                        )
+                        
+                        use_log = gr.Checkbox(
+                            value=True,
+                            label="Use log1p transformation",
+                            info="Recommended for better visualization",
+                        )
+                        
+                        colorscale = gr.Dropdown(
+                            choices=[
+                                "Viridis", "Plasma", "Inferno", "Magma",
+                                "Cividis", "Blues", "Reds", "YlOrRd", "RdYlBu",
+                            ],
+                            value="Viridis",
+                            label="Color Scale",
+                        )
+                    
+                    # Tissue Background - default open
+                    with gr.Accordion("🖼️ Tissue Background", open=True):
+                        show_background = gr.Checkbox(
+                            value=False,
+                            label="Show tissue background",
+                            info="From h5ad file (if available)",
+                        )
+                        
+                        background_opacity = gr.Slider(
+                            minimum=0.1,
+                            maximum=1.0,
+                            value=0.5,
+                            step=0.1,
+                            label="Background Opacity",
+                        )
+
+                # Column 2: Plot
+                with gr.Column(scale=2):
+                    gr.Markdown("### 🔬 Spatial Omics Expression")
+                    gene_plot = gr.Plot(label="Spatial Omics Expression")
+
+                # Column 3: Stats
+                with gr.Column(scale=1):
+                    gr.Markdown("### 📈 Analysis")
+                    
+                    vis_status = gr.Textbox(
+                        label="Status",
+                        lines=2,
+                        interactive=False,
+                    )
+                    
+                    stats_output = gr.Textbox(
+                        label="Expression Statistics",
+                        lines=10,
+                        interactive=False,
+                    )
+
+        # ==================== Batch Visualize Tab ====================
+        with gr.Tab("📊 Batch Visualize") as batch_tab:
+            with gr.Row():
+                # Column 1: Input & Settings
+                with gr.Column(scale=1, elem_classes="control-panel"):
+                    gr.Markdown("### 📝 Batch Input")
+                    gr.Markdown("*Paste variable names (comma, space, or newline separated)*")
+                    
+                    batch_current_dataset = gr.Textbox(
+                        label="📊 Current Dataset",
+                        value="No dataset loaded",
+                        interactive=False,
+                        lines=2,
+                    )
+                    
+                    batch_variables_input = gr.Textbox(
+                        label="🧬 Paste Variables List",
+                        placeholder="Gene1, Gene2, Gene3\nor\nGene1\nGene2\nGene3",
+                        lines=10,
+                        info="Supports comma, space, or newline separated values",
+                    )
+                    
+                    batch_parse_btn = gr.Button("🔍 Parse & Preview", variant="secondary")
+                    
+                    batch_parse_result = gr.Markdown(
+                        value="*Enter variables and click Parse to preview*",
+                        elem_id="batch-parse-result",
+                    )
+                    
+                    gr.Markdown("---")
+                    gr.Markdown("### ⚙️ Batch Settings")
+                    
+                    with gr.Accordion("🎛️ Plot Settings", open=True):
+                        batch_point_size = gr.Slider(
+                            minimum=1,
+                            maximum=20,
+                            value=5,
+                            step=1,
+                            label="Point Size",
+                        )
+                        
+                        batch_use_log = gr.Checkbox(
+                            value=True,
+                            label="Use log1p transformation",
+                        )
+                        
+                        batch_colorscale = gr.Dropdown(
+                            choices=[
+                                "Viridis", "Plasma", "Inferno", "Magma",
+                                "Cividis", "Blues", "Reds", "YlOrRd", "RdYlBu",
+                            ],
+                            value="Viridis",
+                            label="Color Scale",
+                        )
+                    
+                    with gr.Accordion("🖼️ Tissue Background", open=True):
+                        batch_show_background = gr.Checkbox(
+                            value=False,
+                            label="Show tissue background",
+                        )
+                        
+                        batch_background_opacity = gr.Slider(
+                            minimum=0.1,
+                            maximum=1.0,
+                            value=0.5,
+                            step=0.1,
+                            label="Background Opacity",
+                        )
+                    
+                    batch_run_btn = gr.Button(
+                        "🚀 Run Batch Visualization", variant="primary", size="lg"
+                    )
+
+                # Column 2: Preview
+                with gr.Column(scale=2):
+                    gr.Markdown("### 👁️ Preview (First Found Feature)")
+                    batch_preview_plot = gr.Plot(label="Preview")
+                    batch_preview_status = gr.Textbox(
+                        label="Preview Status",
+                        lines=2,
+                        interactive=False,
+                    )
+
+                # Column 3: Results
+                with gr.Column(scale=1):
+                    gr.Markdown("### 📦 Results")
+                    
+                    batch_status = gr.Textbox(
+                        label="Batch Status",
+                        lines=3,
+                        interactive=False,
+                    )
+                    
+                    batch_download = gr.File(
+                        label="📥 Download Results (ZIP)",
+                        file_count="single",
+                        interactive=False,
+                    )
+                    
+                    with gr.Accordion("📋 Summary Report", open=True):
+                        batch_report = gr.Markdown(
+                            value="*Run batch visualization to see report*",
+                        )
+                    
+                    with gr.Accordion("📊 Expression Statistics", open=False):
+                        batch_stats = gr.Markdown(
+                            value="*Run batch visualization to see statistics*",
+                        )
+
+        # ==================== About Tab ====================
+        with gr.Tab("ℹ️ About"):
+            gr.Markdown(
+                """
+                ## About This Tool
+
+                This tool visualizes spatial omics expression from AnnData (.h5ad) files.
+
+                ### Features
+                - 🚀 Auto-loads demo dataset on startup
+                - 🔍 Feature name autocomplete search
+                - 🔗 Load from URLs (HuggingFace, Zenodo, S3, Google Drive)
+                - 📤 Upload h5ad/ZIP files
+                - 🖼️ Tissue background image overlay
+                - 📊 Interactive Plotly visualization
+                - 💾 Memory-efficient backed mode
+
+                ### How to Use
+                1. **Load Data**: Select built-in dataset or import external data
+                2. **Visualize**: Search for features and visualize spatial expression
+                3. **Customize**: Adjust plot settings and background
+
+                ### For Large Files
+                Please **Duplicate this Space** for large files (>2GB), frequent usage, or private data.
+
+                ---
+                Built for the spatial omics research community.
+                """
+            )
+
+        # ============================================
+        # Event bindings
+        # ============================================
+
+        # Import type toggle
+        def toggle_import_type(import_method):
+            return {
+                url_group: gr.update(visible=(import_method == "URL")),
+                upload_group: gr.update(visible=(import_method == "Upload")),
+            }
+
+        import_type.change(
+            toggle_import_type,
+            inputs=[import_type],
+            outputs=[url_group, upload_group],
+        )
+
+        # Switch dataset when clicking on selector
+        def switch_dataset(source_id):
+            """Switch to selected dataset (load if needed) and update all views"""
+            if not source_id:
+                return "", None, "*Select a dataset*", viewer.get_current_dataset_info()
+            
+            try:
+                # 1. Get source info
+                source = viewer.data_manager.get_source(source_id)
+                if source is None:
+                    return f"❌ Dataset {source_id} not found", None, "", ""
+
+                # 2. Lazy load if not already loaded
+                if source.adata is None:
+                    print(f"DEBUG: Lazy loading {source.name} from {source.source_path}")
+                    # Free up memory from other datasets first
+                    import gc
+                    for other_id, other_source in viewer.data_manager.sources.items():
+                        if other_id != source_id and other_source.adata is not None:
+                            print(f"DEBUG: Freeing memory from {other_source.name}")
+                            other_source.adata = None
+                    gc.collect()
+                    
+                    # Load current
+                    adata = H5adLoader.load_from_source(source.source_path)
+                    
+                    # Validate
+                    is_valid, errors = AnnDataValidator.validate(adata)
+                    if not is_valid:
+                        return f"❌ Validation failed: {'; '.join(errors)}", None, "", ""
+                    
+                    # Update source object
+                    source.adata = adata
+                    source.n_obs = adata.n_obs
+                    source.n_vars = adata.n_vars
+                    source.loaded_at = datetime.datetime.now()
+
+                # 3. Set as current
+                viewer.data_manager.set_current(source_id)
+                
+                # 4. Update all views
+                overview_fig = viewer.create_overview_with_background()
+                summary = viewer.get_adata_summary()
+                dataset_info = viewer.get_current_dataset_info()
+                choices = viewer.data_manager.get_source_choices()
+                
+                # Update selector choices to show cell/gene counts
+                selector_update = gr.update(choices=choices, value=source_id)
+                
+                return f"✅ Loaded: {source.name}", overview_fig, summary, dataset_info, selector_update
+            
+            except Exception as e:
+                import traceback
+                print(traceback.format_exc())
+                return f"❌ Error loading dataset: {str(e)}", None, "", "", gr.update()
+
+        dataset_selector.change(
+            switch_dataset,
+            inputs=[dataset_selector],
+            outputs=[load_status, overview_plot, dataset_summary, current_dataset_display, dataset_selector],
+        )
+
+        # Import from URL
+        def import_from_url(url):
+            """Import dataset from URL"""
+            if not url or not url.strip():
+                return "❌ Please enter a URL", None, "", gr.update(), ""
+            
+            url = url.strip()
+            display_name = url.split("/")[-1].split("?")[0] or "URL Dataset"
+            
+            try:
+                # Clear existing memory-heavy data before loading new one
+                import gc
+                for source in viewer.data_manager.sources.values():
+                    source.adata = None
+                gc.collect()
+
+                loaded_data = H5adLoader.load_from_source(url)
+                
+                if not isinstance(loaded_data, list):
+                    loaded_data = [loaded_data]
+                
+                last_id = None
+                for idx, adata in enumerate(loaded_data):
+                    is_valid, errors = AnnDataValidator.validate(adata)
+                    if not is_valid:
+                        return f"❌ Validation failed: {'; '.join(errors)}", None, "", gr.update(), ""
+                    
+                    name = display_name if len(loaded_data) == 1 else f"{display_name} - Part {idx + 1}"
+                    last_id = viewer.data_manager.add_source(
+                        name=name,
+                        source_type="url",
+                        source_path=url,
+                        adata=adata
+                    )
+                
+                # Set the last imported one as current
+                if last_id:
+                    viewer.data_manager.set_current(last_id)
+
+                # Update views
+                overview_fig = viewer.create_overview_with_background()
+                summary = viewer.get_adata_summary()
+                choices = viewer.data_manager.get_source_choices()
+                selector_update = gr.update(choices=choices, value=viewer.data_manager.current_id)
+                dataset_info = viewer.get_current_dataset_info()
+                
+                return f"✅ Imported: {display_name}", overview_fig, summary, selector_update, dataset_info
+                
+            except Exception as e:
+                return f"❌ Error: {str(e)}", None, "", gr.update(), ""
+
+        import_url_btn.click(
+            import_from_url,
+            inputs=[url_input],
+            outputs=[load_status, overview_plot, dataset_summary, dataset_selector, current_dataset_display],
+        )
+
+        # Upload file
+        def upload_file(uploaded_file):
+            """Handle file upload"""
+            if not uploaded_file:
+                return "❌ No file uploaded", None, "", gr.update(), ""
+            
+            display_name = Path(uploaded_file).name
+            
+            try:
+                # Clear existing memory-heavy data
+                import gc
+                for source in viewer.data_manager.sources.values():
+                    source.adata = None
+                gc.collect()
+
+                loaded_data = H5adLoader.load_from_source(uploaded_file)
+                
+                if not isinstance(loaded_data, list):
+                    loaded_data = [loaded_data]
+                
+                last_id = None
+                for idx, adata in enumerate(loaded_data):
+                    is_valid, errors = AnnDataValidator.validate(adata)
+                    if not is_valid:
+                        return f"❌ Validation failed: {'; '.join(errors)}", None, "", gr.update(), ""
+                    
+                    name = display_name if len(loaded_data) == 1 else f"{display_name} - Part {idx + 1}"
+                    last_id = viewer.data_manager.add_source(
+                        name=name,
+                        source_type="upload",
+                        source_path=uploaded_file,
+                        adata=adata
+                    )
+                
+                # Set as current
+                if last_id:
+                    viewer.data_manager.set_current(last_id)
+
+                # Update views
+                overview_fig = viewer.create_overview_with_background()
+                summary = viewer.get_adata_summary()
+                choices = viewer.data_manager.get_source_choices()
+                selector_update = gr.update(choices=choices, value=viewer.data_manager.current_id)
+                dataset_info = viewer.get_current_dataset_info()
+                
+                return f"✅ Uploaded: {display_name}", overview_fig, summary, selector_update, dataset_info
+                
+            except Exception as e:
+                return f"❌ Error: {str(e)}", None, "", gr.update(), ""
+
+        file_input.change(
+            upload_file,
+            inputs=[file_input],
+            outputs=[load_status, overview_plot, dataset_summary, dataset_selector, current_dataset_display],
+        )
+
+        # Visualize tab events
+        def update_on_tab_select():
+            return viewer.get_current_dataset_info()
+
+        visualize_tab.select(
+            update_on_tab_select,
+            inputs=[],
+            outputs=[current_dataset_display],
+        )
+
+        def live_search(query):
+            if not query or len(query.strip()) < 2:
+                return gr.update(choices=[], visible=False)
+            results = viewer.search_genes(query, limit=15)
+            if results:
+                return gr.update(choices=results, visible=True, value=None)
+            return gr.update(choices=[], visible=False)
+
+        gene_input.change(
+            live_search,
+            inputs=[gene_input],
+            outputs=[gene_quick_picks],
+        )
+
+        def quick_visualize(selected_gene, point_size, use_log, colorscale, show_bg, bg_opacity):
+            if not selected_gene:
+                return gr.update(), None, "", "", gr.update(visible=False), ""
+            
+            status, plot, stats, dataset_info = viewer.visualize_gene(
+                selected_gene, point_size, use_log, colorscale, show_bg, bg_opacity
+            )
+            return selected_gene, plot, stats, dataset_info, gr.update(visible=False), status
+
+        gene_quick_picks.change(
+            quick_visualize,
+            inputs=[gene_quick_picks, point_size, use_log, colorscale, show_background, background_opacity],
+            outputs=[gene_input, gene_plot, stats_output, current_dataset_display, gene_quick_picks, vis_status],
+        )
+
+        # Auto-render when any parameter changes
+        def auto_visualize(gene_name, pt_size, log_transform, color_scale, show_bg, bg_opacity):
+            """Auto-render visualization when parameters change"""
+            if not gene_name or gene_name.strip() == "":
+                return gr.update(), gr.update(), gr.update(), ""
+            
+            status, plot, stats, dataset_info = viewer.visualize_gene(
+                gene_name, pt_size, log_transform, color_scale, show_bg, bg_opacity
+            )
+            return status, plot, stats, dataset_info
+
+        # Bind auto-render to all parameter changes
+        auto_render_inputs = [gene_input, point_size, use_log, colorscale, show_background, background_opacity]
+        auto_render_outputs = [vis_status, gene_plot, stats_output, current_dataset_display]
+
+        # Re-render on gene input blur (when user finishes typing)
+        gene_input.blur(
+            auto_visualize,
+            inputs=auto_render_inputs,
+            outputs=auto_render_outputs,
+        )
+        
+        # Re-render on parameter changes
+        point_size.release(
+            auto_visualize,
+            inputs=auto_render_inputs,
+            outputs=auto_render_outputs,
+        )
+        
+        use_log.change(
+            auto_visualize,
+            inputs=auto_render_inputs,
+            outputs=auto_render_outputs,
+        )
+        
+        colorscale.change(
+            auto_visualize,
+            inputs=auto_render_inputs,
+            outputs=auto_render_outputs,
+        )
+        
+        show_background.change(
+            auto_visualize,
+            inputs=auto_render_inputs,
+            outputs=auto_render_outputs,
+        )
+        
+        background_opacity.release(
+            auto_visualize,
+            inputs=auto_render_inputs,
+            outputs=auto_render_outputs,
+        )
+
+        # ============================================
+        # Batch Visualize Tab Events
+        # ============================================
+
+        def update_batch_dataset():
+            return viewer.get_current_dataset_info()
+
+        batch_tab.select(
+            update_batch_dataset,
+            inputs=[],
+            outputs=[batch_current_dataset],
+        )
+
+        def parse_and_preview(variables_text, pt_size, log_transform, color_scale, show_bg, bg_opacity):
+            """Parse variables list and preview first found feature"""
+            found, not_found, all_parsed = viewer.parse_variables_list(variables_text)
+            
+            # Build parse result message
+            result_lines = []
+            result_lines.append(f"**Parsed:** {len(all_parsed)} items")
+            result_lines.append(f"**Found:** {len(found)} features")
+            if found:
+                result_lines.append(f"- `{', '.join(found[:10])}`" + (f" ... (+{len(found)-10} more)" if len(found) > 10 else ""))
+            result_lines.append(f"**Not Found:** {len(not_found)} items")
+            if not_found:
+                result_lines.append(f"- `{', '.join(not_found[:5])}`" + (f" ... (+{len(not_found)-5} more)" if len(not_found) > 5 else ""))
+            
+            parse_result = "\n".join(result_lines)
+            
+            # Preview first found feature
+            if found:
+                first_gene = found[0]
+                status, plot, stats, _ = viewer.visualize_gene(
+                    first_gene, pt_size, log_transform, color_scale, show_bg, bg_opacity
+                )
+                preview_status = f"Previewing: {first_gene}"
+                return parse_result, plot, preview_status
+            else:
+                return parse_result, None, "No features found to preview"
+
+        batch_parse_btn.click(
+            parse_and_preview,
+            inputs=[batch_variables_input, batch_point_size, batch_use_log, batch_colorscale, batch_show_background, batch_background_opacity],
+            outputs=[batch_parse_result, batch_preview_plot, batch_preview_status],
+        )
+
+        # Auto-update preview when settings change (if there's already input)
+        def update_preview_on_settings(variables_text, pt_size, log_transform, color_scale, show_bg, bg_opacity):
+            """Update preview when batch settings change"""
+            found, _, _ = viewer.parse_variables_list(variables_text)
+            if found:
+                first_gene = found[0]
+                status, plot, stats, _ = viewer.visualize_gene(
+                    first_gene, pt_size, log_transform, color_scale, show_bg, bg_opacity
+                )
+                return plot, f"Previewing: {first_gene}"
+            return gr.update(), gr.update()
+
+        batch_preview_inputs = [batch_variables_input, batch_point_size, batch_use_log, batch_colorscale, batch_show_background, batch_background_opacity]
+        batch_preview_outputs = [batch_preview_plot, batch_preview_status]
+
+        batch_point_size.release(update_preview_on_settings, inputs=batch_preview_inputs, outputs=batch_preview_outputs)
+        batch_use_log.change(update_preview_on_settings, inputs=batch_preview_inputs, outputs=batch_preview_outputs)
+        batch_colorscale.change(update_preview_on_settings, inputs=batch_preview_inputs, outputs=batch_preview_outputs)
+        batch_show_background.change(update_preview_on_settings, inputs=batch_preview_inputs, outputs=batch_preview_outputs)
+        batch_background_opacity.release(update_preview_on_settings, inputs=batch_preview_inputs, outputs=batch_preview_outputs)
+
+        def run_batch_visualization(variables_text, pt_size, log_transform, color_scale, show_bg, bg_opacity, progress=gr.Progress()):
+            """Run batch visualization"""
+            status, zip_path, report, stats = viewer.batch_visualize(
+                variables_text, pt_size, log_transform, color_scale, show_bg, bg_opacity, progress
+            )
+            return status, zip_path, report, stats
+
+        batch_run_btn.click(
+            run_batch_visualization,
+            inputs=[batch_variables_input, batch_point_size, batch_use_log, batch_colorscale, batch_show_background, batch_background_opacity],
+            outputs=[batch_status, batch_download, batch_report, batch_stats],
+        )
+
+        # Auto-load all demo datasets on startup
+        def startup_load():
+            """Register all built-in datasets on startup (without loading them into RAM)"""
+            # Skip if already registered
+            if viewer.data_manager.has_sources():
+                overview_fig = viewer.create_overview_with_background()
+                summary = viewer.get_adata_summary()
+                choices = viewer.data_manager.get_source_choices()
+                dataset_info = viewer.get_current_dataset_info()
+                selector_update = gr.update(choices=choices, value=viewer.data_manager.current_id)
+                return "✅ Ready", overview_fig, summary, selector_update, dataset_info
+            
+            # Register local h5ad files as sources (lazy loading)
+            local_files = viewer.get_local_h5ad_files()
+            
+            for filename in local_files:
+                source_path = str(Path("data") / filename)
+                viewer.data_manager.add_source(
+                    name=filename,
+                    source_type="demo",
+                    source_path=source_path,
+                    adata=None  # DON'T LOAD YET
+                )
+            
+            if viewer.data_manager.has_sources():
+                choices = viewer.data_manager.get_source_choices()
+                # We don't load the first one automatically to save RAM
+                # But we can set it as current so the UI shows it as selected
+                viewer.data_manager.current_id = choices[0][1]
+                
+                return (
+                    "📂 Datasets found. Select one to load and visualize.",
+                    None,
+                    "*Select a dataset to load*",
+                    gr.update(choices=choices, value=viewer.data_manager.current_id),
+                    "No dataset loaded"
+                )
+            
+            return "No datasets found in data/ folder", None, "", gr.update(), ""
+
+        app.load(
+            startup_load,
+            inputs=[],
+            outputs=[load_status, overview_plot, dataset_summary, dataset_selector, current_dataset_display],
+        )
+
+    return app
+
+
+if __name__ == "__main__":
+    app = create_interface()
+    app.launch()

data/Mouse_Adult_Brain_M9_70_15um_adata_brain_15um.h5ad

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:07097176920994c442259c2cb55639cd1ab6194ec2a86f78b261e5585b6f1196
+size 834789514

requirements.txt

@@ -0,0 +1,11 @@
+gradio>=4.0.0
+anndata>=0.10.0
+scanpy>=1.10.0
+plotly>=5.18.0
+numpy>=1.24.0
+pandas>=2.0.0
+scipy>=1.11.0
+h5py>=3.10.0
+requests>=2.31.0
+Pillow>=10.0.0
+kaleido>=0.2.1

utils/__init__.py

@@ -0,0 +1,5 @@
+from .loader import H5adLoader
+from .validator import AnnDataValidator
+from .plot import SpatialPlotter
+
+__all__ = ["H5adLoader", "AnnDataValidator", "SpatialPlotter"]

utils/data_source_manager.py

@@ -0,0 +1,186 @@
+from typing import Dict, List, Optional, Tuple
+from dataclasses import dataclass
+from pathlib import Path
+from anndata import AnnData
+import datetime
+
+
+@dataclass
+class DataSource:
+    """Represents a loaded h5ad data source"""
+    id: str  # Unique identifier
+    name: str  # Display name
+    source_type: str  # 'demo', 'url', 'upload'
+    source_path: str  # Original source (URL, file path, etc.)
+    adata: Optional[AnnData]  # The loaded AnnData object (Optional for lazy loading)
+    loaded_at: Optional[datetime.datetime]  # When it was loaded
+    n_obs: int = 0  # Number of observations
+    n_vars: int = 0  # Number of variables
+
+    def get_display_name(self) -> str:
+        """Get formatted display name with metadata"""
+        if self.adata is not None:
+            return f"{self.name} ({self.n_obs:,} cells, {self.n_vars:,} genes)"
+        return f"{self.name} (Not loaded)"
+
+    def get_info(self) -> str:
+        """Get detailed information string"""
+        return (
+            f"Dataset: {self.name}\n"
+            f"Source: {self.source_type}\n"
+            f"Cells/Spots: {self.n_obs:,}\n"
+            f"Genes: {self.n_vars:,}\n"
+            f"Loaded: {self.loaded_at.strftime('%Y-%m-%d %H:%M:%S')}"
+        )
+
+
+class DataSourceManager:
+    """
+    Manage multiple loaded h5ad datasets
+
+    This class handles:
+    - Tracking all loaded datasets
+    - Switching between datasets
+    - Providing dataset metadata
+    """
+
+    def __init__(self):
+        self.sources: Dict[str, DataSource] = {}
+        self.current_id: Optional[str] = None
+        self._id_counter = 0
+
+    def add_source(
+        self,
+        name: str,
+        source_type: str,
+        source_path: str,
+        adata: Optional[AnnData] = None
+    ) -> str:
+        """
+        Add a new data source
+
+        Args:
+            name: Display name for the dataset
+            source_type: Type of source ('demo', 'url', 'upload')
+            source_path: Original source location
+            adata: Optional loaded AnnData object
+
+        Returns:
+            Unique ID of the added source
+        """
+        # Check if already exists by source_path to avoid duplicates
+        for existing_id, source in self.sources.items():
+            if source.source_path == source_path:
+                if adata is not None and source.adata is None:
+                    # Update existing source with loaded adata
+                    source.adata = adata
+                    source.loaded_at = datetime.datetime.now()
+                    source.n_obs = adata.n_obs
+                    source.n_vars = adata.n_vars
+                return existing_id
+
+        # Generate unique ID
+        source_id = f"ds_{self._id_counter}"
+        self._id_counter += 1
+
+        # Create data source
+        source = DataSource(
+            id=source_id,
+            name=name,
+            source_type=source_type,
+            source_path=source_path,
+            adata=adata,
+            loaded_at=datetime.datetime.now() if adata is not None else None,
+            n_obs=adata.n_obs if adata is not None else 0,
+            n_vars=adata.n_vars if adata is not None else 0
+        )
+
+        self.sources[source_id] = source
+
+        # Set as current if it's the first one
+        if self.current_id is None:
+            self.current_id = source_id
+
+        return source_id
+
+    def get_source(self, source_id: str) -> Optional[DataSource]:
+        """Get a data source by ID"""
+        return self.sources.get(source_id)
+
+    def get_current_source(self) -> Optional[DataSource]:
+        """Get the currently active data source"""
+        if self.current_id is None:
+            return None
+        return self.sources.get(self.current_id)
+
+    def set_current(self, source_id: str) -> bool:
+        """
+        Set the current active data source
+
+        Args:
+            source_id: ID of the source to activate
+
+        Returns:
+            True if successful, False if source not found
+        """
+        if source_id in self.sources:
+            self.current_id = source_id
+            return True
+        return False
+
+    def get_all_sources(self) -> List[DataSource]:
+        """Get list of all loaded data sources"""
+        return list(self.sources.values())
+
+    def get_source_choices(self) -> List[Tuple[str, str]]:
+        """
+        Get list of sources for dropdown/radio selection
+
+        Returns:
+            List of (display_name, source_id) tuples
+        """
+        return [
+            (source.get_display_name(), source.id)
+            for source in self.sources.values()
+        ]
+
+    def get_source_names(self) -> List[str]:
+        """Get list of source display names"""
+        return [source.name for source in self.sources.values()]
+
+    def remove_source(self, source_id: str) -> bool:
+        """
+        Remove a data source
+
+        Args:
+            source_id: ID of source to remove
+
+        Returns:
+            True if removed, False if not found
+        """
+        if source_id in self.sources:
+            del self.sources[source_id]
+
+            # Update current_id if we removed the current source
+            if self.current_id == source_id:
+                if len(self.sources) > 0:
+                    self.current_id = list(self.sources.keys())[0]
+                else:
+                    self.current_id = None
+
+            return True
+        return False
+
+    def has_sources(self) -> bool:
+        """Check if any sources are loaded"""
+        return len(self.sources) > 0
+
+    def count_sources(self) -> int:
+        """Get number of loaded sources"""
+        return len(self.sources)
+
+    def clear_all(self):
+        """Remove all data sources"""
+        self.sources.clear()
+        self.current_id = None
+        self._id_counter = 0

utils/loader.py

@@ -0,0 +1,337 @@
+import os
+import tempfile
+import zipfile
+import re
+from pathlib import Path
+from typing import Optional, Union, Callable, List
+import requests
+import anndata
+from anndata import AnnData
+
+
+class H5adLoader:
+    """Handle h5ad file loading with backed='r' for efficient memory usage"""
+
+    ALLOWED_DOMAINS = [
+        "huggingface.co",
+        "zenodo.org",
+        "s3.amazonaws.com",
+        "drive.google.com",
+        "docs.google.com",
+    ]
+
+    MAX_DOWNLOAD_SIZE = 20 * 1024 * 1024 * 1024  # 20GB
+    TIMEOUT = 3000  # 3000 seconds = 50 minutes
+
+    @staticmethod
+    def convert_google_drive_url(url: str) -> str:
+        """
+        Convert Google Drive sharing URL to direct download URL
+
+        Supports formats:
+        - https://drive.google.com/file/d/{FILE_ID}/view?usp=sharing
+        - https://drive.google.com/open?id={FILE_ID}
+        - https://docs.google.com/...
+
+        Args:
+            url: Google Drive sharing URL
+
+        Returns:
+            Direct download URL
+
+        Raises:
+            ValueError: If cannot extract file ID
+        """
+        # Pattern 1: /file/d/{ID}/view
+        match = re.search(r'/file/d/([a-zA-Z0-9_-]+)', url)
+        if match:
+            file_id = match.group(1)
+            return f"https://drive.google.com/uc?export=download&id={file_id}"
+
+        # Pattern 2: open?id={ID}
+        match = re.search(r'[?&]id=([a-zA-Z0-9_-]+)', url)
+        if match:
+            file_id = match.group(1)
+            return f"https://drive.google.com/uc?export=download&id={file_id}"
+
+        # If already a direct download URL, return as-is
+        if 'drive.google.com/uc' in url:
+            return url
+
+        raise ValueError(
+            "Cannot parse Google Drive URL. Please use a sharing link like: "
+            "https://drive.google.com/file/d/{FILE_ID}/view?usp=sharing"
+        )
+
+    @staticmethod
+    def is_zip_file(filepath: str) -> bool:
+        """Check if file is a ZIP archive"""
+        return filepath.lower().endswith('.zip') and zipfile.is_zipfile(filepath)
+
+    @staticmethod
+    def extract_h5ad_from_zip(zip_path: str, extract_dir: Optional[str] = None) -> List[str]:
+        """
+        Extract all .h5ad files from a ZIP archive
+
+        Args:
+            zip_path: Path to ZIP file
+            extract_dir: Directory to extract to (uses temp dir if None)
+
+        Returns:
+            List of paths to extracted h5ad files
+
+        Raises:
+            ValueError: If no h5ad files found in ZIP
+        """
+        if extract_dir is None:
+            extract_dir = tempfile.mkdtemp()
+
+        extracted_h5ad_files = []
+
+        try:
+            with zipfile.ZipFile(zip_path, 'r') as zip_ref:
+                # Get all .h5ad files
+                h5ad_files = [f for f in zip_ref.namelist() if f.lower().endswith('.h5ad')]
+
+                if not h5ad_files:
+                    raise ValueError("No .h5ad files found in ZIP archive")
+
+                # Extract each h5ad file
+                for h5ad_file in h5ad_files:
+                    # Skip macOS metadata files
+                    if '__MACOSX' in h5ad_file or h5ad_file.startswith('.'):
+                        continue
+
+                    zip_ref.extract(h5ad_file, extract_dir)
+                    extracted_path = os.path.join(extract_dir, h5ad_file)
+                    extracted_h5ad_files.append(extracted_path)
+
+                if not extracted_h5ad_files:
+                    raise ValueError("No valid .h5ad files found in ZIP (only hidden/system files)")
+
+        except zipfile.BadZipFile:
+            raise ValueError("Invalid or corrupted ZIP file")
+
+        return extracted_h5ad_files
+
+    @staticmethod
+    def is_valid_url(url: str) -> bool:
+        """Check if URL is from allowed domains"""
+        if not url.startswith(("http://", "https://")):
+            return False
+        return any(domain in url for domain in H5adLoader.ALLOWED_DOMAINS)
+
+    @staticmethod
+    def _extract_filename_from_response(response, url: str) -> str:
+        """
+        Extract filename from HTTP response headers or URL
+
+        Prioritizes Content-Disposition header (especially useful for Google Drive)
+
+        Args:
+            response: requests.Response object
+            url: Original URL
+
+        Returns:
+            Extracted filename
+        """
+        filename = None
+
+        # Try to get filename from Content-Disposition header
+        content_disposition = response.headers.get('Content-Disposition', '')
+        if content_disposition:
+            # Try filename*= (RFC 5987 encoded)
+            match = re.search(r"filename\*=(?:UTF-8''|utf-8'')(.+?)(?:;|$)", content_disposition, re.IGNORECASE)
+            if match:
+                from urllib.parse import unquote
+                filename = unquote(match.group(1).strip())
+
+            # Try filename= with quotes
+            if not filename:
+                match = re.search(r'filename="([^"]+)"', content_disposition)
+                if match:
+                    filename = match.group(1).strip()
+
+            # Try filename= without quotes
+            if not filename:
+                match = re.search(r'filename=([^;\s]+)', content_disposition)
+                if match:
+                    filename = match.group(1).strip()
+
+        # Fallback: try to extract from URL
+        if not filename:
+            filename = url.split("/")[-1].split("?")[0]
+
+        # Default filename if still empty
+        if not filename or filename == "" or filename == "uc":
+            filename = "downloaded_data.h5ad"
+
+        # If no extension, try to determine from content type or URL
+        if '.' not in filename:
+            content_type = response.headers.get('Content-Type', '')
+            if 'zip' in content_type.lower() or 'zip' in url.lower():
+                filename = filename + ".zip"
+            else:
+                filename = filename + ".h5ad"
+
+        return filename
+
+    @staticmethod
+    def download_h5ad(
+        url: str,
+        save_dir: Optional[str] = None,
+        progress_callback: Optional[Callable[[int, int], None]] = None
+    ) -> Union[str, List[str]]:
+        """
+        Download h5ad file (or ZIP containing h5ad files) from URL
+
+        Args:
+            url: URL to h5ad or ZIP file
+            save_dir: Directory to save file (uses temp dir if None)
+            progress_callback: Optional callback function(downloaded_bytes, total_bytes)
+
+        Returns:
+            Path to downloaded file, or list of paths if ZIP was extracted
+
+        Raises:
+            ValueError: If URL is invalid or download fails
+        """
+        # Convert Google Drive URL if needed
+        original_url = url
+        if 'drive.google.com' in url or 'docs.google.com' in url:
+            try:
+                url = H5adLoader.convert_google_drive_url(url)
+            except ValueError as e:
+                raise ValueError(f"Google Drive URL error: {str(e)}")
+
+        if not H5adLoader.is_valid_url(url) and not H5adLoader.is_valid_url(original_url):
+            raise ValueError(
+                f"URL not from allowed domains: {', '.join(H5adLoader.ALLOWED_DOMAINS)}"
+            )
+
+        if save_dir is None:
+            save_dir = tempfile.mkdtemp()
+
+        try:
+            response = requests.get(
+                url,
+                stream=True,
+                timeout=H5adLoader.TIMEOUT,
+                allow_redirects=True
+            )
+            response.raise_for_status()
+
+            # Extract filename from response headers (handles Google Drive properly)
+            filename = H5adLoader._extract_filename_from_response(response, url)
+            filepath = os.path.join(save_dir, filename)
+
+            # Get total size if available
+            total_size = int(response.headers.get('content-length', 0))
+
+            downloaded_size = 0
+            with open(filepath, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    if chunk:
+                        downloaded_size += len(chunk)
+
+                        # Check size limit
+                        if downloaded_size > H5adLoader.MAX_DOWNLOAD_SIZE:
+                            raise ValueError(
+                                f"File too large (>{H5adLoader.MAX_DOWNLOAD_SIZE / 1e9:.1f}GB)"
+                            )
+
+                        f.write(chunk)
+
+                        # Call progress callback if provided
+                        if progress_callback:
+                            progress_callback(downloaded_size, total_size)
+
+            # Check if it's a ZIP file and extract if so
+            if H5adLoader.is_zip_file(filepath):
+                extracted_files = H5adLoader.extract_h5ad_from_zip(filepath, save_dir)
+                return extracted_files  # Return list of extracted h5ad files
+
+            return filepath
+
+        except requests.RequestException as e:
+            raise ValueError(f"Failed to download file: {str(e)}")
+
+    @staticmethod
+    def load_h5ad(
+        path: Union[str, Path],
+        backed: str = "r",
+    ) -> Union[AnnData, List[AnnData]]:
+        """
+        Load h5ad file with backed mode for memory efficiency
+        Also handles ZIP files containing h5ad files
+
+        Args:
+            path: Path to h5ad or ZIP file, or URL
+            backed: Backing mode ('r' for read-only, recommended)
+
+        Returns:
+            AnnData object with backed mode enabled, or list of AnnData if ZIP
+
+        Raises:
+            ValueError: If file cannot be loaded
+        """
+        path_str = str(path)
+
+        # If it's a URL, download first
+        if path_str.startswith(("http://", "https://")):
+            downloaded = H5adLoader.download_h5ad(path_str)
+
+            # Check if we got multiple files from ZIP
+            if isinstance(downloaded, list):
+                # Load all extracted h5ad files
+                adata_list = []
+                for h5ad_path in downloaded:
+                    adata = anndata.read_h5ad(h5ad_path, backed=backed)
+                    adata_list.append(adata)
+                return adata_list
+
+            path_str = downloaded
+
+        # Check if local file is a ZIP
+        if os.path.exists(path_str) and H5adLoader.is_zip_file(path_str):
+            extracted_files = H5adLoader.extract_h5ad_from_zip(path_str)
+
+            if len(extracted_files) == 1:
+                # Single h5ad file in ZIP
+                path_str = extracted_files[0]
+            else:
+                # Multiple h5ad files in ZIP
+                adata_list = []
+                for h5ad_path in extracted_files:
+                    adata = anndata.read_h5ad(h5ad_path, backed=backed)
+                    adata_list.append(adata)
+                return adata_list
+
+        # Validate file exists
+        if not os.path.exists(path_str):
+            raise ValueError(f"File not found: {path_str}")
+
+        # Validate file extension
+        if not path_str.endswith(".h5ad"):
+            raise ValueError("File must have .h5ad extension")
+
+        try:
+            # Load with backed mode for efficient memory usage
+            adata = anndata.read_h5ad(path_str, backed=backed)
+            return adata
+
+        except Exception as e:
+            raise ValueError(f"Failed to load h5ad file: {str(e)}")
+
+    @staticmethod
+    def load_from_source(source: Union[str, Path]) -> AnnData:
+        """
+        Convenience method to load h5ad from file path or URL
+
+        Args:
+            source: File path or URL to h5ad file
+
+        Returns:
+            AnnData object loaded with backed='r'
+        """
+        return H5adLoader.load_h5ad(source, backed="r")

utils/plot.py

@@ -0,0 +1,504 @@
+import numpy as np
+import plotly.graph_objects as go
+import plotly.express as px
+from typing import Optional, Tuple, Dict, Any, Union
+from PIL import Image
+import base64
+from io import BytesIO
+
+
+class SpatialImageExtractor:
+    """Extract spatial background images from AnnData objects"""
+
+    @staticmethod
+    def get_spatial_image(
+        adata,
+        library_id: Optional[str] = None,
+        prefer_lowres: bool = True,
+    ) -> Optional[Tuple[np.ndarray, Dict[str, Any], str]]:
+        """
+        Extract spatial background image from AnnData object
+        
+        Spatial images are typically stored in:
+        - adata.uns['spatial'][library_id]['images']['hires'] or 'lowres'
+        - adata.uns['spatial'][library_id]['scalefactors']
+        
+        Args:
+            adata: AnnData object
+            library_id: Library/sample ID. If None, uses first available.
+            prefer_lowres: If True, prefer lowres image for faster rendering
+            
+        Returns:
+            Tuple of (image_array, scalefactors, image_key) or None if not found
+        """
+        try:
+            # Check if spatial data exists
+            if 'spatial' not in adata.uns:
+                return None
+            
+            spatial_data = adata.uns['spatial']
+            
+            # Get library_id
+            if library_id is None:
+                # Use first available library
+                if isinstance(spatial_data, dict) and len(spatial_data) > 0:
+                    library_id = list(spatial_data.keys())[0]
+                else:
+                    return None
+            
+            if library_id not in spatial_data:
+                return None
+            
+            library_data = spatial_data[library_id]
+            
+            # Get images
+            if 'images' not in library_data:
+                return None
+            
+            images = library_data['images']
+            
+            # Select image based on preference (lowres is faster)
+            image_key = None
+            if prefer_lowres and 'lowres' in images:
+                img_array = images['lowres']
+                image_key = 'lowres'
+            elif 'hires' in images:
+                img_array = images['hires']
+                image_key = 'hires'
+            elif 'lowres' in images:
+                img_array = images['lowres']
+                image_key = 'lowres'
+            else:
+                return None
+            
+            # Get scalefactors
+            scalefactors = library_data.get('scalefactors', {})
+            
+            return img_array, scalefactors, image_key
+            
+        except Exception as e:
+            print(f"Warning: Could not extract spatial image: {e}")
+            return None
+
+    @staticmethod
+    def get_available_libraries(adata) -> list:
+        """Get list of available library IDs with spatial images"""
+        try:
+            if 'spatial' not in adata.uns:
+                return []
+            return list(adata.uns['spatial'].keys())
+        except:
+            return []
+
+    @staticmethod
+    def has_spatial_image(adata) -> bool:
+        """Check if AnnData has spatial background image"""
+        try:
+            if 'spatial' not in adata.uns:
+                return False
+            spatial_data = adata.uns['spatial']
+            if not isinstance(spatial_data, dict) or len(spatial_data) == 0:
+                return False
+            # Check first library
+            first_lib = list(spatial_data.keys())[0]
+            lib_data = spatial_data[first_lib]
+            if 'images' not in lib_data:
+                return False
+            images = lib_data['images']
+            return 'hires' in images or 'lowres' in images
+        except:
+            return False
+
+
+class SpatialPlotter:
+    """Create spatial visualizations for gene expression"""
+
+    @staticmethod
+    def plot_spatial_gene(
+        spatial_coords: np.ndarray,
+        expression: np.ndarray,
+        gene_name: str,
+        point_size: int = 5,
+        use_log: bool = False,
+        colorscale: str = "Viridis",
+        width: int = 800,
+        height: int = 800,
+        background_image: Optional[Union[np.ndarray, str]] = None,
+        scalefactors: Optional[Dict[str, float]] = None,
+        background_opacity: float = 0.5,
+    ) -> go.Figure:
+        """
+        Create spatial scatter plot of gene expression
+
+        Args:
+            spatial_coords: Nx2 array of spatial coordinates
+            expression: N-length array of gene expression values
+            gene_name: Name of the gene
+            point_size: Size of scatter points
+            use_log: Whether to apply log1p transformation to expression
+            colorscale: Plotly colorscale name
+            width: Figure width in pixels
+            height: Figure height in pixels
+            background_image: Background image as numpy array or file path
+            scalefactors: Scale factors from h5ad for coordinate mapping
+            background_opacity: Opacity of background image (0.0-1.0)
+
+        Returns:
+            Plotly Figure object
+        """
+        # Prepare expression values
+        expr_values = expression.copy()
+
+        # Apply log transformation if requested
+        if use_log:
+            expr_values = np.log1p(expr_values)
+            expr_label = f"log1p({gene_name})"
+        else:
+            expr_label = gene_name
+
+        # Extract coordinates
+        x = spatial_coords[:, 0]
+        y = spatial_coords[:, 1]
+
+        # Create figure
+        fig = go.Figure()
+
+        # Add background image if provided
+        if background_image is not None:
+            try:
+                # Handle different input types
+                if isinstance(background_image, str):
+                    # File path
+                    img = Image.open(background_image)
+                    img_array = np.array(img)
+                elif isinstance(background_image, np.ndarray):
+                    img_array = background_image
+                else:
+                    img_array = None
+                
+                if img_array is not None:
+                    # Convert numpy array to PIL Image for Plotly
+                    if img_array.dtype == np.float64 or img_array.dtype == np.float32:
+                        # Normalize float images to 0-255
+                        img_array = (img_array * 255).astype(np.uint8)
+                    
+                    img = Image.fromarray(img_array)
+                    
+                    # Calculate image bounds in spatial coordinate system
+                    # The spatial coordinates in adata.obsm['spatial'] are in full-resolution pixel space
+                    # The stored image is scaled down by scalefactors
+                    img_height, img_width = img_array.shape[:2]
+                    
+                    # Determine the scale factor used for this image
+                    if scalefactors:
+                        # Get scale factor based on image_key (passed via scalefactors dict)
+                        image_key = scalefactors.get('_image_key', 'hires')
+                        if image_key == 'lowres':
+                            scale = scalefactors.get('tissue_lowres_scalef', 1.0)
+                        else:
+                            scale = scalefactors.get('tissue_hires_scalef', 1.0)
+                        
+                        # Image spans from (0,0) to (img_width/scale, img_height/scale) in spatial coords
+                        img_x_min = 0
+                        img_y_min = 0
+                        img_x_max = img_width / scale
+                        img_y_max = img_height / scale
+                    else:
+                        # No scalefactors: fit image to coordinate bounds with padding
+                        padding = 0.05  # 5% padding
+                        x_range = x.max() - x.min()
+                        y_range = y.max() - y.min()
+                        img_x_min = x.min() - x_range * padding
+                        img_y_min = y.min() - y_range * padding
+                        img_x_max = x.max() + x_range * padding
+                        img_y_max = y.max() + y_range * padding
+                    
+                    # Convert to base64 for Plotly (use JPEG for faster encoding)
+                    buffered = BytesIO()
+                    # Convert RGBA to RGB if needed for JPEG
+                    if img.mode == 'RGBA':
+                        img_rgb = Image.new('RGB', img.size, (255, 255, 255))
+                        img_rgb.paste(img, mask=img.split()[3])
+                        img = img_rgb
+                    img.save(buffered, format="JPEG", quality=85)
+                    img_base64 = base64.b64encode(buffered.getvalue()).decode()
+                    img_src = f"data:image/jpeg;base64,{img_base64}"
+                    
+                    # With Y-axis reversed (autorange="reversed"), smaller Y is at top
+                    # Image anchor point is top-left, so y should be img_y_min (top of image)
+                    fig.add_layout_image(
+                        dict(
+                            source=img_src,
+                            xref="x",
+                            yref="y",
+                            x=img_x_min,
+                            y=img_y_min,  # Top of image (smallest Y value)
+                            sizex=img_x_max - img_x_min,
+                            sizey=img_y_max - img_y_min,
+                            sizing="stretch",
+                            opacity=background_opacity,
+                            layer="below",
+                            yanchor="top",
+                        )
+                    )
+            except Exception as e:
+                print(f"Warning: Could not load background image: {e}")
+
+        # Add scatter plot
+        fig.add_trace(
+            go.Scatter(
+                x=x,
+                y=y,
+                mode="markers",
+                marker=dict(
+                    size=point_size,
+                    color=expr_values,
+                    colorscale=colorscale,
+                    showscale=True,
+                    colorbar=dict(title=expr_label),
+                    line=dict(width=0),
+                ),
+                text=[f"Expression: {val:.2f}" for val in expr_values],
+                hovertemplate="<b>%{text}</b><br>"
+                + "X: %{x:.1f}<br>"
+                + "Y: %{y:.1f}<br>"
+                + "<extra></extra>",
+            )
+        )
+
+        # Update layout
+        fig.update_layout(
+            title=dict(
+                text=f"Spatial Expression: {gene_name}",
+                x=0.5,
+                xanchor="center",
+                font=dict(size=18),
+            ),
+            xaxis=dict(
+                title="Spatial X",
+                showgrid=False,
+                zeroline=False,
+            ),
+            yaxis=dict(
+                title="Spatial Y",
+                showgrid=False,
+                zeroline=False,
+                scaleanchor="x",
+                scaleratio=1,
+                autorange="reversed",  # Flip Y-axis to match image coordinate system
+            ),
+            width=width,
+            height=height,
+            hovermode="closest",
+            plot_bgcolor="white",
+        )
+
+        return fig
+
+    @staticmethod
+    def create_overview_plot(
+        spatial_coords: np.ndarray,
+        width: int = 600,
+        height: int = 600,
+    ) -> go.Figure:
+        """
+        Create overview plot of spatial coordinates (without gene expression)
+
+        Args:
+            spatial_coords: Nx2 array of spatial coordinates
+            width: Figure width in pixels
+            height: Figure height in pixels
+
+        Returns:
+            Plotly Figure object
+        """
+        x = spatial_coords[:, 0]
+        y = spatial_coords[:, 1]
+
+        fig = go.Figure()
+
+        fig.add_trace(
+            go.Scatter(
+                x=x,
+                y=y,
+                mode="markers",
+                marker=dict(
+                    size=3,
+                    color="lightblue",
+                    line=dict(width=0),
+                ),
+                hovertemplate="X: %{x:.1f}<br>Y: %{y:.1f}<extra></extra>",
+            )
+        )
+
+        fig.update_layout(
+            title=dict(
+                text="Spatial Overview",
+                x=0.5,
+                xanchor="center",
+            ),
+            xaxis=dict(
+                title="Spatial X",
+                showgrid=False,
+                zeroline=False,
+            ),
+            yaxis=dict(
+                title="Spatial Y",
+                showgrid=False,
+                zeroline=False,
+                scaleanchor="x",
+                scaleratio=1,
+            ),
+            width=width,
+            height=height,
+            plot_bgcolor="white",
+        )
+
+        return fig
+
+    @staticmethod
+    def create_overview_plot_with_background(
+        spatial_coords: np.ndarray,
+        background_image: Optional[np.ndarray] = None,
+        scalefactors: Optional[Dict[str, Any]] = None,
+        width: int = 600,
+        height: int = 600,
+        background_opacity: float = 0.6,
+    ) -> go.Figure:
+        """
+        Create overview plot of spatial coordinates with optional tissue background
+
+        Args:
+            spatial_coords: Nx2 array of spatial coordinates
+            background_image: Optional background image as numpy array
+            scalefactors: Scale factors for coordinate mapping
+            width: Figure width in pixels
+            height: Figure height in pixels
+            background_opacity: Opacity of background image
+
+        Returns:
+            Plotly Figure object
+        """
+        x = spatial_coords[:, 0]
+        y = spatial_coords[:, 1]
+
+        fig = go.Figure()
+
+        # Add background image if provided
+        if background_image is not None:
+            try:
+                img_array = background_image
+                if img_array.dtype == np.float64 or img_array.dtype == np.float32:
+                    img_array = (img_array * 255).astype(np.uint8)
+                
+                img = Image.fromarray(img_array)
+                img_height, img_width = img_array.shape[:2]
+                
+                # Calculate image bounds
+                if scalefactors:
+                    image_key = scalefactors.get('_image_key', 'hires')
+                    if image_key == 'lowres':
+                        scale = scalefactors.get('tissue_lowres_scalef', 1.0)
+                    else:
+                        scale = scalefactors.get('tissue_hires_scalef', 1.0)
+                    img_x_min = 0
+                    img_y_min = 0
+                    img_x_max = img_width / scale
+                    img_y_max = img_height / scale
+                else:
+                    padding = 0.05
+                    x_range = x.max() - x.min()
+                    y_range = y.max() - y.min()
+                    img_x_min = x.min() - x_range * padding
+                    img_y_min = y.min() - y_range * padding
+                    img_x_max = x.max() + x_range * padding
+                    img_y_max = y.max() + y_range * padding
+                
+                # Convert to base64
+                buffered = BytesIO()
+                if img.mode == 'RGBA':
+                    img_rgb = Image.new('RGB', img.size, (255, 255, 255))
+                    img_rgb.paste(img, mask=img.split()[3])
+                    img = img_rgb
+                img.save(buffered, format="JPEG", quality=85)
+                img_base64 = base64.b64encode(buffered.getvalue()).decode()
+                img_src = f"data:image/jpeg;base64,{img_base64}"
+                
+                fig.add_layout_image(
+                    dict(
+                        source=img_src,
+                        xref="x",
+                        yref="y",
+                        x=img_x_min,
+                        y=img_y_min,
+                        sizex=img_x_max - img_x_min,
+                        sizey=img_y_max - img_y_min,
+                        sizing="stretch",
+                        opacity=background_opacity,
+                        layer="below",
+                        yanchor="top",
+                    )
+                )
+            except Exception as e:
+                print(f"Warning: Could not add background image: {e}")
+
+        fig.add_trace(
+            go.Scatter(
+                x=x,
+                y=y,
+                mode="markers",
+                marker=dict(
+                    size=3,
+                    color="rgba(65, 105, 225, 0.7)",  # Royal blue with transparency
+                    line=dict(width=0),
+                ),
+                hovertemplate="X: %{x:.1f}<br>Y: %{y:.1f}<extra></extra>",
+            )
+        )
+
+        fig.update_layout(
+            title=dict(
+                text="Spatial Overview",
+                x=0.5,
+                xanchor="center",
+            ),
+            xaxis=dict(
+                title="Spatial X",
+                showgrid=False,
+                zeroline=False,
+            ),
+            yaxis=dict(
+                title="Spatial Y",
+                showgrid=False,
+                zeroline=False,
+                scaleanchor="x",
+                scaleratio=1,
+                autorange="reversed",  # Match image coordinate system
+            ),
+            width=width,
+            height=height,
+            plot_bgcolor="white",
+        )
+
+        return fig
+
+    @staticmethod
+    def get_expression_stats(expression: np.ndarray) -> dict:
+        """
+        Calculate basic statistics for expression values
+
+        Args:
+            expression: Expression array
+
+        Returns:
+            Dictionary with statistics
+        """
+        return {
+            "min": float(np.min(expression)),
+            "max": float(np.max(expression)),
+            "mean": float(np.mean(expression)),
+            "median": float(np.median(expression)),
+            "std": float(np.std(expression)),
+            "non_zero_count": int(np.sum(expression > 0)),
+            "non_zero_percent": float(100 * np.sum(expression > 0) / len(expression)),
+        }

utils/validator.py

@@ -0,0 +1,131 @@
+from typing import Tuple, List
+import numpy as np
+from anndata import AnnData
+
+
+class AnnDataValidator:
+    """Validate AnnData objects for spatial visualization requirements"""
+
+    MAX_OBS = 500_000  # Max number of observations (cells/spots)
+    MAX_VARS = 50_000  # Max number of variables (genes)
+
+    @staticmethod
+    def validate(adata: AnnData) -> Tuple[bool, List[str]]:
+        """
+        Validate AnnData object for spatial visualization
+
+        Args:
+            adata: AnnData object to validate
+
+        Returns:
+            Tuple of (is_valid, error_messages)
+        """
+        errors = []
+
+        # Check spatial coordinates exist
+        if "spatial" not in adata.obsm:
+            errors.append(
+                "Missing spatial coordinates. adata.obsm['spatial'] is required."
+            )
+
+        # Validate spatial coordinates format
+        if "spatial" in adata.obsm:
+            spatial = adata.obsm["spatial"]
+            if spatial.shape[1] != 2:
+                errors.append(
+                    f"Spatial coordinates must be 2D (x, y). Got shape: {spatial.shape}"
+                )
+
+        # Check number of observations
+        if adata.n_obs > AnnDataValidator.MAX_OBS:
+            errors.append(
+                f"Too many observations: {adata.n_obs:,} (max: {AnnDataValidator.MAX_OBS:,})"
+            )
+
+        # Check number of variables
+        if adata.n_vars > AnnDataValidator.MAX_VARS:
+            errors.append(
+                f"Too many variables: {adata.n_vars:,} (max: {AnnDataValidator.MAX_VARS:,})"
+            )
+
+        # Check if data is accessible
+        try:
+            _ = adata.var_names
+        except Exception as e:
+            errors.append(f"Cannot access variable names: {str(e)}")
+
+        return (len(errors) == 0, errors)
+
+    @staticmethod
+    def validate_gene(adata: AnnData, gene_name: str) -> Tuple[bool, str]:
+        """
+        Validate if a gene exists in the dataset
+
+        Args:
+            adata: AnnData object
+            gene_name: Gene name to check
+
+        Returns:
+            Tuple of (exists, message)
+        """
+        if gene_name not in adata.var_names:
+            # Try to find similar gene names
+            var_names = list(adata.var_names)
+            similar = [g for g in var_names if gene_name.lower() in g.lower()][:5]
+
+            if similar:
+                return (
+                    False,
+                    f"Gene '{gene_name}' not found. Similar genes: {', '.join(similar)}",
+                )
+            else:
+                return (False, f"Gene '{gene_name}' not found in dataset.")
+
+        return (True, f"Gene '{gene_name}' found.")
+
+    @staticmethod
+    def get_gene_expression(adata: AnnData, gene_name: str) -> np.ndarray:
+        """
+        Extract gene expression for a specific gene
+
+        Args:
+            adata: AnnData object
+            gene_name: Gene name to extract
+
+        Returns:
+            Expression vector as numpy array
+
+        Raises:
+            ValueError: If gene not found
+        """
+        is_valid, message = AnnDataValidator.validate_gene(adata, gene_name)
+        if not is_valid:
+            raise ValueError(message)
+
+        # Extract gene expression (works with backed mode)
+        gene_data = adata[:, gene_name].X
+
+        # Convert to dense array if sparse
+        if hasattr(gene_data, "toarray"):
+            gene_data = gene_data.toarray()
+
+        # Flatten if needed
+        if gene_data.ndim > 1:
+            gene_data = gene_data.flatten()
+
+        return gene_data
+
+    @staticmethod
+    def get_gene_list(adata: AnnData, limit: int = 1000) -> List[str]:
+        """
+        Get list of available genes (limited for performance)
+
+        Args:
+            adata: AnnData object
+            limit: Maximum number of genes to return
+
+        Returns:
+            List of gene names
+        """
+        var_names = list(adata.var_names)
+        return var_names[:limit]