coco_pipe.viz.plots =================== .. py:module:: coco_pipe.viz.plots .. autoapi-nested-parse:: coco_pipe/viz/plots.py ---------------------- Minimal plotting helpers: - plot_topomap: 2D topographic map using MNE's plot_topomap for EEG layouts. - plot_bar: Generic ranked bar plots with optional error bars. Both functions are data-agnostic: pass any metric (e.g., accuracy, importance) for any analysis unit (sensors, features, regions). Functions --------- .. autoapisummary:: coco_pipe.viz.plots._coerce_series coco_pipe.viz.plots._coerce_coords coco_pipe.viz.plots.plot_topomap coco_pipe.viz.plots.plot_bar coco_pipe.viz.plots.plot_scatter2d Module Contents --------------- .. py:function:: _coerce_series(data: Union[pandas.Series, Mapping[str, float], Sequence[float]], index: Optional[Sequence[str]] = None) -> pandas.Series .. py:function:: _coerce_coords(coords: Union[pandas.DataFrame, Mapping[str, Tuple[float, float]], Sequence[Tuple[float, float]]], index: Optional[Sequence[str]] = None) -> pandas.DataFrame .. py:function:: plot_topomap(values: Union[pandas.Series, Mapping[str, float], Sequence[float]], coords: Union[pandas.DataFrame, Mapping[str, Tuple[float, float]], Sequence[Tuple[float, float]]], *, index: Optional[Sequence[str]] = None, vmin: Optional[float] = None, vmax: Optional[float] = None, cmap: str = 'RdBu_r', head_radius: float = 0.5, levels: int = 64, fill: bool = True, sensors: str = 'markers', sensor_size: float = 30.0, outlines: bool = True, contours: int = 0, symmetric: bool = True, title: Optional[str] = None, cbar: bool = True, cbar_label: Optional[str] = None, text_size: Optional[float] = None, title_size: Optional[float] = None, title_loc: Optional[str] = None, tick_size: Optional[float] = None, cbar_size: Optional[float] = None, figsize: Tuple[float, float] = (5, 5), ax: Optional[matplotlib.pyplot.Axes] = None, save: Optional[str] = None) -> Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes] Plot a topographic map for arbitrary sensor values using MNE. :param values: Sensor values. If Series or Mapping, keys should match coords names. :type values: Series | Mapping | Sequence :param coords: Sensor coordinates. Accepts: - DataFrame with columns ['x','y'] and index = sensor names - Mapping[name] -> (x,y) - Sequence[(x,y)], plus `index` to name them :type coords: DataFrame | Mapping | Sequence :param index: Names for values/coords when passing sequences. :type index: sequence, optional :param sensors: One of {"markers", "labels", "none"} to show sensor markers/labels. :type sensors: str :param contours: Number of contour lines to draw on top (0 disables). :type contours: int :param symmetric: If True, use symmetric color limits around 0 (vlim = [-a, +a]) where a is a rounded-up amplitude from the data range. Set False to use asymmetric nice-rounded limits. :type symmetric: bool, default=True .. rubric:: Notes - Requires the optional dependency 'mne'. Install with `pip install mne`. - Uses mne.viz.plot_topomap for robust EEG topographies. - vmin/vmax are rounded to "nice" values: we floor vmin and ceil vmax to the nearest power-of-10 step (e.g., 0.87 -> 0.9, 0.012 -> 0.02). - Use `text_size` to scale all text; override with `title_size`, `tick_size`, or `cbar_size` for finer control. - Use `title_loc` to set title alignment: 'left', 'center', or 'right'. .. py:function:: plot_bar(scores: Union[pandas.Series, Mapping[str, float], Sequence[float]], *, errors: Optional[Union[pandas.Series, Mapping[str, float], Sequence[float]]] = None, labels: Optional[Sequence[str]] = None, label_map: Optional[Mapping[str, str]] = None, top_n: Optional[int] = None, ascending: bool = False, orientation: str = 'vertical', color: Optional[Union[str, Sequence[str]]] = None, cmap: Optional[str] = None, abs_values: bool = False, nice_axis_limits: bool = False, axis_break_orders: Optional[float] = None, axis_break_pad: float = 0.05, remove_spines: Optional[Union[str, Sequence[str]]] = None, remove_ticks: Optional[Union[str, Sequence[str]]] = None, text_size: Optional[float] = None, title_size: Optional[float] = None, title_loc: Optional[str] = None, axis_label_size: Optional[float] = None, tick_size: Optional[float] = None, grid_axis: Optional[str] = 'y', title: Optional[str] = None, xlabel: Optional[str] = None, ylabel: Optional[str] = None, axis_lim: Optional[Tuple[float, float]] = None, figsize: Tuple[float, float] = (7, 4), ax: Optional[matplotlib.pyplot.Axes] = None, save: Optional[str] = None) -> Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes] Plot a ranked bar chart of scores with optional error bars. :param scores: Values to plot. If Sequence, provide `labels`. :type scores: Series | Mapping | Sequence :param errors: Error bars (std/sem). Keys or order must match `scores`. :type errors: Series | Mapping | Sequence, optional :param label_map: Mapping from original item names (index of `scores`) to custom display labels for tick names. Unmapped labels fall back to their original names. :type label_map: Mapping[str, str], optional :param top_n: Show only the top-N items after sorting by value. :type top_n: int, optional :param ascending: Sort ascending (False for descending/top highest). :type ascending: bool :param orientation: "vertical" or "horizontal". :type orientation: str :param axis_lim: Limits for the numeric axis (y for vertical, x for horizontal). If provided, applies via `ax.set_ylim(axis_lim)` (vertical) or `ax.set_xlim(axis_lim)` (horizontal). :type axis_lim: tuple(float, float), optional :param color: Single color or list per bar. If not provided and `cmap` is set, colors are mapped from values. :type color: str | list, optional :param cmap: Colormap name to map bar colors by value. :type cmap: str, optional :param abs_values: If True, plot absolute values of `scores` and also sort/select top_n by absolute magnitude. :type abs_values: bool, default=False :param nice_axis_limits: If True and `axis_lim` is not provided, set the numeric axis limits to "nice-rounded" floor(min(values)) and ceil(max(values)). Applies to the y-axis for vertical orientation and x-axis for horizontal orientation. :type nice_axis_limits: bool, default=False :param remove_spines: Remove axis spines by name. Accepts any of {"left","right","top","bottom"}, or the shortcut "right_top" to remove both right and top. You can also pass a list like ["right", "bottom"]. :type remove_spines: str | sequence, optional :param remove_ticks: Hide tick marks (not labels) on the x and/or y axes. Accepts "x", "y", or "both". You can combine as a space/comma-separated string (e.g., "x y" or "x,y") or pass a list like ["x", "y"]. :type remove_ticks: str | sequence, optional :param text_size: Base font size for all text in the plot (title, axis labels, ticks). :type text_size: float, optional :param title_size: Overrides title font size; falls back to `text_size`. :type title_size: float, optional :param axis_label_size: Overrides axis label font size; falls back to `text_size`. :type axis_label_size: float, optional :param tick_size: Overrides tick label font size; falls back to `text_size`. :type tick_size: float, optional :param title_loc: Title alignment: one of {"left", "center", "right"}. Defaults to matplotlib's default (center) if not provided. :type title_loc: str, optional :param grid_axis: Which axis to draw grid lines on: one of {"x", "y", "both", "auto"}. Use "none" or None to disable the grid. "auto" chooses 'y' for vertical bars and 'x' for horizontal bars. :type grid_axis: str | None, default="y" :param axis_break_orders: If provided, automatically create a broken numeric axis (y for vertical, x for horizontal) when the largest value is at least 10**axis_break_orders times the second largest. Only applied when values are non-negative and `axis_lim` is not set. Keeps API compatible by returning the primary axis (bottom/left) of the broken pair. :type axis_break_orders: float, optional :param axis_break_pad: Fractional padding around the split limits for the broken axes. :type axis_break_pad: float, default=0.05 .. py:function:: plot_scatter2d(x: Union[pandas.Series, Sequence[float], numpy.ndarray], y: Union[pandas.Series, Sequence[float], numpy.ndarray], *, labels: Optional[Union[pandas.Series, Sequence[Any], numpy.ndarray]] = None, label_map: Optional[Mapping[Any, str]] = None, palette: Optional[Sequence[str]] = None, alpha: float = 0.8, s: float = 25.0, text_size: Optional[float] = None, title_size: Optional[float] = None, title_loc: Optional[str] = None, axis_label_size: Optional[float] = None, tick_size: Optional[float] = None, legend_size: Optional[float] = None, title: Optional[str] = None, xlabel: Optional[str] = None, ylabel: Optional[str] = None, legend: bool = True, figsize: Tuple[float, float] = (5, 5), ax: Optional[matplotlib.pyplot.Axes] = None, save: Optional[str] = None) -> Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes] Scatter plot with class-based coloring. :param x: Coordinates for points. :type x: array-like :param y: Coordinates for points. :type y: array-like :param labels: Class labels for coloring. If None, a single color is used. :type labels: array-like, optional :param label_map: Mapping from raw labels to display names in legend. :type label_map: mapping, optional :param palette: Colors to cycle over classes (defaults to matplotlib tab10). :type palette: sequence of colors, optional :param legend: Whether to show legend for classes. :type legend: bool