coco_pipe.viz.decoding#

Static visualization helpers for decoding result tables.

Functions#

`plot_confusion_matrix`(result_or_matrix[, model, fold, ...])	Plot an aggregated confusion matrix from decoding diagnostics.
`plot_roc_curve`(result_or_curve[, model, fold, title, ...])	Plot receiver-operating-characteristic curves.
`plot_pr_curve`(result_or_curve[, model, fold, title, ...])	Plot precision-recall curves from decoding diagnostics.
`plot_calibration_curve`(result_or_curve[, model, fold, ...])	Plot calibration reliability curves.
`plot_fold_score_dispersion`(result_or_scores[, metric, ...])	Plot fold-level scalar score distributions by model and metric.
`plot_temporal_score_curve`(result_or_scores[, metric, ...])	Plot mean temporal decoding score curves.
`plot_temporal_generalization_matrix`(result_or_scores)	Plot a train-time by test-time temporal generalization matrix.
`plot_temporal_statistical_assessment`(result_or_assessment)	Plot temporal statistical assessment results.
`plot_null_interval_summary`(result_or_assessment[, ...])	Plot observed scalar scores against null interval summaries.
`plot_training_history`(result_or_artifacts[, model, ...])	Plot neural training-history artifacts.
`plot_decoding_scores`(result[, metric, model, kind, ...])	Plot aggregate scalar decoding scores by model and metric.
`plot_model_comparison`(result[, metric, reference, ...])	Plot model-comparison score differences.
`plot_fit_diagnostics`(result, *[, by, show_warnings, ...])	Plot fit-time diagnostics by model or fold.
`plot_probability_diagnostics`(result[, model, metric, ...])	Plot probability-quality diagnostics.
`plot_subject_diagnostics`(result[, unit, metric, ...])	Plot per-unit prediction accuracy diagnostics.
`plot_group_summary`(result[, group, metric, model, ...])	Plot group-level prediction accuracy summaries.
`plot_regression_diagnostics`(result[, model, fold, ...])	Plot regression prediction diagnostics.
`plot_search_results`(result[, model, top_n, ax, figsize])	Plot compact hyperparameter-search results.
`plot_feature_importance`(result[, model, top_n, ...])	Plot ranked feature importances.
`plot_feature_stability`(result[, model, top_n, kind, ...])	Plot feature-selection stability.
`plot_feature_scores`(result[, model, top_n, ...])	Plot univariate feature-selector scores.
`plot_decoding_topomap`(sensor_df, value[, info, ...])	Plot a topomap from sensor-level decoding values.
`plot_sensor_feature_heatmap`(result, feature_metadata)	Plot feature-family importance summarized by sensor.
`plot_sensor_feature_profile`(result, feature_metadata, ...)	Plot feature importances for one sensor.
`plot_feature_sensor_profile`(result, feature_metadata, ...)	Plot a sensor topomap for one feature family.
`plot_head_to_head`(frame, *, label, value[, error, ...])	Plot labelled estimates for cross-result head-to-head comparisons.
`plot_paired_delta`(frame, *, label, delta[, lower, ...])	Plot paired deltas with optional confidence intervals.

Module Contents#

coco_pipe.viz.decoding.plot_confusion_matrix(result_or_matrix, model=None, fold=None, title=None, ax=None, figsize=None)#

Plot an aggregated confusion matrix from decoding diagnostics.

Parameters:

result_or_matrix (Any) – Experiment result with get_confusion_matrices() or a tidy confusion matrix DataFrame containing TrueLabel, PredictedLabel, and Value.
model (str | None) – Optional model name used to filter rows before aggregation.
fold (int | None) – Optional fold index used to filter rows before aggregation.
title (str | None) – Optional axes title. Defaults to "Confusion Matrix".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when ax is not provided.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_confusion_matrix: Interactive Plotly version.
plot_roc_curve: Receiver-operating-characteristic curve.
plot_probability_diagnostics: Probability-calibration quality metrics.
plot_decoding_scores: Aggregate scalar score summary.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "TrueLabel": list("AABB"),
...         "PredictedLabel": list("ABAB"),
...         "Value": [5, 1, 2, 4],
...     }
... )
>>> fig, ax = viz.plot_confusion_matrix(df)

