GIRAFI

Graph-informed random-forest imputation for single-cell proteomics

The GIRAFI method and research are credited to Huan Zhong and the GIRAFI research collaborators. Existing implementation credits include Ziming Wang and the GIRAFI contributors. Junseo Park maintains the Python package and its distribution.

GIRAFI estimates missing protein abundances using empirical protein associations and an optional curated protein interaction prior. Protein-specific random forests use graph-restricted predictors, and graph polishing updates only missing entries. Measured values are preserved.

The package provides Local and Neighbor variants, validation-based selection for dataset completion, and nested masking for reconstruction evaluation.

Installation

Python 3.11 or later is required. The initial distribution is a release candidate:

python -m pip install "girafi==0.1.0rc1"
girafi --help

Python example

Use a CSV matrix with cells in rows, proteins in columns, and cell IDs in the first column. Empty fields and NaN represent missing values; zero is an observed value. This example assumes linear intensities and explicitly disables the PPI prior:

import pandas as pd
from girafi import GIRAFIConfig, GIRAFIPipeline

X = pd.read_csv("expression.csv", index_col=0)
config = GIRAFIConfig.from_dict({
    "workflow": "biology",
    "input_scale": "linear",
    "graph": {"ppi_weight": 0.0},
})
result = GIRAFIPipeline(config).run(X)
result.save("runs/my-analysis")

For log2-transformed input, set input_scale to log2. To use a PPI prior, provide a table with source, target, and optional weight columns with matching protein identifiers, set graph.ppi_weight explicitly, and pass the table to run(X, ppi=ppi).

Workflows and command line

• biology selects a variant using validation masks and then completes the supplied matrix.
• nested selects variants within inner validation masks and evaluates reconstruction on held-out outer entries.

girafi run --config config.yaml --matrix expression.csv --out runs/my-analysis

Configurations accept YAML or JSON. Results include resolved settings, selection records, masks, input hashes, and software versions. The source distribution includes the Methods, Configuration, and Validation guides, synthetic examples, and tests. Repository documentation is available on the GIRAFI package branch, subject to repository access.

Reconstruction scores on artificially withheld observations do not establish accuracy at naturally missing entries. Nested entry masking evaluates reconstruction within the supplied cells, rather than prediction for unseen cells. Validation scores from biology are not independent test estimates.

Citation and license

Zhong, H., Chi, S., et al. Recovering biological structure in sparse single-cell proteomics with GIRAFI. bioRxiv (2026). doi:10.64898/2026.05.18.726081.

Please cite the manuscript and report the GIRAFI software version. Publication through a package maintainer's account does not change the method or manuscript authorship. Original implementation attribution is retained in the packaged girafi/provenance.json. The source distribution includes AUTHORS.md and CITATION.cff.

MIT License. Existing copyright and permission notices are retained in the distribution.