spectrochempy.plot_score

plot_score(scores, components=(1, 2), *, ax=None, clear=True, cmap=None, color=None, color_mapping='index', show_labels=False, labels_column=None, elev=None, azim=None, marker=None, s=None, alpha=None, show=True, **kwargs)[source]

Plot PCA scores as a 2D or 3D scatter plot.

Parameters:

  • scores (array-like or NDDataset) – Scores data with shape (n_samples, n_components). If an NDDataset, the data attribute is used.

  • components (tuple of int, optional) – Principal components to plot (1-based indexing). Length 2 for 2D plot, length 3 for 3D plot. Default: (1, 2).

  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure is created.

  • clear (bool, optional) – Whether to clear the axes before plotting. Default: True. Only used when ax is provided.

  • cmap (str or Colormap, optional) – Colormap for coloring points. Default: preferences.colormap_sequential.

  • color (color or array-like, optional) – If provided, use this color for all points (single color) or as color values for each point. Overrides color_mapping.

  • color_mapping ({β€œindex”, β€œlabels”}, optional) – Method for mapping colors to points:

    • "index" (default): Sequential colors by sample index.

    • "labels": Color by categorical labels from scores.y.labels. Adds a legend showing label categories.

  • show_labels (bool, optional) – If True, annotate each point with its label from scores.y.labels. Labels are placed intelligently using adjustText if available, otherwise shifted slightly from the marker position to avoid overlap. Default: False.

  • labels_column (int, optional) – Column index in scores.y.labels to use (0-based). If None, uses column 0 for color_mapping, or last column for show_labels.

  • elev (float, optional) – Elevation angle (degrees) for 3D plots. If None, uses preferences.axes3d_elev.

  • azim (float, optional) – Azimuth angle (degrees) for 3D plots. If None, uses preferences.axes3d_azim.

  • marker (str, optional) – Marker style for scatter points. Passed to ax.scatter. If None, uses matplotlib default.

  • s (float or array-like, optional) – Marker size(s) for scatter points. Passed to ax.scatter. If None, uses matplotlib default.

  • alpha (float, optional) – Transparency (0-1) for scatter points. If None, fully opaque.

  • show (bool, optional) – Whether to display the figure. Default: True.

  • **kwargs – Additional keyword arguments passed to ax.scatter.

Returns:

matplotlib.axes.Axes – The axes containing the scatter plot.

Raises:

ValueError – If components has invalid length (not 2 or 3). If component index exceeds available components. If color_mapping=”labels” but scores has no labels. If show_labels=True but scores has no y coordinate or labels.

Examples

>>> import spectrochempy as scp
>>> from spectrochempy import plot_score
>>> scores = scp.random(size=(50, 5))
>>> ax = plot_score(scores, components=(1, 2), show=False)

With label-based coloring:

>>> ax = plot_score(scores, color_mapping="labels", show=False)