coco_pipe.viz.base ================== .. py:module:: coco_pipe.viz.base Functions --------- .. autoapisummary:: coco_pipe.viz.base.plot_bar coco_pipe.viz.base.centered_color_limits coco_pipe.viz.base.accuracy_color_limits coco_pipe.viz.base.plot_heatmap coco_pipe.viz.base.plot_line coco_pipe.viz.base.plot_error_points coco_pipe.viz.base.plot_distribution_groups coco_pipe.viz.base.plot_histogram coco_pipe.viz.base.plot_scatter2d coco_pipe.viz.base.plot_scatter3d coco_pipe.viz.base.plot_hexbin coco_pipe.viz.base.plot_streamfield coco_pipe.viz.base.plot_topomap coco_pipe.viz.base.plot_timecourses coco_pipe.viz.base.plot_roi_sensors Module Contents --------------- .. py:function:: 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, xlabel = None, ylabel = None, figsize = None, ax = None, **_) Plot a ranked bar chart with optional error bars. :param scores: Values to plot. Accepts a Series, ``{label: value}`` mapping, or a plain sequence. :param errors: Optional symmetric error magnitudes aligned with ``scores``. :param labels: Tick labels used when ``scores`` is a plain sequence. :param label_map: Optional ``{raw_label: display_label}`` mapping applied to tick labels. :param top_n: Keep only the first ``top_n`` entries after sorting. :param ascending: Sort direction when ``sort=True``. :param sort: Whether to sort bars by value before plotting. :param orientation: ``"vertical"`` or ``"horizontal"``. :param color: Bar color or per-bar color sequence. Ignored when ``cmap`` is set. :param cmap: Colormap name used to derive per-bar colors from values. :param abs_values: Plot and sort by absolute values while preserving the sign for errors. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: centered_color_limits(values, *, center, minimum_half_range = 0.0, bounds = None) Return finite color limits symmetric around ``center``. .. py:function:: accuracy_color_limits(values, *, center = 0.5, minimum_half_range = 0.02) Return chance-centered color limits for accuracy-like values. .. py:function:: plot_heatmap(matrix, x_labels = None, y_labels = None, cmap = SEQUENTIAL, center = None, minimum_half_range = 0.0, vmin = None, vmax = None, aspect = 'auto', origin = None, colorbar = True, colorbar_label = None, annotate = False, annotation_format = '.3g', title = None, xlabel = None, ylabel = None, xtick_rotation = 45, xtick_ha = 'right', figsize = None, ax = None, **_) Plot a 2D numeric matrix as a heatmap. :param matrix: Values to display. A DataFrame provides default axis labels. :param x_labels: Column tick labels. Overrides DataFrame column names. :param y_labels: Row tick labels. Overrides DataFrame index. :param cmap: Colormap name. :param center: When set, a ``TwoSlopeNorm`` is applied so this value maps to the colormap midpoint. Limits are symmetric around the center unless both ``vmin`` and ``vmax`` are supplied. :param minimum_half_range: Minimum distance from ``center`` to either color limit. :param vmin: Explicit colormap lower bound. :param vmax: Explicit colormap upper bound. :param aspect: Passed directly to ``imshow``. :param origin: Passed directly to ``imshow`` when not ``None``. :param colorbar: Whether to attach a colorbar. :param colorbar_label: Optional colorbar label. :param annotate: Overlay each cell with its numeric value. :param annotation_format: Format string used for cell annotations. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param xtick_rotation: X-tick label rotation in degrees. :param xtick_ha: X-tick label horizontal alignment. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_line(x, y, yerr = None, error_style = 'band', label = None, color = None, marker = None, linestyle = None, linewidth = 2.0, alpha = 1.0, band_alpha = 0.15, title = None, xlabel = None, ylabel = None, legend = False, figsize = None, ax = None, **_) Plot a 2D line with optional uncertainty band or error bars. :param x: Horizontal axis values. :param y: Vertical axis values aligned with ``x``. :param yerr: Optional symmetric error magnitudes. Rendered as a shaded band or error bars depending on ``error_style``. :param error_style: ``"band"`` for a filled ``fill_between`` region, ``"bar"`` for ``errorbar`` caps. :param label: Legend label. :param color: Line and band color. :param marker: Matplotlib marker string. :param linestyle: Matplotlib linestyle string. :param linewidth: Line width in points. :param alpha: Line opacity. :param band_alpha: Opacity of the uncertainty band when ``error_style="band"``. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param legend: Whether to show the legend. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_error_points(x, y, xerr = None, yerr = None, labels = None, marker = 'o', color = None, label = None, capsize = 3.0, reference_x = None, reference_y = None, reference_style = None, title = None, xlabel = None, ylabel = None, xtick_rotation = 45, xtick_ha = 'right', legend = False, figsize = None, ax = None, **_) Plot point estimates with optional x/y error bars and references. :param x: Horizontal positions of the points. :param y: Vertical positions of the points. :param xerr: Optional horizontal error magnitudes passed to ``errorbar``. :param yerr: Optional vertical error magnitudes passed to ``errorbar``. :param labels: Tick labels placed at each ``x`` position. :param marker: Matplotlib marker string. :param color: Point and error bar color. :param label: Legend label for the point series. :param capsize: Error bar cap size in points. :param reference_x: Draw a vertical dashed reference line at this x value. :param reference_y: Draw a horizontal dashed reference line at this y value. :param reference_style: Optional style overrides for the reference lines. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param xtick_rotation: X-tick label rotation in degrees. :param xtick_ha: X-tick label horizontal alignment. :param legend: Whether to show the legend. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_distribution_groups(groups, labels, kind = 'box', show_points = True, jitter = 0.15, point_color = 'black', point_alpha = 0.55, point_size = 18, showmeans = True, title = None, xlabel = None, ylabel = None, xtick_rotation = 45, xtick_ha = 'right', figsize = None, ax = None, **_) Plot grouped scalar distributions as box or violin plots. :param groups: Sequence of data arrays, one per group. Non-finite values are dropped. :param labels: Group labels aligned with ``groups``. :param kind: ``"box"`` or ``"violin"``. :param show_points: Overlay jittered individual points on top of the box or violin. :param jitter: Half-width of the jitter band around each group position. :param point_color: Color of the overlaid individual points. :param point_alpha: Opacity of the overlaid individual points. :param point_size: Size of the overlaid individual points. :param showmeans: Whether to show the mean marker inside each box or violin. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param xtick_rotation: X-tick label rotation in degrees. :param xtick_ha: X-tick label horizontal alignment. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_histogram(values, bins = 30, color = None, title = None, xlabel = None, ylabel = 'Count', figsize = None, ax = None, **_) Plot a histogram of a 1D array of scalar values. :param values: Values to histogram. Non-finite values are dropped. :param bins: Number of bins, or explicit bin edges, passed to ``ax.hist``. :param color: Bar color. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label (defaults to ``"Count"``). :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_scatter2d(x, y, labels = None, label_map = None, palette = None, c = None, color = None, cmap = None, colorbar = False, colorbar_label = 'Value', xerr = None, yerr = None, reference_x = None, reference_y = None, reference_style = None, error_color = '0.35', capsize = 0.0, alpha = 0.8, s = 25.0, title = None, xlabel = None, ylabel = None, legend = True, legend_title = None, figsize = (5, 5), ax = None, **_) Scatter plot with optional class coloring. :param x: Horizontal coordinates. :param y: Vertical coordinates. :param labels: Discrete class labels used to color points. When provided, ``color`` and ``c`` are ignored and each class gets its own legend entry. :param label_map: Optional ``{raw_label: display_label}`` mapping for the legend. :param palette: Explicit per-class color sequence, overriding the default qualitative palette. :param c: Continuous scalar values used for colormap encoding when ``labels`` is ``None``. :param color: Single color for all points when neither ``labels`` nor ``c`` is set. :param cmap: Colormap name used with ``c``. :param colorbar: Whether to attach a colorbar when ``c`` is provided. :param colorbar_label: Optional colorbar label. :param xerr: Optional horizontal error magnitudes. :param yerr: Optional vertical error magnitudes. :param reference_x: Draw a vertical dashed reference line at this x value. :param reference_y: Draw a horizontal dashed reference line at this y value. :param reference_style: Optional style overrides for the reference lines. :param error_color: Color of the error bars. :param capsize: Error bar cap size. :param alpha: Point opacity. :param s: Point marker size. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param legend: Whether to show the class legend. :param legend_title: Optional legend title. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_scatter3d(x, y, z, labels = None, label_map = None, palette = None, c = None, color = None, cmap = None, colorbar = False, colorbar_label = 'Value', alpha = 0.8, s = 25.0, title = None, xlabel = None, ylabel = None, zlabel = None, legend = True, legend_title = None, figsize = (5, 5), ax = None, **_) 3D scatter plot with optional class coloring. :param x: X-axis coordinates. :param y: Y-axis coordinates. :param z: Z-axis coordinates. :param labels: Discrete class labels used to color points. Each class gets its own legend entry. :param label_map: Optional ``{raw_label: display_label}`` mapping for the legend. :param palette: Explicit per-class color sequence, overriding the default qualitative palette. :param c: Continuous scalar values used for colormap encoding when ``labels`` is ``None``. :param color: Single color for all points when neither ``labels`` nor ``c`` is set. :param cmap: Colormap name used with ``c``. :param colorbar: Whether to attach a colorbar when ``c`` is provided. :param colorbar_label: Optional colorbar label. :param alpha: Point opacity. :param s: Point marker size. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param zlabel: Optional z-axis label. :param legend: Whether to show the class legend. :param legend_title: Optional legend title. :param figsize: Figure size used when creating new axes. :param ax: Existing 3D Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_hexbin(x, y, gridsize = 40, cmap = SEQUENTIAL, mincnt = 1, colorbar = True, colorbar_label = None, reference_identity = False, reference_style = None, title = None, xlabel = None, ylabel = None, legend = False, figsize = (5, 5), ax = None, **_) Hexbin density plot for paired numeric values. :param x: Horizontal values. :param y: Vertical values aligned with ``x``. :param gridsize: Number of hexagons in the horizontal direction. :param cmap: Colormap name encoding bin counts. :param mincnt: Minimum count per bin required to display a hexagon. :param colorbar: Whether to attach a colorbar. :param colorbar_label: Optional colorbar label. :param reference_identity: Overlay a dashed red identity line (``y = x``). :param reference_style: Optional style overrides for the identity reference line. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param legend: Whether to show the legend. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_streamfield(x_grid, y_grid, u_grid, v_grid, points = None, density = 1.5, cmap = SEQUENTIAL, colorbar_label = None, point_color = '#DDDDDD', point_size = 15, point_alpha = 0.6, title = None, xlabel = None, ylabel = None, figsize = (5, 5), ax = None, **_) Plot a 2D stream field from gridded vector components. :param x_grid: 2D grid of x-coordinates produced by ``np.meshgrid``. :param y_grid: 2D grid of y-coordinates produced by ``np.meshgrid``. :param u_grid: Horizontal velocity component on the same grid. :param v_grid: Vertical velocity component on the same grid. :param points: Optional ``(N, 2)`` array of raw data points scattered beneath the streamlines. :param density: Streamline density passed to ``matplotlib.axes.Axes.streamplot``. :param cmap: Colormap used to encode local flow speed along streamlines. :param colorbar_label: Optional colorbar label. :param point_color: Color for the optional raw data scatter points. :param point_size: Marker size for raw data scatter points. :param point_alpha: Opacity of raw data scatter points. :param title: Optional axes title. :param xlabel: Optional x-axis label. :param ylabel: Optional y-axis label. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_topomap(values, coords=None, index = None, info=None, vmin = None, vmax = None, cmap = None, sensors = 'markers', outlines = True, contours = 0, symmetric = True, title = None, cbar = True, cbar_label = None, figsize = (5, 5), ax = None, **_) Plot a topographic map for sensor values using MNE. :param values: Sensor values to plot. A Series or mapping must be keyed by sensor name; a plain sequence requires ``index`` or ``coords``/``info`` to supply the names. :param coords: Sensor coordinate source: an MNE-style ``(N, 2+)`` array, a ``{name: (x, y)}`` mapping, or a DataFrame with ``x`` and ``y`` columns and sensor names in the index or a ``FeatureName`` / ``Sensor`` column. :param index: Explicit sensor name list used when ``values`` is a plain sequence. :param info: MNE ``Info`` object from which electrode positions are extracted. Takes priority over ``coords``. :param vmin: Colormap lower bound. Computed symmetrically when ``symmetric=True``. :param vmax: Colormap upper bound. Computed symmetrically when ``symmetric=True``. :param cmap: Colormap name. Defaults to the diverging theme map when ``symmetric=True``, otherwise the sequential map. :param sensors: ``"markers"`` to show sensor dots, ``"labels"`` to annotate each sensor, or ``"none"`` to hide sensors. :param outlines: Whether to draw the head outline. :param contours: Number of contour lines drawn over the topomap. :param symmetric: Derive ``vmin``/``vmax`` symmetrically around zero. :param title: Optional axes title. :param cbar: Whether to attach a colorbar. :param cbar_label: Optional colorbar label. :param figsize: Figure size used when creating new axes. :param ax: Existing Matplotlib axes to draw into. :returns: The created or reused figure and axes. :rtype: tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] .. py:function:: plot_timecourses(data, times, channel_names = None, rois = None, group_labels = None, group_name_map = None, palette = None, linestyle_map = None, n_cols = None, error_style = 'band', xlabel = 'Time', ylabel = 'Amplitude', title = None, figsize = None, sharey = True, sharex = True, add_zero = False, axes_kws = None, **kwargs) Plot timecourses (ERPs, ERFs, source activations) across channels or ROIs. :param data: Shape ``(n_trials, n_channels, n_times)`` or ``(n_channels, n_times)``. :param times: Time axis values, shape ``(n_times,)``. :param channel_names: Names of the channels in ``data``. Required if ``rois`` specifies channel names. If ``data`` is ``(n_channels, n_times)`` and ``channel_names`` is omitted, channels are numbered. :param rois: Mapping of ``{roi_name: [channel_names]}`` to average over. If a sequence of strings is provided, each string is treated as a single-channel ROI. If None, all channels are plotted individually. :param group_labels: Shape ``(n_trials,)`` assigning each trial to a group. If None, all trials are averaged together. :param group_name_map: Mapping to rename groups for the legend. :param palette: Color mapping for groups. Can be a dictionary or a list of colors. :param linestyle_map: Linestyle mapping for groups. :param n_cols: Maximum number of columns for the subplot grid. :param error_style: "band" (shaded SEM) or "bar" (errorbars). Passed to `plot_line`. :param xlabel: X-axis label. :param ylabel: Y-axis label. :param title: Figure title. :param figsize: Custom figure size. :param sharey: Whether to share axes across subplots. :param sharex: Whether to share axes across subplots. :param add_zero: Whether to add reference lines at Time=0 and Amplitude=0. :param axes_kws: Dictionary of keyword arguments passed to `finalize_axes` (e.g. `grid=False`). :param kwargs: Additional arguments passed to `plot_line`. :returns: Figure and axes array. :rtype: tuple[matplotlib.figure.Figure, np.ndarray] .. py:function:: plot_roi_sensors(container, rois, palette = None, montage = 'standard_1005', figsize = None, axes_kws = None) Plot scalp topomaps highlighting specific Regions of Interest (ROIs). :param container: The DataContainer containing the channel coordinates. :param rois: A dictionary mapping ROI names to lists of channel names. :param palette: A list of colors to use for highlighting each ROI. If None, uses the default colorblind palette. :param montage: The MNE montage to use for plotting sensors. Can be a string name of a standard montage (e.g. 'standard_1005') or an mne.channels.DigMontage object. :param figsize: Figure size. If None, automatically scaled based on the number of ROIs. :param axes_kws: Additional keyword arguments passed to `finalize_axes`. :returns: The matplotlib Figure and Axes array. :rtype: fig, axes