FEAST-py 1.0.1

Spatial Transcriptomics Simulator

FEAST | From features to slice: parameter-cloud modeling of spatial transcriptomics for simulation and 3D interpolatory augmentation

FEAST (Feature-space-based modeling of Spatial Transcriptomics) is a comprehensive computational framework for simulating and interpolating spatial transcriptomics (ST) data. By modeling gene expression through a "parameter cloud" - a latent manifold capturing mean, variance, and sparsity - FEAST generates high-fidelity synthetic ST slices with controllable biological and technical variations. This work has been submitted to top conference in computational biology RECOMB 2026, and will release preprint soon.

Key Features

• High-Fidelity Simulation: Generate realistic ST data that preserves gene-level statistics, spatial patterns, and biological heterogeneity
• Controllable Alterations: Systematically modify gene expression (mean, variance, sparsity) for robust benchmarking
• Multiple ST Technologies: Support for Visium, MERFISH, Stereo-seq, Slide-seq, Xenium, and OpenST
• Alignment Benchmarks: Create paired datasets with controlled geometric transformations (rotation, warping) for testing alignment algorithms
• Deconvolution Ground Truth: Generate multi-resolution data with known cell-type compositions
• 3D Interpolation: Reconstruct missing tissue slices using optimal transport in parameter space

Installation

From PyPI (Recommended)

pip install FEAST-py

Directly From Source

git clone https://github.com/maiziezhoulab/FEAST
cd FEAST
pip install -e .

Dependencies

• Python >= 3.8
• scanpy
• anndata
• numpy
• scipy
• pandas
• scikit-learn
• pyvinecopulib
• POT (Python Optimal Transport)
• tps (Thin Plate Spline)

Quick Start

Single Slice Simulation

from FEAST import simulator
import scanpy as sc

# Load your reference data
adata = sc.read_h5ad("your_spatial_data.h5ad")

# Simple simulation with default parameters
simulated_adata = simulator.simulate_single_slice(
    adata=adata,
    sigma=1.0,  # Spatial smoothness parameter
    verbose=True
)

# Simulation with expression alteration
from FEAST.modeling.marginal_alteration import AlterationConfig

alteration_config = AlterationConfig.mean_only(fold_change=2.0)
altered_adata = simulator.simulate_single_slice(
    adata=adata,
    alteration_config=alteration_config,
    sigma=1.0
)

Alignment Simulation

from FEAST.alignment.alignment_simulator import simulate_alignment_rotation

# Generate paired datasets with rotation for alignment benchmarking
original, rotated = simulate_alignment_rotation(
    adata=adata,
    rotation_angle=30.0,  # degrees
    data_type='imaging',  # or 'sequencing'
    sigma=0  # Perfect pattern preservation
)

Deconvolution Simulation

from FEAST.deconvolution.generate_deconvolution import create_deconvolution_benchmark_data

# Generate multi-resolution data with known cell-type compositions
deconv_adata = create_deconvolution_benchmark_data(
    adata=single_cell_adata,
    downsampling_factor=0.25,
    grid_type='hexagonal',
    cell_type_key='cell_type'
)

3D Slice Interpolation

from FEAST.interpolation.interpolation_pipeline import interpolate_slices

# Interpolate missing slices between consecutive sections
interpolated_slices = interpolate_slices(
    adata_list=[slice_k, slice_k_plus_1],
    n_interpolate=3,  # Number of intermediate slices
    alpha=0.01,
    verbose=True
)

Tutorials

Try FEAST with notebook! Comprehensive Jupyter notebooks are provided in the repository:

• example_single_sim.ipynb: Basic single-slice simulation for both sequencing-based and imaging-based ST data

• example_interpolation.ipynb: Interpolation augumentation for MERFISH slices

Architecture

FEAST/
├── FEAST_core/          # Core simulation engine
│   ├── simulator.py     # Main simulation logic (G-SRBA algorithm)
│   ├── parameter_cloud.py  # Parameter cloud modeling
│   └── APIs.py          # Unified FEAST API
├── alignment/           # Alignment simulation
│   ├── alignment_simulator.py
│   └── spatial_align_alter.py  # Rotation & warping transformations
├── deconvolution/       # Deconvolution simulation
│   ├── deconvolution_simulator.py
│   └── generate_deconvolution.py
├── interpolation/       # 3D interpolation
│   ├── interpolation_pipeline.py
│   ├── parameter_interpolation.py
│   └── coordinate_generation.py
└── modeling/            # Statistical models
    ├── StudentT_mixture_model.py
    ├── Beta_mixture_model.py
    └── marginal_alteration.py

Reproduction Scripts

The reproduction/ folder contains scripts to reproduce all benchmarking results from the paper. Each subdirectory corresponds to a specific analysis:

reproduction/
├── 1_Simulator_benchmark/     # Figure 2: Simulation fidelity evaluation
├── 2_Clustering_simulation/   # Figure 3: Clustering robustness testing
├── 3_Alignment_simulation/    # Figure 4: Alignment algorithm benchmarking
├── 4_Deconvolution_simulation/# Supp Fig: Deconvolution ground truth generation
└── 5_Interpolation_simulation/# Figure 5: 3D slice interpolation evaluation

Dataset Organization

All scripts expect datasets in a data/ directory with the following naming convention:

data/
├── DLPFC_{sample_id}.h5ad          # Human DLPFC sections
├── MERFISH_{slice_id}.h5ad         # Mouse brain MERFISH slices
├── OpenST_{slice_id}.h5ad          # Lymph node OpenST slices
├── Stereoseq_{sample_id}.h5ad      # Mouse embryo Stereo-seq slices
├── Slideseq_{sample_id}.h5ad       # Slide-seqV2 slices
└── Xenium_{sample_id}.h5ad         # Xenium tissue slices

Required Datasets

Dataset	Technology	Source	Usage	Files
DLPFC	10X Visium	spatialLIBD	Simulation, Clustering, Alignment	DLPFC_151670.h5ad DLPFC_151676.h5ad DLPFC_151675.h5ad
MERFISH	MERFISH	Allen Brain Atlas	Simulation, Deconvolution, Interpolation	MERFISH_006.h5ad MERFISH_007.h5ad MERFISH_005-009.h5ad (5 files)
OpenST	OpenST	GEO: GSE251926	Simulation	OpenST_005.h5ad OpenST_006.h5ad
Stereo-seq	Stereo-seq	MOSTA	Simulation	Stereoseq_E14_5_E2S2.h5ad
Slide-seq	Slide-seqV2	SODB	Simulation	Slideseq_001.h5ad
Xenium	Xenium	10X Genomics	Simulation	Xenium_LymphNode.h5ad

Note: FEAST is actively maintained. If you have any question, please let me know!