coco_pipe.viz.decoding.plot_roc_curve(result_or_curve, model=None, fold=None, title=None, ax=None, figsize=None, mean_only=False)#

Plot receiver-operating-characteristic curves.

Parameters:

result_or_curve (Any) – Experiment result with get_roc_curve() or a DataFrame containing Model, FPR, and TPR. Optional Fold and Class columns are used for grouping.
model (str | None) – Optional model name to display.
fold (int | None) – Optional fold index to display.
title (str | None) – Optional axes title. Defaults to "ROC Curve".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.
mean_only (bool) – If True, interpolate fold curves onto a common x-grid and draw the mean curve with a standard-deviation band.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_roc_curve: Interactive Plotly version.
plot_pr_curve: Precision-recall curve.
plot_calibration_curve: Probability calibration reliability curve.
plot_confusion_matrix: Predicted-vs-true class heatmap.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": "SVM",
...         "FPR": np.linspace(0, 1, 10),
...         "TPR": np.linspace(0, 1, 10) ** 0.5,
...     }
... )
>>> fig, ax = viz.plot_roc_curve(df)

coco_pipe.viz.decoding.plot_pr_curve(result_or_curve, model=None, fold=None, title=None, ax=None, figsize=None, mean_only=False)#

Plot precision-recall curves from decoding diagnostics.

Parameters:

result_or_curve (Any) – Experiment result with get_pr_curve() or a DataFrame containing Model, Recall, and Precision. Optional Fold and Class columns are used for grouping.
model (str | None) – Optional model name to display.
fold (int | None) – Optional fold index to display.
title (str | None) – Optional axes title. Defaults to "Precision-Recall Curve".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.
mean_only (bool) – If True, interpolate fold curves onto a common recall grid and draw the mean curve with a standard-deviation band.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_pr_curve: Interactive Plotly version.
plot_roc_curve: Receiver-operating-characteristic curve.
plot_calibration_curve: Probability calibration reliability curve.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": "SVM",
...         "Recall": np.linspace(0, 1, 10),
...         "Precision": np.linspace(1, 0.5, 10),
...     }
... )
>>> fig, ax = viz.plot_pr_curve(df)

coco_pipe.viz.decoding.plot_calibration_curve(result_or_curve, model=None, fold=None, title=None, ax=None, figsize=None, mean_only=False)#

Plot calibration reliability curves.

Parameters:

result_or_curve (Any) – Experiment result with get_calibration_curve() or a DataFrame containing Model, MeanPredictedProbability, and FractionPositive.
model (str | None) – Optional model name to display.
fold (int | None) – Optional fold index to display.
title (str | None) – Optional axes title. Defaults to "Calibration Curve".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.
mean_only (bool) – If True, interpolate fold curves onto a common probability grid and draw the mean curve with a standard-deviation band.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_calibration_curve: Interactive Plotly version.
plot_roc_curve: Receiver-operating-characteristic curve.
plot_pr_curve: Precision-recall curve.
plot_probability_diagnostics: Scalar probability-quality metrics.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": "SVM",
...         "MeanPredictedProbability": np.linspace(0, 1, 10),
...         "FractionPositive": np.linspace(0.05, 0.95, 10),
...     }
... )
>>> fig, ax = viz.plot_calibration_curve(df)

coco_pipe.viz.decoding.plot_fold_score_dispersion(result_or_scores, metric=None, model=None, title=None, ax=None, figsize=None)#

Plot fold-level scalar score distributions by model and metric.

Parameters:

result_or_scores (Any) – Experiment result with get_detailed_scores() or a detailed score DataFrame containing scalar Value rows.
metric (str | None) – Optional metric name used to filter scores.
model (str | None) – Optional model name used to filter scores.
title (str | None) – Optional axes title. Defaults to "Fold Score Dispersion".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_fold_score_dispersion: Interactive Plotly version.
plot_decoding_scores: Aggregate score summary with error bars.
plot_model_comparison: Pairwise score-difference plot.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": "SVM",
...         "Fold": [0, 1, 2, 3, 4],
...         "Metric": "accuracy",
...         "Value": [0.82, 0.79, 0.85, 0.81, 0.83],
...     }
... )
>>> fig, ax = viz.plot_fold_score_dispersion(df)

