girafi 0.1.0rc1__tar.gz

girafi-0.1.0rc1/AUTHORS.md

@@ -0,0 +1,11 @@
+# Authors and attribution
+
+The **GIRAFI method and research** are credited to **Huan Zhong and the GIRAFI research collaborators**, as documented in the manuscript cited below.
+
+**Existing implementation attribution** includes **Ziming Wang and the GIRAFI contributors**. The original Python packaging metadata names Ziming Wang; the implementation source hashes and existing credits are retained in `src/girafi/provenance.json`.
+
+**Junseo Park** is the **Python package maintainer and distribution contact**. This role concerns package maintenance and release distribution; it does not identify Junseo Park as the originator of the GIRAFI method.
+
+The software is distributed under the **MIT License**. Existing copyright and permission notices are retained in `LICENSE`.
+
+Please cite **Zhong, H., Chi, S., et al. Recovering biological structure in sparse single-cell proteomics with GIRAFI. bioRxiv (2026). https://doi.org/10.64898/2026.05.18.726081** and record the software version used. The manuscript author list is retained in `CITATION.cff`.

girafi-0.1.0rc1/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.1.0rc1
+
+- Credit Huan Zhong and the GIRAFI research collaborators explicitly, retain existing implementation attribution, and identify Junseo Park as the package maintainer.
+- Add a self-contained PyPI description and include attribution in source and wheel distributions.
+- Unified Local and Neighbor learners with count-weighted empirical/PPI graphs.
+- Added dataset-level (`biology`) and nested entry-masking (`nested`) workflows.
+- Added validation-only variant selection, explicit configuration, Python API, CLI, and run artifacts.
+- Added synthetic reference fixtures, leakage checks, and installed-package verification.

girafi-0.1.0rc1/CITATION.cff

@@ -0,0 +1,37 @@
+cff-version: 1.2.0
+message: "Please cite the GIRAFI manuscript and identify the software version used."
+type: software
+title: "GIRAFI: Graph-informed random-forest imputation"
+version: 0.1.0rc1
+repository-code: "https://github.com/dorothyzh/GIRAFI/tree/package"
+license: MIT
+authors:
+  - family-names: Zhong
+    given-names: Huan
+  - family-names: Wang
+    given-names: Ziming
+  - name: GIRAFI contributors
+preferred-citation:
+  type: article
+  title: "Recovering biological structure in sparse single-cell proteomics with GIRAFI"
+  doi: "10.64898/2026.05.18.726081"
+  journal: bioRxiv
+  year: 2026
+  authors:
+    - {family-names: Zhong, given-names: Huan}
+    - {family-names: Chi, given-names: Shuxin}
+    - {family-names: Wong, given-names: Rachel}
+    - {family-names: Rogalski, given-names: Jason}
+    - {family-names: Wang, given-names: Ziming}
+    - {family-names: Chan, given-names: Susanna}
+    - {family-names: Bailey, given-names: Melanie L.}
+    - {family-names: Ebrahimi, given-names: Arpa}
+    - {family-names: Jayme, given-names: Gabrielle}
+    - {family-names: Yin, given-names: Jerry}
+    - {family-names: Gong, given-names: Albie}
+    - {family-names: Zhong, given-names: Peipei}
+    - {family-names: Snutch, given-names: Terrance P.}
+    - {family-names: Maier, given-names: Claudia S.}
+    - {family-names: Marra, given-names: Marco A.}
+    - {family-names: Foster, given-names: Leonard J.}
+    - {family-names: Tang, given-names: Xin}

girafi-0.1.0rc1/IMPORT_PROVENANCE.json

