proteobench.score.entrapmentscores module#

Module containing plasma quantification score calculators (PYE - Plasma Year Edition).

class proteobench.score.entrapmentscores.EntrapmentScores[source]#

Bases: ScoreBase

Class for computing entrapment scores for entrapment benchmarking.

This class inherits from ScoreBase and extends it with entrapment metrics and calculations.

Parameters:: precursor_column_name (str) – Name of the precursor column.

calculate_fdp_at_fdr_thresholds(df: DataFrame, n_intervals: int = 10) → Dict[float, Dict[str, float]][source]#

Compute lower-bound, combined, and paired FDP at Q-value thresholds.

Thresholds are the union of n_intervals evenly-spaced values from max_q / n_intervals to max_q and the fixed set {0.001, 0.01, 0.05, 0.1, 1.0} capped at max_q. The mapping file is loaded once and the pair-index merge is performed once; only the Q-value filter varies per step.

Parameters:

df (pd.DataFrame) – Intermediate DataFrame produced by generate_intermediate and produced by generate_intermediate.
n_intervals (int) – Number of evenly-spaced thresholds. Defaults to 10.

Returns:

Mapping of {threshold: {lower_bound_FDP, combined_FDP, paired_FDP, nr_id_features}}. Thresholds where no targets are identified are omitted.

Return type:

Dict[float, Dict[str, float]]

static calculate_lower_bound_fdp(df: DataFrame) → Dict[int, float][source]#

Compute the lower bound false discovery proportion (FDP) for the given DataFrame.

Parameters:: df (pd.DataFrame) – DataFrame containing the intermediate file for which to compute the lower bound FDP.
Returns:: The computed lower bound FDP value.
Return type:: Float

calculate_metrics(df: DataFrame) → Dict[str, float][source]#

Handle the calculation of all entrapment metrics for the given DataFrame.

The input df must already contain "Target or Entrapment" and "peptide_pair_index" columns (populated by the benchmarking module).

Parameters:: df (pd.DataFrame) – Intermediate DataFrame produced by generate_intermediate.
Returns:: A dictionary containing all computed metric values.
Return type:: Dict[str, float]

static calculate_paired_fdp(df: DataFrame) → float[source]#

Compute the paired false discovery proportion (FDP) for the given DataFrame.

Requires peptide_pair_index to already be present in df (populated by the benchmarking module when applying the mapping file).

Parameters:: df (pd.DataFrame) – Intermediate DataFrame with peptide_pair_index already present.
Returns:: The computed paired FDP value.
Return type:: float

static calculate_reported_fdr(df: DataFrame, score_col: str = 'Q-Value') → float[source]#

Estimate the FDR threshold applied by the search engine from the output data.

The reported FDR is inferred as the maximum score value in the DataFrame for the given score column. For Q-value-based outputs this equals the least significant accepted Q-value, which corresponds to the FDR cutoff the search engine applied. The score_col parameter makes the method applicable to different entrapment levels: use "Q-Value" for PSM/precursor level, or the appropriate column name for peptide- or protein-level outputs.

Parameters:

df (pd.DataFrame) – DataFrame containing the intermediate data for one entrapment run. Must contain the column specified by score_col.
score_col (str, optional) – Name of the Q-value (or equivalent score) column. Defaults to "Q-Value".

Returns:

The maximum value found in score_col, interpreted as the applied FDR threshold.

Return type:

float

static calculate_upper_bound_combined_fdp(df: DataFrame) → Dict[int, float][source]#

Compute the false discovery proportion (FDP) for the given DataFrame.

Parameters:: df (pd.DataFrame) – DataFrame containing the intermediate file for which to compute the FDP.
Returns:: The computed FDP value.
Return type:: Float

static categorise_metric(lower_bound: float, upper_bound: float, fdr: float) → str[source]#

Categorise the FDR into: valid: Upper bound lower than reported FDR invalid: Lower bound higher than reported FDR inconclusive: Lower bound lower than reported FDR but upper bound higher than reported FDR

Parameters:

lower_bound (float) – The lower bound for categorisation.
upper_bound (float) – The upper bound for categorisation.
fdr (float) – The false discovery rate for categorisation.

Returns:

The category of the metric value (“valid”, “invalid”, or “inconclusive”).

Return type:

str

generate_intermediate(filtered_df: DataFrame) → DataFrame[source]#

Generate intermediate data structure for entrapment scores.

The input DataFrame must already have "Target or Entrapment" and "peptide_pair_index" columns populated by the caller (i.e. the benchmarking module applies the mapping file before this step).

Parameters:: filtered_df (pd.DataFrame) – DataFrame containing the filtered data with target/entrapment labels and peptide pair indices already assigned.
Returns:: DataFrame containing the intermediate data structure.
Return type:: pd.DataFrame