coco_pipe.viz.decoding.plot_temporal_score_curve(result_or_scores, metric=None, model=None, title=None, ax=None, figsize=None, smooth_window=None)#

Plot mean temporal decoding score curves.

Parameters:

result_or_scores (Any) – Experiment result with get_temporal_score_summary() or a DataFrame containing Model, Metric, Time, and Mean.
metric (str | None) – Optional metric name used to filter temporal scores.
model (str | None) – Optional model name used to filter temporal scores.
title (str | None) – Optional axes title. Defaults to "Temporal Decoding Value".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.
smooth_window (int | None)

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

Notes

Non-numeric time labels are plotted at integer positions and displayed as rotated tick labels.

See also

coco_pipe.viz.interactive.decoding.plot_temporal_score_curve: Interactive Plotly version.
plot_temporal_generalization_matrix: Train-time x test-time heatmap.
plot_temporal_statistical_assessment: Temporal curve with permutation null band.
plot_null_interval_summary: Scalar null-interval summary per model.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> t = np.linspace(0, 0.5, 10)
>>> df = pd.DataFrame(
...     {
...         "Model": "SVM",
...         "Metric": "accuracy",
...         "Time": t,
...         "Mean": 0.5 + 0.1 * np.arange(10) / 10,
...     }
... )
>>> fig, ax = viz.plot_temporal_score_curve(df)

coco_pipe.viz.decoding.plot_temporal_generalization_matrix(result_or_scores, metric=None, model=None, title=None, ax=None, figsize=None)#

Plot a train-time by test-time temporal generalization matrix.

Parameters:

result_or_scores (Any) – Experiment result with get_temporal_score_summary() or a DataFrame containing Model, Metric, TrainTime, TestTime, and Mean.
metric (str | None) – Optional metric name. A single model/metric pair must remain after filtering.
model (str | None) – Optional model name. A single model/metric pair must remain after filtering.
title (str | None) – Optional axes title. Defaults to "<model> / <metric>".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_temporal_generalization_matrix: Interactive Plotly version.
plot_temporal_score_curve: Mean temporal score curve over time.
plot_temporal_statistical_assessment: Temporal curve with permutation null band.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> times = np.linspace(0, 0.5, 5)
>>> rows = [
...     {
...         "Model": "SVM",
...         "Metric": "accuracy",
...         "TrainTime": t1,
...         "TestTime": t2,
...         "Mean": 0.7,
...     }
...     for t1 in times
...     for t2 in times
... ]
>>> fig, ax = viz.plot_temporal_generalization_matrix(pd.DataFrame(rows))

coco_pipe.viz.decoding.plot_temporal_statistical_assessment(result_or_assessment, metric=None, model=None, title=None, ax=None, figsize=None)#

Plot temporal statistical assessment results.

Parameters:

result_or_assessment (Any) – Experiment result with get_statistical_assessment() or an assessment DataFrame containing Model, Metric, Observed, and Time.
metric (str | None) – Optional metric name. A single model/metric pair must remain after filtering.
model (str | None) – Optional model name. A single model/metric pair must remain after filtering.
title (str | None) – Optional axes title. Defaults to a model/metric statistical-assessment title.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

Notes

NullLower and NullUpper are rendered as a null band when present. Significant rows are overlaid as square markers.

See also

coco_pipe.viz.interactive.decoding.plot_temporal_statistical_assessment: Interactive Plotly version.
plot_temporal_score_curve: Mean temporal score curve over time.
plot_null_interval_summary: Scalar null-interval summary per model.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> rng = np.random.default_rng(42)
>>> t = np.linspace(0, 0.5, 10)
>>> df = pd.DataFrame(
...     {
...         "Model": "SVM",
...         "Metric": "accuracy",
...         "Time": t,
...         "Observed": 0.5 + 0.1 * rng.normal(size=10),
...     }
... )
>>> fig, ax = viz.plot_temporal_statistical_assessment(df)

coco_pipe.viz.decoding.plot_null_interval_summary(result_or_assessment, metric=None, model=None, title=None, ax=None, figsize=None)#

Plot observed scalar scores against null interval summaries.

Parameters:

