coco_pipe.viz ============= .. py:module:: coco_pipe.viz .. autoapi-nested-parse:: Curated plotting helpers for coco_pipe. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/coco_pipe/viz/dim_reduction/index /autoapi/coco_pipe/viz/plotly_utils/index /autoapi/coco_pipe/viz/plots/index /autoapi/coco_pipe/viz/utils/index Functions --------- .. autoapisummary:: coco_pipe.viz.plot_eigenvalues coco_pipe.viz.plot_embedding coco_pipe.viz.plot_feature_correlation_heatmap coco_pipe.viz.plot_feature_importance coco_pipe.viz.plot_interpretation coco_pipe.viz.plot_local_metrics coco_pipe.viz.plot_loss_history coco_pipe.viz.plot_metrics coco_pipe.viz.plot_shepard_diagram coco_pipe.viz.plot_streamlines coco_pipe.viz.plot_trajectory coco_pipe.viz.plot_trajectory_metric_series coco_pipe.viz.plot_channel_traces_interactive coco_pipe.viz.plot_bar coco_pipe.viz.plot_scatter2d coco_pipe.viz.plot_topomap Package Contents ---------------- .. py:function:: plot_eigenvalues(values: numpy.ndarray, title: str = 'Scree Plot', ylabel: str = 'Explained Variance', figsize: Tuple[int, int] = (8, 5), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False) -> Union[matplotlib.pyplot.Figure, Any] Plot Scree plot of eigenvalues or explained variance. :param values: Array of eigenvalues or variance ratios. :type values: np.ndarray :param title: Plot title, by default "Scree Plot". :type title: str, optional :param ylabel: Label for y-axis, by default "Explained Variance". :type ylabel: str, optional :param figsize: Figure size, by default (8, 5). :type figsize: tuple, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plotly_utils.plot_scree_interactive` .. py:function:: plot_embedding(X_emb: numpy.ndarray, labels: Optional[numpy.ndarray] = None, metadata: Optional[Dict[str, Any]] = None, dims: Union[Tuple[int, int], Tuple[int, int, int]] = (0, 1), title: str = 'Embedding', figsize: Tuple[int, int] = (10, 8), cmap: str = 'viridis', palette: str = 'deep', s: int = 40, alpha: float = 0.8, metrics: Optional[Dict[str, Any]] = None, ax: Optional[matplotlib.pyplot.Axes] = None, save_path: Optional[str] = None, interactive: bool = False, random_state: Optional[int] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot an explicit embedding with optional labels and metadata. :param X_emb: Embedding array with shape ``(n_samples, n_dimensions)``. :type X_emb: np.ndarray :param labels: Optional values aligned with the sample axis. Categorical values are shown with a legend and continuous values with a colorbar. :type labels: np.ndarray, optional :param metadata: Optional column-oriented metadata aligned with the sample axis. :type metadata: dict, optional :param dims: Embedding dimensions to visualize. Length must be 2 or 3. :type dims: tuple of int, default=(0, 1) :param title: Figure title. :type title: str, default="Embedding" :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param cmap: Colormap for continuous labels or value overlays. :type cmap: str, default="viridis" :param palette: Seaborn categorical palette name. :type palette: str, default="deep" :param s: Marker size. :type s: int, default=40 :param alpha: Marker opacity. :type alpha: float, default=0.8 :param metrics: Optional scalar metrics to annotate on the figure. :type metrics: dict, optional :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param save_path: Optional file path for saving the static figure. :type save_path: str, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param random_state: Random seed used by the interactive path when sampling is needed. :type random_state: int, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any :raises ValueError: If the embedding is not 2D or the requested dimensions are invalid. .. seealso:: :obj:`plotly_utils.plot_embedding_interactive`, :obj:`prepare_embedding_frame`, :obj:`plot_metrics` .. py:function:: plot_feature_correlation_heatmap(correlations: Any, title: str = 'Feature Correlation', top_n: Optional[int] = 25, figsize: Tuple[int, int] = (10, 8), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, method: Optional[str] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot feature-to-dimension correlations as a heatmap. :param correlations: Correlation interpretation payload or records. :type correlations: Any :param title: Figure title. :type title: str, default="Feature Correlation" :param top_n: Maximum number of features to show. Features are ranked by the maximum absolute correlation across dimensions. :type top_n: int, optional :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param method: Method name to select when multiple methods are present. :type method: str, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plot_interpretation`, :obj:`plotly_utils.plot_feature_correlation_heatmap_interactive` .. py:function:: plot_feature_importance(scores: Any, title: str = 'Feature Importance', top_n: int = 20, figsize: Tuple[int, int] = (8, 6), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, analysis: Optional[str] = None, method: Optional[str] = None, dimension: Optional[str] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot feature-importance scores as a horizontal bar chart. :param scores: Raw ``feature -> score`` mapping, interpretation payload, or interpretation record table. :type scores: Any :param title: Figure title. :type title: str, default="Feature Importance" :param top_n: Maximum number of features to show. :type top_n: int, default=20 :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(8, 6) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param analysis: Interpretation analysis to select when multiple analyses are present. :type analysis: str, optional :param method: Method name to select when multiple methods are present. :type method: str, optional :param dimension: Dimension label to select when the interpretation contains multiple dimensions. :type dimension: str, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`prepare_feature_scores`, :obj:`plot_interpretation`, :obj:`plotly_utils.plot_feature_importance_interactive` .. py:function:: plot_interpretation(interpretation: Any, *, analysis: str, title: Optional[str] = None, figsize: Tuple[int, int] = (10, 8), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, method: Optional[str] = None, dimension: Optional[str] = None, top_n: int = 20) -> Union[matplotlib.pyplot.Figure, Any] Plot one interpretation analysis using an appropriate visualization. :param interpretation: Interpretation payload or interpretation records. :type interpretation: Any :param analysis: Interpretation analysis to plot. :type analysis: str :param title: Figure title. Defaults to a title derived from ``analysis``. :type title: str, optional :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param method: Method name to select when multiple methods are present. :type method: str, optional :param dimension: Dimension label to select when the interpretation contains multiple dimensions. :type dimension: str, optional :param top_n: Maximum number of features to show in bar or heatmap views. :type top_n: int, default=20 :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plot_feature_importance`, :obj:`plot_feature_correlation_heatmap`, :obj:`plotly_utils.plot_interpretation_interactive` .. py:function:: plot_local_metrics(X_emb: numpy.ndarray, local_scores: numpy.ndarray, title: str = 'Local Quality Map', cmap: str = 'RdYlGn', ax: Optional[matplotlib.pyplot.Axes] = None) -> matplotlib.pyplot.Figure Plot the embedding colored by local quality (e.g. point-wise trustworthiness). :param X_emb: Embedding coordinates (2D). :type X_emb: np.ndarray :param local_scores: Score per sample. :type local_scores: np.ndarray :param title: Plot title. :type title: str :param cmap: Colormap (Green=Good, Red=Bad). :type cmap: str :returns: Static figure colored by the provided local scores. :rtype: matplotlib.figure.Figure .. seealso:: :obj:`plot_embedding` .. py:function:: plot_loss_history(loss_history: list, title: str = 'Training Loss', figsize: Tuple[int, int] = (8, 5), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False) -> Union[matplotlib.pyplot.Figure, Any] Plot training loss over epochs. :param loss_history: List of loss values. :type loss_history: list :param title: Plot title, by default "Training Loss". :type title: str, optional :param figsize: Figure size, by default (8, 5). :type figsize: tuple, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plotly_utils.plot_loss_history_interactive` .. py:function:: plot_metrics(scores: Any, title: str = 'Quality Metrics', figsize: Tuple[int, int] = (8, 6), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, plot_type: str = 'auto', metric: Optional[str] = None, scope: Optional[str] = None, method: Optional[Union[str, Sequence[str]]] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot tidy metric observations using one shared entrypoint. :param scores: Metric mapping, tidy metric frame, list of records, or object exposing ``to_frame()``. :type scores: Any :param title: Figure title. :type title: str, default="Quality Metrics" :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(8, 6) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param plot_type: Plot style to use. ``"auto"`` infers an appropriate view from the filtered metric records. :type plot_type: str, default="auto" :param metric: Restrict plotting to one metric. :type metric: str, optional :param scope: Restrict plotting to one scope. :type scope: str, optional :param method: Restrict plotting to one or more methods. :type method: str or sequence of str, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any :raises ValueError: If no metrics remain after filtering. .. seealso:: :obj:`plotly_utils.plot_metric_details`, :obj:`prepare_metrics_frame`, :obj:`infer_metric_plot_type` .. py:function:: plot_shepard_diagram(X_orig: numpy.ndarray, X_emb: numpy.ndarray, sample_size: int = 1000, title: str = 'Shepard Diagram', ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, random_state: Optional[int] = None, distances: Optional[Dict[str, numpy.ndarray]] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot Shepard Diagram (Original vs Embedded Distances). :param X_orig: Original high-dimensional data. :type X_orig: np.ndarray :param X_emb: Embedded low-dimensional data. :type X_emb: np.ndarray :param sample_size: Number of points to sample for distance calculation (to speed up), by default 1000. :type sample_size: int, optional :param title: Plot title, by default "Shepard Diagram". :type title: str, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plotly_utils.plot_shepard_interactive` .. py:function:: plot_streamlines(X_emb: numpy.ndarray, V_emb: numpy.ndarray, grid_density: int = 25, title: str = 'Velocity Streamlines', ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, random_state: Optional[int] = None) -> Union[matplotlib.pyplot.Figure, Any] Plot streamlines of a vector field on the embedding. :param X_emb: Coordinates of the embedding (2D only). :type X_emb: np.ndarray :param V_emb: Velocity vectors in the embedding space. :type V_emb: np.ndarray :param grid_density: Density of the grid for interpolation, by default 25. :type grid_density: int, optional :param title: Plot title, by default "Velocity Streamlines". :type title: str, optional :param ax: Existing axes to plot on. :type ax: plt.Axes, optional :param interactive: If True, returns a Plotly figure. :type interactive: bool, optional :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any :raises ValueError: If X_emb is not 2D. .. seealso:: :obj:`plotly_utils.plot_streamlines_interactive` .. py:function:: plot_trajectory(X: numpy.ndarray, times: Optional[numpy.ndarray] = None, values: Optional[numpy.ndarray] = None, labels: Optional[numpy.ndarray] = None, smooth_window: int = 1, title: str = 'Trajectory Plot', dimensions: int = 2, figsize: Tuple[int, int] = (10, 8), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False, cmap: str = 'viridis') -> Union[matplotlib.pyplot.Figure, Any] Plot already-prepared native trajectory tensors. :param X: Trajectory tensor with shape ``(n_trajectories, n_times, n_dimensions)``. :type X: np.ndarray :param times: Explicit time axis aligned with the time dimension. :type times: np.ndarray, optional :param values: Optional scalar overlay with shape ``(n_trajectories, n_times)``. :type values: np.ndarray, optional :param labels: Optional label per trajectory. :type labels: np.ndarray, optional :param smooth_window: Moving-average window applied independently to each already-valid trajectory when greater than 1. :type smooth_window: int, default=1 :param title: Figure title. :type title: str, default="Trajectory Plot" :param dimensions: Number of embedding dimensions to display. Must be 2 or 3. :type dimensions: int, default=2 :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 8) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :param cmap: Colormap used for scalar overlays. :type cmap: str, default="viridis" :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any :raises ValueError: If the input is not a native 3D trajectory tensor or if aligned arrays do not match the trajectory/time axes. .. seealso:: :obj:`plot_trajectory_metric_series`, :obj:`plotly_utils.plot_trajectory_interactive` .. py:function:: plot_trajectory_metric_series(series: Any, *, times: Optional[numpy.ndarray] = None, labels: Optional[numpy.ndarray] = None, title: str = 'Trajectory Metric', ylabel: str = 'Value', figsize: Tuple[int, int] = (10, 6), ax: Optional[matplotlib.pyplot.Axes] = None, interactive: bool = False) -> Union[matplotlib.pyplot.Figure, Any] Plot evaluated trajectory metric time series. :param series: One-dimensional series, two-dimensional ``(trajectory, time)`` array, or mapping of ``name -> timecourse``. :type series: Any :param times: Explicit time axis aligned with the time dimension. :type times: np.ndarray, optional :param labels: Optional trajectory labels aligned with the first axis of 2D inputs. :type labels: np.ndarray, optional :param title: Figure title. :type title: str, default="Trajectory Metric" :param ylabel: Y-axis label. :type ylabel: str, default="Value" :param figsize: Matplotlib figure size for static plots. :type figsize: tuple of int, default=(10, 6) :param ax: Existing axes to draw on. :type ax: matplotlib.axes.Axes, optional :param interactive: If ``True``, return the Plotly equivalent. :type interactive: bool, default=False :returns: Matplotlib figure for static plots or the Plotly figure returned by the interactive backend. :rtype: matplotlib.figure.Figure or Any .. seealso:: :obj:`plot_trajectory`, :obj:`plotly_utils.plot_trajectory_metric_series_interactive` .. py:function:: plot_channel_traces_interactive(data: numpy.ndarray, times: Optional[numpy.ndarray] = None, group_labels: Optional[numpy.ndarray] = None, channel_names: Optional[collections.abc.Sequence[str] | numpy.ndarray] = None, selected_channels: Optional[collections.abc.Sequence[int] | collections.abc.Sequence[str]] = None, group_name_map: Optional[dict[Any, str]] = None, color_map: Optional[dict[Any, str]] = None, title: str = 'Grouped Channel Time Series', xaxis_title: str = 'Time', yaxis_title: str = 'Amplitude', template: str = 'plotly_white', shared_xaxes: bool = True, vertical_spacing: float = 0.05, line_width: float = 2.0, opacity: float = 1.0, base_height: int = 300, row_height: int = 220, showlegend: bool = True) -> plotly.graph_objects.Figure Plot grouped channel traces as stacked interactive subplots. :param data: Three-dimensional array with shape ``(n_groups, n_channels, n_times)``. :type data: np.ndarray :param times: Explicit time axis aligned with the last dimension of ``data``. :type times: np.ndarray, optional :param group_labels: Labels aligned with the first axis of ``data``. :type group_labels: np.ndarray, optional :param channel_names: Channel names aligned with the channel axis. :type channel_names: sequence of str or np.ndarray, optional :param selected_channels: Channel indices or names to plot. When omitted, all channels are shown. :type selected_channels: sequence of int or sequence of str, optional :param group_name_map: Optional mapping from raw group labels to display names. :type group_name_map: dict, optional :param color_map: Optional mapping from raw group labels to trace colors. :type color_map: dict, optional :param title: Figure title. :type title: str, default="Grouped Channel Time Series" :param xaxis_title: X-axis label for the final row. :type xaxis_title: str, default="Time" :param yaxis_title: Y-axis label per subplot row. :type yaxis_title: str, default="Amplitude" :param template: Plotly layout template. :type template: str, default="plotly_white" :param shared_xaxes: Whether subplot rows share the same x-axis. :type shared_xaxes: bool, default=True :param vertical_spacing: Vertical spacing between subplot rows. :type vertical_spacing: float, default=0.05 :param line_width: Trace line width. :type line_width: float, default=2.0 :param opacity: Trace opacity. :type opacity: float, default=1.0 :param base_height: Base figure height before row scaling. :type base_height: int, default=300 :param row_height: Additional height per plotted row. :type row_height: int, default=220 :param showlegend: Whether to show the legend. :type showlegend: bool, default=True :returns: Interactive multi-row channel trace figure. :rtype: plotly.graph_objects.Figure :raises ValueError: If the input shape or aligned labels/names are invalid. :raises TypeError: If ``selected_channels`` contains unsupported selector types. .. 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 .. 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'.