spacr.trial_metrics

Per-trial scalar metrics recorded on each row of a regression sweep.

A row that reports only a hit count is insufficient for choosing a sweep configuration: a larger count can coincide with losing a known positive control. Each row therefore records model quality, design diagnostics, and control recovery alongside its hit count.

So a row carries four kinds of thing, and they answer different questions:

fit quality is the model describing the data at all residuals are its standard errors, and therefore its p-values, real design is the thing even identifiable, and how much data reached it controls does it recover what is known to be true

The controls matter most. When the user has named a positive control, a configuration should be judged first by where that control ranks: a setting that pushes a known true hit down the list is not detected by any goodness-of-fit statistic.

Every function here returns a flat dict of scalars, because a sweep row is a row: nothing nested, nothing that needs unpacking to sort on.

Every metric here is cheap to compute, by design. A sweep runs hundreds of trials, so a per-trial diagnostic that costs seconds costs hours across the run. The full 23-panel suite in spacr.regression_qc was measured at ~5.8 s per fit – ten minutes per hundred trials. These scalars were measured at 73-230 ms on screen-shaped fits (606-2400 rows, 200-400 parameters), which is under half a percent of the ~60 s a real trial takes. A sweep therefore records the numbers on every row and draws the plots only for rows that are reopened.

Nothing here refits anything. Every statistic is read off the model the trial already fitted, which is what keeps it cheap.

Functions

calibration(→ dict)	Return the genomic inflation and low-p excess of the raw p-values.
control_recovery(→ dict)	Summarize where configured controls rank in a result table.
design_diagnostics(→ dict)	Rank, identifiability and collinearity -- read off the existing fit.
design_summary(→ dict)	How much data reached the fit, and whether it was identifiable.
fit_quality(→ dict)	R-squared and the information criteria, when the model reports them.
guide_support_summary(→ dict)	How many of the hits rest on a single guide.
hit_counts(→ dict)	Count the trial's result rows and hits, by raw and adjusted p-value.
qc_verdicts(→ dict)	Summarize design and inference diagnostics for one sweep trial.
residual_diagnostics(→ dict)	Homoscedasticity, autocorrelation and normality of the residuals.
summarise_trial(→ dict)	Return every metric for one trial as a flat dict for its sweep row.

Module Contents

spacr.trial_metrics.calibration(results: pandas.DataFrame) → dict

Return the genomic inflation and low-p excess of the raw p-values.

Parameters:

results – result table carrying raw p_value values.

spacr.trial_metrics.control_recovery(results: pandas.DataFrame, settings: Mapping[str, Any]) → dict

Summarize where configured controls rank in a result table.

Both rank and percentile are returned because result tables can contain different numbers of coefficients. Missing controls are reported with a false *_control_found value and no invented rank.

Parameters:

• results (pandas.DataFrame) – Coefficient table produced by a regression trial.

• settings (mapping) – Trial settings containing optional positive and negative controls.

Returns:

dict – Control presence, rank, percentile, effect, and significance fields.

spacr.trial_metrics.design_diagnostics(model) → dict

Rank, identifiability and collinearity – read off the existing fit.

Parameters:

model – fitted model result object, or None.

Values the fit already holds are read, not recomputed. spacr.regression_diagnostics.design_report() answers the same questions, but it takes the well-by-guide matrix and pays for a fresh matrix_rank and a full SVD. A sweep does not have that matrix – it has a fitted model – and statsmodels computed the rank at fit time and kept it on model.model.rank. The field names below deliberately match design_report’s so the two read the same in a trial folder.

identifiable is the one that decides whether the rest of the row means anything. A rank-deficient design does not have unique coefficients, so its per-guide effects are one of infinitely many solutions and its p-values rank an arbitrary choice among them. spaCR fits these designs without an error – statsmodels falls back to a pseudo-inverse rather than refusing – so nothing else in the output reports it.

spacr.trial_metrics.design_summary(output: Mapping[str, Any]) → dict

How much data reached the fit, and whether it was identifiable.

Parameters:

output – trial output mapping optionally carrying prepared model_data and measured per-level fit_designs. Fitted counts are reported per level; an unqualified count is emitted only when every fit records the same value. Legacy outputs without fit records retain their table-based counts.

spacr.trial_metrics.fit_quality(model) → dict

R-squared and the information criteria, when the model reports them.

Parameters:

model – fitted model result object, or None.

The supported model families do not agree on which statistics exist. An RLM fit has no R-squared, a penalised model’s value is not comparable to OLS’s, and a permutation test has no model object at all. A statistic the model does not report, or that is not finite, is left out of the returned dict (NaN in the sweep table) rather than estimated.

spacr.trial_metrics.guide_support_summary(results: pandas.DataFrame, alpha: float = 0.05) → dict

How many of the hits rest on a single guide.

Parameters:

results – guide-level result table used to compute gene support.

A gene with one surviving guide has a gene-level p identical to that guide’s, so it is not independent evidence. The row records n_single_guide_hits among the gene hits at alpha, together with the discordant-hit count and the median guides per hit.

spacr.trial_metrics.hit_counts(output: Mapping[str, Any], alpha: float = 0.05) → dict

Count the trial’s result rows and hits, by raw and adjusted p-value.

Parameters:

output – trial output carrying result and significant-hit frames.

spacr.trial_metrics.qc_verdicts(row: Mapping[str, Any]) → dict

Summarize design and inference diagnostics for one sweep trial.

Parameters:

row (mapping) – Trial metrics produced by summarise_trial(). Design scoring uses well, parameter, rank, and condition-number fields. Inference scoring uses the result count and genomic-inflation estimate.

Returns:

dict – Available qc_design and qc_inference levels, plus qc_verdict containing the more severe available level. A diagnostic is omitted when its required metrics are unavailable.

Notes

The overall verdict is intentionally the worst available diagnostic rather than a pass rate. This prevents a severe identifiability or calibration problem from being hidden by otherwise acceptable checks.

spacr.trial_metrics.residual_diagnostics(model) → dict

Homoscedasticity, autocorrelation and normality of the residuals.

Parameters:

model – fitted model result object, or None.

These are what decide whether the p-values mean anything. A funnel in the residuals inflates or deflates every standard error in the fit, so a heteroscedastic model can rank genes plausibly and still be wrong about all of them.

spacr.trial_metrics.summarise_trial(output: Mapping[str, Any], settings: Mapping[str, Any]) → dict

Return every metric for one trial as a flat dict for its sweep row.

Parameters:

• output – completed trial output with results, model, and fitted data.

• settings – trial settings used for thresholds and control recovery.

Each block is guarded on its own: a family with no R-squared must still contribute its control recovery, and a design too wide for White’s test must still contribute its residual trend. One missing statistic is a NaN in one column, never a lost row.