result_or_assessment (Any) – Experiment result with get_statistical_assessment() or an assessment DataFrame containing Model, Metric, and Observed.
metric (str | None) – Optional metric name used to filter assessment rows.
model (str | None) – Optional model name used to filter assessment rows.
title (str | None) – Optional axes title. Defaults to "Null Interval Summary".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

Notes

NullLower/NullUpper are drawn as error intervals around their midpoint. NullMedian is shown as an optional marker series.

See also

coco_pipe.viz.interactive.decoding.plot_null_interval_summary: Interactive Plotly version.
plot_temporal_statistical_assessment: Significance-annotated temporal heatmap.
plot_decoding_scores: Aggregate scalar score summary.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM", "SVM"],
...         "Metric": ["accuracy", "accuracy"],
...         "Observed": [0.72, 0.68],
...         "NullLower": [0.45, 0.44],
...         "NullUpper": [0.55, 0.54],
...     }
... )
>>> fig, ax = viz.plot_null_interval_summary(df)

coco_pipe.viz.decoding.plot_training_history(result_or_artifacts, model=None, title=None, ax=None, figsize=None)#

Plot neural training-history artifacts.

Parameters:

result_or_artifacts (Any) – Experiment result with get_model_artifacts() or an artifact DataFrame containing Model, Key, ArtifactType, and Value. History values are expected to be records keyed by epoch and metric names.
model (str | None) – Optional model name used to filter artifacts.
title (str | None) – Optional axes title. Defaults to "Training History".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_training_history: Interactive Plotly version.
plot_fit_diagnostics: Fit-time diagnostics by model or fold.
plot_decoding_scores: Aggregate scalar score summary.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> history = {
...     "epoch": [1, 2, 3],
...     "loss": [0.9, 0.7, 0.5],
...     "val_loss": [1.0, 0.8, 0.65],
... }
>>> df = pd.DataFrame(
...     {
...         "Model": ["DNN"],
...         "Key": ["history"],
...         "ArtifactType": ["training_history"],
...         "Value": [history],
...     }
... )
>>> fig, ax = viz.plot_training_history(df)

coco_pipe.viz.decoding.plot_decoding_scores(result, metric=None, model=None, kind='point', aggregate='mean', ax=None, figsize=None)#

Plot aggregate scalar decoding scores by model and metric.

Parameters:

result (Any) – Experiment result with get_detailed_scores() or a detailed score DataFrame containing scalar Value rows.
metric (str | None) – Optional metric name used to filter scores.
model (str | None) – Optional model name used to filter scores.
kind (Literal['point', 'bar', 'box']) – Plot type: "point" for aggregate +/- SEM, "bar" for bar summaries, or "box" for fold-level distributions.
aggregate (Literal['mean', 'median']) – Summary statistic used by "point" and "bar" plots.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_decoding_scores: Interactive Plotly version.
plot_model_comparison: Score differences between model pairs.
plot_fold_score_dispersion: Per-fold score spread.
plot_null_interval_summary: Observed scores versus null bands.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM"] * 5,
...         "Metric": ["accuracy"] * 5,
...         "Type": ["detailed_score"] * 5,
...         "Value": [0.71, 0.73, 0.69, 0.74, 0.70],
...     }
... )
>>> fig, ax = viz.plot_decoding_scores(df)

coco_pipe.viz.decoding.plot_model_comparison(result, metric='accuracy', reference=None, paired=True, ax=None, figsize=None)#

Plot model-comparison score differences.

Parameters:

result (Any) – Experiment result or a comparison DataFrame. DataFrames must contain a Difference column and may include ModelA, ModelB, CILower, and CIUpper.
metric (str) – Metric used when computing comparisons from an experiment result.
reference (str | None) – Optional reference model. When provided with paired=True, all other models are compared against this model.
paired (bool) – If True and reference is provided, use compare_models_paired. Otherwise use compare_models when available. Results with only detailed scores fall back to mean-score differences.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_model_comparison: Interactive Plotly version.
plot_decoding_scores: Aggregate scalar score summary.
plot_fold_score_dispersion: Per-fold score spread.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "ModelA": ["SVM", "SVM"],
...         "ModelB": ["LDA", "RF"],
...         "Difference": [0.05, -0.02],
...         "CILower": [0.01, -0.06],
...         "CIUpper": [0.09, 0.02],
...     }
... )
>>> fig, ax = viz.plot_model_comparison(df)

