ms2rescore.report

Functionality for analyzing and reporting MS²Rescore results, including reusable Plotly-based charts and HTML-report generation.

Generate report

Generate an HTML report with various QC charts for MS²Rescore results.

ms2rescore.report.generate.generate_report(output_path_prefix, data, output_file=None)

Generate the HTML report from an in-memory ReportData.

Parameters:

output_path_prefix (str) – Prefix of the MS²Rescore output file names, used to locate the log file and to derive the default report path. For example, if the output PSM file is /path/to/file.ms2rescore.tsv, the prefix is /path/to/file.ms2rescore.
data (ReportData) – Fully-populated report data. Build it with ReportData.from_run() (in-memory run) or ReportData.from_files() (standalone from output files).
output_file (Path | None) – Path to the output HTML file. Defaults to output_path_prefix + ".report.html".

Charts

Collection of Plotly-based charts for reporting results of MS²Rescore.

ms2rescore.report.charts.score_histogram(psms)

Plot histogram of scores for a single PSM dataset.

Parameters:: psms (PSMList | DataFrame) – PSMs to plot, as psm_utils.PSMList or pandas.DataFrame generated with psm_utils.PSMList.to_dataframe().
Return type:: Figure

ms2rescore.report.charts.pp_plot(psms)

Generate PP plot of target and decoy score distributions.

Parameters:: psms (PSMList | DataFrame) – PSMs to plot, as psm_utils.PSMList or pandas.DataFrame generated with psm_utils.PSMList.to_dataframe().
Return type:: Figure

ms2rescore.report.charts.fdr_plot(psms, fdr_thresholds=None, log=True)

Plot number of identifications in function of FDR threshold.

Parameters:

psms (PSMList | DataFrame) – PSMs to plot, as psm_utils.PSMList or pandas.DataFrame generated with psm_utils.PSMList.to_dataframe().
fdr_thresholds (list[float] | None) – List of FDR thresholds to draw as vertical lines.
log (bool) – Whether to plot the x-axis on a log scale. Defaults to True.

Return type:

Figure

ms2rescore.report.charts.feature_weights(feature_weights, color_discrete_map=None)

Plot bar chart of feature weights.

Parameters:

feature_weights (DataFrame) – Data frame with columns feature, feature_generator, and weight.
color_discrete_map (dict[str, str] | None) – Mapping of feature generator names to colors for plotting.

Return type:

Figure

ms2rescore.report.charts.feature_weights_by_generator(feature_weights, color_discrete_map=None)

Plot bar chart of feature weights, summed by feature generator.

Parameters:

feature_weights (DataFrame) – Data frame with columns “feature”, “feature_generator”, and “weight”.
color_discrete_map (dict[str, str] | None) – Mapping of feature generator names to colors for plotting.

Return type:

Figure

ms2rescore.report.charts.ms2pip_correlation(features, is_decoy, qvalue, color=None)

Plot MS²PIP correlation for target PSMs with q-value <= 0.01.

Parameters:

features (DataFrame) – Data frame with features. Must contain the column spec_pearson_norm.
is_decoy (Series | ndarray) – Boolean array indicating whether each PSM is a decoy.
qvalue (Series | ndarray) – Array of q-values for each PSM.
color (str | None) – Bar color. Defaults to the MS²PIP feature-generator color.

Return type:

Figure

ms2rescore.report.charts.calculate_feature_qvalues(features, is_decoy)

Calculate q-values and ECDF AUC for all rescoring features.

Q-values are calculated for each feature as if it was directly used PSM score. For each q-value distribution, the ECDF AUC is calculated as a measure of overall individual performance of the feature.

As it is not known whether higher or lower values are better for each feature, q-values are calculated for both the original and reversed scores. The q-values and ECDF AUC are returned for the calculation with the highest ECDF AUC.

Parameters:

