coco_pipe.viz.interactive.base#

General-purpose interactive (Plotly) visualization helpers.

Mirrors the static helpers in coco_pipe.viz.base (plot_bar, plot_distribution_groups, plot_heatmap) for cases where the report or notebook wants an interactive figure.

Functions#

plot_bar(scores[, errors, labels, label_map, top_n, ...])

Interactive ranked bar chart with optional error bars.

plot_scatter(data, x, y[, color, text, hovertemplate, ...])

Interactive 2D scatter / line-scatter, optionally split into colored groups.

plot_grouped_bar(data, x, y, group[, text, ...])

Interactive grouped bar chart (barmode="group") from a long DataFrame.

plot_ranked_bar(data, *, value, category, color[, ...])

Ranked grouped bar: sort by value, keep top_n, color by color.

plot_distribution_groups(groups, labels[, kind, ...])

Interactive grouped distribution plot (box or violin) with overlaid points.

plot_group_scatter_with_mean(groups, labels[, error, ...])

Per-group scatter of individual observations plus a mean +/- error-bar marker.

plot_heatmap(matrix[, x_labels, y_labels, cmap, ...])

Interactive 2D heatmap.

Module Contents#

coco_pipe.viz.interactive.base.plot_bar(scores, errors=None, labels=None, label_map=None, top_n=None, ascending=False, sort=True, orientation='vertical', color=None, cmap=None, abs_values=False, title=None, xaxis_title=None, yaxis_title=None, height=None)#

Interactive ranked bar chart with optional error bars.

Parameters:

  • scores (pandas.Series | collections.abc.Mapping[str, float] | collections.abc.Sequence[float]) – Values to plot. Accepts a pd.Series, {label: value} mapping, or a plain sequence (then labels is required for tick labels).

  • errors (pandas.Series | collections.abc.Mapping[str, float] | collections.abc.Sequence[float] | None) – Optional symmetric error magnitudes aligned with scores.

  • labels (collections.abc.Sequence[str] | None) – Tick labels used when scores is a plain sequence.

  • label_map (collections.abc.Mapping[str, str] | None) – Optional {raw_label: display_label} mapping applied to tick labels.

  • top_n (int | None) – Keep only the first top_n entries after sorting.

  • ascending (bool) – Sort direction when sort=True.

  • sort (bool) – Whether to sort bars by value before plotting.

  • orientation (Literal['vertical', 'horizontal']) – "vertical" (default) or "horizontal".

  • color (str | collections.abc.Sequence[str] | None) – Bar color or per-bar color sequence. Ignored when cmap is set.

  • cmap (str | None) – Plotly colorscale name used to color bars by value.

  • abs_values (bool) – Sort and plot by absolute values while preserving the sign for errors.

  • title (str | None) – Layout labels.

  • xaxis_title (str | None) – Layout labels.

  • yaxis_title (str | None) – Layout labels.

  • height (int | None) – Figure height in pixels.

Returns:

Interactive bar chart.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.base.plot_bar

Static Matplotlib version.

plot_distribution_groups

Per-group distribution comparison.

coco_pipe.viz.interactive.base.plot_scatter(data, x, y, color=None, text=None, hovertemplate=None, mode='markers', sort_x=None, color_map=None, marker_size=8, line_width=2.0, title=None, xaxis_title=None, yaxis_title=None, legend_title=None, height=None)#

Interactive 2D scatter / line-scatter, optionally split into colored groups.

