Metadata-Version: 2.5
Name: eykthyr
Version: 1.0.0
Summary: Eykthyr: Revealing transcriptional regulators of spatial gene programs
Project-URL: Homepage, https://github.com/ma-compbio/Eykthyr
Project-URL: Documentation, https://eykthyr.readthedocs.io
Project-URL: Bug Tracker, https://github.com/ma-compbio/Eykthyr/issues
Author-email: Spencer Krieger <spencer.krieger@gmail.com>
License: MIT License
        
        Copyright (c) 2024 Spencer Krieger
        
        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.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: anndata>=0.9.1
Requires-Dist: awkward>=2.0
Requires-Dist: leidenalg<0.11,>=0.9.0
Requires-Dist: louvain>=0.8.0
Requires-Dist: matplotlib<3.11,>=3.7.0
Requires-Dist: numba>=0.59
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=1.5.2
Requires-Dist: popari<0.1,>=0.0.72
Requires-Dist: scanpy>=1.9.2
Requires-Dist: scikit-learn>=0.24.1
Requires-Dist: scipy>=1.7.1
Requires-Dist: seaborn>=0.11.1
Requires-Dist: setuptools<81
Requires-Dist: squidpy>=1.2.3
Requires-Dist: torch>=1.13.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: umap-learn>=0.5.1
Provides-Extra: figures
Requires-Dist: fa2-modified; extra == 'figures'
Requires-Dist: gseapy; extra == 'figures'
Requires-Dist: jupyterlab; extra == 'figures'
Requires-Dist: pysam; extra == 'figures'
Provides-Extra: simulation
Requires-Dist: ipycanvas; extra == 'simulation'
Requires-Dist: jupyterlab; extra == 'simulation'
Description-Content-Type: text/markdown

# Overview of EYKTHYR

<img width="649" alt="EYKTHYR overview" src="https://github.com/user-attachments/assets/bbc155b5-a2fe-4479-b38f-37d2740bb7b9">

EYKTHYR is the first method developed to infer region-specific TF influences on spatial gene programs (or metagenes) using spatial multiome data. EYKTHYR addresses high technical dropout by introducing a novel combination of linear embeddings for gene expression and chromatin accessibility, denoising the data while maintaining interpretability, as shifts in metagene embeddings map directly back to input gene expression. Using information from spatially proximal neighbors, EYKTHYR learns a linear relationship between TF activity and metagene expression in each cell, where these two layers of linear mappings—from TF activity to metagenes, and from metagenes to gene expression—enable reasoning about how TF activity changes affect gene expression.

# Running EYKTHYR
## Input Data Format

EYKTHYR requires spatial transcriptomics and spatial chromatin accessibility data to be provided as AnnData objects, structured as follows:

**Spatial coordinates:**
The spatial coordinates of each cell should be included in the `.obsm` attribute of the AnnData object. The coordinates must be stored under `.obsm['spatial']` and formatted as an array with dimensions `[number of cells, 2]` (representing x and y coordinates for each cell).

**Gene expression data:**
Gene expression data should be stored in `.X` as a sparse matrix (recommended for large datasets) or a dense matrix, with dimensions `[number of cells, number of genes]`.

While not required, any additional metadata (e.g., cell types, batch labels) can be stored in `.obs`.

**Chromatin accessibility data:**
Chromatin accessibility data can be in the form of a fragments file, where each fragment corresponds to a cell, using the same cell IDs as in the gene expression data.

## System Requirements

The package was tested on Linux operating systems. Theoretically any OS that can run Python 3.10+ should be compatible, however extensive testing has not yet occurred.

A GPU is essentially required for running Popari, which is required for running EYKTHYR.

Expected installation time is around 10 minutes.

Expected runtime varies by dataset, but should take less than an hour including running plotting tools.

## Installation

The steps below were tested on Linux with Python 3.12 and NumPy 2.

### Step 1: Create a conda environment

```
conda create -n eykthyr -c conda-forge python=3.12
conda activate eykthyr
```

### Step 2: Install PyTorch

