FEAST-py 0.1.7__tar.gz

feast_py-0.1.7/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) <year> <copyright holders>
+
+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.

feast_py-0.1.7/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: FEAST-py
+Version: 0.1.7
+Summary: Spatial Transcriptomics Simulator
+Home-page: https://github.com/maiziezhoulab/FEAST-sim
+Author: Yiru CHEN
+Author-email: Yiru CHEN <yiru.22@intl.zju.edu.cn>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: alphashape>=1.3.1
+Requires-Dist: anndata>=0.9.2
+Requires-Dist: geomloss>=0.2.6
+Requires-Dist: joblib>=1.4.2
+Requires-Dist: matplotlib>=3.7.5
+Requires-Dist: numba>=0.55.2
+Requires-Dist: numpy>=1.22.4
+Requires-Dist: pandas>=2.0.3
+Requires-Dist: paste2>=1.0.1
+Requires-Dist: scanpy>=1.9.8
+Requires-Dist: scikit-learn>=1.2.1
+Requires-Dist: scipy>=1.10.1
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: torch>=1.12.1
+Requires-Dist: tqdm>=4.66.4
+Requires-Dist: spateo-release==1.1.1
+Requires-Dist: pydot>=4.0.1
+Requires-Dist: pyvinecopulib>=0.7.5
+Requires-Dist: thin-plate-spline>=1.2.0
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# FEAST: From features to slice: parameter-cloud modeling and 3D interpolation of spatial transcriptomics
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+**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-sim generates high-fidelity synthetic ST slices with controllable biological and technical variations.
+
+## 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)
+```bash
+pip install FEAST-sim
+```
+
+### Directly From Source
+```bash
+git clone https://github.com/maiziezhoulab/FEAST-sim.git
+cd FEAST-sim
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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-sim with notebook! Comprehensive Jupyter notebooks are provided in the repository:
+
+- **[example_single_sim.ipynb](example_single_sim.ipynb)**: Basic single-slice simulation for both sequencing-based and imaging-based ST data
+  - Visualization of parameter clouds
+  - Quality evaluation metrics
+  - Expression alteration examples
+
+To get the datasets for tutorial, you can download via https://drive.google.com/drive/folders/1lOQasZ9nxIDIZwlqEQDCBY0kJaA7GwZD?usp=drive_link
+
+
+## Architecture
+
+```
+FEAST-sim/
+├── 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](http://research.libd.org/spatialLIBD/) | Simulation, Clustering, Alignment | `DLPFC_151670.h5ad`<br>`DLPFC_151676.h5ad`<br>`DLPFC_151675.h5ad` |
+| **MERFISH** | MERFISH | [Allen Brain Atlas](https://alleninstitute.github.io/abc_atlas_access/descriptions/Zhuang-ABCA-1.html) | Simulation, Deconvolution, Interpolation | `MERFISH_006.h5ad`<br>`MERFISH_007.h5ad`<br>`MERFISH_005-009.h5ad` (5 files) |
+| **OpenST** | OpenST | [GEO: GSE251926](https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE251926) | Simulation | `OpenST_005.h5ad`<br>`OpenST_006.h5ad` |
+| **Stereo-seq** | Stereo-seq | [MOSTA](https://www.sciencedirect.com/science/article/pii/S0092867422003993) | Simulation | `Stereoseq_E14_5_E2S2.h5ad` |
+| **Slide-seq** | Slide-seqV2 | [SODB](https://gene.ai.tencent.com/SpatialOmics/dataset?datasetID=119) | Simulation | `Slideseq_001.h5ad` |
+| **Xenium** | Xenium | [10X Genomics](https://www.10xgenomics.com/datasets/human-lymph-node-preview-data-xenium-human-multi-tissue-and-cancer-panel-1-standard) | Simulation | `Xenium_LymphNode.h5ad` |
+
+
+**Note**: FEAST-sim is actively maintained. If you have any question, please let me know!

feast_py-0.1.7/README.md

@@ -0,0 +1,190 @@
+# FEAST: From features to slice: parameter-cloud modeling and 3D interpolation of spatial transcriptomics
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+
+**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-sim generates high-fidelity synthetic ST slices with controllable biological and technical variations.
+
+## 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)
+```bash
+pip install FEAST-sim
+```
+
+### Directly From Source
+```bash
+git clone https://github.com/maiziezhoulab/FEAST-sim.git
+cd FEAST-sim
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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-sim with notebook! Comprehensive Jupyter notebooks are provided in the repository:
+
+- **[example_single_sim.ipynb](example_single_sim.ipynb)**: Basic single-slice simulation for both sequencing-based and imaging-based ST data
+  - Visualization of parameter clouds
+  - Quality evaluation metrics
+  - Expression alteration examples
+
+To get the datasets for tutorial, you can download via https://drive.google.com/drive/folders/1lOQasZ9nxIDIZwlqEQDCBY0kJaA7GwZD?usp=drive_link
+
+
+## Architecture
+
+```
+FEAST-sim/
+├── 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](http://research.libd.org/spatialLIBD/) | Simulation, Clustering, Alignment | `DLPFC_151670.h5ad`<br>`DLPFC_151676.h5ad`<br>`DLPFC_151675.h5ad` |
+| **MERFISH** | MERFISH | [Allen Brain Atlas](https://alleninstitute.github.io/abc_atlas_access/descriptions/Zhuang-ABCA-1.html) | Simulation, Deconvolution, Interpolation | `MERFISH_006.h5ad`<br>`MERFISH_007.h5ad`<br>`MERFISH_005-009.h5ad` (5 files) |
+| **OpenST** | OpenST | [GEO: GSE251926](https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE251926) | Simulation | `OpenST_005.h5ad`<br>`OpenST_006.h5ad` |
+| **Stereo-seq** | Stereo-seq | [MOSTA](https://www.sciencedirect.com/science/article/pii/S0092867422003993) | Simulation | `Stereoseq_E14_5_E2S2.h5ad` |
+| **Slide-seq** | Slide-seqV2 | [SODB](https://gene.ai.tencent.com/SpatialOmics/dataset?datasetID=119) | Simulation | `Slideseq_001.h5ad` |
+| **Xenium** | Xenium | [10X Genomics](https://www.10xgenomics.com/datasets/human-lymph-node-preview-data-xenium-human-multi-tissue-and-cancer-panel-1-standard) | Simulation | `Xenium_LymphNode.h5ad` |
+
+
+**Note**: FEAST-sim is actively maintained. If you have any question, please let me know!

feast_py-0.1.7/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "FEAST-py"
+version = "0.1.7"
+description = "Spatial Transcriptomics Simulator"
+readme = "README.md"
+authors = [
+    {name = "Yiru CHEN", email = "yiru.22@intl.zju.edu.cn"}
+]
+license = {text = "MIT"}
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "alphashape>=1.3.1",
+    "anndata>=0.9.2",
+    "geomloss>=0.2.6",
+    "joblib>=1.4.2",
+    "matplotlib>=3.7.5",
+    "numba>=0.55.2",
+    "numpy>=1.22.4",
+    "pandas>=2.0.3",
+    "paste2>=1.0.1",
+    "scanpy>=1.9.8",
+    "scikit-learn>=1.2.1",  
+    "scipy>=1.10.1",
+    "seaborn>=0.13.2",
+    "torch>=1.12.1",
+    "tqdm>=4.66.4",
+    "spateo-release==1.1.1",
+    "pydot>=4.0.1",
+    "pyvinecopulib>=0.7.5",
+    "thin-plate-spline>=1.2.0",
+    
+]
+
+
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

feast_py-0.1.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

feast_py-0.1.7/setup.py

@@ -0,0 +1,41 @@
+from setuptools import setup, find_packages
+
+with open("README.md", "r", encoding="utf-8") as fh:
+    long_description = fh.read()
+
+setup(
+    name="FEAST-py",
+    version="0.1.7",
+    author="Yiru CHEN",
+    author_email="yiru.22@intl.zju.edu.cn",
+    description="Spatial Transcriptomics Simulator",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    url="https://github.com/maiziezhoulab/FEAST-sim",
+    package_dir={"": "src"},
+    packages=find_packages(where="src"),
+    license="MIT",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.8",
+    install_requires=[
+        "alphashape>=1.3.1",
+        "anndata>=0.9.2",
+        "geomloss>=0.2.6",
+        "joblib>=1.4.2",
+        "matplotlib>=3.7.5",
+        "numba>=0.55.2",
+        "numpy>=1.22.4",
+        "pandas>=2.0.3",
+        "paste2>=1.0.1",
+        "scanpy>=1.9.8",
+        "scikit-learn>=1.2.1",  
+        "scipy>=1.10.1",
+        "seaborn>=0.13.2",  
+        "torch>=1.12.1",
+        "tqdm>=4.66.4",
+    ],
+)