Parameters:

  • data (pandas.DataFrame) – Source DataFrame.

  • x (str) – Column names for the x and y axes.

  • y (str) – Column names for the x and y axes.

  • color (str | None) – Optional column name. When given, one trace is drawn per unique value (each gets a legend entry and palette color); otherwise a single trace is drawn.

  • text (str | None) – Optional column name supplying per-point hover/label text.

  • hovertemplate (str | None) – Optional Plotly hovertemplate applied to every trace. %{text} refers to the text column.

  • mode (str) – Plotly scatter mode, e.g. "markers" (default), "lines+markers", or "lines".

  • sort_x (bool | None) – Whether to sort each trace by x before plotting. None (default) auto-enables sorting when mode contains "lines" so line segments connect in order.

  • color_map (collections.abc.Mapping[Any, str] | None) – Optional {group_value: color} overriding palette colors for groups.

  • marker_size (int) – Marker size in pixels.

  • line_width (float) – Line width for line modes.

  • title (str | None) – Layout labels. Axis titles default to the x / y column names.

  • xaxis_title (str | None) – Layout labels. Axis titles default to the x / y column names.

  • yaxis_title (str | None) – Layout labels. Axis titles default to the x / y column names.

  • legend_title (str | None) – Optional legend title (typically the color column name).

  • height (int | None) – Figure height in pixels.

Returns:

Interactive scatter figure.

Return type:

plotly.graph_objects.Figure

See also

plot_bar

Ranked bar chart.

plot_grouped_bar

Grouped bar chart from a long DataFrame.

coco_pipe.viz.interactive.base.plot_grouped_bar(data, x, y, group, text=None, text_position='outside', color_map=None, x_order=None, orientation='vertical', title=None, xaxis_title=None, yaxis_title=None, legend_title=None, baseline=None, baseline_label=None, value_range=None, height=None)#

Interactive grouped bar chart (barmode="group") from a long DataFrame.

Parameters:

  • data (pandas.DataFrame) – Long-format DataFrame: one row per (x, group) bar.

  • x (str) – Column name for the category axis (shared across groups). Placed on the x-axis when vertical and the y-axis when horizontal.

  • y (str) – Column name for the bar values.

  • group (str) – Column name defining the bar groups; one trace (legend entry) is drawn per unique value.

  • text (str | None) – Optional column name supplying per-bar text labels.

  • text_position (str) – Plotly textposition for bar labels (default "outside").

  • color_map (collections.abc.Mapping[Any, str] | None) – Optional {group_value: color} overriding palette colors.

  • x_order (collections.abc.Sequence[Any] | None) – Optional explicit ordering for the category (x) axis, applied to whichever visual axis carries the categories.

  • orientation (Literal['vertical', 'horizontal']) – "vertical" (default) or "horizontal". Horizontal puts the category (x) on the y-axis and the values (y) on the x-axis, which reads better for many long category labels.

  • title (str | None) – Layout labels. Axis titles refer to the literal visual axes and default to the appropriate column name for the orientation.

  • xaxis_title (str | None) – Layout labels. Axis titles refer to the literal visual axes and default to the appropriate column name for the orientation.

  • yaxis_title (str | None) – Layout labels. Axis titles refer to the literal visual axes and default to the appropriate column name for the orientation.

  • legend_title (str | None) – Optional legend title (typically the group column name).

  • baseline (float | None) – Optional reference value drawn as a dashed line on the value axis (e.g. chance for balanced accuracy).

  • baseline_label (str | None) – Optional annotation for the baseline line.

  • value_range (collections.abc.Sequence[float] | None) – Optional (low, high) range for the value axis, e.g. to anchor it at chance instead of zero.

  • height (int | None) – Figure height in pixels.

Returns:

Interactive grouped bar chart.

Return type:

plotly.graph_objects.Figure

See also

plot_bar

Single-series ranked bar chart.

plot_scatter

Scatter / line-scatter from a long DataFrame.

coco_pipe.viz.interactive.base.plot_ranked_bar(data, *, value, category, color, text=None, top_n=None, ascending=False, orientation='horizontal', color_map=None, title=None, value_title=None, category_title=None, legend_title=None, baseline=None, baseline_label=None, value_range=None, height=None)#

Ranked grouped bar: sort by value, keep top_n, color by color.