coco_pipe.viz.decoding.plot_fit_diagnostics(result, *, by='Model', show_warnings=True, kind='bar', ax=None, figsize=None)#

Plot fit-time diagnostics by model or fold.

Parameters:

result (Any) – Experiment result with get_fit_diagnostics() or a diagnostics DataFrame containing TotalTime plus the selected by column.
by (Literal['Model', 'Fold']) – Column used for grouping, usually "Model" or "Fold".
show_warnings (bool) – If True, annotate the plot with the number of non-null WarningMessage entries when present.
kind (Literal['bar', 'box']) – Plot type: "bar" for mean total time or "box" for grouped total-time distributions.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_fit_diagnostics: Interactive Plotly version.
plot_training_history: Neural training-history artifacts.
plot_decoding_scores: Aggregate scalar score summary.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM", "SVM", "LDA", "LDA"],
...         "Fold": [0, 1, 0, 1],
...         "TotalTime": [1.2, 1.3, 0.5, 0.6],
...     }
... )
>>> fig, ax = viz.plot_fit_diagnostics(df)

coco_pipe.viz.decoding.plot_probability_diagnostics(result, model=None, metric=None, ax=None, figsize=None)#

Plot probability-quality diagnostics.

Parameters:

result (Any) – Experiment result with get_probability_diagnostics() or a DataFrame containing Model, Metric, and Value.
model (str | None) – Optional model name used to filter diagnostics.
metric (str | None) – Optional diagnostic metric used to filter rows.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_probability_diagnostics: Interactive Plotly version.
plot_calibration_curve: Calibration curve for probability estimates.
plot_confusion_matrix: Aggregated confusion matrix.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM", "SVM"],
...         "Metric": ["brier_score", "log_loss"],
...         "Value": [0.18, 0.42],
...     }
... )
>>> fig, ax = viz.plot_probability_diagnostics(df)

coco_pipe.viz.decoding.plot_subject_diagnostics(result, unit='Subject', metric='accuracy', model=None, kind='strip', ax=None, figsize=None)#

Plot per-unit prediction accuracy diagnostics.

Parameters:

result (Any) – Experiment result with get_predictions() or a prediction DataFrame containing Model, y_true, y_pred, and the selected unit column.
unit (str) – Metadata column used as the unit of aggregation, such as "Subject".
metric (str) – Metric to compute. Currently only "accuracy" is supported.
model (str | None) – Optional model name used to filter predictions.
kind (Literal['strip', 'dot', 'caterpillar']) – Plot type. "strip" and "dot" show one point per unit grouped by model. "caterpillar" shows sorted unit scores with horizontal stems.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_subject_diagnostics: Interactive Plotly version.
plot_group_summary: Group-level accuracy summaries.
plot_decoding_scores: Aggregate scalar score summary.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM"] * 6,
...         "Subject": ["S1", "S1", "S2", "S2", "S3", "S3"],
...         "Fold": [0, 1, 0, 1, 0, 1],
...         "y_true": [0, 1, 1, 0, 0, 1],
...         "y_pred": [0, 1, 0, 0, 0, 1],
...     }
... )
>>> fig, ax = viz.plot_subject_diagnostics(df)

coco_pipe.viz.decoding.plot_group_summary(result, group='Group', metric='accuracy', model=None, kind='point', ax=None, figsize=None)#

Plot group-level prediction accuracy summaries.

Parameters:

result (Any) – Experiment result with get_predictions() or a prediction DataFrame containing Model, Fold, y_true, y_pred, and the selected grouping column.
group (str) – Prediction metadata column used to define groups.
metric (str) – Metric to compute. Currently only "accuracy" is supported.
model (str | None) – Optional model name used to filter predictions.
kind (Literal['point', 'violin']) – Plot type: "point" for mean +/- SEM or "violin" for fold-level distributions.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_group_summary: Interactive Plotly version.
plot_subject_diagnostics: Per-subject accuracy diagnostics.
plot_decoding_scores: Aggregate scalar score summary.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM"] * 8,
...         "Group": ["A"] * 4 + ["B"] * 4,
...         "Fold": [0, 1, 2, 3] * 2,
...         "y_true": [0, 1, 1, 0, 0, 1, 0, 1],
...         "y_pred": [0, 1, 0, 0, 0, 1, 0, 1],
...     }
... )
>>> fig, ax = viz.plot_group_summary(df)

