Skip to content
zhanglabtoolsPublic

About

Multi-relational graph representation learning for spatial epigenomics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

SEAREG

Dissecting spatially resolved chromatin regulation from spatial epigenomics data.

SEAREG is a multi-relational heterogeneous graph representation learning framework that connects tissue organization with chromatin regulatory features. It learns shared representations of tissue spots and genomic peaks, incorporating transcription factor (TF) motif nodes in sequence-informed analyses.

SEAREG framework: spatial epigenomic data and motif associations form a heterogeneous graph for multi-relational LightGCN, node embeddings, spatial domains, signal imputation, TF activity inference and gene regulatory inference

From tissue domains to regulatory features

The shared representations support four analyses:

  • Spatial domain identification: delineate tissue regions and connect them to associated peaks and TF motifs.
  • Spatial epigenomic signal imputation: estimate peak-level spatial profiles from spot–peak embedding similarity.
  • Spatial TF activity inference: estimate putative spatial TF activity from spot–motif associations.
  • Spatial gene regulatory inference: combine learned profiles, sequence matches and downstream peak–gene evidence to prioritize candidate TF–element–target relationships.

The manuscript investigates regional and interface-associated chromatin features in the mouse embryo, ATAC/H3K27ac programs in the P22 brain, and B-cell-state and receptor-associated programs in human tonsil. The two P22 assays are modeled independently before regional comparison. The developmental study uses a motif-free joint spot–peak representation across developing mouse brain stages. See method and score interpretation.

Tutorials

T1–T6 cover input preparation, model training, spatial domain identification, spot UMAP and joint node visualization. T1–T5 model individual sections with motif information; T6 jointly models four developing mouse brain sections with shared peaks. T1 includes a PRDM1–Peak1–Pou3f2 example that calculates the locus tracks, RNA distributions and motif hit from the supplied inputs. T7 starts from saved T3/T4 runs and calculates and draws Fig. 4d–j, from spatial-domain correspondence and candidate enhancer selection through the regulatory network and SOX6–Mal locus. Both notebooks list the external input files needed to rerun the recorded example. View the rendered T7 tutorial.

Tutorial Dataset Notebook
1 Mouse embryo (E13, spatial ATAC–RNA-seq) T1
2 Mouse embryo (E13, spatial-ATAC-seq) T2
3 Mouse brain (P22, spatial ATAC–RNA-seq) T3
4 Mouse brain (P22, spatial CUT&Tag–RNA-seq, H3K27ac) T4
5 Human tonsil (spatial-ATAC-seq) T5
6 Developing mouse brain (E11.0–E18.5, MISAR-seq) T6
7 P22 candidate enhancers and regulatory networks T7

T1 also demonstrates spatial feature scores for a peak and a TF motif.

T6 demonstrates joint modeling of four developing mouse brain sections with adaptive_depth_gate. It trains from chromatin counts and uses the final embeddings to identify spatial domains and construct UMAPs. The saved tutorial results are under result/Embryo_multislice/adaptive_depth_gate/. See the multislice guide for configuration and loading saved results.

The model inputs are chromatin counts, spatial coordinates and optional motif annotations. RNA informs downstream biological interpretation and selected reference-guided analyses in the manuscript.

Getting started

Use a complete GitHub checkout or Download ZIP for the notebooks, compressed example inputs and provided embeddings. Install the pinned Python 3.10.22 environment on Linux; the default uses PyTorch 2.2.0 with CUDA 12.1. The installation guide also covers CPU execution and package-only installation.

git clone https://github.com/zhanglabtools/SEAREG.git
cd SEAREG
conda env create -f environment.yml
conda activate seareg
python -m pip install "torch==2.2.0+cu121" --index-url https://download.pytorch.org/whl/cu121
python -m pip install "triton==2.2.0"
python -m pip install -r requirements.txt
python -m pip install --no-build-isolation --no-deps -e .
python -m pip check
conda install -c conda-forge tmux
jupyter lab tutorials/T1_Mouse_Embryo_E13_Spatial_ATAC_RNA.ipynb

Configure the paths, output directory, device and parameters in the first code cell, then run the cells in order. T1–T6 default to RUN_MODE="train": they prepare the data and network, train in independent tmux jobs and analyze each completed job's final embeddings. See the tutorial guide.

Data and results

The default example paths are relative to the repository root. data/<dataset>/ contains compressed counts and, for T1–T5, motif annotations; the notebooks prepare them automatically. T6 also includes tissue annotations and display palettes. GitHub Download ZIP and clone include the input bytes, with no separate data download or Git LFS client. Your own input and output paths may be outside the repository. See input data.

Included trained embeddings are under result/. New training saves its model exports, analysis and figures in a separate run directory under OUTPUT_DIR. See result layout.

Running the tutorials

The first code cell contains the complete configuration. For T1–T5 with your own single-section data, change its existing assignments, for example:

DATASET = "my_section"             # A run label.
ATAC_PATH = Path("/data/my_section/counts.h5ad")
MOTIF_PATH = Path("/data/my_section/motifs.h5")
OUTPUT_DIR = Path("/results/my_section")
TARGET_K = 8                       # Choose for your data.
RUN_MODE = "train"

The same cells prepare inputs, filter counts, prepare motif associations and the network, train, analyze and plot. MOTIF_OPTIONS controls reading, scanning or disabling motifs; the option dictionaries expose training, network and analysis settings. See the unified configuration example.

Choose TARGET_K for your single-section data. For joint analyses of your own sections, configure the T6 section and display options.

Notebook training runs in an independent tmux job, so closing the notebook does not stop it. The generated training_job/TRAINING_HANDOFF.md records progress, logs, checkpoints and recovery commands. Use sr.load_training_job(job_path).wait() to reconnect. See workflow and recovery for save schedules and compatible checkpoint recovery. The Python/CLI guide also explains synchronous calls and detached jobs for your own workflows.

For new single-section data, omitted epochs/radius multiplier/negative-refresh interval are 300/4/5 for at most 2,500 spots and 500/3/10 above that threshold; spatial weight defaults to 0.5. Multislice defaults are fixed at 500/4/5 with spatial weight 0.3 and the existing 3% gate budget. Both use max(10, 10 * ceil(E * pn_r / 70000000)) shards, independently per section, with pn_r=10 for single-section and 5 for multislice training. Explicit settings take precedence; all supplied tutorials keep their recorded configurations and outputs. See new-data defaults and stage helpers.

Select a physical GPU for training with SEAREG_PHYSICAL_GPU (T1–T5 default 0; T6 example default 1). For CPU training, install the CPU PyTorch build, set TRAINING_OPTIONS["device"] = "cpu" and EXECUTION_OPTIONS["physical_gpu"] = None in the configuration cell, and leave SEAREG_PHYSICAL_GPU unset in the notebook environment. An existing value overrides physical_gpu in that cell. Both training devices use tmux.

Analyze existing embeddings

To reanalyze an existing export instead of training, set RUN_MODE="provided", choose EMBEDDING_DIR and set ATAC_PATH to its matching counts. This alternative skips model training and writes new analysis and figures. To read saved labels and coordinates without fitting, reopen the saved analysis/ directory. See source selection.

Documentation

The bundled datasets come from Zhang et al. (2023), Deng et al. (2022) and Jiang et al. (2023). See data sources for sample identities and accessions. Citation metadata for the software is in CITATION.cff.

SEAREG source is distributed under the MIT License. Bundled components retain their own licenses; see third-party notices.

About

Multi-relational graph representation learning for spatial epigenomics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages