Edit on GitHub

starplast.prioritization

Transparent candidate explanations and experiment-budget prioritization.

Predictions remain hypotheses. Expected value uses explicit user benefits/costs; uncertainty-driven exploration is reported separately from success probability. Explanations use only the final model's fitting neighbours for unknown genes; held-out rows retain their own evaluation meaning. Measured screen imports keep unresolved identifiers and missing values, so a comparison cannot silently turn unassayed genes into negative measurements.

def explain_candidates(result, nodes, limit=50):

Explain supported unknown-gene calls with observed sources and training neighbours.

Linear contributions describe the fitted model's logits before temperature scaling. For nonlinear models, neighbours provide context rather than causal feature attributions. Held-out evaluation rows are never explained using the final refit, which has seen their labels.

def prioritize( candidates, budget, probability_column='score', cost_column='cost', benefit_column='benefit', group_column=None, exploration_weight=0.0):

Select a greedy budget-constrained list, at most one candidate per supplied group.

Utility is p*benefit + exploration_weight*4*p*(1-p) per cost. This heuristic is not an optimal knapsack solver. Probabilities should come from separately calibrated predictions; score rankings alone must not be passed as probabilities. Missing cost/benefit defaults to one and is recorded in the output.

def compare_screen(nodes, screen, value_column, gene_column='gene_id'):

Join a measured screen to gene evidence without dropping unmapped identifiers.

Duplicate screen genes are refused so guide-level replicates are not silently averaged. Summarize guides in spaCR first, then import the gene-level effects.