Metadata-Version: 2.4
Name: girafi
Version: 0.1.0rc1
Summary: Graph-informed random-forest imputation for single-cell proteomics
Author: Huan Zhong, Ziming Wang, GIRAFI contributors
Maintainer: Junseo Park
License-Expression: MIT
Project-URL: Repository, https://github.com/dorothyzh/GIRAFI/tree/package
Project-URL: Documentation, https://github.com/dorothyzh/GIRAFI/blob/package/README.md
Project-URL: Issues, https://github.com/dorothyzh/GIRAFI/issues
Project-URL: Manuscript, https://doi.org/10.64898/2026.05.18.726081
Keywords: proteomics,imputation,random-forest,protein-interactions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas<4,>=2.2
Requires-Dist: scipy<2,>=1.12
Requires-Dist: scikit-learn<2,>=1.8
Requires-Dist: PyYAML<7,>=6
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Dynamic: license-file

# 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:

```bash
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:

```python
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.

```bash
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](https://github.com/dorothyzh/GIRAFI/tree/package), 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](https://doi.org/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.
