uadapy.dr package

uadapy.dr.uamds module

This module contains functions that implement the uncertainty aware multidimensional scaling (UAMDS) algorithm. This is a dimensionality reduction algorithm for sets of normally distributed random vectors (i.e. multivariate normal distributions). See the corresponding paper at https://doi.org/10.1109/TVCG.2022.3209420.

Copyright: (c) 2024 David Haegele, Patrick Paetzold, Ruben Bauer, Marina Evers

License: MIT

uadapy.dr.uamds.apply_uamds(means: list[ndarray], covs: list[ndarray], target_dim=2) → dict[str, list[ndarray] | float]

Applies UAMDS to the specified normal distributions (given as means and covariance matrices).

Parameters:

  • means (list) – list of vectors that resemble the means of the normal distributions

  • covs (list) – list of matrices that resemble the covariances of the normal distributions

  • target_dim (int) – the dimensionality of the projection space, 2 by default

Returns:

dictionary containing the results:

['means']: list of projected means
['covs']: list of projected covariances
['translations']: list of low-dimensional translation vectors for affine transform of high-dimensional means
['projection']: list of projection matrices for affine transform of high-dimensional means and covs
['stress']: remaining stress of the projection

Return type:

dict

uadapy.dr.uamds.convert_xform_affine_to_uamds(normal_distr_spec: ndarray, affine_transforms: ndarray) → ndarray

Does the opposite of convert_xform_uamds_to_affine.

Parameters:

  • normal_distr_spec (np.ndarray) – normal distributions specification (means followed by covariance matrices)

  • affine_transforms (np.ndarray) – affine transformations for each distribution (low-dim translations followed by projection matrices)

Returns:

uamds transforms for each distribution. This is a matrix starting with n low-dimensional mean vectors followed by n distribution specific projection matrices B_i. The distribution specific projection matrix is the result of transforming it by the basis of the covariance matrix (cov=U*S*U’ -> B = U’*P).

uamds_transforms[:n,:] is the block of mean vectors
uamds_transforms[n:,:] is the block of local projection matrices

Return type:

np.ndarray

uadapy.dr.uamds.convert_xform_uamds_to_affine(normal_distr_spec: ndarray, uamds_transforms: ndarray) → ndarray

Converts the internally used and optimized transformations into generally applicable affine transformations. UAMDS optimizes an affine transform per distribution, each consisting of a projection matrix and translation vector. However, the transforms are reformulated with respect to their distribution to allow for more efficient computations of the stress and gradient. These are called the uamds_transforms and each of them live in their own coordinate system. What this method returns are these transformations, but all with respect to the same coordinate system.

Parameters:

  • normal_distr_spec (np.ndarray) – normal distributions specification (means followed by covariance matrices)

  • uamds_transforms (np.ndarray) – uamds transformations for each distribution (low-dim means followed by local projection matrices B_i)

Returns:

affine transforms for each distribution. This is a matrix starting with n translation vectors followed by n projection matrices. An affine transform is a function of the form f(x)=x*P+t where x is a high-dimensional point, P is a projection matrix into low-dimensional space, and t is a low-dimensional translation.

affine_transforms[:n,:] is the block of translation vectors
affine_transforms[n:,:] is the block of projection matrices

Return type:

np.ndarray

uadapy.dr.uamds.get_means_covs(normal_distr_spec: ndarray) → tuple[list[ndarray], list[ndarray]]

Separates the mean vectors and covariance matrices from the stacked normal distributions specification format.

Parameters:

normal_distr_spec (np.ndarray) – Normal distributions specification. Matrix starting with n row vectors (means) followed by n square matrices (covariances).

Returns:

a list of mean vectors and a list of covariance matrices

Return type:

tuple[list[np.ndarray], list[np.ndarray]]

uadapy.dr.uamds.gradient(normal_distr_spec: ndarray, uamds_transforms: ndarray, precalc_constants: tuple) → ndarray
uadapy.dr.uamds.iterate_simple_gradient_descent(normal_distr_spec: ndarray, uamds_transforms_init: ndarray, precalc_constants: tuple | None = None, n_iter: int = 100, a: float = 0.0001, optimizer='plain', b1: float = 0.9, b2: float = 0.999, e: float = 1e-07, mass=0.8) → ndarray

Performs gradient descent on the UAMDS stress to find an optimal projection. This uses a fixed number of iterations after which the method returns. There are 3 different gradient descent schemes to choose from. Alternatively, the method minimize_scipy(…) can be used to minimize the stress, which runs until convergence is reached.

