coco_pipe.viz.decoding ====================== .. py:module:: coco_pipe.viz.decoding .. autoapi-nested-parse:: Static visualization helpers for decoding result tables. Functions --------- .. autoapisummary:: coco_pipe.viz.decoding.plot_confusion_matrix coco_pipe.viz.decoding.plot_roc_curve coco_pipe.viz.decoding.plot_pr_curve coco_pipe.viz.decoding.plot_calibration_curve coco_pipe.viz.decoding.plot_fold_score_dispersion coco_pipe.viz.decoding.plot_temporal_score_curve coco_pipe.viz.decoding.plot_temporal_generalization_matrix coco_pipe.viz.decoding.plot_temporal_statistical_assessment coco_pipe.viz.decoding.plot_null_interval_summary coco_pipe.viz.decoding.plot_training_history coco_pipe.viz.decoding.plot_decoding_scores coco_pipe.viz.decoding.plot_model_comparison coco_pipe.viz.decoding.plot_fit_diagnostics coco_pipe.viz.decoding.plot_probability_diagnostics coco_pipe.viz.decoding.plot_subject_diagnostics coco_pipe.viz.decoding.plot_group_summary coco_pipe.viz.decoding.plot_regression_diagnostics coco_pipe.viz.decoding.plot_search_results coco_pipe.viz.decoding.plot_feature_importance coco_pipe.viz.decoding.plot_feature_stability coco_pipe.viz.decoding.plot_feature_scores coco_pipe.viz.decoding.plot_decoding_topomap coco_pipe.viz.decoding.plot_sensor_feature_heatmap coco_pipe.viz.decoding.plot_sensor_feature_profile coco_pipe.viz.decoding.plot_feature_sensor_profile coco_pipe.viz.decoding.plot_head_to_head coco_pipe.viz.decoding.plot_paired_delta Module Contents --------------- .. py:function:: plot_confusion_matrix(result_or_matrix, model = None, fold = None, title = None, ax = None, figsize = None) Plot an aggregated confusion matrix from decoding diagnostics. :param result_or_matrix: Experiment result with ``get_confusion_matrices()`` or a tidy confusion matrix DataFrame containing ``TrueLabel``, ``PredictedLabel``, and ``Value``. :param model: Optional model name used to filter rows before aggregation. :param fold: Optional fold index used to filter rows before aggregation. :param title: Optional axes title. Defaults to ``"Confusion Matrix"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when ``ax`` is not provided. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_confusion_matrix` Interactive Plotly version. :py:obj:`plot_roc_curve` Receiver-operating-characteristic curve. :py:obj:`plot_probability_diagnostics` Probability-calibration quality metrics. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. .. rubric:: 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) .. py:function:: plot_roc_curve(result_or_curve, model = None, fold = None, title = None, ax = None, figsize = None, mean_only = False) Plot receiver-operating-characteristic curves. :param result_or_curve: Experiment result with ``get_roc_curve()`` or a DataFrame containing ``Model``, ``FPR``, and ``TPR``. Optional ``Fold`` and ``Class`` columns are used for grouping. :param model: Optional model name to display. :param fold: Optional fold index to display. :param title: Optional axes title. Defaults to ``"ROC Curve"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :param mean_only: 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. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_roc_curve` Interactive Plotly version. :py:obj:`plot_pr_curve` Precision-recall curve. :py:obj:`plot_calibration_curve` Probability calibration reliability curve. :py:obj:`plot_confusion_matrix` Predicted-vs-true class heatmap. .. rubric:: 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) .. py:function:: 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. :param result_or_curve: Experiment result with ``get_pr_curve()`` or a DataFrame containing ``Model``, ``Recall``, and ``Precision``. Optional ``Fold`` and ``Class`` columns are used for grouping. :param model: Optional model name to display. :param fold: Optional fold index to display. :param title: Optional axes title. Defaults to ``"Precision-Recall Curve"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :param mean_only: 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. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_pr_curve` Interactive Plotly version. :py:obj:`plot_roc_curve` Receiver-operating-characteristic curve. :py:obj:`plot_calibration_curve` Probability calibration reliability curve. .. rubric:: 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) .. py:function:: plot_calibration_curve(result_or_curve, model = None, fold = None, title = None, ax = None, figsize = None, mean_only = False) Plot calibration reliability curves. :param result_or_curve: Experiment result with ``get_calibration_curve()`` or a DataFrame containing ``Model``, ``MeanPredictedProbability``, and ``FractionPositive``. :param model: Optional model name to display. :param fold: Optional fold index to display. :param title: Optional axes title. Defaults to ``"Calibration Curve"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :param mean_only: 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. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_calibration_curve` Interactive Plotly version. :py:obj:`plot_roc_curve` Receiver-operating-characteristic curve. :py:obj:`plot_pr_curve` Precision-recall curve. :py:obj:`plot_probability_diagnostics` Scalar probability-quality metrics. .. rubric:: 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) .. py:function:: 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. :param result_or_scores: Experiment result with ``get_detailed_scores()`` or a detailed score DataFrame containing scalar ``Value`` rows. :param metric: Optional metric name used to filter scores. :param model: Optional model name used to filter scores. :param title: Optional axes title. Defaults to ``"Fold Score Dispersion"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_fold_score_dispersion` Interactive Plotly version. :py:obj:`plot_decoding_scores` Aggregate score summary with error bars. :py:obj:`plot_model_comparison` Pairwise score-difference plot. .. rubric:: 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) .. py:function:: 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. :param result_or_scores: Experiment result with ``get_temporal_score_summary()`` or a DataFrame containing ``Model``, ``Metric``, ``Time``, and ``Mean``. :param metric: Optional metric name used to filter temporal scores. :param model: Optional model name used to filter temporal scores. :param title: Optional axes title. Defaults to ``"Temporal Decoding Value"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. rubric:: Notes Non-numeric time labels are plotted at integer positions and displayed as rotated tick labels. .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_temporal_score_curve` Interactive Plotly version. :py:obj:`plot_temporal_generalization_matrix` Train-time x test-time heatmap. :py:obj:`plot_temporal_statistical_assessment` Temporal curve with permutation null band. :py:obj:`plot_null_interval_summary` Scalar null-interval summary per model. .. rubric:: 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) .. py:function:: 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. :param result_or_scores: Experiment result with ``get_temporal_score_summary()`` or a DataFrame containing ``Model``, ``Metric``, ``TrainTime``, ``TestTime``, and ``Mean``. :param metric: Optional metric name. A single model/metric pair must remain after filtering. :param model: Optional model name. A single model/metric pair must remain after filtering. :param title: Optional axes title. Defaults to ``" / "``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_temporal_generalization_matrix` Interactive Plotly version. :py:obj:`plot_temporal_score_curve` Mean temporal score curve over time. :py:obj:`plot_temporal_statistical_assessment` Temporal curve with permutation null band. .. rubric:: 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)) .. py:function:: plot_temporal_statistical_assessment(result_or_assessment, metric = None, model = None, title = None, ax = None, figsize = None) Plot temporal statistical assessment results. :param result_or_assessment: Experiment result with ``get_statistical_assessment()`` or an assessment DataFrame containing ``Model``, ``Metric``, ``Observed``, and ``Time``. :param metric: Optional metric name. A single model/metric pair must remain after filtering. :param model: Optional model name. A single model/metric pair must remain after filtering. :param title: Optional axes title. Defaults to a model/metric statistical-assessment title. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. rubric:: Notes ``NullLower`` and ``NullUpper`` are rendered as a null band when present. ``Significant`` rows are overlaid as square markers. .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_temporal_statistical_assessment` Interactive Plotly version. :py:obj:`plot_temporal_score_curve` Mean temporal score curve over time. :py:obj:`plot_null_interval_summary` Scalar null-interval summary per model. .. rubric:: 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) .. py:function:: 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. :param result_or_assessment: Experiment result with ``get_statistical_assessment()`` or an assessment DataFrame containing ``Model``, ``Metric``, and ``Observed``. :param metric: Optional metric name used to filter assessment rows. :param model: Optional model name used to filter assessment rows. :param title: Optional axes title. Defaults to ``"Null Interval Summary"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. rubric:: Notes ``NullLower``/``NullUpper`` are drawn as error intervals around their midpoint. ``NullMedian`` is shown as an optional marker series. .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_null_interval_summary` Interactive Plotly version. :py:obj:`plot_temporal_statistical_assessment` Significance-annotated temporal heatmap. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. .. rubric:: 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) .. py:function:: plot_training_history(result_or_artifacts, model = None, title = None, ax = None, figsize = None) Plot neural training-history artifacts. :param result_or_artifacts: 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. :param model: Optional model name used to filter artifacts. :param title: Optional axes title. Defaults to ``"Training History"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_training_history` Interactive Plotly version. :py:obj:`plot_fit_diagnostics` Fit-time diagnostics by model or fold. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. .. rubric:: 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) .. py:function:: 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. :param result: Experiment result with ``get_detailed_scores()`` or a detailed score DataFrame containing scalar ``Value`` rows. :param metric: Optional metric name used to filter scores. :param model: Optional model name used to filter scores. :param kind: Plot type: ``"point"`` for aggregate +/- SEM, ``"bar"`` for bar summaries, or ``"box"`` for fold-level distributions. :param aggregate: Summary statistic used by ``"point"`` and ``"bar"`` plots. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_decoding_scores` Interactive Plotly version. :py:obj:`plot_model_comparison` Score differences between model pairs. :py:obj:`plot_fold_score_dispersion` Per-fold score spread. :py:obj:`plot_null_interval_summary` Observed scores versus null bands. .. rubric:: 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) .. py:function:: plot_model_comparison(result, metric = 'accuracy', reference = None, paired = True, ax = None, figsize = None) Plot model-comparison score differences. :param result: Experiment result or a comparison DataFrame. DataFrames must contain a ``Difference`` column and may include ``ModelA``, ``ModelB``, ``CILower``, and ``CIUpper``. :param metric: Metric used when computing comparisons from an experiment result. :param reference: Optional reference model. When provided with ``paired=True``, all other models are compared against this model. :param paired: 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. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_model_comparison` Interactive Plotly version. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. :py:obj:`plot_fold_score_dispersion` Per-fold score spread. .. rubric:: 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) .. py:function:: plot_fit_diagnostics(result, *, by = 'Model', show_warnings = True, kind = 'bar', ax = None, figsize = None) Plot fit-time diagnostics by model or fold. :param result: Experiment result with ``get_fit_diagnostics()`` or a diagnostics DataFrame containing ``TotalTime`` plus the selected ``by`` column. :param by: Column used for grouping, usually ``"Model"`` or ``"Fold"``. :param show_warnings: If True, annotate the plot with the number of non-null ``WarningMessage`` entries when present. :param kind: Plot type: ``"bar"`` for mean total time or ``"box"`` for grouped total-time distributions. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_fit_diagnostics` Interactive Plotly version. :py:obj:`plot_training_history` Neural training-history artifacts. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. .. rubric:: 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) .. py:function:: plot_probability_diagnostics(result, model = None, metric = None, ax = None, figsize = None) Plot probability-quality diagnostics. :param result: Experiment result with ``get_probability_diagnostics()`` or a DataFrame containing ``Model``, ``Metric``, and ``Value``. :param model: Optional model name used to filter diagnostics. :param metric: Optional diagnostic metric used to filter rows. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_probability_diagnostics` Interactive Plotly version. :py:obj:`plot_calibration_curve` Calibration curve for probability estimates. :py:obj:`plot_confusion_matrix` Aggregated confusion matrix. .. rubric:: 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) .. py:function:: plot_subject_diagnostics(result, unit = 'Subject', metric = 'accuracy', model = None, kind = 'strip', ax = None, figsize = None) Plot per-unit prediction accuracy diagnostics. :param result: Experiment result with ``get_predictions()`` or a prediction DataFrame containing ``Model``, ``y_true``, ``y_pred``, and the selected ``unit`` column. :param unit: Metadata column used as the unit of aggregation, such as ``"Subject"``. :param metric: Metric to compute. Currently only ``"accuracy"`` is supported. :param model: Optional model name used to filter predictions. :param kind: Plot type. ``"strip"`` and ``"dot"`` show one point per unit grouped by model. ``"caterpillar"`` shows sorted unit scores with horizontal stems. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_subject_diagnostics` Interactive Plotly version. :py:obj:`plot_group_summary` Group-level accuracy summaries. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. .. rubric:: 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) .. py:function:: plot_group_summary(result, group = 'Group', metric = 'accuracy', model = None, kind = 'point', ax = None, figsize = None) Plot group-level prediction accuracy summaries. :param result: Experiment result with ``get_predictions()`` or a prediction DataFrame containing ``Model``, ``Fold``, ``y_true``, ``y_pred``, and the selected grouping column. :param group: Prediction metadata column used to define groups. :param metric: Metric to compute. Currently only ``"accuracy"`` is supported. :param model: Optional model name used to filter predictions. :param kind: Plot type: ``"point"`` for mean +/- SEM or ``"violin"`` for fold-level distributions. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_group_summary` Interactive Plotly version. :py:obj:`plot_subject_diagnostics` Per-subject accuracy diagnostics. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. .. rubric:: 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) .. py:function:: plot_regression_diagnostics(result, model = None, fold = None, kind = 'scatter', ax = None, figsize = None) Plot regression prediction diagnostics. :param result: Experiment result with ``get_predictions()`` or a prediction DataFrame containing numeric ``y_true`` and ``y_pred`` columns. :param model: Optional model name used to filter predictions. :param fold: Optional fold index used to filter predictions. :param kind: Plot type: ``"scatter"`` for observed vs predicted, ``"residual"`` for residuals vs predicted, or ``"bin"`` for binned mean residuals. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_regression_diagnostics` Interactive Plotly version. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. :py:obj:`plot_confusion_matrix` Classification confusion matrix. .. rubric:: 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) .. py:function:: plot_search_results(result, model = None, top_n = None, ax = None, figsize = None) Plot compact hyperparameter-search results. :param result: Experiment result with ``get_search_results()`` or a search-results DataFrame containing ``Model``, ``Rank``, and ``MeanTestScore``. :param model: Optional model name used to filter search rows. :param top_n: Optional positive number of top-ranked candidates to keep per model. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_search_results` Interactive Plotly version. :py:obj:`plot_model_comparison` Score differences between model pairs. :py:obj:`plot_decoding_scores` Aggregate scalar score summary. .. rubric:: 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) .. py:function:: plot_feature_importance(result, model = None, top_n = 25, signed = False, absolute = False, ax = None, figsize = None, title = None) Plot ranked feature importances. :param result: 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. :param model: Optional model name used to filter importances. :param top_n: Optional number of highest-magnitude features to display. :param signed: If True, use a diverging palette when plotting signed values. :param absolute: If True, rank and display absolute importance values. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :param title: Optional axes title. Defaults to ``"Feature Importance"``. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_feature_importance` Interactive Plotly version. :py:obj:`plot_feature_stability` Feature-selection stability across folds. :py:obj:`plot_feature_scores` Univariate feature-selector scores. .. rubric:: 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) .. py:function:: plot_feature_stability(result, model = None, top_n = 25, kind = 'bar', ax = None, figsize = None) Plot feature-selection stability. :param result: 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``. :param model: Optional model name used to filter feature rows. :param top_n: Optional number of most stable features to display. :param kind: Plot type: ``"bar"`` for mean selection frequency or ``"heatmap"`` for fold-by-feature selected masks. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_feature_stability` Interactive Plotly version. :py:obj:`plot_feature_importance` Ranked feature importances. :py:obj:`plot_feature_scores` Univariate feature-selector scores. .. rubric:: 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) .. py:function:: plot_feature_scores(result, model = None, top_n = 25, show_pvalues = True, ax = None, figsize = None) Plot univariate feature-selector scores. :param result: Experiment result with ``get_feature_scores()`` or a feature-score DataFrame containing ``FeatureName`` and ``Score``. :param model: Optional model name used to filter feature scores. :param top_n: Optional positive number of highest-scoring features to display. :param show_pvalues: If True, annotate bars with ``CorrectedPValue`` when available, otherwise ``PValue``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`coco_pipe.viz.interactive.decoding.plot_feature_scores` Interactive Plotly version. :py:obj:`plot_feature_importance` Ranked feature importances. :py:obj:`plot_feature_stability` Feature-selection stability across folds. .. rubric:: 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) .. py:function:: 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. :param sensor_df: DataFrame containing ``FeatureName`` and the selected value column. ``FeatureName`` entries must match the provided sensor layout. :param value: Numeric column to aggregate and plot. :param info: Optional MNE ``Info`` object used to resolve sensor positions. :param coords: Optional coordinate table used to resolve sensor positions when ``info`` is not provided. :param center: Optional numeric center for diverging color limits. When provided, ``vmin`` and ``vmax`` are computed symmetrically around this value. :param minimum_half_range: Minimum distance from ``center`` to either color limit. :param times: Optional list of time values used to filter rows when ``Time`` exists. :param mask: Optional boolean mask applied after time filtering. :param title: Optional axes title. Defaults to the plotted value name. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`plot_sensor_feature_heatmap` Feature-family importance summarized by sensor. :py:obj:`plot_sensor_feature_profile` Feature importances for one sensor. :py:obj:`plot_feature_sensor_profile` Sensor topomap for one feature family. .. rubric:: 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) .. py:function:: 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. :param result: Experiment result with ``get_feature_importances()`` or a compatible feature-importance DataFrame. :param feature_metadata: Explicit metadata with ``FeatureName``, ``Sensor``, and ``FeatureFamily`` columns. :param feature_group: Optional feature family value used to filter rows. The parameter name is retained for compatibility; it matches ``FeatureFamily`` values. :param sensor_order: Optional ordered list of sensors to display as columns. :param agg: Aggregation function passed to ``pandas.pivot_table``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`plot_decoding_topomap` Sensor topomap for a single score column. :py:obj:`plot_sensor_feature_profile` Feature importances for one sensor. :py:obj:`plot_feature_sensor_profile` Sensor topomap for one feature family. .. rubric:: 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) .. py:function:: plot_sensor_feature_profile(result, feature_metadata, sensor, model = None, ax = None, figsize = None) Plot feature importances for one sensor. :param result: Experiment result with ``get_feature_importances()`` or a compatible feature-importance DataFrame. :param feature_metadata: Explicit metadata with ``FeatureName`` and ``Sensor`` columns. :param sensor: Sensor name used to select features. :param model: Optional model name used to filter importances. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`plot_sensor_feature_heatmap` Feature-family importance summarized by sensor. :py:obj:`plot_feature_sensor_profile` Sensor topomap for one feature family. :py:obj:`plot_feature_importance` Ranked feature importances. .. rubric:: 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") .. py:function:: 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. :param result: Experiment result with ``get_feature_importances()`` or a compatible feature-importance DataFrame. :param feature_metadata: Explicit metadata with ``FeatureName``, ``Sensor``, and ``FeatureFamily`` columns. :param feature_family: Feature-family value to aggregate over sensors. :param info: Optional MNE ``Info`` object used to resolve sensor positions. :param coords: Optional coordinate table used to resolve sensor positions when ``info`` is not provided. :param model: Optional model name used to filter importances. :param title: Optional topomap title. Defaults to ``" Sensor Profile"``. :param ax: Existing Matplotlib axes to draw into. :param figsize: Figure size used when creating a new axes. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. seealso:: :py:obj:`plot_sensor_feature_heatmap` Feature-family importance summarized by sensor. :py:obj:`plot_sensor_feature_profile` Feature importances for one sensor. :py:obj:`plot_decoding_topomap` Sensor topomap for a single score column. .. rubric:: 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 ... ) .. py:function:: 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. .. py:function:: 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.