@@ -0,0 +1,78 @@
+{
+  "source_repository": "https://github.com/junseoparkX/girafi-package",
+  "source_commit": "e2f4055bd6b662f14c1a0658e29aed69bec0e989",
+  "destination": "https://github.com/dorothyzh/GIRAFI/tree/package",
+  "method_sources_unchanged": true,
+  "adaptations": [
+    "README paths and figure",
+    "repository and citation URLs",
+    "root workflows with package working directory",
+    "release instructions",
+    "synthetic fixture ignore exceptions",
+    "include overview figure in source distribution",
+    "installable source at package branch root; branch-specific documentation and workflows",
+    "workflow overview rendered from the original manuscript drawing with recorded crop and export settings"
+  ],
+  "source_file_sha256": {
+    ".gitattributes": "401203af7ba8102643f21ddcaefeb3ff49c3afbb891a8ee4325f8f4b18ebfa09",
+    ".github/workflows/ci.yml": "6c6f269efb9bff7ee23de691108440f4ef517b7619d24f7950eaf0afee98e14d",
+    ".github/workflows/release.yml": "7c5b00d6f4d5ee8ac63d37d7cf100cde5da95136597aba5b232687949cac1576",
+    ".gitignore": "100c0b804cc90b86c1225d6e4515f438759c13e7f63dff39062ac98aca70c15b",
+    "CHANGELOG.md": "d3f2b1fe12131c00a2b203ff256415b57745d703e4ff24e33501092a606fbd14",
+    "CITATION.cff": "023a545a238de6490cb442aef41004cc968f9b4569d094dcf755b7ae995e3e77",
+    "LICENSE": "c55118c93f5e2423040d3282533ac62d9e262d0317f9da4e844ed565b954c221",
+    "MANIFEST.in": "aebe7e74251087835de5aecc809b7068ae7787ffc8aebc1a735dbb22d62f46e7",
+    "README.md": "4f413e80c99dc5dbe1469dc2252313813e8a9c5d797dfec52f9db1f5a8c2a8e4",
+    "configs/biology.yaml": "a4578d844be8297af268b85a1b78c49720c8962512ba796264783b8a6165ba7b",
+    "configs/nested.yaml": "d4115dad828797b38763c58305211a35d290183e6c87eadce66a7df7ae756138",
+    "docs/CONFIGURATION.md": "156e790091a0d264dec211a49ddf1a24c98e0c83ed86c112fe9b1a147dff5de7",
+    "docs/METHODS.md": "a030474a40696a10784680cb7b9fad118b5cbf88234e32dca50308f5e85ca371",
+    "docs/RELEASE.md": "563c9e0a36d6f59205b4610a6180b831c21b71eb9c911d610cd52fbef31eb398",
+    "docs/VALIDATION.md": "edcd964085005cdf83f881cc3df0b12e06ba0ddae533e492109ab4293373500b",
+    "examples/expression.csv": "bd4c044ca14fe97010e3eb9af79fb3b6e55dccb1ae735667e3edb4b793358c2e",
+    "examples/generate.py": "f266917c9ce291efa7b8caa2b4b7e785cab64895c3b83907e360fb1ef5fdd8b9",
+    "examples/ppi.tsv": "8c4cfccd8c3afb2c1e9be5155c783a610c0ebccd5e2654cf39c1f07e4bf91942",
+    "pyproject.toml": "3ec33fd3f670e4898e085d6ab2b7c801f341ab0f76d7f36172b969b378c653e6",
+    "scripts/check_wheel.py": "778119bb4950f3c349217f4872aa095e608be30cb54ee10a361a820a71e2296c",
+    "scripts/generate_reference.py": "d80152bffe8d28835de37ce2ec2537c9bb1fc4d0305732e2461be7f976ec82df",
+    "src/girafi/__init__.py": "e8e3078c47a4fd230a8dad03191922711a5ccb4f196523e92234af9e317e557f",
+    "src/girafi/__main__.py": "935a1c1166b0c1ea35a82256345000bf2c73ded718d77773bc27a71ecce28f7d",
+    "src/girafi/cli.py": "30742f1b6a73a05938fa6450bf14ee4019e03e787c3e668357281b6850e73606",
+    "src/girafi/config.py": "f3d27c7fa74ea339d28fec1e6753fe0d646516c5d2464dc26424b4407d037d93",
+    "src/girafi/core.py": "c43d878c1cb4790263497485e9ccbe28c96eb5b3ed8ac3461801b3feaf00fe5e",
+    "src/girafi/data.py": "55289bdadd41ae95846bb172a7860cad8bd25a577c6b696647263a479c89280d",
+    "src/girafi/pipeline.py": "100eda29d6bff70781901550b2b71441b55023292720cd0f0c0bd8956d92a77e",
+    "src/girafi/provenance.json": "5e51ccd62e764614aafeb51d04da69f1773cbf4b5a3cea2976824df9997add6f",
+    "src/girafi/result.py": "a57d006b899c7c54d57085066842c7dbd5965cc7045eeaada444564ebcaaa586",
+    "src/girafi/validation.py": "00caa00dff516a2e71677076d1267a0492e37d1fb36be2bdc0788d62f25d3ffc",
+    "tests/conftest.py": "b7e789c773a41a66f9f58080d2e496fdf32196b4c7af6c92a26c506a6870e4a3",
+    "tests/data/ppi_reference.json": "4a8f629c71ee873c2700f0f1a2b53091e81af9dc3409c3febe54752ffc855fbe",
+    "tests/data/ppi_reference.npz": "338c1e031b578b6d1571db0a3fe44804469c392ca435382fd20b82e5222da508",
+    "tests/reference/README.md": "103100d7e8af981fc47f2cd05621d59f45db1e339395c7bfd46522b3cf415917",
+    "tests/reference/ppi_engine.py": "318f84fe7047d959ba8ee5fab3dba831a0a81f025be8a2266ea9ff3ffb745a81",
+    "tests/test_cli.py": "f1614ca52583a0e7bb24119770b4d2d0a6b7ed08b870a0721c887979d9cd85a2",
+    "tests/test_contracts.py": "d4af3d47d1a340af6f2db33ca79a87245049b5aa5df0cf1244324703e7809595",
+    "tests/test_reference.py": "4014265fad1e0394f85cb9ce9e745fc3e0cbe6b7827e67d7b10d375fc78dce50",
+    "tests/test_workflows.py": "25c2318ccbd34c486a5e7d38e522fb6aaaf563f828a2c6457786c8b10fb0f50a"
+  },
+  "initial_import_destination": "https://github.com/dorothyzh/GIRAFI/tree/master/package",
+  "branch_split_parent": "3a124a668e6822a04cb7518382b77780baa3a156",
+  "overview_figure": {
+    "path": "docs/assets/girafi-overview.png",
+    "source_name": "figure.pdf",
+    "source_sha256": "640daad2dd77967b885ad4656376e15ecacbc6662df84abf6bc4dc46d5003faf",
+    "crop_box_points": [
+      0.0,
+      303.765,
+      482.111,
+      623.986
+    ],
+    "png_dimensions": [
+      4018,
+      2669
+    ],
+    "png_dpi": 600,
+    "png_sha256": "ad86636d79a7b6f6b83e780adef1f3a1e6910d22fa66c67b7ac5323c22ba88ef",
+    "content_changes": "None; crop and raster export only"
+  }
+}

