featuremap.featuremap_ ====================== .. py:module:: featuremap.featuremap_ Attributes ---------- .. autoapisummary:: featuremap.featuremap_.INT32_MIN featuremap.featuremap_.INT32_MAX featuremap.featuremap_.SMOOTH_K_TOLERANCE featuremap.featuremap_.MIN_K_DIST_SCALE featuremap.featuremap_.NPY_INFINITY featuremap.featuremap_.DISCONNECTION_DISTANCES Classes ------- .. autoapisummary:: featuremap.featuremap_.FeatureMAP Functions --------- .. autoapisummary:: featuremap.featuremap_.kernel_density_estimate featuremap.featuremap_.local_svd featuremap.featuremap_.graph_convolution featuremap.featuremap_.tangent_space_approximation featuremap.featuremap_.project_gauge_to_knn_graph featuremap.featuremap_.recover_gauge_from_embedding featuremap.featuremap_.tangent_space_embedding featuremap.featuremap_.variation_embedding featuremap.featuremap_.simplicial_set_embedding_with_tangent_space_embedding featuremap.featuremap_.clip featuremap.featuremap_.rdist featuremap.featuremap_.optimize_layout_euclidean_anisotropic_projection Module Contents --------------- .. py:data:: INT32_MIN .. py:data:: INT32_MAX .. py:data:: SMOOTH_K_TOLERANCE :value: 1e-05 .. py:data:: MIN_K_DIST_SCALE :value: 0.001 .. py:data:: NPY_INFINITY .. py:data:: DISCONNECTION_DISTANCES .. py:function:: kernel_density_estimate(data, X, bw=0.5, min_radius=5, output_onlylogp=False) Density estimation for data points specified by X with kernel density estimation. :param data: 2D array including data points. Input to density estimation. :type data: array of shape (n_samples, n_features) :param X: 2D array including multiple data points. Input to density estimation. :type X: array :param output_onlylogp: If true, returns logp, else returns p, g, h, msu. :type output_onlylogp: bool :returns: **p** -- 1D array. Unnormalized probability density. The probability density is not normalized due to numerical stability. Exact log probability :rtype: array .. py:function:: local_svd(data, knn_index, neighbor_weights, n_neighbors=15, n_neighbors_in_guage=30) Local singular value decomposition (SVD) for each node in the data :param data: The source data to be embedded by FeatureMAP. :type data: array of shape (n_samples, n_features) :param knn_index: The index of k-nearest neighbors for each node :type knn_index: array of shape (n_samples, n_neighbors) :param weight: The weight matrix of the graph :type weight: array of shape (n_samples, n_samples) :param n_neighbors: The number of nearest neighbors :type n_neighbors: int :param n_neighbors_in_guage: The number of nearest neighbors for local SVD :type n_neighbors_in_guage: int :returns: * **gauge_u** (*list of shape (n_neighbors_in_guage, n_neighbors_in_guage); store u*) * **singular_values** (*list of shape (n_neighbors_in_guage,); store single values for each frame*) * **gauge_vh** (*list of shape (n_neighbors_in_guage, d); store v*) .. py:function:: graph_convolution(features, knn_index, num_iterations, verbose=False, memory_target_mb=256, backend='auto') Perform iterative neighbor averaging as a simple graph convolution. :param features: Input feature matrix of shape (num_nodes, num_features, num_channels). :type features: np.ndarray :param knn_index: Nearest neighbor indices of shape (num_nodes, num_neighbors). :type knn_index: np.ndarray :param num_iterations: Number of smoothing iterations. Default is 20. :type num_iterations: int, optional :returns: Smoothed feature matrix after `num_iterations` iterations. dict: Dictionary storing the first averaged result under the key "VH". :rtype: np.ndarray .. py:function:: tangent_space_approximation(data, graph, featuremap_kwds) Compute the origial gauge in high-dimensional data by local SVD :param data: The source data to be embedded by FeatureMAP. :type data: array of shape (n_samples, n_features) :param graph: The 1-skeleton of the high dimensional fuzzy simplicial set as represented by a graph for which we require a sparse matrix for the (weighted) adjacency matrix. :type graph: sparse matrix :param featuremap_kwds: Key word arguments to be used by the FeatureMAP optimization. :type featuremap_kwds: dict :rtype: Local tangent space U, S, V .. py:function:: project_gauge_to_knn_graph(data, graph, featuremap_kwds, scale=10, use_negative_cosines=False) Project the gauge (rotation matrix) to the KNN graph and compute the transition probability matrix Modified from the scVelo: https://scvelo.readthedocs.io/en/stable/scvelo.utils.get_transition_matrix.html#scvelo.utils.get_transition_matrix :param data: The source data to be embedded by FeatureMAP. :type data: array of shape (n_samples, n_features) :param graph: The 1-skeleton of the high dimensional fuzzy simplicial set as represented by a graph for which we require a sparse matrix for the (weighted) adjacency matrix. :type graph: sparse matrix :param featuremap_kwds: Key word arguments to be used by the FeatureMAP optimization. :type featuremap_kwds: dict :param scale: The scale factor for the transition probability matrix :type scale: float :param use_negative_cosines: Whether to use negative cosine similarity in the transition probability matrix :type use_negative_cosines: bool :returns: **transition_matrix** -- The transition probability matrix :rtype: array of shape (n_samples, n_samples) .. py:function:: recover_gauge_from_embedding(data_embedding, featuremap_kwds) Recover the gauge from the low-dimensional embedding :param data_embedding: The low-dimensional embedding of the data :type data_embedding: array of shape (n_samples, n_components) :param featuremap_kwds: :type featuremap_kwds: dict :returns: * **gauge_v1_emb** (*array of shape (n_samples, n_components)*) -- The recovered gauge v1 in low dimesional space * **gauge_v2_emb** (*array of shape (n_samples, n_components)*) -- The recovered gauge v2 in low dimensional space .. py:function:: tangent_space_embedding(featuremap_kwds) Embedding the gauge (rotation matrix) to low dim space :param featuremap_kwds: Key word arguments to be used by the FeatureMAP optimization. :type featuremap_kwds: dict .. py:function:: variation_embedding(data, featuremap_kwds) Compute the variation embedding of the data :param data: The source data to be embedded by FeatureMAP. :type data: array of shape (n_samples, n_features) :param featuremap_kwds: Key word arguments to be used by the FeatureMAP optimization. :type featuremap_kwds: dict :returns: **emb_variation** -- The optimized of ``graph`` of variation into an ``n_components`` dimensional euclidean space. :rtype: array of shape (n_samples, n_components) .. py:function:: simplicial_set_embedding_with_tangent_space_embedding(data, graph, n_components, initial_alpha, a, b, gamma, negative_sample_rate, n_epochs, init, random_state, metric, metric_kwds, featuremap_kwds, output_feat, output_metric=dist.named_distances_with_gradients['euclidean'], output_metric_kwds={}, euclidean_output=True, parallel=False, verbose=False, tqdm_kwds=None, output_variation=False) Perform a fuzzy simplicial set embedding, using a specified initialisation method and then minimizing the fuzzy set cross entropy between the 1-skeletons of the high and low dimensional fuzzy simplicial sets. :param data: The source data to be embedded by FeatureMAP. :type data: array of shape (n_samples, n_features) :param graph: The 1-skeleton of the high dimensional fuzzy simplicial set as represented by a graph for which we require a sparse matrix for the (weighted) adjacency matrix. :type graph: sparse matrix :param n_components: The dimensionality of the euclidean space into which to embed the data. :type n_components: int :param initial_alpha: Initial learning rate for the SGD. :type initial_alpha: float :param a: Parameter of differentiable approximation of right adjoint functor :type a: float :param b: Parameter of differentiable approximation of right adjoint functor :type b: float :param gamma: Weight to apply to negative samples. :type gamma: float :param negative_sample_rate: The number of negative samples to select per positive sample in the optimization process. Increasing this value will result in greater repulsive force being applied, greater optimization cost, but slightly more accuracy. :type negative_sample_rate: int (optional, default 5) :param n_epochs: The number of training epochs to be used in optimizing the low dimensional embedding. Larger values result in more accurate embeddings. If 0 is specified a value will be selected based on the size of the input dataset (200 for large datasets, 500 for small). :type n_epochs: int (optional, default 0) :param init: How to initialize the low dimensional embedding. Options are: * 'spectral': use a spectral embedding of the fuzzy 1-skeleton * 'random': assign initial embedding positions at random. * A numpy array of initial embedding positions. :type init: string :param random_state: A state capable being used as a numpy random state. :type random_state: numpy RandomState or equivalent :param metric: The metric used to measure distance in high dimensional space; used if multiple connected components need to be layed out. :type metric: string or callable :param metric_kwds: Key word arguments to be passed to the metric function; used if multiple connected components need to be layed out. :type metric_kwds: dict :param featuremap_kwds: Key word arguments to be used by the FeatureMAP optimization. :type featuremap_kwds: dict output_metric: function Function returning the distance between two points in embedding space and the gradient of the distance wrt the first argument. output_metric_kwds: dict Key word arguments to be passed to the output_metric function. euclidean_output: bool Whether to use the faster code specialised for euclidean output metrics parallel: bool (optional, default False) Whether to run the computation using numba parallel. Running in parallel is non-deterministic, and is not used if a random seed has been set, to ensure reproducibility. verbose: bool (optional, default False) Whether to report information on the current progress of the algorithm. tqdm_kwds: dict Key word arguments to be used by the tqdm progress bar. :returns: **embedding** -- The optimized of ``graph`` into an ``n_components`` dimensional euclidean space. :rtype: array of shape (n_samples, n_components) .. py:class:: FeatureMAP(n_neighbors=15, n_components=2, metric='euclidean', metric_kwds=None, output_metric='euclidean', output_metric_kwds=None, n_epochs=None, learning_rate=1.0, init='spectral', min_dist=0.5, spread=1.0, low_memory=True, n_jobs=-1, set_op_mix_ratio=1.0, local_connectivity=1.0, repulsion_strength=1.0, negative_sample_rate=5, a=None, b=None, random_state=None, angular_rp_forest=False, transform_seed=42, transform_mode='embedding', force_approximation_algorithm=False, verbose=False, tqdm_kwds=None, unique=False, feat_lambda=0.5, feat_frac=0.3, feat_gauge_coefficient=1.0, feat_var_shift=0.1, output_feat=False, disconnection_distance=None, output_variation=False, threshold=0.9, gcn_iterations=None) Bases: :py:obj:`sklearn.base.BaseEstimator` Feature-preserving Manifold Approximation and Projection Approximate the high dimensional manifold of the input data by low dimensional embedding, with feature-preserving property. The algorithm is based on the paper: Feature-preserving manifold approximation and projection to visulize single-cell data, Yang et al. 2023. The algorithm is based on the UMAP algorithm, and the main difference is that FeatureMAP uses the tangent space of the input data to compute the (embedding) gauge for low dimensional embedding, where the features are locally illustrated by the embedding tangent space (i.e., gauge) and data points are embedded to the low dimensional space with the gauge. :param n_neighbors: The size of local neighborhood (in terms of number of neighboring sample points) used for manifold approximation. Larger values result in more global views of the manifold, while smaller values result in more local data being preserved. In general values should be in the range 2 to 100. :type n_neighbors: float (optional, default 15) :param n_components: The dimension of the space to embed into. This defaults to 2 to provide easy visualization, but can reasonably be set to any integer value in the range 2 to 100. :type n_components: int (optional, default 2) :param metric: The metric to use to compute distances in high dimensional space. :type metric: string (currently, only 'euclidean' is supported) :param n_epochs: The number of training epochs to be used in optimizing the low dimensional embedding. Larger values result in more accurate embeddings. If None is specified a value will be selected based on the size of the input dataset (200 for large datasets, 500 for small). :type n_epochs: int (optional, default None) :param learning_rate: The initial learning rate for the embedding optimization. :type learning_rate: float (optional, default 1.0) :param init: How to initialize the low dimensional embedding. Options are: * 'spectral': use a spectral embedding of the fuzzy 1-skeleton * 'random': assign initial embedding positions at random. * A numpy array of initial embedding positions. :type init: string (optional, default 'spectral') :param min_dist: The effective minimum distance between embedded points. Smaller values will result in a more clustered/clumped embedding where nearby points on the manifold are drawn closer together, while larger values will result on a more even dispersal of points. The value should be set relative to the ``spread`` value, which determines the scale at which embedded points will be spread out. :type min_dist: float (optional, default 0.5) :param spread: The effective scale of embedded points. In combination with ``min_dist`` this determines how clustered/clumped the embedded points are. :type spread: float (optional, default 1.0) :param low_memory: For some datasets the nearest neighbor computation can consume a lot of memory. If you find that FeatureMAP is failing due to memory constraints consider setting this option to True. This approach is more computationally expensive, but avoids excessive memory use. :type low_memory: bool (optional, default True) :param set_op_mix_ratio: Interpolate between (fuzzy) union and intersection as the set operation used to combine local fuzzy simplicial sets to obtain a global fuzzy simplicial sets. Both fuzzy set operations use the product t-norm. The value of this parameter should be between 0.0 and 1.0; a value of 1.0 will use a pure fuzzy union, while 0.0 will use a pure fuzzy intersection. :type set_op_mix_ratio: float (optional, default 1.0) :param local_connectivity: The local connectivity required -- i.e. the number of nearest neighbors that should be assumed to be connected at a local level. The higher this value the more connected the manifold becomes locally. In practice this should be not more than the local intrinsic dimension of the manifold. :type local_connectivity: int (optional, default 1) :param repulsion_strength: Weighting applied to negative samples in low dimensional embedding optimization. Values higher than one will result in greater weight being given to negative samples. :type repulsion_strength: float (optional, default 1.0) :param negative_sample_rate: The number of negative samples to select per positive sample in the optimization process. Increasing this value will result in greater repulsive force being applied, greater optimization cost, but slightly more accuracy. :type negative_sample_rate: int (optional, default 5) :param a: More specific parameters controlling the embedding. If None these values are set automatically as determined by ``min_dist`` and ``spread``. :type a: float (optional, default None) :param b: More specific parameters controlling the embedding. If None these values are set automatically as determined by ``min_dist`` and ``spread``. :type b: float (optional, default None) :param random_state: If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; If None, the random number generator is the RandomState instance used by `np.random`. :type random_state: int, RandomState instance or None, optional (default: None) :param metric_kwds: Arguments to pass on to the metric, such as the ``p`` value for Minkowski distance. If None then no arguments are passed on. :type metric_kwds: dict (optional, default None) :param angular_rp_forest: Whether to use an angular random projection forest to initialise the approximate nearest neighbor search. This can be faster, but is mostly on useful for metric that use an angular style distance such as cosine, correlation etc. In the case of those metrics angular forests will be chosen automatically. :type angular_rp_forest: bool (optional, default False) :param transform_seed: Random seed used for the stochastic aspects of the transform operation. This ensures consistency in transform operations. :type transform_seed: int (optional, default 42) :param verbose: Controls verbosity of logging. :type verbose: bool (optional, default False) :param tqdm_kwds: Key word arguments to be used by the tqdm progress bar. :type tqdm_kwds: dict (optional, defaul None) :param unique: Controls if the rows of your data should be uniqued before being embedded. If you have more duplicates than you have n_neighbour you can have the identical data points lying in different regions of your space. It also violates the definition of a metric. For to map from internal structures back to your data use the variable _unique_inverse_. :type unique: bool (optional, default False) :param featuremap: Specifies whether the featity-augmented objective of FeatureMAP should be used for optimization. Turning on this option generates an embedding where the local featities are encouraged to be correlated with those in the original space. Parameters below with the prefix 'feat' further control the behavior of this extension. :type featuremap: bool (optional, default False) :param feat_lambda: Controls the regularization weight of the anisotropic density correlation term in FeatureMAP. Higher values prioritize density preservation over the FeatureMAP objective, and vice versa for values closer to zero. Setting this parameter to zero is equivalent to running the original UMAP algorithm. :type feat_lambda: float (optional, default 2.0) :param feat_frac: Controls the fraction of epochs (between 0 and 1) where the feature-augmented objective is used in FeatureMAP. The first (1 - feat_frac) fraction of epochs optimize the original UMAP objective before introducing the anisotropic density correlation term. :type feat_frac: float (optional, default 0.3) :param feat_gauge_coefficient: A coefficient multiplication of n_neighbors as number of neighbors in gauge construction. Larger coefficient means long distance information :type feat_gauge_coefficient: float (default 1.0) :param feat_var_shift: A small constant added to the variance of local radii in the embedding when calculating the anisotropic density correlation objective to prevent numerical instability from dividing by a small number :type feat_var_shift: float (optional, default 0.1) :param output_feat: Whether to compute the embedding radius. If set to True, the algorithm will compute the embedding radius and return the embedding radius. :type output_feat: bool (optional, default False) :param disconnection_distance: Disconnect any vertices of distance greater than or equal to disconnection_distance when approximating the manifold via our k-nn graph. This is particularly useful in the case that you have a bounded metric. The UMAP assumption that we have a connected manifold can be problematic when you have points that are maximally different from all the rest of your data. The connected manifold assumption will make such points have perfect similarity to a random set of other points. Too many such points will artificially connect your space. :type disconnection_distance: float (optional, default np.inf or maximal value for bounded distances) :param output_variation: Whether to compute the variation embedding only. If set to True, the algorithm will compute the variation embedding only and return the embedding. If set to False, the algorithm will compute the Feature-augmented embedding. :type output_variation: bool (optional, default True) :param threshold: The threshold to compute the intrinsic dimensionality of the data. The intrinsic dimensionality is computed by the number of principal components that accumulates 90% of the variance of the data. :type threshold: float (optional, default 0.9) .. py:attribute:: n_neighbors :value: 15 .. py:attribute:: metric :value: 'euclidean' .. py:attribute:: output_metric :value: 'euclidean' .. py:attribute:: metric_kwds :value: None .. py:attribute:: output_metric_kwds :value: None .. py:attribute:: n_epochs :value: None .. py:attribute:: init :value: 'spectral' .. py:attribute:: n_components :value: 2 .. py:attribute:: repulsion_strength :value: 1.0 .. py:attribute:: learning_rate :value: 1.0 .. py:attribute:: spread :value: 1.0 .. py:attribute:: min_dist :value: 0.5 .. py:attribute:: low_memory :value: True .. py:attribute:: set_op_mix_ratio :value: 1.0 .. py:attribute:: local_connectivity :value: 1.0 .. py:attribute:: negative_sample_rate :value: 5 .. py:attribute:: random_state :value: None .. py:attribute:: angular_rp_forest :value: False .. py:attribute:: transform_seed :value: 42 .. py:attribute:: transform_mode :value: 'embedding' .. py:attribute:: force_approximation_algorithm :value: False .. py:attribute:: verbose :value: False .. py:attribute:: tqdm_kwds :value: None .. py:attribute:: unique :value: False .. py:attribute:: feat_lambda :value: 0.5 .. py:attribute:: feat_frac :value: 0.3 .. py:attribute:: feat_gauge_coefficient :value: 1.0 .. py:attribute:: feat_var_shift :value: 0.1 .. py:attribute:: output_feat :value: False .. py:attribute:: disconnection_distance :value: None .. py:attribute:: output_variation :value: False .. py:attribute:: threshold :value: 0.9 .. py:attribute:: gcn_iterations :value: None .. py:attribute:: n_jobs :value: -1 .. py:attribute:: a :value: None .. py:attribute:: b :value: None .. py:method:: fit(X) Fit X into an embedded space. :param X: If the metric is 'precomputed' X must be a square distance matrix. Otherwise it contains a sample per row. If the method is 'exact', X may be a sparse matrix of type 'csr', 'csc' or 'coo'. :type X: array, shape (n_samples, n_features) or (n_samples, n_samples) .. py:method:: fit_transform(X) Fit X into an embedded space and return that transformed output. :param X: If the metric is 'precomputed' X must be a square distance matrix. Otherwise it contains a sample per row. :type X: array, shape (n_samples, n_features) or (n_samples, n_samples) :returns: **X_new** -- Embedding of the training data in low-dimensional space. :rtype: array, shape (n_samples, n_components) .. py:method:: __repr__() .. py:function:: clip(val) Standard clamping of a value into a fixed range (in this case -4.0 to 4.0) :param val: The value to be clamped. :type val: float :rtype: The clamped value, now fixed to be in the range -4.0 to 4.0. .. py:function:: rdist(x, y) Reduced Euclidean distance. :param x: :type x: array of shape (embedding_dim,) :param y: :type y: array of shape (embedding_dim,) :rtype: The squared euclidean distance between x and y .. py:function:: optimize_layout_euclidean_anisotropic_projection(head_embedding, tail_embedding, head, tail, n_epochs, n_vertices, epochs_per_sample, a, b, rng_state, gamma=1.0, initial_alpha=1.0, negative_sample_rate=5.0, parallel=False, verbose=False, featuremap_kwds=None, tqdm_kwds=None, move_other=False) Improve an embedding using stochastic gradient descent to minimize the fuzzy set cross entropy between the 1-skeletons of the high dimensional and low dimensional fuzzy simplicial sets. In practice this is done by sampling edges based on their membership strength (with the (1-p) terms coming from negative sampling similar to word2vec). :param head_embedding: The initial embedding to be improved by SGD. :type head_embedding: array of shape (n_samples, n_components) :param tail_embedding: The reference embedding of embedded points. If not embedding new previously unseen points with respect to an existing embedding this is simply the head_embedding (again); otherwise it provides the existing embedding to embed with respect to. :type tail_embedding: array of shape (source_samples, n_components) :param head: The indices of the heads of 1-simplices with non-zero membership. :type head: array of shape (n_1_simplices) :param tail: The indices of the tails of 1-simplices with non-zero membership. :type tail: array of shape (n_1_simplices) :param n_epochs: The number of training epochs to use in optimization. :type n_epochs: int :param n_vertices: The number of vertices (0-simplices) in the dataset. :type n_vertices: int :param epochs_per_sample: A float value of the number of epochs per 1-simplex. 1-simplices with weaker membership strength will have more epochs between being sampled. :type epochs_per_sample: array of shape (n_1_simplices) :param a: Parameter of differentiable approximation of right adjoint functor :type a: float :param b: Parameter of differentiable approximation of right adjoint functor :type b: float :param rng_state: The internal state of the rng :type rng_state: array of int64, shape (3,) :param gamma: Weight to apply to negative samples. :type gamma: float (optional, default 1.0) :param initial_alpha: Initial learning rate for the SGD. :type initial_alpha: float (optional, default 1.0) :param negative_sample_rate: Number of negative samples to use per positive sample. :type negative_sample_rate: int (optional, default 5) :param parallel: Whether to run the computation using numba parallel. Running in parallel is non-deterministic, and is not used if a random seed has been set, to ensure reproducibility. :type parallel: bool (optional, default False) :param verbose: Whether to report information on the current progress of the algorithm. :type verbose: bool (optional, default False) :param featuremap: Whether to use the feature-augmented featuremap objective :type featuremap: bool (optional, default False) :param featuremap_kwds: Auxiliary data for featuremap :type featuremap_kwds: dict (optional, default None) :param tqdm_kwds: Keyword arguments for tqdm progress bar. :type tqdm_kwds: dict (optional, default None) :param move_other: Whether to adjust tail_embedding alongside head_embedding :type move_other: bool (optional, default False) :returns: **embedding** -- The optimized embedding. :rtype: array of shape (n_samples, n_components)