Install PyTorch with pip **before** installing EYKTHYR. Choose the wheel that matches your hardware (see https://pytorch.org/get-started/locally/ for other CUDA versions):

```
# NVIDIA GPU (CUDA 12.1)
pip install torch --index-url https://download.pytorch.org/whl/cu121

# CPU only
pip install torch --index-url https://download.pytorch.org/whl/cpu
```

Do not use `conda install pytorch -c pytorch`. That channel is no longer updated, and the build it installs can fail to import (`libmkl_intel_lp64.so.2` missing).

### Step 3: Install EYKTHYR

EYKTHYR is available as a PyPI package:

```
pip install "eykthyr[simulation]"
```

`simulation` adds JupyterLab and ipycanvas for the interactive notebooks. It is optional; `pip install eykthyr` installs just the package.

To run the tutorial and figure notebooks, or the tests, install from the GitHub repository instead:

```
git clone https://github.com/ma-compbio/Eykthyr.git
cd Eykthyr
pip install -e ".[simulation,figures]"
```

`figures` adds the extra packages used by the figure notebooks (gseapy, pysam, fa2_modified).

### Step 4: Check the installation

```
python -c "import eykthyr.eykthyr, eykthyr.plotting; print('ok')"

# optional, from a clone of the repository: run the unit tests
pip install pytest
python -m pytest tests/test_correlation.py
```

## Running the Pipeline

The EYKTHYR pipeline has three phases that must be run in order:

1. **ATAC preprocessing** — process spatial ATAC-seq fragments into a peak matrix and annotate peaks with TF motifs
2. **RNA preprocessing** — normalize and embed the spatial transcriptomic data
3. **Training and analysis** — combine TF activity with gene expression for inference and perturbation simulation

We provide tutorial notebooks for each of these steps (see `docs/source/tutorial_gallery/`), as well as a full walkthrough demo in `eykthyr_walkthrough_demo.ipynb`.

## Quick-Start Example

```python
from eykthyr.eykthyr import Eykthyr, load_anndata
import eykthyr.plotting as pl
import scanpy as sc

# 1. Load and preprocess RNA
e = Eykthyr()
adrna = sc.read("data/mouse_embryo2_rna.h5ad")
e.set_RNA([adrna])
e.preprocess_rna(make_plots=True)

# 2. Learn spatial metagenes
e.compute_metagenes(K=16, spatial_iterations=200)
e.analyze_metagenes()

# 3. Compute TF activity from ArchR outputs
e.compute_TF_activity(
    peak_tsvs=["data/spatialATACRNAmouseembryo2_peaks.tsv"],
    archr_dataset_names=["spatialATACRNAmouseembryo2"],
    motif_tsvs=["data/spatialATACRNAmouseembryo2_motifs.tsv"],
)

# 4. Infer TF → metagene regulatory weights
e.compute_TF_metagene_weights(num_hops=2)

# 5. Simulate TF perturbations
e.run_all_perturbations()

# 6. Save session
e.save_anndata("results.h5ad")

# Reload later
e = load_anndata("results.h5ad")

# 7. Visualize
pl.prep_paga(e, "original_leiden")
pl.paga_spatial_simulation(e, ["Msx1"], "original_leiden")
```

# Reproducing Paper Figures

The source data to recreate the papers is available through Zenodo at https://doi.org/10.5281/zenodo.20529989.
The following notebooks reproduce the figures in the EYKTHYR manuscript:

| Notebook | Contents |
|---|---|
| `Eykthyr_fig2.ipynb` | Figure 2 panels (spatial simulation, supplementary panels) |
| `Eykthyr_fig3.ipynb` | Figure 3 panels (pseudotime, TF perturbation simulation, TF ranking, GSEA) |
| `Eykthyr_fig4.ipynb` | Figure 4 panels |
| `Eykthyr_fig5.ipynb` | Figure 5 panels |
| `Nrg1_isoform_spatial.ipynb` | Nrg1 isoform spatial analysis (Figure 2H) |

The notebooks need a few packages beyond the core install. From a clone of this repository:

```
pip install -e ".[figures]"
```

They were run with Python 3.12 and numpy 2.3.5, pandas 2.3.3, scipy 1.16.3, scikit-learn 1.8.0, anndata 0.12.7, scanpy 1.11.5, squidpy 1.7.0, matplotlib 3.10.8, umap-learn 0.5.9.post2, torch 2.5.1 and popari 0.0.72. Newer versions may change figure details.
