shape_variation_plot#

ktch.plot.shape_variation_plot(reducer: Any | None = None, *, descriptor: Any | None = None, descriptor_inverse_transform: Callable[[ndarray], ndarray] | None = None, reducer_inverse_transform: Callable[[ndarray], ndarray] | None = None, explained_variance: ndarray | None = None, n_components: int | None = None, components: Sequence[int] = (0, 1, 2), sd_values: Sequence[float] = (-2.0, -1.0, 0.0, 1.0, 2.0), shape_type: str = 'auto', render_fn: Callable[[...], None] | None = None, n_dim: int | None = None, links: Sequence[Sequence[int]] | None = None, color: str = 'gray', alpha: float = 1.0, fig: object | None = None, dpi: int = 150, figscale: float = 3.0, **render_kw: Any) → object[source]#

Plot reconstructed shapes along component axes.

Creates a grid of subplots showing shape variation along dimensionality reduction (reducer) component axes. Each row corresponds to a component, each column to a standard deviation multiplier.

The function uses a two-stage inverse transform pipeline: scores -> [reducer_inverse_transform] -> coefficients -> [descriptor_inverse_transform] -> shape coordinates.

Parameters:
reducerfitted estimator, optional

Fitted dimensionality reduction object (e.g., sklearn.decomposition.PCA). Convenience parameter that extracts reducer_inverse_transform via .inverse_transform, explained_variance via .explained_variance_, and n_components via .n_components_ (fallback to .n_components).

descriptorfitted estimator, optional

Fitted shape descriptor (e.g., EllipticFourierAnalysis). Convenience parameter that extracts descriptor_inverse_transform via .inverse_transform. For GPA (landmarks): pass None.

descriptor_inverse_transformcallable, optional

Converts coefficient vectors to shape coordinates. Overrides descriptor.inverse_transform. For SHA resolution control, wrap with a lambda: lambda c: sha.inverse_transform(c, theta_range=..., phi_range=...).

reducer_inverse_transformcallable, optional

Converts low-dimensional scores to coefficient space. Overrides reducer.inverse_transform.

explained_variancendarray, optional

Variance per component for SD calculation. Overrides reducer.explained_variance_.

n_componentsint, optional

Total number of components. Overrides reducer.n_components_.

componentssequence of int

0-indexed component indices to display as rows.

sd_valuessequence of float

Standard deviation multipliers for columns.

shape_typestr

Shape rendering type. One of "auto", "curve_2d", "curve_3d", "surface_3d", "landmarks_2d", "landmarks_3d".

render_fncallable, optional

Custom renderer (coords, ax, **kw) -> None. Overrides shape_type.

n_dimint, optional

Spatial dimensionality (for reshape in GPA identity case). Required when descriptor is not provided, unless shape_type is an explicit landmarks type.

linkssequence of sequence of int, optional

Landmark link pairs (e.g., [[0, 1], [1, 2]]).

colorstr

Shape color.

alphafloat

Shape transparency.

figmatplotlib.figure.Figure, optional

Existing figure. If None, a new one is created.

dpiint

Figure resolution (used only when creating a new figure).

figscalefloat

Scale factor for figure size.

**render_kw

Forwarded to the renderer.

Returns:
figmatplotlib.figure.Figure

The figure containing the shape grid.

Raises:
ImportError

If matplotlib is not installed.

ValueError

If required parameters cannot be resolved.

See also

morphospace_plot

Scatter plot with shape insets in morphospace.

explained_variance_ratio_plot

Scree plot of explained variance.

Notes

When shape_type="auto" (the default), the type is inferred from the output of the descriptor inverse transform:

  • 4-D array -> "surface_3d"

  • 3-D array with last dimension 2 -> "curve_2d"

  • 3-D array with last dimension 3 -> "curve_3d"

  • No descriptor (identity / GPA case) with n_dim=2 -> "landmarks_2d"

  • No descriptor (identity / GPA case) with n_dim=3 -> "landmarks_3d"

For 3-D arrays with shape[-1] == 3, auto-detection chooses "curve_3d". If the data represents landmarks, specify shape_type="landmarks_3d" explicitly.

Examples

>>> from sklearn.decomposition import PCA
>>> from ktch.harmonic import EllipticFourierAnalysis
>>> from ktch.plot import shape_variation_plot
>>> efa = EllipticFourierAnalysis(n_harmonics=20)
>>> coeffs = efa.fit_transform(outlines_2d)
>>> pca = PCA(n_components=10).fit(coeffs)
>>> fig = shape_variation_plot(pca, descriptor=efa)
On this page

This Page