coco_pipe.viz.decoding.plot_regression_diagnostics(result, model=None, fold=None, kind='scatter', ax=None, figsize=None)#

Plot regression prediction diagnostics.

Parameters:

result (Any) – Experiment result with get_predictions() or a prediction DataFrame containing numeric y_true and y_pred columns.
model (str | None) – Optional model name used to filter predictions.
fold (int | None) – Optional fold index used to filter predictions.
kind (Literal['scatter', 'residual', 'bin']) – Plot type: "scatter" for observed vs predicted, "residual" for residuals vs predicted, or "bin" for binned mean residuals.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_regression_diagnostics: Interactive Plotly version.
plot_decoding_scores: Aggregate scalar score summary.
plot_confusion_matrix: Classification confusion matrix.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> rng = np.random.default_rng(42)
>>> y = rng.standard_normal(40)
>>> df = pd.DataFrame(
...     {"Model": "Ridge", "y_true": y, "y_pred": y + 0.1 * rng.standard_normal(40)}
... )
>>> fig, ax = viz.plot_regression_diagnostics(df)

coco_pipe.viz.decoding.plot_search_results(result, model=None, top_n=None, ax=None, figsize=None)#

Plot compact hyperparameter-search results.

Parameters:

result (Any) – Experiment result with get_search_results() or a search-results DataFrame containing Model, Rank, and MeanTestScore.
model (str | None) – Optional model name used to filter search rows.
top_n (int | None) – Optional positive number of top-ranked candidates to keep per model.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_search_results: Interactive Plotly version.
plot_model_comparison: Score differences between model pairs.
plot_decoding_scores: Aggregate scalar score summary.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM"] * 3,
...         "Rank": [1, 2, 3],
...         "MeanTestScore": [0.80, 0.78, 0.75],
...     }
... )
>>> fig, ax = viz.plot_search_results(df)

coco_pipe.viz.decoding.plot_feature_importance(result, model=None, top_n=25, signed=False, absolute=False, ax=None, figsize=None, title=None)#

Plot ranked feature importances.

Parameters:

result (Any) – Experiment result with get_feature_importances(), a feature importance DataFrame, or a mapping/sequence coercible to a numeric Series. Non-numeric sequences are delegated to the dimensionality reduction feature-importance plot.
model (str | None) – Optional model name used to filter importances.
top_n (int | None) – Optional number of highest-magnitude features to display.
signed (bool) – If True, use a diverging palette when plotting signed values.
absolute (bool) – If True, rank and display absolute importance values.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.
title (str | None) – Optional axes title. Defaults to "Feature Importance".

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_feature_importance: Interactive Plotly version.
plot_feature_stability: Feature-selection stability across folds.
plot_feature_scores: Univariate feature-selector scores.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM"] * 4,
...         "FeatureName": ["f1", "f2", "f3", "f4"],
...         "Mean": [0.5, 0.3, 0.15, 0.05],
...     }
... )
>>> fig, ax = viz.plot_feature_importance(df)

coco_pipe.viz.decoding.plot_feature_stability(result, model=None, top_n=25, kind='bar', ax=None, figsize=None)#

Plot feature-selection stability.

Parameters:

result (Any) – Experiment result or DataFrame. kind="bar" expects get_feature_stability() data with FeatureName and SelectionFrequency. kind="heatmap" first tries get_selected_features() data with Fold, FeatureName, and Selected.
model (str | None) – Optional model name used to filter feature rows.
top_n (int | None) – Optional number of most stable features to display.
kind (Literal['bar', 'heatmap']) – Plot type: "bar" for mean selection frequency or "heatmap" for fold-by-feature selected masks.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_feature_stability: Interactive Plotly version.
plot_feature_importance: Ranked feature importances.
plot_feature_scores: Univariate feature-selector scores.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM"] * 3,
...         "FeatureName": ["f1", "f2", "f3"],
...         "SelectionFrequency": [0.9, 0.6, 0.4],
...     }
... )
>>> fig, ax = viz.plot_feature_stability(df)

coco_pipe.viz.decoding.plot_feature_scores(result, model=None, top_n=25, show_pvalues=True, ax=None, figsize=None)#

