FlashDeconv Reproducibility

This repository contains code and data links for reproducing the results in the FlashDeconv paper.

FlashDeconv enables atlas-scale, multi-resolution spatial deconvolution via structure-preserving sketching

Chen Yang, Jun Chen, Xianyang Zhang. bioRxiv (2025). DOI: 10.64898/2025.12.22.696108

Quick Start

# 1. Create a reproducible environment
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 2. Run the full Spotless benchmark (download, verify checksums, convert, run)
make benchmark

# 3. Or run everything (benchmark + analyses + figures)
make all

The make benchmark target automates six steps: downloading 13 GB of archived benchmark data from Zenodo (record 10277187), verifying MD5 checksums against Zenodo-published values (pinned in checksums/MD5SUMS), converting RDS files to Python-readable MTX format, validating directory structure and file counts, and running all five benchmark scripts. Individual steps can also be run separately:

make download          # Download + checksum verification
make convert           # RDS → MTX conversion (requires R + Seurat)
make validate          # Verify directory structure and file counts
make benchmark-silver  # Silver Standard only (56 synthetic datasets)
make benchmark-gold    # Gold Standard only (STARMap + seqFISH+)
make benchmark-liver   # Liver case study only
make benchmark-melanoma # Melanoma case study only

bash scripts/download_spotless_data.sh ./data/spotless
bash scripts/verify_checksums.sh ./data/spotless
Rscript scripts/convert_spotless_data.R ./data/spotless
bash scripts/validate_data.sh ./data/spotless
python benchmarks/benchmark_silver_standards.py --data_dir ./data/spotless/converted
python benchmarks/benchmark_gold_standard.py --data_dir ./data/spotless/converted
python benchmarks/benchmark_liver.py --data_dir ./data/spotless/converted
python benchmarks/benchmark_melanoma.py --data_dir ./data/spotless/converted
python benchmarks/benchmark_scalability.py --output_dir ./results

Notebook Reproducibility Layer

The command-line scripts remain the canonical full reproduction path. For interactive inspection of the main narrative analyses, this repository also provides Jupyter notebooks under notebooks/.

pip install -r requirements-notebooks.txt

# Fast synthetic/data-check path
export FD_REPRO_MODE=smoke
python scripts/run_notebook_smoke.py
jupyter notebook notebooks/

# Full-data path after completing the data preparation steps below
export FD_REPRO_MODE=full
export FD_DATA_DIR=./data
export FD_RESULTS_DIR=./results

The first notebook release covers Visium HD/tuft discovery, cortex lamination, and the leverage-score mechanism. Benchmark notebooks are intentionally deferred: benchmarks are better run as CLI jobs and inspected from their CSV outputs.

Repository Structure

flashdeconv-reproducibility/
├── README.md                           # This file
├── LICENSE                             # GPL-3.0-only license notice
├── requirements.txt                    # Reproducible Python runtime constraints
├── requirements-notebooks.txt          # Notebook runtime additions
├── environment.yml                     # Conda environment alternative
├── Makefile                            # One-command reproduction (make benchmark)
├── checksums/                          # Zenodo-published archive checksums
│   └── MD5SUMS
├── benchmarks/                         # Benchmark scripts
│   ├── benchmark_silver_standards.py   # Silver Standard (56 synthetic datasets)
│   ├── benchmark_gold_standard.py      # Gold Standard (STARMap + seqFISH+)
│   ├── benchmark_liver.py              # Liver case study
│   ├── benchmark_melanoma.py           # Melanoma case study
│   └── benchmark_scalability.py        # Scalability benchmark (1K-100K spots)
├── analysis/                           # Analysis pipelines
│   ├── leverage_deep_dive.py           # Leverage mechanism analysis (Figure 2)
│   ├── resolution_horizon_analysis.py  # Visium HD multi-scale analysis (Figure 6)
│   └── hidden_cell_analysis.py         # Hidden cell type discovery
├── figures/                            # Figure generation scripts
│   ├── main/                           # Main paper figures
│   │   ├── figure2_leverage_mechanism.py
│   │   ├── figure5_cortex_lamination.py
│   │   └── figure7_tuft_discovery.py
│   └── supplementary/                  # Supplementary figures
├── notebooks/                          # Narrative smoke/full reproduction notebooks
├── repro/                              # Shared helpers used by scripts and notebooks
├── scripts/                            # Data preparation scripts
│   ├── download_spotless_data.sh       # Download Spotless data from Zenodo
│   ├── convert_spotless_data.R         # Convert RDS to MTX format
│   ├── validate_data.sh               # Validate downloaded/converted data
│   ├── verify_checksums.sh            # MD5 verification against Zenodo
│   ├── download_visium_hd_data.sh      # Download Visium HD data
│   ├── download_cell2location_data.sh  # Download Cell2location mouse brain data
│   ├── run_notebook_smoke.py           # Execute notebook smoke checks
│   └── prepare_haber_reference.py      # Prepare Haber et al. reference
└── results/                            # Output directory for results

