hypertools.reduce

hypertools.reduce(x, reduce='IncrementalPCA', ndims=None, return_model=False, manip=None, normalize=None, align=None, cluster=None, internal=False, format_data=True, random_state=None, model=None)

Reduces dimensionality of an array, or list of arrays

Parameters:

xNumpy array, Pandas DataFrame, text (list of strings), or

list/tuple of arrays/DataFrames The data to reduce. Lists (and tuples, treated identically) are stacked and reduced in one SHARED space (a single model fit on the row-concatenated data), so all datasets in a list must have the same number of columns. None raises a TypeError.

reducestr, dict, class, instance, fitted Reducer, False, or None

Decomposition/manifold learning model to use. Models supported: PCA, IncrementalPCA, SparsePCA, MiniBatchSparsePCA, KernelPCA, FastICA, FactorAnalysis, TruncatedSVD, DictionaryLearning, MiniBatchDictionaryLearning, TSNE, Isomap, SpectralEmbedding, LocallyLinearEmbedding, MDS and UMAP, plus the mixture (soft-clustering) models GaussianMixture, BayesianGaussianMixture, LatentDirichletAllocation and NMF – for these, the returned array holds (n_samples, ndims) membership proportions rather than a projection (GH #174). Also supports the six torch-backed autoencoder reducers (GH #162, hypertools.reduce.autoencoders): Autoencoder, DeepAutoencoder, SparseAutoencoder, ConvolutionalAutoencoder, SequenceAutoencoder, and VariationalAutoencoder – these require the optional torch dependency (pip install “hypertools[torch]”); resolving one of these names without torch installed raises a friendly ImportError. Can be passed as a string, a bare (uninstantiated) scikit-learn-style class, an already-constructed instance, the canonical dict spec {‘model’: …, ‘args’: […], ‘kwargs’: {…}} (both ‘args’ and ‘kwargs’ are OPTIONAL, so the minimal {‘model’: ‘PCA’} works too; passing the legacy ‘params’ key alongside them warns and ignores ‘params’), or the LEGACY dict spec {‘model’ : ‘PCA’, ‘params’ : {‘whiten’ : True}} (accepted for backward compatibility, but emits a DeprecationWarning). A previously-fitted Reducer (as returned by return_model=True) is applied via .transform instead of being refit; models without an out-of-sample transform (TSNE, MDS, SpectralEmbedding) cannot embed new data this way, so reusing their fitted Reducer raises NotImplementedError explaining the refit. None or False skips the reduction entirely and returns the input unchanged. See scikit-learn specific model docs for details on parameters supported for each model.

ndimsint or None

Number of dimensions to reduce to. If None (the default), or if every dataset already has <= ndims columns, no model is fit and the (formatted) input is returned unchanged – reduce() never expands or rotates data at full dimensionality. Requesting MORE dimensions than the data has features also skips the reduction, with a UserWarning (the input comes back unchanged). NOTE: when no reduction runs, there is no fitted model, so return_model=True pairs the unchanged data with None (see return_model below) – pass an explicit ndims (e.g. ndims=3) to actually fit a model.

return_modelbool

If True, also return the fitted model: the fitted Reducer wrapper when only the reduce stage ran, or a fitted hypertools.Pipeline when manip=/normalize=/align=/cluster= made multiple stages run (default: False). When NO reduction ran (ndims=None – the default – with data at/below the requested dimensionality, or reduce=None/False), the model slot of the returned (data, model) tuple is None.

manip, normalize, align, clustermodel spec or None

Cross-module stage kwargs (GH #138): when any of these is given, the other stages also run (via hypertools.core.pipeline.build_pipeline), in the canonical order manip -> normalize -> reduce -> align -> cluster (GH #153), with this function’s own reduce=/ndims= slotted in at the reduce stage (default: None for all four, i.e. only reduce runs).

internalbool

(Internal use, e.g. by hyp.plot/hyp.analyze) if True, always return a list even when the input was a single dataset (default: False).

format_databool

Whether or not to first call the format_data function (default: True).

random_stateint, RandomState, or None

Seed for reproducibility. Injected into the reduction model’s constructor when it accepts a random_state (UMAP, TSNE, MDS, FastICA, the mixture models, …); ignored for deterministic models (PCA, IncrementalPCA, …) and for an already-constructed model instance you pass in (configure that yourself). An explicit random_state in a dict spec’s kwargs takes precedence (default: None).

modelsame forms as reduce, or None

Alias for reduce=, so the own-stage model spec can be spelled model= here exactly as in hyp.manip/hyp.impute/hyp.predict/ hyp.align (release-1.0 audit: the sibling APIs used two different kwarg conventions). Pass only one of reduce=/model=; passing both (with different values) raises ValueError (default: None).

Returns:

x_reducedNumpy array or list of arrays

The reduced data with ndims dimensionality is returned. A list is returned when the input is a list of two or more datasets (or when internal=True); a single dataset – even inside a one-element list – comes back as a bare array. If return_model=True, an (x_reduced, model) tuple is returned instead.

Examples

>>> import numpy as np
>>> import hypertools as hyp
>>> x = np.cumsum(np.random.default_rng(0).standard_normal((40, 5)),
...               axis=0)
>>> reduced = hyp.reduce(x, reduce='PCA', ndims=3)
>>> reduced.shape
(40, 3)