Plot univariate feature-selector scores.

Parameters:

result (Any) – Experiment result with get_feature_scores() or a feature-score DataFrame containing FeatureName and Score.
model (str | None) – Optional model name used to filter feature scores.
top_n (int | None) – Optional positive number of highest-scoring features to display.
show_pvalues (bool) – If True, annotate bars with CorrectedPValue when available, otherwise PValue.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

coco_pipe.viz.interactive.decoding.plot_feature_scores: Interactive Plotly version.
plot_feature_importance: Ranked feature importances.
plot_feature_stability: Feature-selection stability across folds.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> df = pd.DataFrame(
...     {
...         "Model": ["SVM"] * 4,
...         "FeatureName": ["f1", "f2", "f3", "f4"],
...         "Score": [12.3, 8.1, 5.4, 2.0],
...     }
... )
>>> fig, ax = viz.plot_feature_scores(df)

coco_pipe.viz.decoding.plot_decoding_topomap(sensor_df, value, info=None, coords=None, center=None, minimum_half_range=0.02, times=None, mask=None, title=None, ax=None, figsize=None)#

Plot a topomap from sensor-level decoding values.

Parameters:

sensor_df (pandas.DataFrame) – DataFrame containing FeatureName and the selected value column. FeatureName entries must match the provided sensor layout.
value (str) – Numeric column to aggregate and plot.
info – Optional MNE Info object used to resolve sensor positions.
coords – Optional coordinate table used to resolve sensor positions when info is not provided.
center (float | None) – Optional numeric center for diverging color limits. When provided, vmin and vmax are computed symmetrically around this value.
minimum_half_range (float) – Minimum distance from center to either color limit.
times (list[float] | None) – Optional list of time values used to filter rows when Time exists.
mask (numpy.ndarray | None) – Optional boolean mask applied after time filtering.
title (str | None) – Optional axes title. Defaults to the plotted value name.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

plot_sensor_feature_heatmap: Feature-family importance summarized by sensor.
plot_sensor_feature_profile: Feature importances for one sensor.
plot_feature_sensor_profile: Sensor topomap for one feature family.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> names = [f"EEG{i:03d}" for i in range(5)]
>>> df = pd.DataFrame(
...     {"FeatureName": names, "Importance": np.linspace(0.1, 0.9, 5)}
... )
>>> coords = pd.DataFrame(
...     {
...         "ch_name": names,
...         "x": np.cos(np.linspace(0, 2 * np.pi, 5, endpoint=False)),
...         "y": np.sin(np.linspace(0, 2 * np.pi, 5, endpoint=False)),
...     }
... )
>>> fig, ax = viz.plot_decoding_topomap(df, "Importance", coords=coords)

coco_pipe.viz.decoding.plot_sensor_feature_heatmap(result, feature_metadata, feature_group=None, sensor_order=None, agg='mean', ax=None, figsize=None)#

Plot feature-family importance summarized by sensor.

Parameters:

result (Any) – Experiment result with get_feature_importances() or a compatible feature-importance DataFrame.
feature_metadata (pandas.DataFrame) – Explicit metadata with FeatureName, Sensor, and FeatureFamily columns.
feature_group (str | None) – Optional feature family value used to filter rows. The parameter name is retained for compatibility; it matches FeatureFamily values.
sensor_order (list[str] | None) – Optional ordered list of sensors to display as columns.
agg (str) – Aggregation function passed to pandas.pivot_table.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

plot_decoding_topomap: Sensor topomap for a single score column.
plot_sensor_feature_profile: Feature importances for one sensor.
plot_feature_sensor_profile: Sensor topomap for one feature family.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> feat_meta = pd.DataFrame(
...     {
...         "FeatureName": ["f1", "f2", "f3", "f4"],
...         "Sensor": ["S1", "S1", "S2", "S2"],
...         "FeatureFamily": ["band1", "band2", "band1", "band2"],
...     }
... )
>>> importance = pd.DataFrame(
...     {"FeatureName": ["f1", "f2", "f3", "f4"], "Mean": [0.5, 0.3, 0.4, 0.2]}
... )
>>> fig, ax = viz.plot_sensor_feature_heatmap(importance, feat_meta)

