configuration_plot#

ktch.plot.configuration_plot(data: DataFrame | ndarray, *, x: str = 'x', y: str = 'y', z: str | None = None, links: Sequence[Sequence[int]] | None = None, ax: object | None = None, hue: str | None = None, hue_order: Sequence | None = None, palette: str | Sequence | None = None, color: str = 'gray', color_links: str | None = None, style: str | None = None, s: float = 10, alpha: float = 1.0) → object[source]#

Plot configurations of landmarks.

Visualizes one or more configurations of landmarks (specimens) as scatter points with optional line segments connecting landmarks. Supports both 2D and 3D data.

Parameters:
datapandas.DataFrame or numpy.ndarray

Landmark coordinates. Accepts:

  • A DataFrame with MultiIndex (specimen_id, coord_id) for multiple specimens.

  • A DataFrame with a single coord_id index for one specimen (e.g., data.coords.loc[0]).

  • A 2D array of shape (n_landmarks, n_dim) for a single specimen.

  • A 3D array of shape (n_specimens, n_landmarks, n_dim) for multiple specimens.

xstr, default=”x”

Column name for x coordinates.

ystr, default=”y”

Column name for y coordinates.

zstr or None, default=None

Column name for z coordinates. If given, a 3D plot is produced.

linkssequence of sequence of int, optional

Pairs of coord_id values to connect with line segments, e.g., [[0, 1], [1, 2]].

axmatplotlib.axes.Axes or None, default=None

Target axes. If None, a new figure and axes are created. For 3D plots (z is not None), a projection='3d' axes is required; one is created automatically when ax=None.

huestr or None, default=None

Column name (after reset_index()) for color grouping, e.g., "specimen_id". When hue is active, color and color_links are ignored and colors are determined by the palette.

hue_ordersequence or None, default=None

Order of hue categories. If None, uses the order of appearance.

palettestr, sequence, dict, or None, default=None

Seaborn palette name, explicit color list, or a dict mapping hue values to colors. A dict must contain all values in hue_order.

colorstr, default=”gray”

Point color when hue is None.

color_linksstr or None, default=None

Link color when hue is None. If None, uses color.

stylestr or None, default=None

Column name for marker style differentiation (2D only, passed to seaborn.scatterplot). Ignored for 3D plots.

sfloat, default=10

Marker size.

alphafloat, default=1.0

Transparency for both points and links.

Returns:
axmatplotlib.axes.Axes

The axes with the plot.