Parameters:

  • normal_distr_spec (np.ndarray) – Normal distributions specification. Matrix starting with n row vectors (means) followed by n square matrices (covariances).

  • uamds_transforms_init (np.ndarray) – uamds transformations for each distribution (low-dim means followed by local projection matrices B_i)

  • precalc_constants (tuple) – a tuple containing the pre-computed constant expressions of the stress and gradient. Can be None and will be computed by precalculate_constants(normal_distr_spec)

  • n_iter (int) – number of iterations to perform. The required number of iterations varies with the used descent scheme.

  • a (float) – step size (learning rate). Depends on the size of the optimization problem and used descent scheme. Adam and momentum can usually employ larger learning rates than plain gradient descent.

  • optimizer (str) – one of ‘adam’, ‘momentum’, ‘plain’.

  • b1 (float) – only used with ‘adam’, exponential decay rate for the 1st moment estimates.

  • b2 (float) – only used with ‘adam’, exponential decay rate for the 2nd moment estimates

  • mass (flaot) – only used with ‘momentum’, mass parameter in ]0, 1[. When heavy, the descent direction changes only slightly by the current gradient in each iteration.

Returns:

the optimized uamds transforms. The method convert_xform_uamds_to_affine(normal_distr_spec, uamds_transforms) can be used to obtain the corresponding affine transformations.

Return type:

np.ndarray

uadapy.dr.uamds.minimize_scipy(normal_distr_spec: ndarray, uamds_transforms_init: ndarray, precalc_constants: tuple | None = None, method: str = 'BFGS') → ndarray

Minimizes the UAMDS stress using scipy.optimize. This will run until scipy’s optimization routine is returning, i.e., until convergence is reached. Alternatively, the method iterate_simple_gradient_descent(…) can be used to perform a fixed number of gradient descent iterations.

Parameters:

  • normal_distr_spec (np.ndarray) – Normal distributions specification. Matrix starting with n row vectors (means) followed by n square matrices (covariances).

  • uamds_transforms_init (np.ndarray) – uamds transformations for each distribution (low-dim means followed by local projection matrices B_i)

  • precalc_constants (tuple) – a tuple containing the pre-computed constant expressions of the stress and gradient. Can be None and will be computed by precalculate_constants(normal_distr_spec)

  • method (str) – an unconstrained scipy optimization method, ‘BFGS’ by default.

Returns:

the optimal uamds transforms. The method convert_xform_uamds_to_affine(normal_distr_spec, uamds_transforms) can be used to obtain the corresponding affine transformations.

Return type:

np.ndarray

uadapy.dr.uamds.mk_normal_distr_spec(means: list[ndarray], covs: list[ndarray]) → ndarray

Creates a normal distributions specification matrix for the provided means and covariance matrices. This is a matrix starting with n row vectors (means) followed by n square matrices (covariances).

Parameters:

  • means (list[np.ndarray]) – list of mean vectors

  • covs (list[list[np.ndarray]]) – list of covariance matrices

Returns:

normal distributions specification, n means followed by n covariance matrices

Return type:

np.ndarray

uadapy.dr.uamds.perform_projection(normal_distr_spec: ndarray, uamds_transforms: ndarray) → ndarray

Projects the distributions specified in normal_distr_spec using the provided uamds_transforms.

Parameters:

  • normal_distr_spec (np.ndarray) – Normal distributions specification. Matrix starting with n row vectors (means) followed by n square matrices (covariances).

  • uamds_transforms (np.ndarray) – uamds transformations for each distribution (low-dim means followed by local projection matrices B_i)

Returns:

projected normal distributions in the normal distribution specification format (block of means followed by block of covariance matrices).

Return type:

np.ndarray

uadapy.dr.uamds.precalculate_constants(normal_distr_spec: ndarray) → tuple

Computes constant expressions used in the stress and gradient calculations. These constants are specific properties of the individual distributions, e.g. the SVDs of the covariance matrices, or relationships beetween the distributions, such as the pairwise squared distances between the distribution means (similar to the dissimilarity matrix in regular MDS).

Parameters:

normal_distr_spec (np.ndarray) – normal distributions specification (block of means followed by block of covariance matrices)

Returns:

a tuple containing the computed constant expressions

Return type:

tuple

uadapy.dr.uamds.stress(normal_distr_spec: ndarray, uamds_transforms: ndarray, precalc_constants: tuple | None = None) → float
uadapy.dr.uamds.uamds(distributions: list, n_dims: int = 2, seed: int = 0)

Applies the UAMDS algorithm to the provided distributions and returns the projected distributions in lower-dimensional space. It assumes multivariate normal distributions. If you supply other distributions that provide mean and covariance, these values would be used to approximate a normal distribution.

Parameters:

  • distributions (list) – list of input distributions (distribution objects offering mean() and cov() methods)

  • n_dims (int) – target dimensionality, 2 by default.

  • seed (int) – Set the random seed for the initialization, 0 by default

Returns:

List of distributions living in projection space (i.e. of provided dimensionality)

Return type:

list

uadapy.dr.uapca module

uadapy.dr.uapca.compute_ua_cov(means: ndarray, covs: ndarray) → ndarray
uadapy.dr.uapca.compute_uapca(means: ndarray, covs: ndarray) → tuple[ndarray, ndarray]
uadapy.dr.uapca.transform_uapca(means, covs, dims: int = 2) → tuple[ndarray, ndarray]
uadapy.dr.uapca.uapca(distributions, n_dims: int = 2)

Applies UAPCA algorithm to the distribution and returns the distribution in lower-dimensional space. It assumes a normal distributions. If you apply other distributions that provide mean and covariance, these values would be used to approximate a normal distribution :param distributions: List of input distributions :param n_dims: Target dimension :return: List of distributions in low-dimensional space

Module contents