Macrophage GRN Workflow

A Snakemake pipeline to build and interrogate macrophage / dendritic cell transcriptional networks. It combines public ChIP-Atlas binding targets with a curated Zbtb46 list, prunes the network to the supplied cells, infers activity with BITFAM, and runs trajectory-aware analyses and perturbation simulations.

What it does

• Download TF target sets from ChIP-Atlas (mouse mm10) and merge with curated Zbtb46 targets, then prune the network to expressed genes.
• Infer TF activity with my BITFAM fork (custom network and multiple seeded runs) using the provided single-cell object.
• Infer pseudotime trees with Lamian, export branches, and run time/variable differential expression on RNA and Z-scores.
• Prepare Seurat objects and compute markers / differential expression for RNA and activity assays.
• Convert data to CellOracle format, build gradients, and simulate knockdown and overexpression perturbations; aggregate perturbation scores and Markov chain transitions.
• Optional PGD-CellOracle branch to repeat simulations on PGD-transformed embeddings generated with PGDiffusion.

Inputs & configuration

• Primary input: config/config.yaml expects a cells RDS (inputs/cells.rds by default) plus resource paths for atlas factors and the Zbtb46 table.
• Tweak parameters (e.g., BITFAM whitelist regex, CellOracle grid size/mass) inside config/config.yaml.

How to run

1. Install Snakemake and ensure the required R/Python environments for the referenced scripts are available (my BITFAM fork, Lamian, Seurat, CellOracle, PGDiffusion).
2. Update paths in config/config.yaml if your inputs differ.
3. Launch the workflow from the repo root:

   snakemake -s workflow/Snakefile -j 8

Optional: NCBI API key

The whitelist_experiments rule queries NCBI E-utilities to resolve each whitelisted ChIP-seq experiment to its publication. NCBI rate-limits anonymous traffic to 3 req/s; an API key lifts this to 10 req/s and roughly cuts the runtime of that rule from ~10 min to ~3 min. The key is free and active immediately:

1. Sign in at account.ncbi.nlm.nih.gov (creating an account is free; Google/ORCID/etc. SSO works).
2. Click your username (top right) → Account Settings.
3. Scroll to API Key Management → Create an API Key and copy the hex string.
4. Export it before running Snakemake:

   export NCBI_API_KEY="your-hex-key-here"

The script reads this env var automatically; no code changes needed.

Key outputs

• results/bitfam/network/ and results/bitfam/results/: network files and activity estimates.
• results/lamian/: pseudotime, uncertainty, and differential tests.
• results/seurat/: markers and DE tables.
• results/celloracle*/: CellOracle objects, perturbation scores, and transition summaries for baseline and overexpression scenarios.
• results/pgd_celloracle*/: PGD-based variants of the CellOracle outputs.