featuremap

Submodules

• featuremap.core_transition_states
• featuremap.featuremap
• featuremap.features

Classes

FeatureMAP

Feature-preserving Manifold Approximation and Projection

Package Contents

class featuremap.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: 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.

Parameters:

• n_neighbors (float (optional, default 15)) – 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.

• n_components (int (optional, default 2)) – 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.

• metric (string (currently, only 'euclidean' is supported)) – The metric to use to compute distances in high dimensional space.

• n_epochs (int (optional, default None)) – 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).

• learning_rate (float (optional, default 1.0)) – The initial learning rate for the embedding optimization.

• init (string (optional, default 'spectral')) –

  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.

• min_dist (float (optional, default 0.5)) – 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.

• spread (float (optional, default 1.0)) – The effective scale of embedded points. In combination with min_dist this determines how clustered/clumped the embedded points are.

• low_memory (bool (optional, default True)) – 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.

• set_op_mix_ratio (float (optional, default 1.0)) – 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.

• local_connectivity (int (optional, default 1)) – 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.

• repulsion_strength (float (optional, default 1.0)) – Weighting applied to negative samples in low dimensional embedding optimization. Values higher than one will result in greater weight being given to negative samples.

• negative_sample_rate (int (optional, default 5)) – 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.

• a (float (optional, default None)) – More specific parameters controlling the embedding. If None these values are set automatically as determined by min_dist and spread.

• b (float (optional, default None)) – More specific parameters controlling the embedding. If None these values are set automatically as determined by min_dist and spread.

• random_state (int, RandomState instance or None, optional (default: None)) – 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.

• metric_kwds (dict (optional, default None)) – Arguments to pass on to the metric, such as the p value for Minkowski distance. If None then no arguments are passed on.

• angular_rp_forest (bool (optional, default False)) – 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.

• transform_seed (int (optional, default 42)) – Random seed used for the stochastic aspects of the transform operation. This ensures consistency in transform operations.

• verbose (bool (optional, default False)) – Controls verbosity of logging.

• tqdm_kwds (dict (optional, defaul None)) – Key word arguments to be used by the tqdm progress bar.

• unique (bool (optional, default False)) – 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_.

• featuremap (bool (optional, default False)) – 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.

• feat_lambda (float (optional, default 2.0)) – 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.

• feat_frac (float (optional, default 0.3)) – 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.

• feat_gauge_coefficient (float (default 1.0)) – A coefficient multiplication of n_neighbors as number of neighbors in gauge construction. Larger coefficient means long distance information

• feat_var_shift (float (optional, default 0.1)) – 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

• output_feat (bool (optional, default False)) – Whether to compute the embedding radius. If set to True, the algorithm will compute the embedding radius and return the embedding radius.

• disconnection_distance (float (optional, default np.inf or maximal value for bounded distances)) – 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.

• output_variation (bool (optional, default True)) – 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.

• threshold (float (optional, default 0.9)) – 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.

n_neighbors = 15

metric = 'euclidean'

output_metric = 'euclidean'

metric_kwds = None

output_metric_kwds = None

n_epochs = None

init = 'spectral'

n_components = 2

repulsion_strength = 1.0

learning_rate = 1.0

spread = 1.0

min_dist = 0.5

low_memory = True

set_op_mix_ratio = 1.0

local_connectivity = 1.0

negative_sample_rate = 5

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

n_jobs = -1

a = None

b = None

fit(X)

Fit X into an embedded space.

Parameters:

X (array, shape (n_samples, n_features) or (n_samples, n_samples)) – 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’.

fit_transform(X)

Fit X into an embedded space and return that transformed output.

Parameters:

X (array, shape (n_samples, n_features) or (n_samples, n_samples)) – If the metric is ‘precomputed’ X must be a square distance matrix. Otherwise it contains a sample per row.

Returns:

X_new – Embedding of the training data in low-dimensional space.

Return type:

array, shape (n_samples, n_components)

__repr__()