Causomic

Causal inference methods for -omics research

Causomic is a Python package for causal inference on -omics data (proteomics, transcriptomics, metabolomics, phosphoproteomics, etc.). Its goal is to predict the effects of interventions (e.g., drug treatments, protein inhibitions) on biological systems by combining prior-knowledge interaction networks with deep probabilistic causal models.

Table of Contents

• Overview
• Features
• Installation
• Getting Started
• Data Requirements
• Main Components
• Documentation
• Contributing
• Citation
• License

Overview

A fundamental challenge in biological experimentation is understanding how interventions (e.g., drug treatments, protein inhibitions) affect complex biological systems. Traditional machine learning approaches, particularly black box models, attempt to predict these effects without explicitly modeling the underlying causal relationships. This can be problematic when explainability is crucial (e.g., identifying disease-driving pathways) or when models incorrectly infer that downstream proteins causally influence upstream targets. Causomic addresses these limitations by:

1. Integrating prior biological knowledge from biological network databases (e.g., INDRA)
2. Building causal graphs that represent protein relationships and reconciling them with experimental data
3. Training deep probabilistic models with variational Bayesian inference (Pyro/PyTorch)
4. Predicting intervention effects on downstream proteins with uncertainty quantification

The package is particularly useful for:

• Drug discovery and target identification
• Understanding protein pathway dynamics
• Predicting off-target effects of interventions
• Analyzing perturbation experiments in proteomics

Features

🧬 Prior Knowledge Network (PKN) Construction

• Integration with INDRA (Integrated Network and Dynamical Reasoning Assembler)
• Automatic extraction and filtering of protein interaction networks
• Reconciliation of a prior network with experimental data via bootstrapped structure learning

📊 Causal Modeling

• Bayesian probabilistic models using Pyro (latent-variable structural causal models)
• Support for both observational and interventional data
• Native handling of missing data
• Uncertainty quantification for predictions

🎯 Intervention Prediction

• Predict downstream effects of protein inhibitions
• Estimate pathway-level responses
• Validate predictions against experimental data

🔬 MS Data Processing

• Integration with proteomics (MSstats) output format
• Normalization, summarization, and imputation utilities
• Gene-set correlation and pathway over-representation analysis (ORA)

🧪 Simulation

• Generate example graphs exhibiting different causal structures
• Simulate realistic proteomics data over causal graphs
• Procedural DAG generation with INDRA-style misspecification for method development

Installation

Prerequisites

• Python 3.11 or 3.12
• PyTorch 2.3+ (< 2.5)
• Pyro-PPL

Install from source

git clone https://github.com/Vitek-Lab/Causomic.git
cd Causomic
pip install -e .

Optional dependencies

• dev — testing and linting tools (pytest, black, isort): pip install -e ".[dev]"
• INDRA-CoGEx — required only for the Neo4j backend of prior extraction (extract_indra_prior(..., backend="neo4j") and the causomic.graph_construction.prior_extraction.neo4j_* modules). It is not on PyPI; install it from source if you need those features:

  pip install git+https://github.com/gyorilab/indra_cogex.git

  The rest of the package works without it.

Getting Started

The end-to-end workflow follows three steps:

1. Learn the causal graph — build a prior-knowledge network (e.g. from INDRA) and reconcile it with your data into a causal DAG.
2. Train the structural causal model — fit the latent-variable model (LVM) to your protein-level data over that graph.
3. Predict interventions — query the trained model for the downstream effect of an intervention (e.g. inhibiting a target protein).

📓 The complete, runnable walkthrough lives in the User Manual notebook. It covers both a simulated ground-truth system and a real INDRA network (EGFR inhibition), from graph construction through interventional inference. Start there.

Getting a prior network from INDRA

Step 1 above needs an INDRA-derived edge set. extract_indra_prior produces one from either of two backends, returning the same source/target/evidence_count/source_count table each way, so the rest of the pipeline is unaffected by which you pick.

• Local INDRA snapshot (default, offline). Load a pre-cached INDRA network — e.g. a networkx.DiGraph pickled from an INDRA CoGEx export — and pass it as graph:

  import pickle
  from causomic.network import extract_indra_prior
  
  with open("indranet_dir_graph_fix_corr_weights.pkl", "rb") as f:
      indra_graph = pickle.load(f)
  
  prior_edges = extract_indra_prior(
      source=["EGFR"],
      target=["ERK"],
      measured_proteins=data.columns.tolist(),
      graph=indra_graph,
      n_mediators=2,
  )

  This requires no live database connection — only a local copy of the INDRA graph pickle — and is the pattern used throughout the lab's own projects.

  For finer control, the underlying steps are available separately: prepare_graph filters the raw graph, and query_forward_paths, query_neighborhood_paths, query_drug_targets, and query_effect_nodes run the path searches. Import them from causomic.graph_construction.prior_extraction.

• Live Neo4j query. Pass backend="neo4j" with an authenticated client to query a running INDRA CoGEx instance directly, which is useful when you need up-to-date statements rather than a static snapshot. It requires the optional INDRA-CoGEx install and a reachable Neo4j database:

  from indra_cogex.client import Neo4jClient
  
  prior_edges = extract_indra_prior(
      source=["EGFR"],
      target=["ERK"],
      measured_proteins=data.columns.tolist(),
      backend="neo4j",
      client=Neo4jClient(url=api_url, auth=("neo4j", password)),
  )