girafi-0.1.0rc1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 GIRAFI contributors
+Copyright (c) 2026 GIRAFI package contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

girafi-0.1.0rc1/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md README.pypi.md AUTHORS.md LICENSE CITATION.cff CHANGELOG.md
+include IMPORT_PROVENANCE.json
+recursive-include configs *.yaml
+recursive-include docs *.md *.png
+recursive-include examples *.py *.csv *.tsv
+recursive-include scripts *.py
+recursive-include tests *.py *.md *.json *.npz

girafi-0.1.0rc1/PKG-INFO

@@ -0,0 +1,93 @@
+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.

girafi-0.1.0rc1/README.md

@@ -0,0 +1,98 @@
+# GIRAFI
+
+[![Python 3.11 | 3.12 | 3.13](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-007EC6)](docs/VALIDATION.md)
+[![CI](https://github.com/dorothyzh/GIRAFI/actions/workflows/package-ci.yml/badge.svg?branch=package&event=push)](https://github.com/dorothyzh/GIRAFI/actions/workflows/package-ci.yml?query=branch%3Apackage)
+
+**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. See [Authors and attribution](AUTHORS.md) and cite the manuscript below.
+
+GIRAFI estimates missing protein abundances by combining empirical protein associations with a curated protein interaction prior. Protein-specific random forests learn from observed intensities using graph-restricted predictors; a graph-polishing step updates only missing entries. Measured values are preserved.
+
+![GIRAFI overview: protein association and interaction graphs inform imputation and downstream analyses.](docs/assets/girafi-overview.png)
+
+*GIRAFI overview. Empirical protein associations and a protein interaction prior inform imputation for downstream analyses.*
+
+This package provides the **Local** and **Neighbor** variants through a common implementation, with validation-based selection for dataset completion and nested masking for reconstruction evaluation.
+
+This is the **package** branch. Manuscript experiments, benchmarks, and figure reproduction are maintained on the [reproducibility branch](https://github.com/dorothyzh/GIRAFI/tree/reproducibility).
+
+## Method
+
+The empirical graph uses positive Spearman correlations, weighted by shared observation counts and restricted to the strongest neighbors. Row normalization gives $W^{(\mathrm{corr})}$. Following the manuscript notation, a weighted PPI adjacency $A^{(\mathrm{ppi})}$ is symmetrically degree-normalized as $W^{(\mathrm{ppi})} = D^{-1/2} A^{(\mathrm{ppi})} D^{-1/2}$, where $D$ is its diagonal degree matrix. The graphs are fused using the PPI weight $\lambda$:
+
+$$
+W = \lambda W^{(\mathrm{ppi})} + (1-\lambda) W^{(\mathrm{corr})}.
+$$
+
+The fused graph is then row-normalized, with self-loops excluded.
+
+- **Local** predicts a target from the weighted mean and standard deviation of its observed neighbors.
+- **Neighbor** predicts a target directly from neighboring protein abundances.
+
+The PPI weight and other model parameters are explicit settings. Automatic selection compares Local and Neighbor using masked-entry reconstruction error; downstream biological outcomes are not selection inputs. See [Methods](docs/METHODS.md) for the exact graph, support, and scoring definitions.
+
+## Installation
+
+Python 3.11 or later is required. [Compatibility checks](docs/VALIDATION.md) passed on Python 3.11, 3.12, and 3.13; the CI matrix includes these versions on Linux, Windows, and macOS. Install the `package` branch from this repository:
+
+```bash
+git clone --branch package --single-branch https://github.com/dorothyzh/GIRAFI.git
+cd GIRAFI
+python -m pip install .
+```
+
+## Usage
+
+Expression data have **cells in rows and proteins in columns**, with cell IDs in the first CSV column and missing values represented by empty fields or `NaN`. PPI tables contain `source`, `target`, and an optional `weight` column using the same protein identifiers. Zero is treated as an observed value.
+
+Run the examples below from the cloned repository root. The supplied configurations expect linear intensities (`input_scale: linear`); for data already on the log2 scale, set `input_scale: log2`. See [input and transformation](docs/METHODS.md#input-and-transformation) for preprocessing details.
+
+```python
+import pandas as pd
+from girafi import GIRAFIConfig, GIRAFIPipeline
+
+X = pd.read_csv("examples/expression.csv", index_col=0)
+ppi = pd.read_csv("examples/ppi.tsv", sep="\t")
+config = GIRAFIConfig.from_yaml("configs/biology.yaml")
+
+result = GIRAFIPipeline(config).run(X, ppi=ppi)
+result.save("runs/python-example")
+```
+
+The supplied example is synthetic. Both workflows are also available from the command line:
+
+```bash
+girafi run --config configs/biology.yaml --matrix examples/expression.csv --ppi examples/ppi.tsv --out runs/biology
+girafi run --config configs/nested.yaml --matrix examples/expression.csv --ppi examples/ppi.tsv --out runs/nested
+```
+
+## Selection workflows
+
+| Workflow | Variant selection | Output |
+| :--- | :--- | :--- |
+| **`biology`** | Select once using mean NRMSE across repeated validation masks, then refit on the full input. | One completed matrix and its selection record. |
+| **`nested`** | Select by inner validation within each outer masking repeat, then refit and evaluate on held-out outer entries. | Outer reconstruction scores and a selection record for each repeat. |
+
+Set `variant` to `auto`, `local`, or `neighbor`. The example configurations use 100 trees; the API default is 500. Masking fractions, repeats, scoring support, tie rules, and PPI weight are configurable. To run without a PPI prior, explicitly set `graph.ppi_weight: 0`. See [Configuration](docs/CONFIGURATION.md).
+
+Each run saves its resolved configuration, masks, candidate scores, graph and input hashes, and software versions. The `biology` workflow also writes `imputed.csv.gz`; the `nested` workflow writes `outer_scores.csv`. Existing output directories are preserved.
+
+Reconstruction scores describe artificially withheld observed entries. They do not establish accuracy at naturally missing values. Nested entry masking evaluates reconstruction within the supplied cells; it is distinct from predicting previously unseen cells. Selection scores from `biology` are validation scores, not independent test estimates.
+
+## Citation
+
+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).
+
+Software citation metadata are provided in [CITATION.cff](CITATION.cff). Implementation provenance and historical compatibility are documented in [Methods](docs/METHODS.md#implementation-provenance). The PyPI project description is maintained in [README.pypi.md](README.pypi.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m build
+python -m twine check dist/*
+```
+
+MIT License. Original GIRAFI method and implementation credits are retained in the source provenance.

girafi-0.1.0rc1/README.pypi.md

@@ -0,0 +1,59 @@
+# 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.

girafi-0.1.0rc1/configs/biology.yaml

@@ -0,0 +1,17 @@
+workflow: biology
+variant: auto
+input_scale: linear
+random_state: 123
+model:
+  trees: 100
+graph:
+  ppi_weight: 0.1
+selection:
+  strategy: repeated_holdout
+  mask_scope: complete_region
+  n_repeats: 5
+  mask_fraction: 0.1
+  tie_breaker: mean_rmse_then_local
+  nrmse_tie_atol: 1.0e-12
+  min_region_rows: 10
+  min_region_cols: 5

girafi-0.1.0rc1/configs/nested.yaml

@@ -0,0 +1,19 @@
+workflow: nested
+variant: auto
+input_scale: linear
+random_state: 29101
+model:
+  trees: 100
+graph:
+  ppi_weight: 0.1
+selection:
+  strategy: holdout
+  mask_scope: observed_entries
+  n_repeats: 1
+  mask_fraction: 0.1
+  tie_breaker: local_first
+  nrmse_tie_atol: 0.0
+evaluation:
+  mask_scope: observed_entries
+  mask_fraction: 0.1
+  n_repeats: 5

girafi-0.1.0rc1/docs/CONFIGURATION.md

@@ -0,0 +1,53 @@
+# Configuration
+
+Load YAML with `GIRAFIConfig.from_yaml`, JSON with `GIRAFIConfig.from_json`, or a mapping with `GIRAFIConfig.from_dict`. Unknown keys and invalid values are errors. The same configuration drives the Python and command-line interfaces.
+
+| Setting | Meaning | Default |
+| --- | --- | --- |
+| `workflow` | Dataset completion or nested entry evaluation | `biology` |
+| `variant` | `auto`, `local`, or `neighbor` | `auto` |
+| `input_scale` | `linear` or already `log2` | `linear` |
+| `output_scale` | `input` or standardized `model` | `input` |
+| `random_state` | Base seed | `123` |
+| `model.trees` | Trees per fitted target forest | `500` |
+| `model.neighbors` | Maximum graph neighbors per target | `24` |
+| `model.min_leaf` | Minimum samples per leaf | `5` |
+| `model.local_min_obs` | Minimum eligible Local training cells | `8` |
+| `model.neighbor_min_obs` | Minimum eligible Neighbor training cells | `12` |
+| `graph.ppi_weight` | Fixed fusion weight; zero disables the prior | `0.1` |
+| `graph.corr_topk` | Empirical neighbors retained per protein | `50` |
+| `graph.overlap_exponent` | Shared-observation shrinkage exponent | `0.5` |
+| `graph.polish_weight` | Missing-entry polishing weight | `0.2` |
+| `execution.n_jobs` | Forest workers; `-1` uses available cores | `1` |
+
+## Workflow presets
+
+When no selection settings are supplied, workflow-dependent defaults are:
+
+| Selection setting | `biology` | `nested` |
+| --- | --- | --- |
+| `strategy` | `repeated_holdout` | `holdout` |
+| `mask_scope` | `complete_region` | `observed_entries` |
+| `mask_fraction` | `0.1` | `0.1` |
+| `n_repeats` | `5` | `1` |
+| `tie_breaker` | `mean_rmse_then_local` | `local_first` |
+| `nrmse_tie_atol` | `1e-12` | `0` |
+
+`holdout` requires one repeat. To average several inner validation masks in a nested run, set `selection.strategy: repeated_holdout` and `selection.n_repeats` explicitly. A complete region must contain at least `selection.min_region_rows` rows and `selection.min_region_cols` columns (defaults: 10 and 5). The region defines scoring support; the full permitted matrix remains the learner input.
+
+Nested evaluation has separate `evaluation.mask_scope`, `evaluation.mask_fraction`, and `evaluation.n_repeats`, defaulting to `observed_entries`, `0.1`, and `5`. Outer scoring never participates in selection. Seeds are base seed plus outer repeat index; validation mask seeds add 100000 plus the inner repeat index, and forest seeds add 10000 for validation or 20000 for refitting. Mask sampling uses a further offset of 1000. Each resolved seed and mask hash is saved.
+
+For no-PPI imputation:
+
+```yaml
+workflow: biology
+variant: auto
+graph:
+  ppi_weight: 0
+selection:
+  mask_scope: observed_entries
+```
+
+`artifacts.save_masks` defaults to true. `artifacts.save_predictions` defaults to true for biology and false for nested. A biology run always saves its final completed matrix. Nested prediction matrices are optional and correspond to the outer-visible input, not a final imputation of all original observations. Each run includes an environment report and audit manifest.
+
+The CLI can override `variant` and `ppi_weight`, with the resolved values saved. A supplied `--workflow` must agree with the configuration file. With no configuration file, `--workflow` selects the corresponding defaults. Use `girafi run --help` for input and output options.

girafi-0.1.0rc1/docs/METHODS.md

@@ -0,0 +1,49 @@
+# Methods
+
+## Input and transformation
+
+GIRAFI operates on a cell-by-protein matrix with explicit missingness. Protein membership and any upstream quality control are supplied by the caller. Each protein must retain at least one observed value. Zero is an observed value, not a missing-value marker.
+
+For nonnegative linear intensities, the pseudocount is half the smallest positive value in the permitted training view, bounded below by `1e-12`. Values are transformed by `log2(x + pseudocount)` and standardized per protein using the population standard deviation (`ddof=0`). A zero training standard deviation is replaced by one. For `input_scale: log2`, the logarithm is omitted. All fitted quantities are recomputed for each validation or refit view.
+
+Output is returned to the input scale by default, and originally observed entries are copied exactly from the input. Missing-entry predictions are inverse transformed without clipping. Consequently, a linear-scale model prediction is not constrained to be nonnegative. `output_scale: model` instead returns the standardized model scale, with the associated transformation recorded in the manifest.
+
+## Protein graphs
+
+Positive pairwise-complete Spearman correlations require at least three shared observations. A correlation is multiplied by `(n_ij / n_cells)^overlap_exponent`, where `n_ij` is the **integer number** of shared observations. Each row retains up to `corr_topk` positive neighbors, followed by row normalization.
+
+PPI edges are aligned by protein ID, made undirected, and combined by maximum weight when duplicate edges occur. Self-edges are excluded. A square PPI DataFrame must already be symmetric, nonnegative, finite, and loop-free. Missing protein IDs have zero prior weight. A positive requested PPI weight requires at least one aligned positive edge.
+
+The aligned prior is symmetrically degree-normalized, fused with the empirical graph, and row-normalized. `ppi_weight=0` makes the model independent of the supplied prior. Neighbor ranking follows descending `numpy.argsort` order on the given protein order. Input order and numerical environment are therefore recorded.
+
+## Local and Neighbor
+
+Both variants use at most `model.neighbors` graph neighbors per target.
+
+**Local** builds weighted neighbor mean and standard-deviation predictors from currently observed neighbors. Training cells require an observed target and finite predictors. Missing prediction features use medians from those eligible training cells. The forest uses two candidate features at each split.
+
+**Neighbor** uses neighboring abundance columns with observed-column median completion. A training cell requires an observed target and at least `max(2, floor(0.3 * n_neighbors))` observed neighbors. The forest uses `max_features="sqrt"`.
+
+The minimum training support is eight cells for Local and twelve for Neighbor by default. A target with insufficient neighbors or training support receives its observed training median, with the reason counted in the run audit. Unexpected fitting errors propagate. Forest seeds are the fit seed plus the target column index, reduced modulo `2**32 - 1`.
+
+After target-wise fitting, the source cleanup stage receives an already finite matrix and is an identity operation: it fits no additional forests. Polishing updates only missing positions using `(1-gamma) * X_imp + gamma * (X_imp @ W)`. The right-multiplication direction is retained explicitly.
+
+## Masking and selection
+
+Scoring support can be all observed entries or an NA-free region found by deterministic greedy row/column elimination. The latter is a found region, not a guaranteed largest submatrix. In either case the learner receives the full permitted matrix.
+
+Masks are sampled without replacement by position, independent of intensity values. The requested count is `floor(mask_fraction * eligible_entries)`, with at least two entries required. The sampler retains at least one training observation per protein; infeasible requests fail. This support guard can make masks differ from historical runners without the guard. Both variants use identical masks and fitted transformations within each validation repeat.
+
+NRMSE is RMSE divided by the population standard deviation of masked reference values on the training-standardized scale. Zero reference variance and nonfinite scored values are errors. Candidate scores are averaged equally over validation repeats. `mean_rmse_then_local` uses mean RMSE among candidates within the declared NRMSE tolerance, then Local for remaining exact ties. `local_first` uses Local among candidates within that tolerance. The PPI weight and other parameters are fixed; automatic selection only chooses the variant.
+
+The **biology** workflow selects once, then refits on the complete permitted input without artificial masking. The **nested** workflow selects independently within each outer repeat and scores outer values only after refitting. The selector accepts only the outer-visible matrix, not outer truth or biological endpoints. A fixed variant skips selection. Any downstream cell-level cross-validation must independently fit its complete analysis pipeline within training folds; this package does not implement retained-model prediction for new cells.
+
+## Implementation provenance
+
+Method ID: `girafi-count-overlap-v1`.
+
+The learner and graph arithmetic were extracted from the audited Python engine used for the fixed-PPI experiments. Its SHA-256 and attribution are included in `girafi/provenance.json`. The original GIRAFI Python/R implementations and paper analyses are separate provenance sources.
+
+In particular, one archived public Python graph implementation used boolean matrix multiplication before converting to float. This release uses integer shared-observation counts. Original paper scores, that public implementation, and this maintained implementation must not be assumed numerically identical. The package also adds explicit input contracts, repeat aggregation, ID alignment, output inversion, and support-preserving masking.
+
+Reference fixtures test the extracted computation against the source engine on synthetic inputs with fixed masks. The fixture metadata specify the software versions used. Bitwise reproducibility across untested library versions or platforms is not asserted.

girafi-0.1.0rc1/docs/RELEASE.md

@@ -0,0 +1,20 @@
+# Release procedure
+
+The initial distribution is `girafi==0.1.0rc1`. The repository is `dorothyzh/GIRAFI`, with the installable source at the root of the `package` branch. The Python import and command are both `girafi`. Check out the `package` branch and run local build and verification commands from the repository root.
+
+## Authorship and account roles
+
+Retain Huan Zhong and the GIRAFI research collaborators as the method/research credits, Ziming Wang and the GIRAFI contributors as the existing implementation credits, and Junseo Park as the Python package maintainer. The upload account and PyPI project roles control distribution access; they do not replace the author metadata or manuscript citation. Keep `AUTHORS.md`, `CITATION.cff`, `README.pypi.md`, and the packaged provenance consistent. Preserve `LICENSE` verbatim.
+
+## Build and publish
+
+1. Run the test suite and build the wheel/source distribution. Check metadata with `python -m twine check dist/*`, then verify the wheel with `python scripts/check_wheel.py --wheel dist/<wheel filename>`.
+2. Confirm the version in `pyproject.toml`, `src/girafi/__init__.py`, `CITATION.cff`, and `CHANGELOG.md`. Verify that the examples, method ID, and source provenance match the release.
+3. After the `package` branch has been pushed, inspect the GitHub test matrix. Select `package` when manually running the release workflow. The **Package Release** workflow defaults to `build`, which uploads distribution artifacts without publishing a package.
+4. An authenticated PyPI/TestPyPI account must configure the publisher. For a new project, use a pending Trusted Publisher with project name `girafi`, GitHub owner `dorothyzh`, repository `GIRAFI`, workflow filename `package-release.yml`, and environment `testpypi` (TestPyPI) or `pypi` (PyPI). The PyPI account may belong to the distribution maintainer. Use the official GIRAFI repository for the workflow. Existing projects require an account with the necessary project management role.
+5. Choose `testpypi` in the manual Package Release workflow and inspect an installation of that release. After checking the release candidate, choose `pypi` explicitly. No stored PyPI API token is needed. The `pypi`/`testpypi` GitHub environment names must match the registered publishers; do not weaken existing environment protections.
+6. Record the release tag, commit, distribution hashes, and environment. Package versions and uploaded filenames cannot be reused; increment the version for subsequent releases.
+
+The publishing jobs consume the distributions produced and checked by the build job. Ordinary pushes and pull requests run tests only. Account-side publishers and environments are configured by the repository/package owner; they are not created by these source files.
+
+Only after a successful upload and public readback should the reviewer response say that GIRAFI is available on PyPI. Record the exact version and project URL; retain a preparation-only statement while account setup or publication is pending.