API Reference

This package contains functions to apply lenses and work with UMAP models.

lensed_umap.apply_lens(projector, values, resolution=5, circular=False, discretization='regular', skip_embedding=False, reset_local_connectivity=False, ret_bins=False, **kwargs)

Filters edges from a UMAP model that cross-over segments in discretised lens dimensions.

Discretises the given lenses into segments. Only edges within one segment, or to a direct neighbour segment are kept.

Parameters:
projectorUMAP

A fitted UMAP object to apply the lens to. Only the computed graph is needed, so some compute time can be safed by specifying ‘transform_mode=”graph”’ when constructing the UMAP object.

valuesarray_like

The 1 dimensional values to serve as lens dimension.

resolutionint, default=5

The number of segments to create in the lens.

circularbool, default=False

A flag indicating wether the extrema should be seen as neighbours.

discretizationstr, default=’regular’

A flag indicating which discretization strategy to apply:

  • ‘regular’ -> each segment contains the same value-range.

  • ‘balanced’ -> each segment contains the same number of points.

skip_embeddingbool, default=False

A flag indicating whether to skip computing the embedding.

reset_local_connectivitybool, default=False

A flag to enable normalising edge weights after applying the lens.

UMAP’s embedding assumes each point has at least one fully connected edge. This assumption can be enforced by enabling this flag. Embeddings tend to vary more smoothly when this setting is enabled.

ret_binsbool, default=False

A flag to return an array with each points’ bin id.

**kwargsdict, otpional

UMAP arguments to overwrite projector’s values. These can overwrite layout parameters to fine-tune the filtered embedding.

Returns:
cloneUMAP

A clone of projector with filtered graph_ and updated embedding_.

Other attributes are soft-copies, modifying them also modifies the input object’s attributes!

lensed_umap.apply_local_mask(projector, values, metric='euclidean', metric_kwds=None, n_neighbors=5, skip_embedding=False, reset_local_connectivity=False, **kwargs)

Filters the given UMAP model by keeping only each points’ n_neighbors closest edges by the metric over the lens values.

Computes the distance for each edge in the UMAP model, and keeps the n_neigbhors closest ones.

Parameters:
projectorUMAP

A fitted UMAP object to apply the lens to. Only the computed graph is needed, so some compute time can be safed by specifying ‘transform_mode=”graph”’ when constructing the UMAP object.

valuesarray_like

The values to serve as lens dimensions, which are used to compute lens-distances.

metricstring or function, default=’euclidean’

The metric to use to compute distances in high dimensional space. If a string is passed it must match a valid predefined metric. If a general metric is required a function that takes two 1d arrays and returns a float can be provided. For performance purposes it is required that this be a numba jit’d function. Valid string metrics include:

  • euclidean (or l2)

  • manhattan (or l1)

  • cityblock

  • braycurtis

  • canberra

  • chebyshev

  • correlation

  • cosine

  • dice

  • hamming

  • jaccard

  • kulsinski

  • ll_dirichlet

  • mahalanobis

  • matching

  • minkowski

  • rogerstanimoto

  • russellrao

  • seuclidean

  • sokalmichener

  • sokalsneath

  • sqeuclidean

  • yule

  • wminkowski

Metrics that take arguments (such as minkowski, mahalanobis etc.) can have arguments passed via the metric_kwds dictionary. At this time care must be taken and dictionary elements must be ordered appropriately; this will hopefully be fixed in the future.

metric_kwdsdict, default={}

Arguments to pass on to the metric, such as the p value for Minkowski distance. Should be in calling order.

n_neighborsint, default=10

The number of edges to keep for each point. Should be lower than the value used on Projector.

skip_embeddingbool, default=False

A flag indicating whether to skip computing the embedding.

reset_local_connectivitybool, default=False

A flag to enable normalising edge weights after applying the lens.

UMAP’s embedding assumes each point has at least one fully connected edge. This assumption can be enforced by enabling this flag. Embeddings tend to vary more smoothly when this setting is enabled.

**kwargsdict, optional

UMAP arguments to overwrite projector’s values. These can overwrite layout parameters to fine-tune the filtered embedding.

Returns:
cloneUMAP

A clone of projector with filtered graph_ and updated embedding_.

Other attributes are soft-copies, modifying them also modifies the input object’s attributes!

lensed_umap.apply_mask(projector, masker, skip_embedding=False, reset_local_connectivity=False, **kwargs)

Filters edges from a UMAP model that do not exist in the mask-model.

Parameters:
projectorUMAP

A fitted UMAP object to apply the lens to. Only the computed graph is needed, so some compute time can be safed by specifying ‘transform_mode=”graph”’ when constructing the UMAP object.

maskerUMAP

A fitted UMAP object to serve as mask for the lens. Only the computed graph is needed, so some compute time can be safed by specifying ‘transform_mode=”graph”’ when constructing the UMAP object.

skip_embeddingbool, default=False

A flag indicating whether to skip computing the embedding.

reset_local_connectivitybool, default=False

A flag to enable normalising edge weights after applying the lens.

UMAP’s embedding assumes each point has at least one fully connected edge. This assumption can be enforced by enabling this flag. Embeddings tend to vary more smoothly when this setting is enabled.

**kwargsdict, optional

UMAP arguments to overwrite projector’s values. These can overwrite layout parameters to fine-tune the filtered embedding.

Returns:
cloneUMAP

A clone of projector with filtered graph_ and updated embedding_.

Other attributes are soft-copies, modifying them also modifies the input object’s attributes!

lensed_umap.embed_graph(projector, repulsion_strengths=None, epoch_sequence=None)

(Re)-Computes UMAP embedding of (fitted) UMAP projector. Uses the current embedding as initialisation if one is present.

Parameters:
projectorUMAP

A fitted UMAP object (at least with transform_mode=’graph’). The embedding_ field will be created or updated if present.

repulsion_strengthslist of float, optional

Runs embedding procedure with given repulsion strengths in sequence, allowing fine-grained repulsion ramps that can improve convergence. Defaults to the projector’s repulsion_strength attribute.

epoch_sequencelist of int, optional

The number of epochs to run each repulsion strength. If not given, uses the projector’s n_epochs attribute.

Returns
——-
projectorUMAP

Projector with filled embedding_ field.

This return value is provided to chain functions but can be ignored as the given UMAP object is updated inplace.

lensed_umap.extract_embedding(projector)

Returns the first two embedding coordinates as individual variables.

Parameters:
projectorUMAP

A fitted UMAP object to extract the embedding from.

The returned arrays are views into embedding_.

Returns:
x, yarray_like

Views with the embedded coordinates.

Changes to the returned variables also change the original UMAP object’s embedding_ field.

lensed_umap.tile_components(projector, component_labels, secondary_axis=None, padding=20)

Tiles connected components along the vertical axis. Ensures the within-component structure remains visible. Maintains component order (as indicated by their) label value and centers components horizontally (after PCA transformation).

Parameters:
projectorUMAP

A fitted UMAP object with embedding computed.

The embedding is updated inplace.

component_labelsarray_like

An integer label (zero to N) indicating which connected component each point belongs to.

secondary_axisarray_like

A feature to align along the horizontal axis. Components are flipped to have the highest correlation between their x-coordinate and the given feature.

paddingint, default=20

A padding percentage to separate each component.

Returns:
projectorUMAP

The fitted UMAP object with updated embedding.

This return value is provided to chain functions but can be ignored as the given UMAP object is updated inplace.