Data Requirements

Input Data Format

Causomic expects data in different formats depending on where in the pipeline you start. The causal model and graph construction expect data in wide format with genes as columns, samples as rows, and values being quantitative experimental measurements.

Preprocessing with MSstats (R)

If you are using MS-based proteomics data, we recommend running the data through the MSstats pipeline via dataProcess. The resulting ProteinLevelData object can be passed directly into Causomic. A Python-side dataProcess is available in causomic.data_analysis for simulated and summarized data.

Main Components

🕸️ Graph Construction (causomic.graph_construction)

Three subpackages, one per stage of building a causal graph.

prior_extraction — pull a candidate edge set out of INDRA, from a local networkx graph (default) or a live Neo4j-CoGEx instance.

• prepare_graph, add_evidence_info, filter_graph_by_evidence_count

• query_forward_paths, query_neighborhood_paths, query_drug_targets, query_effect_nodes, query_confounders

• resolve_curies, format_query_results, pull_downstream_network

  query_forward_paths is the built-in control for maximum path length / mediator count between a source and target node — its n_mediators argument caps how many intermediate nodes a path may have, so you don't need to reimplement path-length pruning yourself.

posterior_estimation — learn which candidate edges the data supports.

• SparseHillClimb — hill-climb search restricted to prior edges
• BICGaussIndraPriors, BICGaussNoPriors, AICGaussIndraPriors, AICGaussNoPriors — scoring functions, with and without the prior term
• run_bootstrap, consensus_dag, best_scoring_dag — resample, then reduce many candidate DAGs to one
• run_dagma — continuous-optimization alternative to the hill climb
• prepare_indra_priors, calculate_edge_probabilities — evidence counts to edge probabilities
• filter_to_causal_subgraph, search_path_diagnostic

ci_repair — test the learned graph and repair what fails.

• find_failed_tests, convert_to_y0_graph
• lookup_confounder_candidates, process_failed_test

🎯 Causal Modeling (causomic.causal_model)

Probabilistic structural causal models for intervention prediction.

• LVM — latent-variable model (fit / intervention interface)
• ProteomicPerturbationModel, StochasticEdgeProteomicModel — underlying Pyro models

📈 Data Analysis (causomic.data_analysis)

Proteomics preprocessing and downstream analysis.

• dataProcess, normalize_median, summarize_data, imputation
• gen_correlation_matrix, test_gene_sets, prep_msstats_data
• run_ora, fetch_pathway_library, select_diverse_pathways, export_to_cytoscape

🧪 Simulation (causomic.simulation)

Synthetic graph and data generation for testing and method development.

• mediator, backdoor, frontdoor, signaling_network — example graphs
• simulate_data, generate_coefficients, build_igf_network
• generate_structured_dag, generate_indra_data, generate_cyclic_graph

🚀 High-Level Entry Points

• causomic.network — network estimation helpers (estimate_posterior_dag, filter_to_causal_subgraph, repair_confounding, extract_indra_prior, …)

• causomic.workflows — packaged pipelines (run_causal_workflow, run_toxicity_detection_workflow)

  extract_indra_prior defaults to backend="nx", which reads a local INDRA graph pickle and needs no credentials. backend="neo4j" queries INDRA-CoGEx live and requires the optional INDRA-CoGEx install (see Getting a prior network from INDRA).

Documentation

User Manual

The primary documentation is the runnable notebook:

• User Manual — complete workflow, from graph construction to interventional inference, on both simulated and real data.

API Reference

Detailed API documentation lives in the source-code docstrings. Key modules:

• causomic.causal_model.LVM — latent-variable causal model
• causomic.causal_model.models — underlying Pyro model definitions
• causomic.graph_construction.prior_extraction — INDRA prior networks (nx and Neo4j backends)
• causomic.graph_construction.posterior_estimation — structure learning and scoring
• causomic.graph_construction.ci_repair — independence testing and confounder repair
• causomic.data_analysis.proteomics_data_processor — data preprocessing
• causomic.simulation — synthetic graph and data generation

Contributing

We welcome contributions! Please also see CONTRIBUTING.md.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/Vitek-Lab/Causomic.git
cd Causomic
pip install -e ".[dev]"

Code Style & Tests

We use Black for formatting and isort for import sorting, and pytest for tests:

black --check src/ tests/
isort --check-only src/ tests/
pytest

Citation

If you use Causomic in your research, please cite:

@software{kohler2024causomic,
  title={Causomic: Causal inference methods for -omics research},
  author={Kohler, Devon},
  year={2024},
  url={https://github.com/Vitek-Lab/Causomic},
  version={0.9.0}
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

• Author: Devon Kohler
• Email: kohler.d@northeastern.edu
• Institution: Northeastern University
• GitHub: @devonjkohler

Acknowledgments

• INDRA - Integrated Network and Dynamical Reasoning Assembler
• MSstats - Statistical tools for proteomics
• Pyro - Probabilistic programming framework
• NetworkX - Network analysis library