qbiocode.visualization.visualize_correlation module#

Correlation analysis and publication-quality figures for QProfiler results.

Summary#

Classes:

CorrelationFigures

The three figures plot_results_correlation() produces.

Functions:

`compute_results_correlation`	This function takes in as input a Pandas Dataframe containing the results and data evaluations for a given dataset.
`plot_results_correlation`	Plot publication-quality correlation figures from a `correlations_df`.
`publication_style`	Return a copy of `PUBLICATION_STYLE` for use as a matplotlib style.

Reference#

PUBLICATION_STYLE = {'axes.grid': False, 'axes.labelsize': 12, 'axes.linewidth': 1.2, 'axes.spines.right': False, 'axes.spines.top': False, 'axes.titlesize': 13, 'figure.titlesize': 13, 'font.family': 'sans-serif', 'font.sans-serif': ['Arial', 'DejaVu Sans', 'Helvetica', 'Liberation Sans'], 'font.size': 11, 'grid.alpha': 0.3, 'grid.linestyle': '--', 'grid.linewidth': 0.5, 'legend.fontsize': 10, 'savefig.bbox': 'tight', 'savefig.dpi': 600, 'savefig.pad_inches': 0.05, 'xtick.labelsize': 10, 'xtick.major.size': 5, 'xtick.major.width': 1.2, 'xtick.minor.size': 3, 'xtick.minor.width': 0.8, 'ytick.labelsize': 10, 'ytick.major.size': 5, 'ytick.major.width': 1.2, 'ytick.minor.size': 3, 'ytick.minor.width': 0.8}#

Publication defaults for scientific journals, applied per figure through matplotlib.pyplot.rc_context().

These were previously assigned straight into plt.rcParams at module scope, so import qbiocode – which imports this module transitively – silently reconfigured the importing program’s matplotlib: font family, tick geometry, spine visibility and a 600-dpi savefig default leaked into every unrelated figure the caller drew afterwards, with nothing in the traceback or the call stack to attribute it to. Call publication_style() to opt in globally.

class CorrelationFigures(scatter: Figure, scatter_ax: Axes, clustered_heatmap: sns.matrix.ClusterGrid, ordered_heatmap: sns.matrix.ClusterGrid)[source]#

Bases: NamedTuple

The three figures plot_results_correlation() produces.

Returned so a caller can compose, restyle or save them without re-running the computation, and so a notebook can display exactly the one it wants. Every figure is closed before the function returns – a Figure object stays fully usable after plt.close, including fig.savefig and Jupyter’s inline display, it is only removed from pyplot’s global figure manager. That is what keeps figures from accumulating when QProfiler calls this once per iteration.

scatter: Figure#: Alias for field number 0

scatter_ax: Axes#: Alias for field number 1

clustered_heatmap: ClusterGrid#: Alias for field number 2

ordered_heatmap: ClusterGrid#: Alias for field number 3

publication_style()[source]#

Return a copy of PUBLICATION_STYLE for use as a matplotlib style.

The plotting functions here apply it per figure, so callers need this only to style figures of their own:

import matplotlib.pyplot as plt
import qbiocode as qbc

with plt.rc_context(qbc.visualization.publication_style()):
    fig, ax = plt.subplots()

Mutating the returned dict does not affect the module default.

Return type:: dict

compute_results_correlation(results_df, correlation='spearman', thresh=0.7)[source]#

This function takes in as input a Pandas Dataframe containing the results and data evaluations for a given dataset. It then produces a spearman correlation between the data evaluation characteristics (features) and instances where an F1 score was observed above a certain threshold (thresh). The function returns the input DataFrame with additional columns for datatype and model_embed_datatype, as well as a new DataFrame containing the computed correlations between metrics and features. The correlation is computed for each model-embedding-dataset combination, and the results are aggregated. The features considered for correlation include various data characteristics such as ‘Feature_Samples_ratio’, ‘Intrinsic_Dimension’, etc. The metrics considered for correlation include ‘accuracy’, ‘f1_score’, ‘time’, and ‘auc’. The function also calculates the median metric value and the fraction of instances above the specified threshold for each combination. The resulting DataFrame contains the model-embedding-dataset, metric, feature, median metric value, fraction above threshold, and the computed correlation. This function is useful for understanding how different data characteristics relate to model performance metrics, particularly in the context of machine learning models applied to datasets.

Parameters:

results_df (pd.DataFrame) – A DataFrame containing the results and data evaluations.
correlation (str) – The type of correlation to compute, default is ‘spearman’.
thresh (float) – The threshold for F1 score to consider, default is 0.7.

Returns:

The input DataFrame with additional columns for datatype and model_embed_datatype. correlations_df (pd.DataFrame): A DataFrame containing the computed correlations between metrics and features.

Return type:

results_df (pd.DataFrame)

plot_results_correlation(correlations_df, metric='f1_score', title='', correlation_type='Spearman ρ', figsize=(6.5, 10), save_file_path='', size='median_metric', xticks=True, key='model_embed_datatype', legend_offset=1.0, show_plots=True, colorbar_label='Correlation coefficient', size_label='Median metric value')[source]#

Plot publication-quality correlation figures from a correlations_df.

Draws three figures from the frame produced by compute_results_correlation(): a dot plot, a row/column-clustered heatmap, and a heatmap with quantum models ordered first. In the dot plot the larger the circle, the higher the metric value for that data set; circle colour is the correlation between the data characteristic and the metric – red positive, blue anti-correlated, darker meaning stronger.

Parameters:

correlations_df (pd.DataFrame) – A DataFrame containing the computed correlations between metrics and features.
metric (str) – The metric to plot, default is ‘f1_score’.
title (str) – The title of the plot, default is an empty string.
correlation_type (str) – The type of correlation to display in the legend, default is ‘Spearman ρ’.
figsize (tuple) – The size of the dot-plot figure; the heatmaps are scaled from it.
save_file_path (str) – Where to write the dot plot. The two heatmaps are written alongside it with _heatmap and _noncluster_heatmap inserted before the extension, so any image format works and the three never collide. Nothing is written when this is "".
size (str) – The column name to use for the size of the dots, default is ‘median_metric’.
xticks (bool) – Whether to label the heatmap x-axis.
key (str) – Column identifying each model/embedding/datatype combination.
legend_offset (float) – Horizontal offset of the size legend.
show_plots (bool) – Whether to call plt.show(). Default True for notebook use; it is a no-op under a non-interactive backend or with no display, so a headless or batch run neither blocks nor warns.
colorbar_label (str) – Label for the colorbar, default is ‘Correlation coefficient’.
size_label (str) – Label for the size legend, default is ‘Median metric value’.

Returns:

the three figures, as (scatter, scatter_ax, clustered_heatmap, ordered_heatmap). All are already closed – pyplot no longer tracks them, which is what stops figures accumulating across QProfiler’s iterations – but each remains usable for fig.savefig(...) or inline display.

Return type:

CorrelationFigures

Notes

PUBLICATION_STYLE is applied for the duration of this call only, via plt.rc_context, and is restored even if plotting raises. The caller’s plt.rcParams are never modified; use publication_style() to adopt the same settings deliberately.