A thin ranking layer over plot_grouped_bar(). Rows are sorted by value (descending by default), truncated to top_n, and colored by the color column (one legend entry per value). Each row is one bar, so category must be unique per row — it supplies the per-bar tick label. Horizontal orientation (the default, better for many long labels) places the highest-ranked bar at the top; vertical keeps rank order left-to-right.

Parameters:

  • data (pandas.DataFrame) – Long-format DataFrame, one row per bar.

  • value (str) – Column with the numeric bar values driving the ranking.

  • category (str) – Column supplying the per-bar tick label (unique per row).

  • color (str) – Column defining the bar color / legend groups.

  • text (str | None) – Optional column supplying per-bar text labels.

  • top_n (int | None) – Keep only the first top_n rows after sorting.

  • ascending (bool) – Sort direction (default False — highest value first).

  • orientation (Literal['vertical', 'horizontal']) – "horizontal" (default) or "vertical".

  • color_map (collections.abc.Mapping[Any, str] | None) – Optional {color_value: color} overriding palette colors.

  • title (str | None) – Layout labels; axis titles map to the value / category axes for the chosen orientation.

  • value_title (str | None) – Layout labels; axis titles map to the value / category axes for the chosen orientation.

  • category_title (str | None) – Layout labels; axis titles map to the value / category axes for the chosen orientation.

  • legend_title (str | None) – Optional legend title (typically the color column name).

  • baseline (float | None) – Forwarded to plot_grouped_bar() — a dashed reference line on the value axis and an explicit value-axis range (e.g. anchored at chance).

  • baseline_label (str | None) – Forwarded to plot_grouped_bar() — a dashed reference line on the value axis and an explicit value-axis range (e.g. anchored at chance).

  • value_range (collections.abc.Sequence[float] | None) – Forwarded to plot_grouped_bar() — a dashed reference line on the value axis and an explicit value-axis range (e.g. anchored at chance).

  • height (int | None) – Figure height in pixels.

Returns:

Interactive ranked, grouped bar chart.

Return type:

plotly.graph_objects.Figure

See also

plot_grouped_bar

Grouped bars without the ranking / top-N layer.

plot_bar

Single-series ranked bar chart (no color grouping).

coco_pipe.viz.interactive.base.plot_distribution_groups(groups, labels, kind='box', show_points=True, point_opacity=0.55, showmeans=True, title=None, xaxis_title=None, yaxis_title=None, color=None, height=None, sig_pairs=None, baseline=None, baseline_label=None, value_range=None)#

Interactive grouped distribution plot (box or violin) with overlaid points.

Parameters:

  • groups (collections.abc.Sequence[collections.abc.Sequence[float] | numpy.ndarray | pandas.Series]) – Sequence of data arrays, one per group. Non-finite values are dropped.

  • labels (collections.abc.Sequence[Any]) – Group labels aligned with groups.

  • kind (Literal['box', 'violin']) – "box" (default) or "violin".

  • show_points (bool) – Overlay individual points on top of each box / violin.

  • point_opacity (float) – Opacity for overlaid individual points.

  • showmeans (bool) – Whether to mark the mean inside each box / violin.

  • title (str | None) – Layout labels.

  • xaxis_title (str | None) – Layout labels.

  • yaxis_title (str | None) – Layout labels.

  • color (str | collections.abc.Sequence[str] | None) – Single color or per-group color list. Defaults to the colorblind palette.

  • height (int | None) – Figure height in pixels.

  • sig_pairs (collections.abc.Sequence[tuple[int, int, str]] | None) – Optional sequence of (idx_a, idx_b, annotation) triples drawing a horizontal significance bracket between groups at indices idx_a and idx_b with the given annotation (e.g., "*", "p=0.01").

  • baseline (float | None) – Optional reference value drawn as a dashed horizontal line (e.g. chance).

  • baseline_label (str | None) – Optional annotation for the baseline line.

  • value_range (collections.abc.Sequence[float] | None) – Optional (low, high) range for the value (y) axis.

Returns:

Interactive distribution figure.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.base.plot_distribution_groups

