hypertools.apply_model

hypertools.apply_model(data, model, mode='auto', return_model=False, format_data=True, stack=True, ndims=None)[source]

Apply a model (or pipeline of models) to one or more datasets.

Parameters:
datanumpy array, pandas DataFrame, or list of arrays/DataFrames

The dataset(s) to transform.

modelstr, class, dict, sklearn-style instance, or list

  • str: a registered model name (see hypertools.core.supported_models()), e.g. ‘PCA’, ‘KMeans’, ‘GaussianMixture’. (This registry covers the REDUCE and CLUSTER model families only; manipulator, aligner, forecaster, and imputer names – e.g. ‘ZScore’, ‘HyperAlign’, ‘Kalman’ – are handled by their own dispatchers, hyp.manip/hyp.align/ hyp.predict/hyp.impute, because those models operate on whole datasets rather than stacked arrays. hyp.Pipeline additionally accepts manipulator and aligner names in a step list.) An unknown name raises a ValueError saying exactly this.

  • class: a scikit-learn style model class, instantiated with the spec’s ‘args’/’kwargs’ (or defaults)

  • dict: the canonical {‘model’: <str, class, or instance>, ‘args’: […], ‘kwargs’: {…}} (both ‘args’ and ‘kwargs’ optional; ‘args’ are positional constructor arguments and require a name/class ‘model’), or the legacy {‘model’: …, ‘params’: {…}} form (accepted for backward compatibility, emits a DeprecationWarning)

  • instance: any object exposing fit/transform/fit_transform/ fit_predict/predict_proba (scikit-learn convention)

  • list: a pipeline; each element is applied in sequence, with each stage’s output feeding the next stage’s input

modestr

How to apply the model: ‘fit_transform’, ‘fit_predict’, ‘predict_proba’, or ‘auto’ (default), which prefers predict_proba (fitting first), then fit_transform/transform, then fit_predict. For a list (pipeline) spec, an explicit mode applies to the FINAL stage only (earlier stages run in ‘auto’ mode), so e.g. [‘PCA’, ‘KMeans’] with mode=’fit_predict’ reduces, then returns cluster labels. An explicit mode the model cannot honor raises a ValueError naming the modes it does support. Note that ‘auto’ can return a different result KIND than hyp.Pipeline’s fit_transform for the same model (e.g. GaussianMixture: membership probabilities here via predict_proba, hard labels from a raw Pipeline step).

return_modelbool

If True, also return the fitted model (default: False):

  • single spec + stack=True: the fitted model instance

  • single spec + stack=False: a LIST of fitted instances, one per dataset (even for a single input dataset)

  • list spec + stack=True: a fitted hypertools.Pipeline wrapping each stage’s already-fitted model, in order

  • list spec + stack=False: a list of fitted hypertools.Pipeline objects, one per dataset

Fitted models/pipelines are reusable on held-out data via .transform()/pipeline.named_steps/pipeline.steps. Caveat: models with no out-of-sample method (e.g. TSNE, MDS, SpectralEmbedding) cannot honor .transform() on new data – reusing such a pipeline raises a TypeError explaining this.

format_databool

Whether to run hypertools’ format_data on the input (default: True).

stackbool

If True (default), datasets are vertically stacked and the model is fit ONCE across all of them, then results are split back to match the input structure. NOTE: with stack=True, a passed-in model INSTANCE is fitted in place (the caller’s object gains the fitted state). If False, a separate model is fit per dataset; each dataset gets its own clone and the caller’s instance is left untouched.

ndimsint or None

Convenience: sets n_components on models that accept it. Must be a positive integer (or None); invalid values raise the same ValueError as hyp.reduce’s ndims= (release-1.0 audit, X2-error-quality-018: apply_model(x, ‘PCA’, ndims=0) used to silently return a width-0 array).

Returns:
result (and fitted model(s) if return_model=True; see return_model
for the exact shape). Lists in, lists out: a single input dataset
returns a single result.