uadapy.dr.vipurpca module

This module provides helper and plotting functions built on top of the VIPurPCA library for uncertainty-aware principal component analysis (PCA).

It enables the computation of eigenvectors under uncertainty and the visualization of distribution trajectories in principal component space.

For details on the VIPurPCA method, see the corresponding paper: https://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=10368349

uadapy.dr.vipurpca.compute_distribution_trajectories(distributions, n_components=2, n_frames=10, seed=55)

Compute trajectories of distributions under PCA with uncertainty.

For each distribution, PCA directions are sampled according to the propagated covariance of eigenvectors. Trajectories in the principal component space are then computed for each sample.

Parameters:

  • distributions (list of Distribution) – List of distribution objects with .mean() and .cov()

  • n_components (int, default=2) – Number of principal components to retain.

  • n_frames (int, default=10) – Number of trajectory samples to draw.

  • seed (int, default=55) – Random seed for reproducibility.

Returns:

trajectories – Trajectory coordinates in the selected PC plane for each sample. The first dimension corresponds to sampled eigenvector frames.

Return type:

ndarray of shape (n_frames + 1, n_samples, n_components)

uadapy.dr.vipurpca.compute_uncertain_projections(model, pcx=1, pcy=2, n_samples=1000, seed=55)

Computes projected distributions for VIPurPCA model eigenvector samples.

Parameters:

  • model (vipurpca.PCA) – Fitted VIPurPCA model with computed eigenvectors and eigenvector covariance.

  • pcx (int) – 1-based indices of principal components to return.

  • pcy (int) – 1-based indices of principal components to return.

  • n_samples (int, default=1000) – Number of eigenvector samples to draw.

  • seed (int, default=55) – Random seed for reproducibility.

Returns:

projected_distributions – list of Distribution objects (one per data point)

Return type:

list

uadapy.dr.vipurpca.draw_loading_arrows(model, ax, pcx=1, pcy=2, feature_names=None, point_names=None, arrow_scale=1.0, arrow_color='red', arrow_lw=2.0, arrow_head_width=0.2, arrow_head_length=0.4, point_label_fontsize=9, feature_label_fontsize=10, show_uncertainty=False, n_std=1.0, wedge_fill_alpha=0.15, wedge_line_alpha=0.5)

Draws PCA loading arrows for each feature and labels each data point at its mean score position onto existing axes. Optionally draws an angular uncertainty wedge around each loading arrow.

Parameters:

  • model (vipurpca.PCA) – Fitted VIPurPCA model with computed eigenvectors and eigenvector covariance.

  • ax (matplotlib.axes.Axes) – Existing axes to draw onto.

  • pcx (int, optional) – 1-based index of the PC to use as the x-axis. Defaults to 1.

  • pcy (int, optional) – 1-based index of the PC to use as the y-axis. Defaults to 2.

  • feature_names (list of str, optional) – Names for each feature used to label loading arrows. Defaults to [‘x1’, ‘x2’, …] if not provided.

  • point_names (list of str, optional) – Names for each data point used to label score positions. Defaults to [‘P1’, ‘P2’, …] if not provided.

  • arrow_scale (float, optional) – Multiplicative scaling factor applied to all loading arrows relative to the plot range. Defaults to 1.0.

  • arrow_color (str, optional) – Color of loading arrows, feature labels, and uncertainty wedges. Defaults to ‘red’.

  • arrow_lw (float, optional) – Line width of the loading arrows. Defaults to 2.0.

  • arrow_head_width (float, optional) – Width of the arrow head. Defaults to 0.2.

  • arrow_head_length (float, optional) – Length of the arrow head. Defaults to 0.4.

  • point_label_fontsize (int, optional) – Font size for data point labels drawn at score positions. Defaults to 9.

  • feature_label_fontsize (int, optional) – Font size for feature name labels drawn at arrow tips. Defaults to 10.

  • show_uncertainty (bool, optional) – If True, draws an angular uncertainty wedge around each loading arrow using the covariance of eigenvectors from the model. Defaults to False.

  • n_std (float, optional) – Number of standard deviations used for the wedge half-width. Defaults to 1.0.

  • wedge_fill_alpha (float, optional) – Opacity of the uncertainty wedge filled region. Defaults to 0.15.

  • wedge_line_alpha (float, optional) – Opacity of the dashed wedge boundary lines. Defaults to 0.5.

Returns:

ax – The input axes with loading arrows, feature labels, point labels, and optional uncertainty wedges drawn in-place.

Return type:

matplotlib.axes.Axes

uadapy.dr.vipurpca.draw_pc_wedge(res, ax, line_len, label, fill_alpha, line_alpha, n_std)

Draws a single PC directional uncertainty wedge (lines + filled region) onto existing axes.

Parameters:

  • res (dict) – Single entry from estimate_pc_direction_uncertainty output, with keys ‘pc’, ‘mu’ (unit vector), ‘sigma’ (float, radians).

  • ax (matplotlib.axes.Axes) – Axes to draw onto.

  • line_len (float) – Half-length of the direction lines (typically from ax xlim/ylim).

  • label (str) – Legend label for this PC line.

  • fill_alpha (float) – Opacity of the uncertainty wedge fill.

  • line_alpha (float) – Opacity of the direction lines.

  • n_std (float) – Number of std deviations for the wedge width.

Returns:

ax – The input axes with the PC direction line, dashed uncertainty boundary lines, and filled wedge added in-place.

Return type:

matplotlib.axes.Axes

uadapy.dr.vipurpca.estimate_pc_direction_uncertainty(mean_w_matrix, cov_eigenvectors, n_samples=1000, seed=55)

Estimate principal-direction mean and angular uncertainty for N-dimensional PCs.

For each PC, samples directions from the Gaussian uncertainty, resolves sign ambiguity, computes the Frechet mean direction, and estimates angular spread via signed tangent-plane projection.

Parameters:

  • mean_w_matrix (array-like of shape (p, n_components)) – Eigenvector matrix from model.eigenvectors. Each column is one principal component direction.

  • cov_eigenvectors (array-like of shape (n_components*p, n_components*p)) – Joint covariance of all eigenvector weights from model.cov_eigenvectors.

  • n_samples (int, default=1000) – Number of Monte Carlo samples per PC.

  • seed (int, default=55) – Random seed for reproducibility.

Returns:

results –

Each dict contains:

’pc’ : int - PC index (1-based) ‘mu’ : ndarray (p,) - unit mean direction vector ‘sigma’ : float - angular standard deviation in radians

Return type:

list of dict, one per PC

uadapy.dr.vipurpca.fit_distribution_pca(dists, n_components=2)

Fit an uncertainty-aware PCA model on a set of distributions and return the full PCA model.

Parameters:

  • dists (list of Distribution) – List of distribution objects with .mean() and .cov().

  • n_components (int, default=2) – Number of principal components to retain.

Returns:

model – A fitted VIPurPCA PCA model. The returned object exposes both standard PCA outputs and uncertainty-related quantities needed for distribution plots.

Return type:

vipurpca.PCA