Static Matplotlib version.

plot_bar

Bar chart with optional error bars.

coco_pipe.viz.interactive.base.plot_group_scatter_with_mean(groups, labels, error='sem', point_jitter=0.12, point_labels=None, title=None, xaxis_title=None, yaxis_title=None, color=None, height=None, baseline=None, baseline_label=None, value_range=None)#

Per-group scatter of individual observations plus a mean +/- error-bar marker.

Unlike plot_distribution_groups() (box/violin summaries), this draws each observation (e.g. one point per subject) as a jittered marker and overlays a single larger marker at the group mean with an error bar — the “one dot per subject, plus average with error bars” comparison used to show a representation-to-representation enhancement.

Parameters:

  • groups (collections.abc.Sequence[collections.abc.Sequence[float] | numpy.ndarray | pandas.Series]) – Sequence of data arrays, one per group. Non-finite values are dropped.

  • labels (collections.abc.Sequence[Any]) – Group labels aligned with groups, shown as x-axis tick labels.

  • error (Literal['sem', 'sd']) – Error-bar type for the mean marker: "sem" (default) or "sd".

  • point_jitter (float) – Half-width of the horizontal jitter applied to individual points, in x-axis units (groups are one unit apart).

  • point_labels (collections.abc.Sequence[collections.abc.Sequence[Any]] | None) – Optional per-point hover labels (e.g. subject ids), aligned with groups.

  • title (str | None) – Layout labels.

  • xaxis_title (str | None) – Layout labels.

  • yaxis_title (str | None) – Layout labels.

  • color (str | collections.abc.Sequence[str] | None) – Single color or per-group color list. Defaults to the colorblind palette.

  • height (int | None) – Figure height in pixels.

  • baseline (float | None) – Optional reference value drawn as a dashed horizontal line (e.g. chance).

  • baseline_label (str | None) – Optional annotation for the baseline line.

  • value_range (collections.abc.Sequence[float] | None) – Optional (low, high) range for the value (y) axis.

Returns:

Interactive scatter-plus-mean figure.

Return type:

plotly.graph_objects.Figure

See also

plot_distribution_groups

Box/violin group comparison with overlaid points.

plot_bar

Bar chart with optional error bars from pre-aggregated values.

coco_pipe.viz.interactive.base.plot_heatmap(matrix, x_labels=None, y_labels=None, cmap=None, center=None, vmin=None, vmax=None, annotate=False, annotation_format='.3g', title=None, xaxis_title=None, yaxis_title=None, colorbar_label=None, height=None)#

Interactive 2D heatmap.

Parameters:

  • matrix (pandas.DataFrame | collections.abc.Sequence[collections.abc.Sequence[float]] | numpy.ndarray) – 2D matrix to display. A DataFrame provides default axis labels.

  • x_labels (collections.abc.Sequence[Any] | None) – Tick labels. Override DataFrame columns / index when provided.

  • y_labels (collections.abc.Sequence[Any] | None) – Tick labels. Override DataFrame columns / index when provided.

  • cmap (str | None) – Plotly colorscale. Defaults to SEQUENTIAL unless center is provided, in which case DIVERGING is used.

  • center (float | None) – Value mapped to the colormap midpoint (uses DIVERGING).

  • vmin (float | None) – Explicit colormap bounds.

  • vmax (float | None) – Explicit colormap bounds.

  • annotate (bool) – Print values inside cells.

  • annotation_format (str) – Python format spec for cell annotations.

  • title (str | None) – Layout labels.

  • xaxis_title (str | None) – Layout labels.

  • yaxis_title (str | None) – Layout labels.

  • colorbar_label (str | None) – Layout labels.

  • height (int | None) – Figure height in pixels.

Returns:

Interactive heatmap.

Return type:

plotly.graph_objects.Figure

See also

coco_pipe.viz.base.plot_heatmap

Static Matplotlib version.

plot_coranking_matrix

Square coranking-matrix heatmap.