PerTurbo 2.0.0rc1

PerTurbo 2.0.0 release candidate 1. The NumPyro/JAX implementation replaces the PyTorch one, which stays available as the optional perturbo[legacy] extra.

What is new

• A conditional randomization test (--crt), evaluated in closed form rather than by resampling, so every perturbation-gene pair of a genome-scale screen can be tested. The null of the negative-binomial score statistic under random reassignment of the guide is a weighted sum of independent Bernoulli variables; its cumulant generating function is exact and a saddlepoint approximation gives tail probabilities to 1e-12 with no resamples drawn. One baseline fit is amortised over every pair. --crt-only stops after the test.
• Both screen designs from one test. --crt-pool control-anchored tests each perturbation inside the control cells plus its own (one perturbation per cell); --crt-pool all-cells tests each element as a marginal association over every cell (many per cell). The default auto measures the design: all cells when the median guides per cell exceeds 3, the control pool otherwise. The run prints the measurement, reports how many cells carry only control guides, warns below 1,000 cells or 1%, and records everything in crt_metadata.json.
• Element maps on the control-anchored pool. The assignment is collapsed to elements, the pool is the cells carrying nothing but control guides, and cells carrying two or more elements are set aside and counted rather than reinterpreted.
• Two tables from one run. --pairs-to-test writes element_effects_requested_pairs.parquet beside the transcriptome-wide table, with Benjamini-Hochberg recomputed within the requested set.

Breaking changes

• --pairs-to-test no longer restricts the fit; it selects the rows of the second table. Callers that relied on it for speed will get a transcriptome-wide run, and the command line says so at startup.
• The command-line entry point is perturbo; Python 3.11 is the minimum.
• Guide-level summaries are derived only where a guide's effect differs from its element's (the relative strategy). Under shared they equal the element effects and nothing is derived.

Fixed

• A perturbation with more cells than --max-chunk-size takes a chunk of its own instead of aborting the run.
• Perturbation codes are 32-bit; a single-perturbation chunk no longer overflows.
• The guide-summary step no longer draws the whole effect matrix (tens of gigabytes at screen scale).

Compatibility

Cortado-format MuData registrations and fit bundles are read and migrated. The IGVF CRISPR_Pipeline branch perturbo-v2-single-run uses this image (ghcr.io/pinellolab/perturbo:v2.0.0rc1).