PreciCE: Data-driven multi-gene control for precision cell-fate engineering

Project website · Scientific background (bioRxiv preprint v1)

PreciCE is a workflow for data-driven precision cell-fate engineering through highly multiplexed gene control. Given single-cell expression data, it:

1. preprocesses cells and genes;
2. identifies differential expression between source and target cell types;
3. uses either a supplied fitted regulatory network or a network inferred with pySCENIC;
4. computes candidate transcription-factor perturbations; and
5. produces a Precision Score plot and reusable tabular artifacts.

The model/precice_script.py command is the primary Release 1 interface. IPython, Notebook, and direct Python API use are also supported from a repository checkout.

Requirements and installation

Release 1 supports a Linux x86-64 CPU environment and is tested and recommended for human gene-symbol data. Create the readable Conda environment from the repository root with:

CONDA_CHANNEL_PRIORITY=strict conda env create \
    --file environment-linux-64-cpu.yml
conda activate precice-release1-cpu

The same environment can be created with Mamba or micromamba. An explicit Linux x86-64 package specification is also available when the exact recorded package artifacts are required. See the Conda environment guide for the purpose of each file and portable commands.

Release 1 runs from a repository checkout; it is not installed as a Python package. Its environment includes IPython and an IPython kernel, but not a Jupyter server or Qt graphical stack.

Inputs and resources

The workflow requires an .h5ad file containing a cell-by-gene count matrix and observation metadata with:

• a cell-type column containing the requested source and target values; and
• a batch column used by scVI.

The defaults are label for cell type and day for batch. Use --inspect-cell-metadata before a run if those names or values are unknown.

Generated human networks also require these pySCENIC resources:

Role	Repository-relative path
Transcription-factor list	data/input/resources/TF_names_v_1.01_human.txt
Ranking database	data/input/resources/hg38__refseq-r80__500bp_up_and_100bp_down_tss.mc9nr.genes_vs_motifs.rankings.feather
Motif annotations	data/input/resources/motifs-v9-nr.hgnc-m0.001-o0.0.tbl

The optimizer requires the species TF list for both generated- and supplied- network runs. Release 1 bundles the small human and mouse TF lists; obtain the large ranking database and motif annotations from their original providers as described in the resource guide. Generated-network resources may instead be passed explicitly. Default paths are resolved from the checkout, not the caller's working directory. Principal resource and dependency attribution is collected in THIRD_PARTY_NOTICES.md.

PreciCE validates that each resource is readable but cannot establish biological compatibility among the species, genome build, TF list, ranking database, motif annotations, expression data, and fitted network.

The example-dataset guide describes the optional Friedman human cardiac-differentiation dataset. Input datasets are not selected implicitly.

Quick starts

Every full run requires a fresh --project-dir. The directory may be missing or empty; a nonempty directory is rejected rather than resumed or overwritten.

Supplied network

The repository includes a fitted Friedman all-cells network. From the repository root:

python model/precice_script.py \
    --input-path /path/to/Friedman.h5ad \
    --project-dir /path/to/fresh-supplied-network-run \
    --source-name stem \
    --target-name meso \
    --network-file data/input/networks/friedman-all-cells/fitted-network.csv

--network-file requires a nonempty CSV with TF, target, and weight columns. It bypasses GRN inference and weight learning, while preprocessing, differential expression, optimization, and plotting still run normally. See the fitted-network guide for the bundled network's scope.

Generated network

With the human resource files at their documented default paths:

python model/precice_script.py \
    --input-path /path/to/Friedman.h5ad \
    --project-dir /path/to/fresh-generated-network-run \
    --source-name stem \
    --target-name meso

By default, the source and target cells are used for network inference. Select another set or all cells with, for example:

--grn-cell-types stem meso endo
--grn-cell-types all

all cannot be combined with other values. This selection changes the cells used to infer the network; source and target still define the differential- expression transition.

Inspect input metadata

Metadata inspection is read-only and does not require --project-dir:

python model/precice_script.py \
    --input-path /path/to/dataset.h5ad \
    --inspect-cell-metadata

The summary lists observation columns and value counts for columns with no more than 20 distinct values. Add --cell-type-label COLUMN to mark the intended cell-type column.

Important command-line options

Option	Default	Purpose
--input-path	required	Input .h5ad file
--project-dir	required for full runs	Fresh run-output boundary
--source-name / --target-name	stem / meso	Cell-state transition
--cell-type-label / --batch-key	label / day	Observation-metadata columns
--species	human	Resource and solver TF selection; human is the only tested and recommended Release 1 species
--network-file	none	Supplied final TF,target,weight network
--grn-cell-types	source and target	Cells used for generated-network inference; all selects every cell
--tf-list	documented human file	Generated-network TF list
--ranking-db	documented human file	Generated-network ranking database; repeat for multiple databases
--motif-annotation	documented human file	Generated-network motif annotations
--n-workers	36	GRNBOOST2 workers
--prune-workers	all available CPUs	Motif-pruning workers
--prune-chunk-size	100	Modules assigned to each pruning task
--seed	777	Seed for scVI, posterior DE, GRNBOOST2, and weight learning; range 0..4294967295
--mito-percent-max	5	Retain cells below this mitochondrial-count percentage; 20 is a more permissive suggested value when supported by dataset QC, not a universal threshold
--de-fdr-target	0.05	Posterior expected FDR target for scVI DE
--p-thresh	0.02	Adjusted-p cutoff for compatible frequentist or precomputed DE tables; it does not replace --de-fdr-target for scVI
--hops	3	Maximum regulatory-network path length used in optimization
--lambda-max-step	1	Regularization-path maximum step
--lambda-step-size	1e-4	Regularization-path step size
--max-rows	12	Maximum rows in the Precision Score plot
--plot-output	precision.png	Plot basename; PNG, JPEG, and PDF are supported
--no-plot	disabled	Skip plot construction and saving