coco_pipe.viz.decoding.plot_sensor_feature_profile(result, feature_metadata, sensor, model=None, ax=None, figsize=None)#

Plot feature importances for one sensor.

Parameters:

result (Any) – Experiment result with get_feature_importances() or a compatible feature-importance DataFrame.
feature_metadata (pandas.DataFrame) – Explicit metadata with FeatureName and Sensor columns.
sensor (str) – Sensor name used to select features.
model (str | None) – Optional model name used to filter importances.
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

plot_sensor_feature_heatmap: Feature-family importance summarized by sensor.
plot_feature_sensor_profile: Sensor topomap for one feature family.
plot_feature_importance: Ranked feature importances.

Examples

>>> import pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> feat_meta = pd.DataFrame(
...     {"FeatureName": ["f1", "f2", "f3"], "Sensor": ["S1", "S1", "S1"]}
... )
>>> importance = pd.DataFrame(
...     {"FeatureName": ["f1", "f2", "f3"], "Mean": [0.5, 0.3, 0.1]}
... )
>>> fig, ax = viz.plot_sensor_feature_profile(importance, feat_meta, sensor="S1")

coco_pipe.viz.decoding.plot_feature_sensor_profile(result, feature_metadata, feature_family, info=None, coords=None, model=None, title=None, ax=None, figsize=None)#

Plot a sensor topomap for one feature family.

Parameters:

result (Any) – Experiment result with get_feature_importances() or a compatible feature-importance DataFrame.
feature_metadata (pandas.DataFrame) – Explicit metadata with FeatureName, Sensor, and FeatureFamily columns.
feature_family (str) – Feature-family value to aggregate over sensors.
info – Optional MNE Info object used to resolve sensor positions.
coords – Optional coordinate table used to resolve sensor positions when info is not provided.
model (str | None) – Optional model name used to filter importances.
title (str | None) – Optional topomap title. Defaults to "<feature_family> Sensor Profile".
ax (matplotlib.pyplot.Axes | None) – Existing Matplotlib axes to draw into.
figsize (tuple[float, float] | None) – Figure size used when creating a new axes.

Returns:

The created or reused figure and axes.

Return type:

tuple[matplotlib.figure.Figure, matplotlib.axes.Axes]

See also

plot_sensor_feature_heatmap: Feature-family importance summarized by sensor.
plot_sensor_feature_profile: Feature importances for one sensor.
plot_decoding_topomap: Sensor topomap for a single score column.

Examples

>>> import numpy as np, pandas as pd
>>> from coco_pipe.viz import decoding as viz
>>> feat_meta = pd.DataFrame(
...     {
...         "FeatureName": ["f1", "f2"],
...         "Sensor": ["S1", "S2"],
...         "FeatureFamily": ["band1", "band1"],
...     }
... )
>>> importance = pd.DataFrame({"FeatureName": ["f1", "f2"], "Mean": [0.5, 0.3]})
>>> coords = pd.DataFrame(
...     {"ch_name": ["S1", "S2"], "x": [0.1, -0.1], "y": [0.1, -0.1]}
... )
>>> fig, ax = viz.plot_feature_sensor_profile(
...     importance, feat_meta, "band1", coords=coords
... )

coco_pipe.viz.decoding.plot_head_to_head(frame, *, label, value, error=None, reference=None, title='Head-to-Head Comparison', ylabel=None, ax=None, figsize=None)#

Plot labelled estimates for cross-result head-to-head comparisons.

Parameters:

frame (pandas.DataFrame)
label (str)
value (str)
error (str | None)
reference (float | None)
title (str)
ylabel (str | None)
ax (matplotlib.pyplot.Axes | None)
figsize (tuple[float, float] | None)

Return type:

tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

coco_pipe.viz.decoding.plot_paired_delta(frame, *, label, delta, lower=None, upper=None, title='Paired Difference', xlabel='Comparison', ylabel='Delta', ax=None, figsize=None)#

Plot paired deltas with optional confidence intervals.

Parameters:

frame (pandas.DataFrame)
label (str)
delta (str)
lower (str | None)
upper (str | None)
title (str)
xlabel (str)
ylabel (str)
ax (matplotlib.pyplot.Axes | None)
figsize (tuple[float, float] | None)

Return type:

tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]