pertrank 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pertrank-0.2.0/CHANGELOG.md +10 -0
- pertrank-0.2.0/INTEGRATION.md +11 -0
- pertrank-0.2.0/LICENSE +14 -0
- pertrank-0.2.0/MANIFEST.in +10 -0
- pertrank-0.2.0/PKG-INFO +177 -0
- pertrank-0.2.0/PYPI_DESCRIPTION.md +145 -0
- pertrank-0.2.0/README.md +145 -0
- pertrank-0.2.0/READ_FIRST.zh.md +62 -0
- pertrank-0.2.0/docs/api.md +165 -0
- pertrank-0.2.0/docs/community_integration.md +59 -0
- pertrank-0.2.0/docs/input_contracts.md +55 -0
- pertrank-0.2.0/docs/release_process.md +40 -0
- pertrank-0.2.0/docs/reproducibility.md +58 -0
- pertrank-0.2.0/docs/scientific_design.md +48 -0
- pertrank-0.2.0/docs/validation.md +20 -0
- pertrank-0.2.0/provenance/CURRENT_RELEASE.json +73 -0
- pertrank-0.2.0/pyproject.toml +42 -0
- pertrank-0.2.0/requirements-tested.txt +9 -0
- pertrank-0.2.0/scripts/README.md +11 -0
- pertrank-0.2.0/scripts/build_pypi_description.py +19 -0
- pertrank-0.2.0/scripts/check_distribution.py +91 -0
- pertrank-0.2.0/scripts/check_installation.py +55 -0
- pertrank-0.2.0/scripts/check_tutorials.py +70 -0
- pertrank-0.2.0/scripts/curate_replogle.py +97 -0
- pertrank-0.2.0/scripts/curate_tcell.py +79 -0
- pertrank-0.2.0/setup.cfg +4 -0
- pertrank-0.2.0/src/pertrank/__init__.py +11 -0
- pertrank-0.2.0/src/pertrank/_version.py +3 -0
- pertrank-0.2.0/src/pertrank/api.py +457 -0
- pertrank-0.2.0/src/pertrank/core.py +255 -0
- pertrank-0.2.0/src/pertrank/data/replogle_k562.npz +0 -0
- pertrank-0.2.0/src/pertrank/data/replogle_k562.provenance.json +63 -0
- pertrank-0.2.0/src/pertrank/data/tcell_d3_rest.npz +0 -0
- pertrank-0.2.0/src/pertrank/data/tcell_d3_rest.provenance.json +64 -0
- pertrank-0.2.0/src/pertrank/datasets.py +52 -0
- pertrank-0.2.0/src/pertrank/evaluation.py +107 -0
- pertrank-0.2.0/src/pertrank/py.typed +0 -0
- pertrank-0.2.0/src/pertrank.egg-info/PKG-INFO +177 -0
- pertrank-0.2.0/src/pertrank.egg-info/SOURCES.txt +61 -0
- pertrank-0.2.0/src/pertrank.egg-info/dependency_links.txt +1 -0
- pertrank-0.2.0/src/pertrank.egg-info/requires.txt +12 -0
- pertrank-0.2.0/src/pertrank.egg-info/top_level.txt +1 -0
- pertrank-0.2.0/tests/REFERENCE_PROVENANCE.json +5 -0
- pertrank-0.2.0/tests/conftest.py +41 -0
- pertrank-0.2.0/tests/reference_core.py +225 -0
- pertrank-0.2.0/tests/test_anndata_api.py +283 -0
- pertrank-0.2.0/tests/test_core_contract.py +124 -0
- pertrank-0.2.0/tests/test_evaluation.py +122 -0
- pertrank-0.2.0/tests/test_packaged_data.py +30 -0
- pertrank-0.2.0/tests/test_release_checkers.py +72 -0
- pertrank-0.2.0/tutorials/00_anndata_quickstart.py +17 -0
- pertrank-0.2.0/tutorials/01_replogle.ipynb +500 -0
- pertrank-0.2.0/tutorials/02_tcell.ipynb +637 -0
- pertrank-0.2.0/validation/ENVIRONMENT.json +14 -0
- pertrank-0.2.0/validation/INSTALLATION.json +20 -0
- pertrank-0.2.0/validation/LINK_VALIDATION.json +60 -0
- pertrank-0.2.0/validation/PYPI_SNAPSHOT.json +8 -0
- pertrank-0.2.0/validation/RELEASE_VALIDATION.json +51 -0
- pertrank-0.2.0/validation/TUTORIALS.json +32 -0
- pertrank-0.2.0/validation/pip_check.log +1 -0
- pertrank-0.2.0/validation/source_py312.log +3 -0
- pertrank-0.2.0/validation/wheel_py312.log +3 -0
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
# 0.2.0 formal release
|
|
2
|
+
|
|
3
|
+
- Preserve the numerical API, fixed parameters, authentic tutorial arrays and regression oracle from the audited source baseline.
|
|
4
|
+
- Update the project description and navigation for the completed rvalues comparison and predefined transcriptional-program nomination studies.
|
|
5
|
+
- Add `docs/reproducibility.md` with independent package, experiment-bundle and native-refitting scopes.
|
|
6
|
+
- Retain version-pinned scientific design, API and tutorial links; use the repository release listing to locate complete reproduction bundles.
|
|
7
|
+
- Keep experiment data and PertRank-Q outside the installable wheel.
|
|
8
|
+
- Record validation for the newly built artifacts and preserve the inherited software-license status pending the rights holder's decision.
|
|
9
|
+
|
|
10
|
+
The package version identifies this software delivery. It does not rename an existing repository release or assign a new DOI.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Software integration
|
|
2
|
+
|
|
3
|
+
This tree supplies the PertRank Python package formal release `0.2.0`. Package releases and full reproduction bundles have separate version histories. Repository bundles are listed at [GitHub Releases](https://github.com/anonymous-rl-lab/PertRank/releases); the current source distribution includes the package-specific documentation and validation record.
|
|
4
|
+
|
|
5
|
+
The numerical API, five control directions, attenuation 0.9 and authentic tutorial arrays are retained. Source reliability statistics remain distinct from the effects used for ranking. `tests/reference_core.py` is a frozen regression oracle, with its content hash recorded in `tests/REFERENCE_PROVENANCE.json`.
|
|
6
|
+
|
|
7
|
+
The full bundle adds experiment-specific evaluation, uncertainty summaries and reference data. Its compact `modules/new_results/` entry covers rvalues scoring, D3 program diagnostics, frozen sci-Plex3 evaluation and the completed exploratory direction adjustments. See [reproduction guide](docs/reproducibility.md) for execution and scope. These scientific materials are not embedded into the wheel.
|
|
8
|
+
|
|
9
|
+
PertRank-Q remains a separate optional checkpoint-replay module in the full bundle. The core package does not import it. Wheel and source distributions should be built from a copy outside a checksum-protected experiment bundle.
|
|
10
|
+
|
|
11
|
+
The inherited software-license status remains pending. A rights-holder decision and matching release metadata are required before public upload; see [release process](docs/release_process.md).
|
pertrank-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
Private review distribution
|
|
2
|
+
|
|
3
|
+
This anonymous release is supplied for installation, examination and
|
|
4
|
+
reproduction of the accompanying method during private review. Copyright
|
|
5
|
+
and other rights remain with their respective owners. No new public
|
|
6
|
+
open-source license is granted by this packaging step.
|
|
7
|
+
|
|
8
|
+
Before a public PyPI release or scverse submission, the authors must select
|
|
9
|
+
and apply an OSI-approved license to their software. Third-party datasets
|
|
10
|
+
retain their original terms and attribution; the tutorial provenance files
|
|
11
|
+
identify the sources. Public dataset redistribution must respect those terms.
|
|
12
|
+
|
|
13
|
+
This notice describes the current distribution status and does not replace
|
|
14
|
+
any existing license or rights attached to a third-party component.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
include README.md PYPI_DESCRIPTION.md READ_FIRST.zh.md LICENSE CHANGELOG.md INTEGRATION.md requirements-tested.txt
|
|
2
|
+
recursive-include docs *.md
|
|
3
|
+
recursive-include tutorials *.ipynb *.py *.md
|
|
4
|
+
recursive-include tests *.py *.json
|
|
5
|
+
recursive-include scripts *.py *.md
|
|
6
|
+
recursive-include src/pertrank/data *.npz *.json *.csv *.md
|
|
7
|
+
exclude tutorials/outputs/*
|
|
8
|
+
recursive-include validation *.json *.txt *.log
|
|
9
|
+
recursive-include provenance *.json *.txt
|
|
10
|
+
global-exclude __pycache__ *.py[cod]
|
pertrank-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: pertrank
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Reusable control-geometry reliability for gene-specific perturbation prioritization
|
|
5
|
+
License: Private review distribution; public license pending author selection
|
|
6
|
+
Project-URL: Repository, https://github.com/anonymous-rl-lab/PertRank/tree/v0.1.2
|
|
7
|
+
Project-URL: Documentation, https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/README.md
|
|
8
|
+
Project-URL: Scientific Design, https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/scientific_design.md
|
|
9
|
+
Project-URL: API Reference, https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/api.md
|
|
10
|
+
Project-URL: Replogle Tutorial, https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/01_replogle.ipynb
|
|
11
|
+
Project-URL: T-cell Tutorial, https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/02_tcell.ipynb
|
|
12
|
+
Project-URL: Code Releases, https://github.com/anonymous-rl-lab/PertRank/releases
|
|
13
|
+
Project-URL: Baseline Archive DOI, https://doi.org/10.5281/zenodo.24281072
|
|
14
|
+
Classifier: Development Status :: 3 - Alpha
|
|
15
|
+
Classifier: Intended Audience :: Science/Research
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
18
|
+
Requires-Python: >=3.10
|
|
19
|
+
Description-Content-Type: text/markdown
|
|
20
|
+
License-File: LICENSE
|
|
21
|
+
Requires-Dist: numpy>=1.24
|
|
22
|
+
Requires-Dist: scipy<1.17,>=1.10
|
|
23
|
+
Requires-Dist: pandas>=1.5
|
|
24
|
+
Requires-Dist: anndata>=0.9
|
|
25
|
+
Provides-Extra: test
|
|
26
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
27
|
+
Requires-Dist: h5py>=3.8; extra == "test"
|
|
28
|
+
Provides-Extra: tutorial
|
|
29
|
+
Requires-Dist: jupyterlab>=4; extra == "tutorial"
|
|
30
|
+
Requires-Dist: matplotlib>=3.6; extra == "tutorial"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
# PertRank
|
|
34
|
+
|
|
35
|
+
**Use control geometry to improve candidate selection while preserving the biological readout.** PertRank combines profile-wide effect and variance information with leading covariance directions from matched controls to calculate one reliability weight per perturbation. It applies that weight to the queried gene effect, producing separate candidate lists for increasing and decreasing the response.
|
|
36
|
+
|
|
37
|
+
The package provides an AnnData interface, reuse of fitted reliability with labeled external effect estimates, two real-data statistics tutorials, and numerical checks against the research implementation. The distribution and import name is `pertrank`.
|
|
38
|
+
|
|
39
|
+
Version **0.2.0** is a documentation and packaging maintenance release. It connects the reusable tool to the completed rvalues and transcriptional-program studies while preserving the numerical API and fixed parameters. The reproduction guide (`docs/reproducibility.md` in the source archive) explains which results belong to the Python tool and which are reproduced by the separate experiment bundle. Bundle releases are listed in the [repository](https://github.com/anonymous-rl-lab/PertRank/releases).
|
|
40
|
+
|
|
41
|
+
## What the software separates
|
|
42
|
+
|
|
43
|
+
| Step | Information used | Output |
|
|
44
|
+
|---|---|---|
|
|
45
|
+
| Estimate reliability | Matched controls and each target's own effect and sampling variation across the expression profile | One bounded weight per target |
|
|
46
|
+
| Read the response | Original gene effects, or a labeled upstream effect estimate such as FR-Perturb | A response-specific up/down score |
|
|
47
|
+
| Allocate shortlist positions | The same eligible candidates and a fixed list length | Candidate lists and exact boundary-tie inclusion probabilities |
|
|
48
|
+
|
|
49
|
+
The three returned methods make the contribution inspectable: **Unweighted** uses the effect directly, **Euclidean** uses target-level reliability without directional geometry, and **PertRank** adds the fixed control geometry. A complete-workflow comparison against Unweighted and a geometry comparison against Euclidean answer different questions. See [scientific design](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/scientific_design.md) for the equations, estimator reuse and connection to the manuscript evidence.
|
|
50
|
+
|
|
51
|
+
## Install
|
|
52
|
+
|
|
53
|
+
Use Python 3.10 or later. From the extracted source distribution, install the package in a separate environment:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
python -m pip install .
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
To create a wheel from the source tree:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
python -m pip wheel --no-deps . --wheel-dir dist
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Dependencies are declared in `pyproject.toml`. For development and checks:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
python -m pip install '.[test]'
|
|
69
|
+
python -m pytest
|
|
70
|
+
python scripts/check_tutorials.py --output-dir ../pertrank-tutorial-check
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Rank candidates from AnnData
|
|
74
|
+
|
|
75
|
+
Start with quality-controlled input cells and their matched non-targeting controls. Keep planning cells and reference cells separate. Gene and cell identifiers must be unique, and perturbed genes must use the same identifier namespace as query genes.
|
|
76
|
+
|
|
77
|
+
```python
|
|
78
|
+
import anndata as ad
|
|
79
|
+
import pertrank as pr
|
|
80
|
+
|
|
81
|
+
adata = ad.read_h5ad("screen_inputs.h5ad", backed="r")
|
|
82
|
+
result = pr.rank(
|
|
83
|
+
adata,
|
|
84
|
+
queries=["CTLA4", "IL2"],
|
|
85
|
+
input_scale="counts",
|
|
86
|
+
layer=None, # raw counts in X
|
|
87
|
+
full_gene_axis=True, # assert the full measured axis is present
|
|
88
|
+
strata_keys=["donor", "condition", "batch"],
|
|
89
|
+
target_key="target_ids",
|
|
90
|
+
target_gene_key="target_gene_ids",
|
|
91
|
+
control_key="is_control",
|
|
92
|
+
top_k=25,
|
|
93
|
+
)
|
|
94
|
+
adata.file.close()
|
|
95
|
+
|
|
96
|
+
result.nominations.to_csv("nominations.csv", index=False)
|
|
97
|
+
result.weights.to_csv("reliability_weights.csv", index=False)
|
|
98
|
+
result.all_candidate_scores.to_csv("all_candidate_scores.csv", index=False)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The count path accepts one prespecified matching stratum per call. The example's donor, condition and batch columns must therefore each have one value in the supplied object. Split the screen into its prespecified matching strata before calling this path. `strata_keys=[]` explicitly declares that the supplied cells belong to one stratum; use it only when the experimental design supports that declaration.
|
|
102
|
+
|
|
103
|
+
All supplied input cells contribute to the fit; define the query set and input-cell selection before calling the package. The paper's shallow examples use 20 cells per target and 2,000 controls; these experimental budgets differ from the numerical minimum. See input contracts (`docs/input_contracts.md` in the source archive) for scale, control matching and memory behavior.
|
|
104
|
+
|
|
105
|
+
## Read the outputs
|
|
106
|
+
|
|
107
|
+
| Output | Meaning |
|
|
108
|
+
|---|---|
|
|
109
|
+
| `nominations` | Deterministic top-k lists for up/down responses and the Unweighted, Euclidean and PertRank methods |
|
|
110
|
+
| `all_candidate_scores` | Eligible query–target scores, ranks and boundary-tie inclusion probabilities |
|
|
111
|
+
| `weights` | Target-level reliability weights and input counts |
|
|
112
|
+
| `effects` | Target-by-gene original-coordinate effects |
|
|
113
|
+
| `controls`, `statistics`, `metadata` | Control models, sufficient statistics and computation provenance |
|
|
114
|
+
|
|
115
|
+
The up score is `effect × weight`; the down score reverses its sign. The perturbed gene is excluded from its own query. A zero weight retains the candidate at a zero score. Tie inclusion probabilities describe random selection among equally scored candidates at the cutoff; they are not probabilities of biological correctness.
|
|
116
|
+
|
|
117
|
+
## Reuse reliability with an existing effect estimate
|
|
118
|
+
|
|
119
|
+
An external effect matrix must have unique target and gene labels, the same target population, and compatible effect orientation. Align it by labels rather than by row order.
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
import pandas as pd
|
|
123
|
+
|
|
124
|
+
external = pd.read_csv("external_effects.csv", index_col=0)
|
|
125
|
+
external_result = result.rank_effects(
|
|
126
|
+
external, queries=["CTLA4", "IL2"], top_k=25
|
|
127
|
+
)
|
|
128
|
+
external_result.nominations.to_csv("external_nominations.csv", index=False)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
This holds the fitted reliability calculation fixed while replacing the effect estimator. The returned `Unweighted`, `Euclidean` and `PertRank` arms then all use the supplied external effects, so the geometry comparison remains matched. The operation neither fits the upstream estimator nor re-estimates its uncertainty. Record that estimator's configuration and input design alongside the exported ranking.
|
|
132
|
+
|
|
133
|
+
## Evaluate a fixed shortlist against a separate reference
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
reference = pd.read_csv("reference_effects.csv", index_col=0)
|
|
137
|
+
scores = pr.evaluate_reference(result, reference)
|
|
138
|
+
scores.to_csv("reference_precision.csv", index=False)
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Provide a target-by-gene reference effect table with the same target population and every queried gene. The evaluator returns precision and expected overlap for each method, query and direction, using the result's fixed list length and self-target exclusions. It accounts for boundary ties in both the predicted and reference lists. The reference is used only for scoring. Define its construction independently of the fitted ranking; biological interpretation depends on that design. See [API reference](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/api.md#evaluate_reference) for the exact scoring rule. Query-level uncertainty and manuscript-specific aggregation remain in the full scientific reproduction bundle.
|
|
142
|
+
|
|
143
|
+
## Try the interface immediately
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
python tutorials/00_anndata_quickstart.py
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
This quickstart creates a small synthetic AnnData solely for a software
|
|
150
|
+
check. The two atlas notebooks instead use authentic archived statistics.
|
|
151
|
+
|
|
152
|
+
## Learn and reproduce
|
|
153
|
+
|
|
154
|
+
- [API reference](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/api.md): public functions and result fields.
|
|
155
|
+
- [Scientific design](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/scientific_design.md): reliability, readout and the interpretation of matched comparisons.
|
|
156
|
+
- Input contracts (`docs/input_contracts.md` in the source archive): counts, normalized inputs and matching strata.
|
|
157
|
+
- [Replogle tutorial](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/01_replogle.ipynb) and [T-cell tutorial](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/02_tcell.ipynb): worked examples using archived real-data sufficient statistics. The tutorials identify the source and processing level of each fixture. They replay candidate ranking from saved statistics; the AnnData example above is the cell-input route.
|
|
158
|
+
- Reproduction guide (`docs/reproducibility.md` in the source archive): package examples, the two completed experimental additions, and full-bundle execution.
|
|
159
|
+
- `tests/`: checks of the public interface and numerical agreement with the frozen implementation.
|
|
160
|
+
- Community integration proposal (`docs/community_integration.md` in the source archive): prepared scverse registration and pertpy contribution scope.
|
|
161
|
+
- Distribution and release process (`docs/release_process.md` in the source archive): installation, artifact verification and the remaining public-release metadata.
|
|
162
|
+
|
|
163
|
+
The scientific use is candidate prioritization for follow-up experiments. Weights describe estimated profile reliability, not calibrated probabilities of biological validation. The manuscript evaluates decision quality with fixed-length lists, matched exclusions and reference-supported precision; its independent RNA comparison supports the complete workflow, while matched Euclidean contrasts isolate the added geometry.
|
|
164
|
+
|
|
165
|
+
## Research resources and attribution
|
|
166
|
+
|
|
167
|
+
PertRank-Q is a separate, optional checkpoint-replay module in the full reproduction bundle (`modules/pertrank_q`); it is not part of the `pertrank` Python API. Its reference-supervised candidate-subpool evaluation must not be read as an unsupervised full-pool deployment result.
|
|
168
|
+
|
|
169
|
+
The computational equations and fixed parameters (`k=5`, `beta=0.9`) follow the manuscript implementation. The accompanying paper now also evaluates a fixed native rvalues comparator and predefined transcriptional-program nomination in a drug screen. Their experiment-specific inputs, reference resampling and diagnostics are distributed in the separate reproduction bundle. They do not add a program-ranking or PertRank-Q API to this wheel.
|
|
170
|
+
|
|
171
|
+
The source manifests identify the method and datasets, whose rights remain with their original owners. The inherited software-license decision remains pending; see release process (`docs/release_process.md` in the source archive) for the publication requirements.
|
|
172
|
+
|
|
173
|
+
## Where the documentation lives
|
|
174
|
+
|
|
175
|
+
The scientific design, API reference and both tutorial links above open the stable interface documentation at `v0.1.2` in the anonymous GitHub repository over HTTPS. These links describe the numerical interface retained by this maintenance release; they are not evidence that the newer experiment bundle is contained in that archived version. These documents and notebooks are also included in the source distribution for offline reading. PyPI hosts distribution archives, not separate web pages for files inside them. The wheel includes the runtime and tutorial data, while the notebooks and prose documentation remain in the source archive.
|
|
176
|
+
|
|
177
|
+
`PYPI_DESCRIPTION.md` is generated from this README by `python scripts/build_pypi_description.py`. It preserves HTTPS links, including the version-pinned documentation targets and the API `#evaluate_reference` anchor, and converts the remaining local links into explicit source-archive paths. `pyproject.toml` uses it as the PyPI description so local paths cannot resolve to nonexistent PyPI pages. Run `python scripts/check_distribution.py` against the newly built archives before a release. Package versions, reproduction-bundle versions and paper versions identify separate artifacts.
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# PertRank
|
|
2
|
+
|
|
3
|
+
**Use control geometry to improve candidate selection while preserving the biological readout.** PertRank combines profile-wide effect and variance information with leading covariance directions from matched controls to calculate one reliability weight per perturbation. It applies that weight to the queried gene effect, producing separate candidate lists for increasing and decreasing the response.
|
|
4
|
+
|
|
5
|
+
The package provides an AnnData interface, reuse of fitted reliability with labeled external effect estimates, two real-data statistics tutorials, and numerical checks against the research implementation. The distribution and import name is `pertrank`.
|
|
6
|
+
|
|
7
|
+
Version **0.2.0** is a documentation and packaging maintenance release. It connects the reusable tool to the completed rvalues and transcriptional-program studies while preserving the numerical API and fixed parameters. The reproduction guide (`docs/reproducibility.md` in the source archive) explains which results belong to the Python tool and which are reproduced by the separate experiment bundle. Bundle releases are listed in the [repository](https://github.com/anonymous-rl-lab/PertRank/releases).
|
|
8
|
+
|
|
9
|
+
## What the software separates
|
|
10
|
+
|
|
11
|
+
| Step | Information used | Output |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Estimate reliability | Matched controls and each target's own effect and sampling variation across the expression profile | One bounded weight per target |
|
|
14
|
+
| Read the response | Original gene effects, or a labeled upstream effect estimate such as FR-Perturb | A response-specific up/down score |
|
|
15
|
+
| Allocate shortlist positions | The same eligible candidates and a fixed list length | Candidate lists and exact boundary-tie inclusion probabilities |
|
|
16
|
+
|
|
17
|
+
The three returned methods make the contribution inspectable: **Unweighted** uses the effect directly, **Euclidean** uses target-level reliability without directional geometry, and **PertRank** adds the fixed control geometry. A complete-workflow comparison against Unweighted and a geometry comparison against Euclidean answer different questions. See [scientific design](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/scientific_design.md) for the equations, estimator reuse and connection to the manuscript evidence.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
Use Python 3.10 or later. From the extracted source distribution, install the package in a separate environment:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
python -m pip install .
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
To create a wheel from the source tree:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
python -m pip wheel --no-deps . --wheel-dir dist
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Dependencies are declared in `pyproject.toml`. For development and checks:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
python -m pip install '.[test]'
|
|
37
|
+
python -m pytest
|
|
38
|
+
python scripts/check_tutorials.py --output-dir ../pertrank-tutorial-check
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Rank candidates from AnnData
|
|
42
|
+
|
|
43
|
+
Start with quality-controlled input cells and their matched non-targeting controls. Keep planning cells and reference cells separate. Gene and cell identifiers must be unique, and perturbed genes must use the same identifier namespace as query genes.
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
import anndata as ad
|
|
47
|
+
import pertrank as pr
|
|
48
|
+
|
|
49
|
+
adata = ad.read_h5ad("screen_inputs.h5ad", backed="r")
|
|
50
|
+
result = pr.rank(
|
|
51
|
+
adata,
|
|
52
|
+
queries=["CTLA4", "IL2"],
|
|
53
|
+
input_scale="counts",
|
|
54
|
+
layer=None, # raw counts in X
|
|
55
|
+
full_gene_axis=True, # assert the full measured axis is present
|
|
56
|
+
strata_keys=["donor", "condition", "batch"],
|
|
57
|
+
target_key="target_ids",
|
|
58
|
+
target_gene_key="target_gene_ids",
|
|
59
|
+
control_key="is_control",
|
|
60
|
+
top_k=25,
|
|
61
|
+
)
|
|
62
|
+
adata.file.close()
|
|
63
|
+
|
|
64
|
+
result.nominations.to_csv("nominations.csv", index=False)
|
|
65
|
+
result.weights.to_csv("reliability_weights.csv", index=False)
|
|
66
|
+
result.all_candidate_scores.to_csv("all_candidate_scores.csv", index=False)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The count path accepts one prespecified matching stratum per call. The example's donor, condition and batch columns must therefore each have one value in the supplied object. Split the screen into its prespecified matching strata before calling this path. `strata_keys=[]` explicitly declares that the supplied cells belong to one stratum; use it only when the experimental design supports that declaration.
|
|
70
|
+
|
|
71
|
+
All supplied input cells contribute to the fit; define the query set and input-cell selection before calling the package. The paper's shallow examples use 20 cells per target and 2,000 controls; these experimental budgets differ from the numerical minimum. See input contracts (`docs/input_contracts.md` in the source archive) for scale, control matching and memory behavior.
|
|
72
|
+
|
|
73
|
+
## Read the outputs
|
|
74
|
+
|
|
75
|
+
| Output | Meaning |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `nominations` | Deterministic top-k lists for up/down responses and the Unweighted, Euclidean and PertRank methods |
|
|
78
|
+
| `all_candidate_scores` | Eligible query–target scores, ranks and boundary-tie inclusion probabilities |
|
|
79
|
+
| `weights` | Target-level reliability weights and input counts |
|
|
80
|
+
| `effects` | Target-by-gene original-coordinate effects |
|
|
81
|
+
| `controls`, `statistics`, `metadata` | Control models, sufficient statistics and computation provenance |
|
|
82
|
+
|
|
83
|
+
The up score is `effect × weight`; the down score reverses its sign. The perturbed gene is excluded from its own query. A zero weight retains the candidate at a zero score. Tie inclusion probabilities describe random selection among equally scored candidates at the cutoff; they are not probabilities of biological correctness.
|
|
84
|
+
|
|
85
|
+
## Reuse reliability with an existing effect estimate
|
|
86
|
+
|
|
87
|
+
An external effect matrix must have unique target and gene labels, the same target population, and compatible effect orientation. Align it by labels rather than by row order.
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
import pandas as pd
|
|
91
|
+
|
|
92
|
+
external = pd.read_csv("external_effects.csv", index_col=0)
|
|
93
|
+
external_result = result.rank_effects(
|
|
94
|
+
external, queries=["CTLA4", "IL2"], top_k=25
|
|
95
|
+
)
|
|
96
|
+
external_result.nominations.to_csv("external_nominations.csv", index=False)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
This holds the fitted reliability calculation fixed while replacing the effect estimator. The returned `Unweighted`, `Euclidean` and `PertRank` arms then all use the supplied external effects, so the geometry comparison remains matched. The operation neither fits the upstream estimator nor re-estimates its uncertainty. Record that estimator's configuration and input design alongside the exported ranking.
|
|
100
|
+
|
|
101
|
+
## Evaluate a fixed shortlist against a separate reference
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
reference = pd.read_csv("reference_effects.csv", index_col=0)
|
|
105
|
+
scores = pr.evaluate_reference(result, reference)
|
|
106
|
+
scores.to_csv("reference_precision.csv", index=False)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Provide a target-by-gene reference effect table with the same target population and every queried gene. The evaluator returns precision and expected overlap for each method, query and direction, using the result's fixed list length and self-target exclusions. It accounts for boundary ties in both the predicted and reference lists. The reference is used only for scoring. Define its construction independently of the fitted ranking; biological interpretation depends on that design. See [API reference](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/api.md#evaluate_reference) for the exact scoring rule. Query-level uncertainty and manuscript-specific aggregation remain in the full scientific reproduction bundle.
|
|
110
|
+
|
|
111
|
+
## Try the interface immediately
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
python tutorials/00_anndata_quickstart.py
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
This quickstart creates a small synthetic AnnData solely for a software
|
|
118
|
+
check. The two atlas notebooks instead use authentic archived statistics.
|
|
119
|
+
|
|
120
|
+
## Learn and reproduce
|
|
121
|
+
|
|
122
|
+
- [API reference](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/api.md): public functions and result fields.
|
|
123
|
+
- [Scientific design](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/scientific_design.md): reliability, readout and the interpretation of matched comparisons.
|
|
124
|
+
- Input contracts (`docs/input_contracts.md` in the source archive): counts, normalized inputs and matching strata.
|
|
125
|
+
- [Replogle tutorial](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/01_replogle.ipynb) and [T-cell tutorial](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/02_tcell.ipynb): worked examples using archived real-data sufficient statistics. The tutorials identify the source and processing level of each fixture. They replay candidate ranking from saved statistics; the AnnData example above is the cell-input route.
|
|
126
|
+
- Reproduction guide (`docs/reproducibility.md` in the source archive): package examples, the two completed experimental additions, and full-bundle execution.
|
|
127
|
+
- `tests/`: checks of the public interface and numerical agreement with the frozen implementation.
|
|
128
|
+
- Community integration proposal (`docs/community_integration.md` in the source archive): prepared scverse registration and pertpy contribution scope.
|
|
129
|
+
- Distribution and release process (`docs/release_process.md` in the source archive): installation, artifact verification and the remaining public-release metadata.
|
|
130
|
+
|
|
131
|
+
The scientific use is candidate prioritization for follow-up experiments. Weights describe estimated profile reliability, not calibrated probabilities of biological validation. The manuscript evaluates decision quality with fixed-length lists, matched exclusions and reference-supported precision; its independent RNA comparison supports the complete workflow, while matched Euclidean contrasts isolate the added geometry.
|
|
132
|
+
|
|
133
|
+
## Research resources and attribution
|
|
134
|
+
|
|
135
|
+
PertRank-Q is a separate, optional checkpoint-replay module in the full reproduction bundle (`modules/pertrank_q`); it is not part of the `pertrank` Python API. Its reference-supervised candidate-subpool evaluation must not be read as an unsupervised full-pool deployment result.
|
|
136
|
+
|
|
137
|
+
The computational equations and fixed parameters (`k=5`, `beta=0.9`) follow the manuscript implementation. The accompanying paper now also evaluates a fixed native rvalues comparator and predefined transcriptional-program nomination in a drug screen. Their experiment-specific inputs, reference resampling and diagnostics are distributed in the separate reproduction bundle. They do not add a program-ranking or PertRank-Q API to this wheel.
|
|
138
|
+
|
|
139
|
+
The source manifests identify the method and datasets, whose rights remain with their original owners. The inherited software-license decision remains pending; see release process (`docs/release_process.md` in the source archive) for the publication requirements.
|
|
140
|
+
|
|
141
|
+
## Where the documentation lives
|
|
142
|
+
|
|
143
|
+
The scientific design, API reference and both tutorial links above open the stable interface documentation at `v0.1.2` in the anonymous GitHub repository over HTTPS. These links describe the numerical interface retained by this maintenance release; they are not evidence that the newer experiment bundle is contained in that archived version. These documents and notebooks are also included in the source distribution for offline reading. PyPI hosts distribution archives, not separate web pages for files inside them. The wheel includes the runtime and tutorial data, while the notebooks and prose documentation remain in the source archive.
|
|
144
|
+
|
|
145
|
+
`PYPI_DESCRIPTION.md` is generated from this README by `python scripts/build_pypi_description.py`. It preserves HTTPS links, including the version-pinned documentation targets and the API `#evaluate_reference` anchor, and converts the remaining local links into explicit source-archive paths. `pyproject.toml` uses it as the PyPI description so local paths cannot resolve to nonexistent PyPI pages. Run `python scripts/check_distribution.py` against the newly built archives before a release. Package versions, reproduction-bundle versions and paper versions identify separate artifacts.
|
pertrank-0.2.0/README.md
ADDED
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# PertRank
|
|
2
|
+
|
|
3
|
+
**Use control geometry to improve candidate selection while preserving the biological readout.** PertRank combines profile-wide effect and variance information with leading covariance directions from matched controls to calculate one reliability weight per perturbation. It applies that weight to the queried gene effect, producing separate candidate lists for increasing and decreasing the response.
|
|
4
|
+
|
|
5
|
+
The package provides an AnnData interface, reuse of fitted reliability with labeled external effect estimates, two real-data statistics tutorials, and numerical checks against the research implementation. The distribution and import name is `pertrank`.
|
|
6
|
+
|
|
7
|
+
Version **0.2.0** is a documentation and packaging maintenance release. It connects the reusable tool to the completed rvalues and transcriptional-program studies while preserving the numerical API and fixed parameters. The [reproduction guide](docs/reproducibility.md) explains which results belong to the Python tool and which are reproduced by the separate experiment bundle. Bundle releases are listed in the [repository](https://github.com/anonymous-rl-lab/PertRank/releases).
|
|
8
|
+
|
|
9
|
+
## What the software separates
|
|
10
|
+
|
|
11
|
+
| Step | Information used | Output |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| Estimate reliability | Matched controls and each target's own effect and sampling variation across the expression profile | One bounded weight per target |
|
|
14
|
+
| Read the response | Original gene effects, or a labeled upstream effect estimate such as FR-Perturb | A response-specific up/down score |
|
|
15
|
+
| Allocate shortlist positions | The same eligible candidates and a fixed list length | Candidate lists and exact boundary-tie inclusion probabilities |
|
|
16
|
+
|
|
17
|
+
The three returned methods make the contribution inspectable: **Unweighted** uses the effect directly, **Euclidean** uses target-level reliability without directional geometry, and **PertRank** adds the fixed control geometry. A complete-workflow comparison against Unweighted and a geometry comparison against Euclidean answer different questions. See [scientific design](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/scientific_design.md) for the equations, estimator reuse and connection to the manuscript evidence.
|
|
18
|
+
|
|
19
|
+
## Install
|
|
20
|
+
|
|
21
|
+
Use Python 3.10 or later. From the extracted source distribution, install the package in a separate environment:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
python -m pip install .
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
To create a wheel from the source tree:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
python -m pip wheel --no-deps . --wheel-dir dist
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Dependencies are declared in `pyproject.toml`. For development and checks:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
python -m pip install '.[test]'
|
|
37
|
+
python -m pytest
|
|
38
|
+
python scripts/check_tutorials.py --output-dir ../pertrank-tutorial-check
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Rank candidates from AnnData
|
|
42
|
+
|
|
43
|
+
Start with quality-controlled input cells and their matched non-targeting controls. Keep planning cells and reference cells separate. Gene and cell identifiers must be unique, and perturbed genes must use the same identifier namespace as query genes.
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
import anndata as ad
|
|
47
|
+
import pertrank as pr
|
|
48
|
+
|
|
49
|
+
adata = ad.read_h5ad("screen_inputs.h5ad", backed="r")
|
|
50
|
+
result = pr.rank(
|
|
51
|
+
adata,
|
|
52
|
+
queries=["CTLA4", "IL2"],
|
|
53
|
+
input_scale="counts",
|
|
54
|
+
layer=None, # raw counts in X
|
|
55
|
+
full_gene_axis=True, # assert the full measured axis is present
|
|
56
|
+
strata_keys=["donor", "condition", "batch"],
|
|
57
|
+
target_key="target_ids",
|
|
58
|
+
target_gene_key="target_gene_ids",
|
|
59
|
+
control_key="is_control",
|
|
60
|
+
top_k=25,
|
|
61
|
+
)
|
|
62
|
+
adata.file.close()
|
|
63
|
+
|
|
64
|
+
result.nominations.to_csv("nominations.csv", index=False)
|
|
65
|
+
result.weights.to_csv("reliability_weights.csv", index=False)
|
|
66
|
+
result.all_candidate_scores.to_csv("all_candidate_scores.csv", index=False)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The count path accepts one prespecified matching stratum per call. The example's donor, condition and batch columns must therefore each have one value in the supplied object. Split the screen into its prespecified matching strata before calling this path. `strata_keys=[]` explicitly declares that the supplied cells belong to one stratum; use it only when the experimental design supports that declaration.
|
|
70
|
+
|
|
71
|
+
All supplied input cells contribute to the fit; define the query set and input-cell selection before calling the package. The paper's shallow examples use 20 cells per target and 2,000 controls; these experimental budgets differ from the numerical minimum. See [input contracts](docs/input_contracts.md) for scale, control matching and memory behavior.
|
|
72
|
+
|
|
73
|
+
## Read the outputs
|
|
74
|
+
|
|
75
|
+
| Output | Meaning |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `nominations` | Deterministic top-k lists for up/down responses and the Unweighted, Euclidean and PertRank methods |
|
|
78
|
+
| `all_candidate_scores` | Eligible query–target scores, ranks and boundary-tie inclusion probabilities |
|
|
79
|
+
| `weights` | Target-level reliability weights and input counts |
|
|
80
|
+
| `effects` | Target-by-gene original-coordinate effects |
|
|
81
|
+
| `controls`, `statistics`, `metadata` | Control models, sufficient statistics and computation provenance |
|
|
82
|
+
|
|
83
|
+
The up score is `effect × weight`; the down score reverses its sign. The perturbed gene is excluded from its own query. A zero weight retains the candidate at a zero score. Tie inclusion probabilities describe random selection among equally scored candidates at the cutoff; they are not probabilities of biological correctness.
|
|
84
|
+
|
|
85
|
+
## Reuse reliability with an existing effect estimate
|
|
86
|
+
|
|
87
|
+
An external effect matrix must have unique target and gene labels, the same target population, and compatible effect orientation. Align it by labels rather than by row order.
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
import pandas as pd
|
|
91
|
+
|
|
92
|
+
external = pd.read_csv("external_effects.csv", index_col=0)
|
|
93
|
+
external_result = result.rank_effects(
|
|
94
|
+
external, queries=["CTLA4", "IL2"], top_k=25
|
|
95
|
+
)
|
|
96
|
+
external_result.nominations.to_csv("external_nominations.csv", index=False)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
This holds the fitted reliability calculation fixed while replacing the effect estimator. The returned `Unweighted`, `Euclidean` and `PertRank` arms then all use the supplied external effects, so the geometry comparison remains matched. The operation neither fits the upstream estimator nor re-estimates its uncertainty. Record that estimator's configuration and input design alongside the exported ranking.
|
|
100
|
+
|
|
101
|
+
## Evaluate a fixed shortlist against a separate reference
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
reference = pd.read_csv("reference_effects.csv", index_col=0)
|
|
105
|
+
scores = pr.evaluate_reference(result, reference)
|
|
106
|
+
scores.to_csv("reference_precision.csv", index=False)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Provide a target-by-gene reference effect table with the same target population and every queried gene. The evaluator returns precision and expected overlap for each method, query and direction, using the result's fixed list length and self-target exclusions. It accounts for boundary ties in both the predicted and reference lists. The reference is used only for scoring. Define its construction independently of the fitted ranking; biological interpretation depends on that design. See [API reference](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/api.md#evaluate_reference) for the exact scoring rule. Query-level uncertainty and manuscript-specific aggregation remain in the full scientific reproduction bundle.
|
|
110
|
+
|
|
111
|
+
## Try the interface immediately
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
python tutorials/00_anndata_quickstart.py
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
This quickstart creates a small synthetic AnnData solely for a software
|
|
118
|
+
check. The two atlas notebooks instead use authentic archived statistics.
|
|
119
|
+
|
|
120
|
+
## Learn and reproduce
|
|
121
|
+
|
|
122
|
+
- [API reference](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/api.md): public functions and result fields.
|
|
123
|
+
- [Scientific design](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/docs/scientific_design.md): reliability, readout and the interpretation of matched comparisons.
|
|
124
|
+
- [Input contracts](docs/input_contracts.md): counts, normalized inputs and matching strata.
|
|
125
|
+
- [Replogle tutorial](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/01_replogle.ipynb) and [T-cell tutorial](https://github.com/anonymous-rl-lab/PertRank/blob/v0.1.2/modules/paper_analysis/software/tutorials/02_tcell.ipynb): worked examples using archived real-data sufficient statistics. The tutorials identify the source and processing level of each fixture. They replay candidate ranking from saved statistics; the AnnData example above is the cell-input route.
|
|
126
|
+
- [Reproduction guide](docs/reproducibility.md): package examples, the two completed experimental additions, and full-bundle execution.
|
|
127
|
+
- `tests/`: checks of the public interface and numerical agreement with the frozen implementation.
|
|
128
|
+
- [Community integration proposal](docs/community_integration.md): prepared scverse registration and pertpy contribution scope.
|
|
129
|
+
- [Distribution and release process](docs/release_process.md): installation, artifact verification and the remaining public-release metadata.
|
|
130
|
+
|
|
131
|
+
The scientific use is candidate prioritization for follow-up experiments. Weights describe estimated profile reliability, not calibrated probabilities of biological validation. The manuscript evaluates decision quality with fixed-length lists, matched exclusions and reference-supported precision; its independent RNA comparison supports the complete workflow, while matched Euclidean contrasts isolate the added geometry.
|
|
132
|
+
|
|
133
|
+
## Research resources and attribution
|
|
134
|
+
|
|
135
|
+
PertRank-Q is a separate, optional checkpoint-replay module in the full reproduction bundle (`modules/pertrank_q`); it is not part of the `pertrank` Python API. Its reference-supervised candidate-subpool evaluation must not be read as an unsupervised full-pool deployment result.
|
|
136
|
+
|
|
137
|
+
The computational equations and fixed parameters (`k=5`, `beta=0.9`) follow the manuscript implementation. The accompanying paper now also evaluates a fixed native rvalues comparator and predefined transcriptional-program nomination in a drug screen. Their experiment-specific inputs, reference resampling and diagnostics are distributed in the separate reproduction bundle. They do not add a program-ranking or PertRank-Q API to this wheel.
|
|
138
|
+
|
|
139
|
+
The source manifests identify the method and datasets, whose rights remain with their original owners. The inherited software-license decision remains pending; see [release process](docs/release_process.md) for the publication requirements.
|
|
140
|
+
|
|
141
|
+
## Where the documentation lives
|
|
142
|
+
|
|
143
|
+
The scientific design, API reference and both tutorial links above open the stable interface documentation at `v0.1.2` in the anonymous GitHub repository over HTTPS. These links describe the numerical interface retained by this maintenance release; they are not evidence that the newer experiment bundle is contained in that archived version. These documents and notebooks are also included in the source distribution for offline reading. PyPI hosts distribution archives, not separate web pages for files inside them. The wheel includes the runtime and tutorial data, while the notebooks and prose documentation remain in the source archive.
|
|
144
|
+
|
|
145
|
+
`PYPI_DESCRIPTION.md` is generated from this README by `python scripts/build_pypi_description.py`. It preserves HTTPS links, including the version-pinned documentation targets and the API `#evaluate_reference` anchor, and converts the remaining local links into explicit source-archive paths. `pyproject.toml` uses it as the PyPI description so local paths cannot resolve to nonexistent PyPI pages. Run `python scripts/check_distribution.py` against the newly built archives before a release. Package versions, reproduction-bundle versions and paper versions identify separate artifacts.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# PertRank 0.2.0 使用说明
|
|
2
|
+
|
|
3
|
+
本版是软件说明与分发维护更新:保留既有 AnnData 接口、固定的五个对照方向、`beta=0.9`、外部效应复用接口及真实教程数据,并接入两项新增实验的复现导航。
|
|
4
|
+
|
|
5
|
+
`pertrank` 是可安装的通用排序工具;论文代码总包包含实验输入、参考评价、区间、图表和专项诊断。软件版本、总包版本与论文版本分别管理。
|
|
6
|
+
|
|
7
|
+
## 安装与使用
|
|
8
|
+
|
|
9
|
+
使用 Python 3.10 或以上版本。在独立环境中,从解压后的软件源码目录安装:
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
python -m pip install .
|
|
13
|
+
python tutorials/00_anndata_quickstart.py
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
若软件源码来自带校验清单的总代码包,先复制到总包之外再安装和构建。AnnData 示例使用合成输入,演示从细胞数据到候选表的完整软件流程。自己的数据需要明确尺度、靶点身份、完整基因轴和匹配对照,见 [README](README.md) 与 [输入要求](docs/input_contracts.md)。
|
|
17
|
+
|
|
18
|
+
| 需要完成的工作 | 软件入口 |
|
|
19
|
+
|---|---|
|
|
20
|
+
| 计算指定基因的上调/下调候选 | `pertrank.rank(...)` |
|
|
21
|
+
| 将已有可靠性权重用于另一效应估计器 | `result.rank_effects(...)` |
|
|
22
|
+
| 用独立参考评价候选名单 | `pertrank.evaluate_reference(...)` |
|
|
23
|
+
|
|
24
|
+
排名返回 Unweighted、Euclidean、PertRank 三臂。完整流程比较与控制几何的匹配增量分别报告;权重是可靠性估计,不是生物学验证概率。
|
|
25
|
+
|
|
26
|
+
## 真实数据教程
|
|
27
|
+
|
|
28
|
+
| 教程 | 保留统计量的覆盖 |
|
|
29
|
+
|---|---|
|
|
30
|
+
| `tutorials/01_replogle.ipynb` | Replogle K562:2,000 候选、300 查询;权重信息来自 8,202 基因 |
|
|
31
|
+
| `tutorials/02_tcell.ipynb` | T 细胞 D3 Rest:52 候选、293 查询;权重信息来自 13,390 基因,附已存 FR 输出 |
|
|
32
|
+
|
|
33
|
+
教程从归档统计量重新计算权重和排名;每套数据附来源和哈希。执行检查:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
python scripts/check_tutorials.py --output-dir ../pertrank-tutorial-check
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
该命令检查完整 AnnData 示例和两篇 notebook 的代码单元。软件安装、测试环境和实际执行结果见 [验证记录](docs/validation.md)。
|
|
40
|
+
|
|
41
|
+
## 两项新增实验在哪里
|
|
42
|
+
|
|
43
|
+
本轮完成的 **rvalues 固定比较**与**预定义转录程序提名**位于代码总包的 `modules/new_results/`,没有装入 wheel。完整复现入口见 [实验复现指南](docs/reproducibility.md)。
|
|
44
|
+
|
|
45
|
+
从相应总代码包根目录运行:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
python reproduce.py --only new_results --output-dir ../pertrank-new-results
|
|
49
|
+
python reproduce.py --only new_results_exploratory --output-dir ../pertrank-exploratory
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
这些入口从保留的原生输出、精确统计量和参考细胞投影重算结果。默认不重新拟合原生 ASH/rvalues;rvalues 完整拟合材料保留在总包 `modules/rvalues_native/`。程序应用判据通过,ASH 读出上的几何及联合判据未通过,未成功调整也保留。
|
|
53
|
+
|
|
54
|
+
PertRank-Q 仍在总包的 `modules/pertrank_q/`,不属于此软件包的 Python API。
|
|
55
|
+
|
|
56
|
+
## 文档与发布
|
|
57
|
+
|
|
58
|
+
科学设计、API 和两篇教程随源码包提供;其线上链接固定至已有 GitHub `v0.1.2`。它们说明本版保留的接口,不表示该旧存档已经包含新增实验。用 [GitHub Releases](https://github.com/anonymous-rl-lab/PertRank/releases) 查找与所用论文对应的实验包,并核对下载内容及版本。
|
|
59
|
+
|
|
60
|
+
PyPI 长描述由 README 生成,保留有效 HTTPS 链接,将其他本地文档标为源码包内路径,避免指向不存在的 PyPI 页面。
|
|
61
|
+
|
|
62
|
+
许可证继续保持原有待定状态;本轮没有新增公开许可授权。公开上传前的元数据与许可要求见 [发布说明](docs/release_process.md)。
|