features (DataFrame) – Data frame with features. Must contain the column spec_pearson_norm.
is_decoy (_Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Boolean array indicating whether each PSM is a decoy.

Returns:

feature_qvalues – Wide-form data frame with q-values for each feature.
feature_ecdf_auc – Long-form data frame with ECDF AUC for each feature.

Return type:

tuple[DataFrame, DataFrame]

ms2rescore.report.charts.feature_ecdf_auc_bar(feature_ecdf_auc, color_discrete_map=None)

Plot bar chart of feature q-value ECDF AUCs.

Parameters:

feature_ecdf_auc (DataFrame) – Data frame with columns feature, feature_generator, and ecdf_auc.
color_discrete_map (dict[str, str] | None) – Mapping of feature generator names to colors for plotting.

Return type:

Figure

ms2rescore.report.charts.rt_scatter(df, predicted_column='Predicted retention time', observed_column='Observed retention time', xaxis_label='Observed retention time', yaxis_label='Predicted retention time', plot_title='Predicted vs. observed retention times', marker_color=None)

Plot a scatter plot of the predicted vs. observed retention times.

Parameters:

df (pd.DataFrame) – Dataframe containing the predicted and observed retention times.
predicted_column (str, optional) – Name of the column containing the predicted retention times, by default Predicted retention time.
observed_column (str, optional) – Name of the column containing the observed retention times, by default Observed retention time.
xaxis_label (str, optional) – X-axis label, by default Observed retention time.
yaxis_label (str, optional) – Y-axis label, by default Predicted retention time.
plot_title (str, optional) – Scatter plot title, by default Predicted vs. observed retention times
marker_color (str, optional) – Color of the scatter points. Defaults to the Plotly template color. Pass the feature generator color to match the point color to the rest of the report.

Return type:

Figure

ms2rescore.report.charts.rt_distribution_baseline(df, predicted_column='Predicted retention time', observed_column='Observed retention time', highlight_color=None)

Plot a distribution plot of the relative mean absolute error of the current DeepLC performance compared to the baseline performance.

Parameters:

df (pd.DataFrame) – Dataframe containing the predicted and observed retention times.
predicted_column (str, optional) – Name of the column containing the predicted retention times, by default Predicted retention time.
observed_column (str, optional) – Name of the column containing the observed retention times, by default Observed retention time.
highlight_color (str, optional) – Color of the current-performance line. Defaults to the DeepLC feature-generator color.

Return type:

Figure

ms2rescore.report.charts.score_scatter_plot(before, after, fdr_threshold=0.01)

Plot PSM scores before and after rescoring, best-scoring candidate per spectrum.

Collapses before/after to one row per (run, spectrum_id) – the best-scoring candidate on each side, independently – before comparing. Under max_psm_rank_output > 1 either side can have multiple candidate rows per spectrum, and rescoring can legitimately promote a different peptidoform as a spectrum’s winner, so this is a spectrum-level comparison, not a peptidoform-level one.

Parameters:

before (RescoreResult) – Result of evaluating the PSMs’ pre-rescoring score with ristretto.
after (RescoreResult) – Result of rescoring the PSMs with ristretto.
fdr_threshold (float) – FDR threshold for drawing threshold lines.

Returns:

Plotly figure with score comparison.

Return type:

go.Figure

ms2rescore.report.charts.fdr_plot_comparison(before, after, fdr_threshold=0.01)

Plot number of identified spectra as a function of FDR threshold, before vs. after.

Collapses each of before/after independently to one row per (run, spectrum_id) – the best-scoring candidate – before counting, so a spectrum with multiple ambiguous candidate rows (max_psm_rank_output > 1) isn’t counted more than once.

Parameters:

before (RescoreResult) – Result of evaluating the PSMs’ pre-rescoring score with ristretto.
after (RescoreResult) – Result of rescoring the PSMs with ristretto.
fdr_threshold (float) – FDR threshold to draw as a reference line.

Returns:

Plotly figure with FDR comparison.

Return type:

go.Figure

ms2rescore.report.charts.identification_overlap(before, after, fdr_threshold=0.01)

Plot stacked bar charts of removed, retained, and gained IDs at each rollup level.

Compares ristretto’s own before/after rollup tables directly – spectrum, peptidoform, peptide, and (optionally) protein – rather than re-deriving sets from a merged per-PSM dataframe. The latter would only be correct at the peptidoform/peptide/protein level if every spectrum kept the same winning peptidoform between before and after, which is exactly what rescoring is expected to change for at least some spectra.

Parameters:

before (RescoreResult) – Result of evaluating the PSMs’ pre-rescoring score with ristretto.
after (RescoreResult) – Result of rescoring the PSMs with ristretto.
fdr_threshold (float) – FDR threshold for counting identifications.

Returns:

Plotly figure with identification overlap.

Return type:

go.Figure