docs: clarify licensing and add third-party attributions

- Add code-level attribution in backbones.py for the foundation models.

Author: BenjaminIsaac0111

README.md

@@ -3,7 +3,10 @@
 > [!WARNING]
 > **Work in Progress**: This project is under active development. Core architectures, CLI flags, and data formats are subject to major changes.
 
-**SpatialTranscriptFormer** bridges histology and biological pathways through a high-performance transformer architecture. By modeling the dense interplay between morphological features and gene expression signatures, it provides an interpretable and spatially-coherent mapping of the tissue microenvironment.
+> [!TIP]
+> **Framework Release**: SpatialTranscriptFormer has been restructured from a research codebase into a robust framework. You can now use the Python API to train on your own spatial transcriptomics data with custom backbones and architectures.
+
+**SpatialTranscriptFormer** is a modular deep learning framework designed to bridge histology and biological pathways. It leverages transformer architectures to model the interplay between morphological features and gene expression signatures, providing interpretable mapping of the tissue microenvironment.
 
 ## Key Technical Pillars
 
@@ -35,13 +38,13 @@ This project requires [Conda](https://docs.conda.io/en/latest/).
 1. Clone the repository.
 2. Run the automated setup script:
 3. On Windows: `.\setup.ps1`
-   - On Linux/HPC: `bash setup.sh`
+4. On Linux/HPC: `bash setup.sh`
 
-## Usage
+## Usage: HEST-1k Benchmark Recipe
 
-### Dataset Access
+While the core `SpatialTranscriptFormer` framework can be integrated programmatically with any dataset (see the **[Python API Reference](docs/API.md)** and **[Bring Your Own Data Guide](src/spatial_transcript_former/recipes/custom/README.md)**), this repository includes a complete, out-of-the-box CLI pipeline specifically for reproducing our benchmarks on the [HEST-1k dataset](https://huggingface.co/datasets/MahmoodLab/hest).
 
-The model uses the **HEST1k** dataset. You can download specific subsets (by organ, technology, etc.) or the entire dataset using the `stf-download` utility:
+### Dataset Access
 
 ```bash
 # List available filtering options
@@ -94,10 +97,19 @@ Visualization plots will be saved to the `./results` directory.
 
 ## Documentation
 
-- [Models](docs/MODELS.md): Detailed model architectures and scaling parameters.
-- [Data Structure](docs/DATA_STRUCTURE.md): Organization of HEST data on disk.
-- [Pathway Mapping](docs/PATHWAY_MAPPING.md): Clinical interpretability and pathway integration.
-- [Gene Analysis](docs/GENE_ANALYSIS.md): Modeling strategies for high-dimensional gene space.
+### Framework APIs & Usage
+
+- **[Python API Reference](docs/API.md)**: Full documentation for `Trainer`, `Predictor`, and `SpatialDataset`.
+- **[Bring Your Own Data Guide](src/spatial_transcript_former/recipes/custom/README.md)**: Templates and examples for training on your own non-HEST spatial transcriptomics data.
+- **[HEST Recipe Docs](src/spatial_transcript_former/recipes/hest/README.md)**: Detailed documentation for the included HEST-1k dataset recipe.
+- **[Training Guide](docs/TRAINING_GUIDE.md)**: Complete list of configuration flags and preset configurations for HEST models.
+
+### Theory & Interpretability
+
+- **[Models & Architecture](docs/MODELS.md)**: Deep dive into the quad-flow interaction logic and network scaling.
+- **[Pathway Mapping](docs/PATHWAY_MAPPING.md)**: Clinical interpretability, pathway bottleneck design, and MSigDB integration.
+- **[Gene Analysis](docs/GENE_ANALYSIS.md)**: Modeling strategies for mapping morphology to high-dimensional gene spaces.
+- **[Data Structure](docs/DATA_STRUCTURE.md)**: Detailed breakdown of the HEST data structure on disk, metadata conventions, and preprocessing invariants.
 
 ## Development
 

scripts/diagnose_collapse.py

@@ -21,7 +21,7 @@
 import numpy as np
 
 from spatial_transcript_former.models.interaction import SpatialTranscriptFormer
-from spatial_transcript_former.data.dataset import (
+from spatial_transcript_former.recipes.hest.dataset import (
     HEST_FeatureDataset,
     load_global_genes,
 )

scripts/download_hest.py

@@ -5,7 +5,7 @@
 
 # Add src to path
 sys.path.append(os.path.abspath("src"))
-from spatial_transcript_former.data.download import (
+from spatial_transcript_former.recipes.hest.download import (
     download_hest_subset,
     download_metadata,
 )

scripts/inspect_outputs.py

@@ -4,7 +4,7 @@
 import argparse
 import numpy as np
 from spatial_transcript_former.models import SpatialTranscriptFormer
-from spatial_transcript_former.data.utils import get_sample_ids, setup_dataloaders
+from spatial_transcript_former.recipes.hest.utils import get_sample_ids, setup_dataloaders
 
 
 class Args:

scripts/inspect_sample.py

@@ -5,7 +5,7 @@
 
 # Add src to path
 sys.path.append(os.path.abspath("src"))
-from spatial_transcript_former.data.io import get_hest_data_dir, load_h5ad_metadata
+from spatial_transcript_former.recipes.hest.io import get_hest_data_dir, load_h5ad_metadata
 from spatial_transcript_former.config import get_config
 from spatial_transcript_former.data.pathways import (
     download_msigdb_gmt,

src/spatial_transcript_former/data/__init__.py

@@ -20,8 +20,3 @@
     apply_dihedral_to_tensor,
     normalize_coordinates,
 )
-
-# HEST-specific (backward compatibility)
-from .dataset import HEST_Dataset, get_hest_dataloader
-from .splitting import split_hest_patients
-from .download import download_hest_subset, download_metadata, filter_samples

src/spatial_transcript_former/recipes/hest/README.md

@@ -0,0 +1,16 @@
+# HEST-1k Recipe
+
+This directory contains the recipe for training `SpatialTranscriptFormer` on the **HEST-1k** benchmark dataset.
+
+While the core `SpatialTranscriptFormer` framework is dataset-agnostic, this recipe provides a complete, out-of-the-box pipeline for reproducing our benchmarks, including data downloading, preprocessing, and specialized dataloaders.
+
+## Components
+
+- **`dataset.py`**: Contains `HEST_Dataset` and `HEST_FeatureDataset`, which subclass `SpatialDataset` to handle the specific `.h5ad` structure and metadata conventions of the HEST dataset.
+- **`io.py`**: Utilities for reading spatial graphs, coordinates, and `.h5ad` matrices.
+- **`utils.py`**: HEST-specific dataset setup routines, splitting logic, and vocabulary loading.
+- **`download.py`**: Logic for fetching subsets of the gated HEST dataset from Hugging Face.
+
+## Usage
+
+For complete CLI usage and training preset commands, refer to the main **[README.md](../../../../README.md)** and the **[Training Guide](../../../../docs/TRAINING_GUIDE.md)**.

src/spatial_transcript_former/recipes/hest/__init__.py

@@ -19,7 +19,7 @@
 """
 
 # Dataset classes and DataLoader factories
-from spatial_transcript_former.data.dataset import (
+from spatial_transcript_former.recipes.hest.dataset import (
     HEST_Dataset,
     HEST_FeatureDataset,
     get_hest_dataloader,
@@ -29,31 +29,31 @@
 )
 
 # I/O utilities
-from spatial_transcript_former.data.io import (
+from spatial_transcript_former.recipes.hest.io import (
     get_hest_data_dir,
     load_h5ad_metadata,
     get_image_from_h5ad,
     decode_h5_string,
 )
 
 # Download
-from spatial_transcript_former.data.download import (
+from spatial_transcript_former.recipes.hest.download import (
     download_hest_subset,
     download_metadata,
     filter_samples,
 )
 
 # Sample discovery and dataloader setup
-from spatial_transcript_former.data.utils import (
+from spatial_transcript_former.recipes.hest.utils import (
     get_sample_ids,
     setup_dataloaders,
 )
 
 # Splitting
-from spatial_transcript_former.data.splitting import split_hest_patients
+from spatial_transcript_former.recipes.hest.splitting import split_hest_patients
 
 # Vocab building
-from spatial_transcript_former.data.build_vocab import scan_h5ad_files
+from spatial_transcript_former.recipes.hest.build_vocab import scan_h5ad_files
 
 __all__ = [
     # Datasets

…al_transcript_former/data/build_vocab.py …cript_former/recipes/hest/build_vocab.pysrc/spatial_transcript_former/data/build_vocab.py renamed to src/spatial_transcript_former/recipes/hest/build_vocab.py src/spatial_transcript_former/data/build_vocab.py renamed to src/spatial_transcript_former/recipes/hest/build_vocab.py

@@ -11,7 +11,7 @@
 
 # Add src to path
 sys.path.append(os.path.abspath("src"))
-from spatial_transcript_former.data.io import get_hest_data_dir, load_h5ad_metadata
+from spatial_transcript_former.recipes.hest.io import get_hest_data_dir, load_h5ad_metadata
 from spatial_transcript_former.config import get_config
 from spatial_transcript_former.data.pathways import (
     download_msigdb_gmt,

…patial_transcript_former/data/dataset.py …ranscript_former/recipes/hest/dataset.pysrc/spatial_transcript_former/data/dataset.py renamed to src/spatial_transcript_former/recipes/hest/dataset.py src/spatial_transcript_former/data/dataset.py renamed to src/spatial_transcript_former/recipes/hest/dataset.py

@@ -23,7 +23,7 @@
 import pandas as pd
 import numpy as np
 from .io import decode_h5_string, load_h5ad_metadata
-from .base import (
+from spatial_transcript_former.data.base import (
     SpatialDataset,
     apply_dihedral_augmentation,
     apply_dihedral_to_tensor,
@@ -37,7 +37,7 @@
 
 # Augmentation helpers and normalize_coordinates are now in data.base
 # and imported above. Kept here for backward compatibility:
-# from spatial_transcript_former.data.dataset import apply_dihedral_augmentation
+# from spatial_transcript_former.recipes.hest.dataset import apply_dihedral_augmentation
 # still works via the import at the top of this file.