For finer resolution, try --lambda-max-step 10 --lambda-step-size 1e-5; use --max-rows 20 to display more plot rows.

Semantic outputs

A generated-network run writes these stable paths under --project-dir:

Artifact	Meaning
preprocess/de.h5ad	Preprocessed expression data with highly-variable-gene filtering for DE
preprocess/grn.h5ad	Preprocessed expression data without highly-variable-gene filtering for GRN inference and model fitting
de/result.csv	First differential-expression result used by the optimizer
de/result-2.csv, ...	Additional API-produced transitions in call order
de/transitions.json	Source, target, and result-file mapping for every transition
grn/adjacencies.csv	Raw GRNBOOST2 edges with inference importance
grn/inferred-network.csv	Motif-pruned edges with inference importance
grn/regulons.gmt	Enriched regulons
model/fitted-network.csv	Solver-ready edges with learned response weight
results/perturbation-path.csv	Perturbations across tested regularization values
results/selected-perturbations.csv	Selected perturbations and reconstruction scores
plots/precision.png	Default plot unless --no-plot is used; basename follows --plot-output

Motif pruning determines which inferred edges survive; it does not turn inference importance into a fitted response weight. Only model/fitted-network.csv contains learned weight values.

Supplied-network runs do not create grn/ or model/, but retain the other semantic stages. Within a run, PreciCE passes exact producer-returned paths downstream and does not search for conventional filenames.

Precision Score

The Precision Score is the fractional reduction in start-to-target reconstruction RMSE achieved by the selected TF perturbations. It is stored as Relative RMSE Reduction: 0 means no reduction in modeled error, while 1 is displayed as 100% and means exact reconstruction by the fitted linear model. PreciCE preserves but warns about values outside the expected [0, 1] range. This is a model-reconstruction measure, not classification precision or an estimate of experimental conversion efficacy.

Plot-label arrows show the selected TF direction. Pure additions continue the preceding selection with AND; a removal or sign change restates the complete current selection.

Reproducibility and limitations

With identical inputs, resources, settings, dependency versions, worker and thread counts, and CPU profile, --seed provides bounded numerical repeatability. Byte-identical files, exact floating-point equality, cross- version or cross-platform results, and CPU/GPU parity are not guaranteed.

Release 1 also has these user-relevant limits:

• Human is the only tested and recommended species. Mitochondrial QC recognizes MT- and mt- prefixes case-insensitively, but Release 1 mouse workflows have not received equivalent end-to-end scientific validation. Mouse generated-network runs require explicit compatible pySCENIC resources.
• Release 1 uses fixed pySCENIC pruning settings: rank_threshold=5000, auc_threshold=0.05, nes_threshold=3.0, and motif_similarity_fdr=0.001. Alternative settings can change retained regulons and downstream results; only pruning worker count and module chunk size are exposed in this release.
• A supplied network is not automatically proven transferable to another dataset or biological context.
• A project directory cannot be resumed, partially reused, or overwritten.
• The supported environment is CPU-only.

Plotting and unattended runs

Script execution uses Matplotlib's Agg backend unless MPLBACKEND is already set. It saves the requested plot without opening a window. --no-plot skips plotting entirely, and a failed or empty optimizer result stops the workflow.

Notebook callers can use plot.build_precision_figure(...) for an inline figure without saving it. See the IPython, REPL, and Notebook workflow for the supported direct API, explicit GRN resources, generated- and supplied-network alternatives, and returned artifact paths.

Troubleshooting

• Import errors: activate the documented environment and run from a complete repository checkout.
• Missing files: prefer absolute --input-path, --project-dir, network, and resource paths.
• Metadata errors: inspect the input and set --cell-type-label and --batch-key explicitly.
• Memory pressure: reduce --n-workers and --prune-workers.

Tests

Release 1 includes self-contained runtime regression tests for the mathematical core, CLI validation, stable artifacts, plotting, and unattended execution:

MPLBACKEND=Agg python -B -m unittest discover -s tests -p 'test_*.py' -v

They create synthetic and temporary fixtures and use the bundled human TF list and human-derived fitted network. No external expression dataset, ranking database, or motif table is required. They are not a substitute for end-to-end scientific validation.

Scientific background and credits

The current scientific background is the bioRxiv preprint “PreciCE: Precision engineering of cell fates via data-driven multi-gene control of transcriptional networks”. The manuscript is under revision, so this link is provided for scientific context rather than as a formal software citation recommendation. Formal citation metadata will follow after the attribution policy and revised or published manuscript are settled.

PreciCE originated through the work of Yusuf Roohani and Jens Magnusson. Git history is the record for code-level contributions by them and other software contributors; scientific authorship is broader and is not inferred from repository contributions.

The Friedman example, pySCENIC/cisTarget resources, and principal scientific dependencies are acknowledged in THIRD_PARTY_NOTICES.md.

License and feedback

PreciCE-authored software and documentation are available under the MIT License. Bug reports and general feedback are welcome through the public issue tracker. Public pull requests are not currently solicited or supported; see CONTRIBUTING.md.