Software

The FlashDeconv software package is available at: https://github.com/cafferychen777/flashdeconv

pip install -r requirements.txt

Data Integrity

All download archives are verified against pinned checksums. The verification script (scripts/verify_checksums.sh) runs automatically during make download and prefers SHA-256 where available.

Checksums are pinned in checksums/SHA256SUMS (independently computed) and checksums/MD5SUMS (from Zenodo API, record 10277187).

Data Sources

All datasets used in this study are publicly available.

1. Spotless Benchmark Datasets

The primary benchmark datasets are from the Spotless benchmark study (Sang-aram et al., 2024).

Download: https://zenodo.org/records/10277187

Files:

• standards.tar.gz (6.9 GB) - Silver and Gold standards
• liver_datasets.tar.gz (4.5 GB) - Liver case study
• melanoma_datasets.tar.gz (1.3 GB) - Melanoma case study

After downloading and extracting (via download_spotless_data.sh), the expected directory structure is:

data/spotless/
├── reference/                          # Silver Standard scRNA-seq references (6 RDS files)
│   ├── silver_standard_1_brain_cortex.rds
│   ├── silver_standard_2_cerebellum_cell.rds
│   ├── silver_standard_3_cerebellum_nucleus.rds
│   ├── silver_standard_4_hippocampus.rds
│   ├── silver_standard_5_kidney.rds
│   └── silver_standard_6_scc_p5.rds
├── silver_standard_1-1/                # Silver Standard pseudo-spots; each folder has replicate RDS files
│   ├── brain_cortex_artificial_uniform_distinct_rep1.rds
│   ├── ...
│   └── brain_cortex_artificial_uniform_distinct_rep10.rds
├── silver_standard_1-2/
├── ...                                 # brain_cortex has patterns 1-11; others have 1-9
├── silver_standard_6-9/
├── gold_standard_1/                    # seqFISH+ cortex (Eng et al. 2019)
├── gold_standard_2/                    # seqFISH+ olfactory bulb (Eng et al. 2019)
├── gold_standard_3/                    # STARMap (Wang et al. 2018)
├── liver/                              # Liver case study (5 RDS files)
│   ├── liver_mouseStSt_9celltypes.rds  # snRNA-seq reference
│   ├── liver_mouseVisium_JB01.rds      # Visium sample 1
│   ├── liver_mouseVisium_JB02.rds
│   ├── liver_mouseVisium_JB03.rds
│   └── liver_mouseVisium_JB04.rds
└── melanoma/                           # Melanoma case study (4 RDS files)
    ├── melanoma_scrna_ref.rds          # scRNA-seq reference
    ├── melanoma_visium_sample02.rds    # Visium sample 2
    ├── melanoma_visium_sample03.rds
    └── melanoma_visium_sample04.rds

