PASE

PASE estimates molecular associations within individual patients and summarizes them across a single-cell cohort.

Read the online documentation for installation, the API and the statistical meaning of each parameter.

Installation

Use Python 3.10 or later in a fresh environment. Install the published release from PyPI:

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install pase-framework==1.1.1

macOS or Linux:

python3 -m venv .venv
.venv/bin/python -m pip install pase-framework==1.1.1

These commands use the new environment directly; activation is not required. Version 1.1.1 updates the documentation and packaging only. Statistical code and bundled data are unchanged from 1.1.0, which was used for the manuscript.

The distribution is named pase-framework, but the Python import is pase. The unrelated audio package named pase on PyPI uses the same import name; do not install both in one environment. The v1.1.1 release is also available on GitHub. For development, clone this repository and use python -m pip install -e ".[test]".

Quick example

Save this as quickstart.py:

import pase
adata = pase.datasets.load_gse234933_demo()
res = pase.associate(
    adata, anchor="LILRB4", target=["MMP14", "MMP9", "SPP1", "APOE"],
    patient_key="donor", covariates=["log_depth"], cell_mask="myeloid",
    aggregate="equal", min_cells=30,
)
print(res.summary().to_string(index=False))
print(res.patients[["patient_id", "n_cells", "r", "eligible", "reason"]])
ax = res.plot_forest()
ax.figure.savefig("association.pdf", bbox_inches="tight")

Run it with .\.venv\Scripts\python.exe quickstart.py on Windows or .venv/bin/python quickstart.py on macOS/Linux. It prints the cohort summary and patient table and saves a forest plot as association.pdf.

The bundled GSE234933 subset contains real cells and works without a download. The four-gene target above illustrates the interface; it is not the current manuscript's 15-gene signature. The tutorial notebook uses the 15-gene list on this small teaching subset. For the complete cohort analyses, use the RNA workflow. See the quick-start guide for notebook installation and execution.

Input format

Supply an AnnData object with cells in rows and unique gene names in adata.var_names. adata.X, or the requested layer, must already contain transformed expression. For count data, the tutorial uses log1p(10000 * count / total_counts) with totals calculated before selecting genes. associate does not normalize raw counts.

Covariates enter a separate least-squares model for each patient, with an intercept. Encode categorical covariates as numeric dummy variables; integer labels such as 0, 1 and 2 are otherwise treated as a numeric covariate. Patients absent from the object can be retained using patient_ids. See the input guide for missing values and eligibility rules.

Outputs and choice of summary

res.patients reports every patient, cell counts, observed correlation, eligibility, exclusion reasons and, where applicable, weights or shrunken effects. res.summary() returns one row with the selected method, target, estimate, interval, P value and status. res.metadata records the analysis settings and warnings. res.plot_forest() returns a Matplotlib Axes.

REML means restricted maximum likelihood; HKSJ is the Hartung–Knapp–Sidik–Jonkman interval adjustment; EB means empirical Bayes. See the output guide for field definitions and warning codes.

min_cells=30 is adjustable. Version 1.1.0 changes the default min_patients from 2 to 6. Below the selected method's eligible-patient threshold, PASE returns observed patient correlations, descriptive summaries and exclusion reasons, but withholds inferential estimates, intervals and P values. An explicit lower threshold is allowed and recorded as an override.

Reported inference receives a small-cohort warning below 20 eligible patients and a precision warning when the full correlation-scale interval is wider than max_ci_width=0.2. Warnings retain the interval. The patient boundaries are result-informed reporting choices, and 0.2 is a configurable practical tolerance; none guarantees calibrated coverage. See the reporting policy and its evidence.

For the equal-patient mean, an externally specified planning_sd enables a model-based minimum detectable effect (MDE). Record its origin with planning_sd_source; set minimum_relevant_effect to compare the MDE with a scientifically meaningful effect. This is a planning calculation, not achieved power, and is not provided for Fisher or EB targets.

Reproduce the manuscript

The reproduction repository contains figure commands and the full 15-gene RNA workflow. The software tutorial above is a smaller example, not a reproduction of all paper results.

• Simulation protocol, version 2.0.0: the design archived before the formal simulations.
• Core results and reproducibility materials: the subsequent code and results archive, including PASE 1.1.0.
• Supplementary Data S1 and S2 accompany the revised manuscript. They contain the detection-matched gene analysis and unequal-yield native count benchmark, respectively, and are not included in the core-results DOI above.

See reproduction instructions for the scope of each workflow and the software test commands.

Citation

For this code, cite the authors, PASE software version 1.1.1, and its release URL. Machine-readable author information is in CITATION.cff. An earlier analysis archive is available at Zenodo v3; that DOI does not identify this 1.1.1 software release.

Code is distributed under the MIT License. The real-data example retains its source attribution and third-party terms; see THIRD_PARTY_DATA.md. Report software problems through GitHub Issues.