Sovereign 8s.is mirror of standardgalactic/CauTrigger
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
ChengmingZhang-CAS ff6a0be0a1
Some checks failed
Check Build / package (push) Has been cancelled
Test / get-environments (push) Has been cancelled
Test / Tests pass in all hatch environments (push) Has been cancelled
Document velocyto installation workaround
2026-06-26 15:52:04 +09:00
.github fix(ci): replace run-cov with run to fix failing build 2025-11-05 13:52:44 +09:00
.vscode Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
docs Document velocyto installation workaround 2026-06-26 15:52:04 +09:00
src/cautrigger Support uncertain labels in state loss 2026-03-07 22:11:19 +09:00
tests test: simplify smoke test 2025-11-05 13:23:57 +09:00
.codecov.yaml Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
.cruft.json Add docs, notebooks, diagrams, update README 2025-11-04 22:01:05 +09:00
.editorconfig Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
.gitignore Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
.pre-commit-config.yaml Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
.readthedocs.yaml Fix RTD build: add src path and simplify YAML 2025-11-05 11:06:40 +09:00
biome.jsonc Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
CHANGELOG.md Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
environment.yml Document velocyto installation workaround 2026-06-26 15:52:04 +09:00
LICENSE Initialize project from cookiecutter-scverse 2025-10-27 16:41:50 +09:00
pyproject.toml docs(tutorial): polish visualization and layout, update index 2025-11-05 20:42:55 +09:00
README.md Document velocyto installation workaround 2026-06-26 15:52:04 +09:00

CauTrigger

[Tests][tests] Documentation

Deciphering biological system state transitions by hierarchical causal decomposition

CauTrigger is a causal decoupling model constructed on a dual-flow variational autoencoder (DFVAE) framework to identify causal triggers that influence biological state transitions in a hierarchical manner. Triggers (x^n) are processed through a feature selection layer to separate causal triggers (x^{c_n}) and others (\tilde{x}^{c_n}), and are then encoded into a latent space z that consists of causal (z^{c_n}) and spurious (z^{s_n}) components. This latent space is decoded to generate downstream conductors (x^{c_{n-1}}, \dots, x^{c_1}) and to predict the final cell state (y). The model strives to maximize the causal information flow I(z^{c_n} \rightarrow y) from z^{c_n} to y, thereby delineating hierarchical causal paths from x^{c_n} to y via z^{c_n}.


Getting started

Please refer to the documentation for installation instructions, API reference, and end-to-end tutorials.

Tutorials at a glance

The documentation includes four end-to-end tutorials (see the tutorials section):

  • Two-layer synthetic causal simulation – demonstrates how CauTrigger recovers known causal vs. spurious features in a controlled two-layer system.
  • hESC differentiation causal analysis – applies a two-layer TF/TG model to human embryonic stem cell differentiation (0 h vs 96 h).
  • T2D multi-omics causal analysis – uses a three-layer TF–CRE–TG hierarchy to analyze pancreatic islet multi-omics in control, pre-T2D, and T2D donors.
  • Gut–brain axis hierarchical analysis in ASD – models microbiota → host proteome → ASD states to illustrate hierarchical triggers and in silico perturbation.

For new applications, we recommend starting from the tutorial whose data structure is closest to your own dataset and adapting the data-preparation steps accordingly.

Installation

You need to have Python 3.10 or newer installed on your system. Installation usually finishes within a few minutes.

pip install git+https://github.com/ChengmingZhang-CAS/CauTrigger.git@main

The velocyto package is used to access the colDeltaCorpartial function for calculating local partial correlations in the perturbation vector-field utilities. Because velocyto builds Cython extensions and imports NumPy during its build step, install NumPy and Cython first and then install velocyto with build isolation disabled:

pip install numpy cython
pip install velocyto --no-build-isolation

This avoids the clean-environment build error ModuleNotFoundError: No module named 'numpy'. For the full installation guide, please refer to the official documentation velocyto-install.

Analyze your own datasets

Step 1: Prepare your dataset

Core AnnData structure

  • adata is a preprocessed AnnData object (cells in obs, features in var).
  • adata.var has a unique index (e.g. gene symbols).
  • adata.obs has a unique index for all cells.

State labels

  • The system state y is stored in a numeric column "labels" in adata.obs.
    • For binary tasks (n_state = 2), "labels" should lie in [0, 1] (e.g. 0/1 or continuous values).
    • For multi-class tasks (n_state > 2), "labels" contains integer class indices 0, 1, ..., n_state - 1.

Hierarchical inputs (2-layer / 3-layer)

  • For CauTrigger-2L or 3L, adata.obsm contains the downstream feature matrices, e.g. 'X_down' or ('X_down1', 'X_down2'). See the tutorials for complete two-layer and three-layer examples.

Step 2: Run CauTrigger

model = CauTrigger1L(adata)
model.train()

Step 3: Analysis

Select potential causal triggers. By default, SHAP-based attribution is used; you may optionally switch to gradient-based attribution by setting method="Grad".

topk = 10
weight_df_weight1 = model.get_up_feature_weights(
    normalize=True,
    method="SHAP",  # default; use "Grad" for gradient-based attribution
    sort_by_weight=False
)[0]["weight"]
causal_factors_layer1_indices = np.argsort(weight_df_weight1)[-topk:][::-1]

Visualize the causal latent space and then you can do in silico perturbation on it or other embeddings (e.g. UMAP):

adata.obsm["X_ct"] = model.get_model_output()["latent"][:, :2]

Contact

For questions, discussions, or bug reports, please use the GitHub issue tracker.

Citation

t.b.a