The converter accepts this current Spotless layout and older flat test_silver_standard/*.rds layouts. For the 56-dataset benchmark scripts, scripts/convert_spotless_data.R uses the rep1 file from each silver_standard_<dataset>-<pattern>/ directory and writes it as converted/silver_<dataset>_<pattern>_*.

Use bash scripts/validate_data.sh ./data/spotless to verify this structure after extraction.

2. 10x Genomics Datasets

Visium HD Mouse Small Intestine

Used for resolution horizon analysis and rare cell type discovery.

curl -O https://cf.10xgenomics.com/samples/spatial-exp/3.0.0/Visium_HD_Mouse_Small_Intestine/Visium_HD_Mouse_Small_Intestine_binned_outputs.tar.gz

Xenium Fresh Frozen Mouse Colon

Ground truth validation dataset with single-cell resolution.

curl -O https://cf.10xgenomics.com/samples/xenium/2.0.0/Xenium_V1_mouse_Colon_FF/Xenium_V1_mouse_Colon_FF_outs.zip

3. Cell2location Mouse Brain Dataset

Used for cortical lamination validation.

Use the repository downloader so the files land in the paths expected by the analysis loaders:

bash scripts/download_cell2location_data.sh ./data/mouse_brain

4. Intestinal scRNA-seq Reference (Haber et al., 2017)

Single-cell reference for intestinal deconvolution.

curl -L -o haber_processed.h5ad "https://zenodo.org/records/4447233/files/haber_processed.h5ad?download=1"

Reproducing Results

Prerequisites

# Python dependencies
pip install -r requirements.txt

# Alternative conda environment
conda env create -f environment.yml
conda activate flashdeconv-reproducibility

# R dependencies (for data conversion)
R -e "install.packages(c('Seurat', 'Matrix'))"

Part 1: Spotless Benchmark

Step 1: Download Data

# Download Spotless benchmark data (~13 GB total)
bash scripts/download_spotless_data.sh ./data/spotless

# Validate directory structure
bash scripts/validate_data.sh ./data/spotless

Step 2: Convert Data

# Convert RDS files to MTX format
Rscript scripts/convert_spotless_data.R ./data/spotless

# Validate converted files
bash scripts/validate_data.sh ./data/spotless

The conversion script prints a summary showing how many datasets were converted vs. skipped. If many are skipped, see the Troubleshooting section.

Step 3: Run Benchmarks

# Silver Standard benchmark (56 synthetic datasets)
python benchmarks/benchmark_silver_standards.py \
    --data_dir ./data/spotless/converted \
    --output_dir ./results

# Gold Standard benchmark (STARMap + seqFISH+)
python benchmarks/benchmark_gold_standard.py \
    --data_dir ./data/spotless/converted \
    --output_dir ./results

# Case studies
python benchmarks/benchmark_liver.py \
    --data_dir ./data/spotless/converted \
    --output_dir ./results

python benchmarks/benchmark_melanoma.py \
    --data_dir ./data/spotless/converted \
    --output_dir ./results

# Scalability benchmark (no external data needed)
python benchmarks/benchmark_scalability.py \
    --output_dir ./results

Part 2: Visium HD Analysis (Resolution Horizon)

This analysis demonstrates FlashDeconv's scale-space capability, showing how different cell types have characteristic spatial scales and identifying the "resolution horizon" (8-16μm threshold).

Step 1: Download Data

# Download Visium HD and reference data (~6.2 GB)
bash scripts/download_visium_hd_data.sh ./data

Step 2: Prepare Reference

# Prepare Haber et al. reference with cell type annotations
python scripts/prepare_haber_reference.py \
    --data-dir ./data \
    --output ./data/haber_intestine_reference.h5ad

This step is optional when haber_processed.h5ad from download_visium_hd_data.sh is present. The analysis loaders accept haber_intestine_reference.h5ad, haber_intestine_matched.h5ad, or haber_processed.h5ad.

Step 3: Run Analysis

# Resolution horizon analysis (multi-scale deconvolution)
python analysis/resolution_horizon_analysis.py \
    --data_dir ./data \
    --output_dir ./results \
    --bins 16,32,64,128

# Generate Tuft/stem visibility and colocalization intermediates
python analysis/tuft_stem_discovery.py \
    --data_dir ./data \
    --output_dir ./results

# Generate Figure 7: Tuft-Stem discovery
python figures/main/figure7_tuft_discovery.py \
    --results_dir ./results \
    --output_dir ./figures

Part 3: Cortex Lamination (Figure 5)

This analysis validates FlashDeconv using Cell2location's paired mouse brain dataset.

Step 1: Download Data

# Download Cell2location mouse brain data
bash scripts/download_cell2location_data.sh ./data/mouse_brain

This uses the current Cell2location tutorial data portal: the regression-model sc.h5ad reference and the mouse_brain_visium_wo_cloupe_data.zip archive. The loader also remains compatible with the older flat C2L/ST/48/ layout.

Step 2: Run Analysis

# Run deconvolution (generates level2_v3_data.npz)
python analysis/cortex_deconvolution.py \
    --data_dir ./data \
    --output_dir ./results

# Generate Figure 5
python figures/main/figure5_cortex_lamination.py \
    --results_dir ./results \
    --output_dir ./figures

Part 4: Leverage Mechanism (Figure 2)

This analysis demonstrates how leverage scores decouple biological identity from population abundance.

# Download Cell2location data if Part 3 was not run
bash scripts/download_cell2location_data.sh ./data/mouse_brain

# Run leverage analysis
python analysis/leverage_deep_dive.py \
    --data_dir ./data \
    --output_dir ./results

# Generate Figure 2
python figures/main/figure2_leverage_mechanism.py \
    --results_dir ./results \
    --output_dir ./figures

Troubleshooting

Conversion script skips most files

If convert_spotless_data.R reports many [SKIP] messages, the tarballs likely extracted with a top-level directory (e.g., standards/reference/ instead of reference/). Check:

ls ./data/spotless/

The converter and validator understand the current Zenodo layout both at the root and under a top-level standards/ directory. Only move files manually if you have inspected the archive and confirmed the expected reference/, silver_standard_<dataset>-<pattern>/, and gold_standard_* directories are one level deeper than the path passed to the scripts:

mv ./data/spotless/standards/* ./data/spotless/
rmdir ./data/spotless/standards

Then re-run the conversion script.

Download fails or produces small files

The Spotless data is hosted on Zenodo (record 10277187). If downloads fail:

1. Check that the Zenodo record is accessible in your browser
2. Check your internet connection and any institutional proxy settings
3. For large files, curl may time out — retry with a longer timeout:

   curl -fL --max-time 3600 -o file.tar.gz "URL"
   

4. As a fallback, download the tarballs manually from the Zenodo page and place them in ./data/spotless/

Validation script reports missing files

Run bash scripts/validate_data.sh ./data/spotless to see exactly which directories or files are missing. The script checks both raw RDS files and converted MTX files.

Citation

If you use FlashDeconv or this reproducibility code, please cite:

Yang, C., Chen, J. & Zhang, X. FlashDeconv enables atlas-scale, multi-resolution spatial deconvolution via structure-preserving sketching. bioRxiv (2025). https://doi.org/10.64898/2025.12.22.696108

@article{yang2025flashdeconv,
  title={FlashDeconv enables atlas-scale, multi-resolution spatial deconvolution via structure-preserving sketching},
  author={Yang, Chen and Chen, Jun and Zhang, Xianyang},
  journal={bioRxiv},
  year={2025},
  doi={10.64898/2025.12.22.696108},
  url={https://doi.org/10.64898/2025.12.22.696108}
}

License

• Code: GPL-3.0-only
• Data: See individual dataset licenses above

References

1. Sang-aram, C., Browaeys, R., Seurinck, R., & Saeys, Y. (2024). Spotless, a reproducible pipeline for benchmarking cell type deconvolution in spatial transcriptomics. eLife, 12, RP88431.

2. Kleshchevnikov, V., Shmatko, A., Dann, E., et al. (2022). Cell2location maps fine-grained cell types in spatial transcriptomics. Nature Biotechnology, 40, 661-671.

3. Haber, A. L., Biton, M., Rogel, N., et al. (2017). A single-cell survey of the small intestinal epithelium. Nature, 551, 333-339.