HyperTools: one call from high-dimensional data to a plot

One function call from a dataset to a picture

The core pitch is a pipeline in a single call. You feed in a high-dimensional dataset, or a series of high-dimensional datasets, and in one function call HyperTools reduces the dimensionality and creates a plot. It is built on matplotlib, scikit-learn and seaborn, so the plots are ordinary matplotlib objects rather than a rendering model of its own, and the visual output can be customised the way a matplotlib user expects. The package targets dimensionality reduction based visual exploration, and the topics listed for the repository cover data visualisation, data wrangling, high-dimensional data, text vectorization, time series, topic modelling and visualization. The licence is MIT and the project is not archived, with the last push on 2026-10-10 and releases v1.1.0 on 2026-10-10, v1.0.0 on 2026-07-24 and v0.8.2 on 2026-01-29. The README opens with a Geoff Hinton quote about visualising a 3D space and saying fourteen loudly, which is a fair summary of what the package is for.

Hyperalignment is the feature nothing else here replaces

The tour's first example is the one that shows what HyperTools is for beyond plotting. Six stock-market sectors are each reduced to 3-D on their own and then hyperaligned into a shared space, with a heavier path for the market as a whole. The point is that a PCA or UMAP fitted on one dataset is not comparable to one fitted on another, so overlaying them is meaningless until they are aligned. HyperTools has a dedicated function for that, and the keyword `hyperalignment` appears among the package keywords along with PCA, UMAP and clustering. This is the capability that makes the library worth a dependency for anyone comparing conditions, groups or time points. The example gallery in the repository makes the same point with an `examples/plot_align.py` script, sitting alongside the clustering, corpus, colorbar and dataframe examples.

Text in, geometry out

Give `hyp.plot` a list of strings and it embeds them, projects them into 2-D or 3-D, and plots the result. The example in the documentation takes a paragraph about each of five paintings and each becomes its own cloud, drawn in a colour pulled from the canvas itself. This is a pleasant trick and it works because the plotting side and the embedding side share the same coordinate system, so you can attach arbitrary metadata to points after the projection. The text side is the part with dependency weight, since embedding models are optional extras. Version 1.0 added more text embedding models, and 1.1 loads text and market data in one line. The extra names are `hypertools[text]` for the text side and `hypertools[gensim]` for gensim vectorizers, and the corpus and painting embedding examples in the repository show both routes.

Order, morph and the animation API

The animation API grew in 1.1 and is the part with the most distinct modes. `order='serial'` reveals a dataset one piece at a time, and the example is the Mad Tea-Party from Alice's Adventures in Wonderland, where each segment is one turn of the conversation, coloured by speaker and placed by what is being said. `animate='morph'` interpolates between point clouds or meshes, and the built-in shapes come from `hyp.load`:

import hypertools as hyp
names = ['bunny', 'cube', 'sphere', 'teapot', 'vase']
shapes = [hyp.load(n) for n in names]
hyp.plot(shapes, '.', color='k', animate='morph', title=names)

Version 1.0 added morph and 2-D animations, and 1.1 grew the animation API further, with dedicated example scripts for spinning, trails, surface morphs and mixed trails. The distinction between serial order and morph matters for how you read the result. A serial animation is a narrative of one dataset, while a morph compares two or more shapes in a common space, and the second is a visual form of the hyperalignment question without the alignment machinery.

Forecasting, imputation and model comparison

The 1.1 release added model comparisons for forecasting and imputation, alongside `hyp.Pipeline`, `hyp.manip`, `hyp.predict` and `hyp.impute` from the 1.0 rewrite. The distinction between forecasting and imputation is worth holding onto. Forecasting predicts the future of a series, imputation fills in the gaps inside it, and comparing models means running several candidates against the same data and seeing which geometry holds up. The forecasting side has two named forecasters, `Laplace` and `Chronos`, both behind the `hypertools[predict]` extra, with `hypertools[predict-hf]` for the Hugging Face hosted variants. The `examples/animate_forecast.py` script shows the animation of a forecast, and `hyp.plot` can apply a previously fitted model to new data, which is the `examples/plot_apply_model.py` case.

Extras install themselves into your interpreter

The most surprising design decision is that optional features install themselves on demand. The first call that needs an extra installs that extra's requirements into the running interpreter, prints a one-line notice, and carries on. HyperTools itself is never reinstalled, so a development or branch install stays as it is. The declared extras in `pyproject.toml` are `interactive` for the plotly backend, `text` for HF text embeddings, `predict` and `predict-hf` for the forecasters, `torch` for the autoencoder reducers, `gensim` for gensim vectorizers, `kaggle` for Kaggle loading, `lsl` for LSL streaming, `density3d` for 3-D density iso-surfaces and `io` for `.xlsx` loading. The convenience is real, and the cost is that a notebook can mutate the environment it runs in without asking, which matters on a shared machine or in a locked-down deployment.

Installing, and the Python versions that actually work

Installation is a pip command for the stable release:

pip install hypertools

The unstable version comes straight from GitHub:

pip install -U git+https://github.com/ContextLab/hypertools.git

And a local clone is installed in editable mode with `pip install -e .` after `git clone https://github.com/ContextLab/hypertools.git`. The package requires Python 3.10 or higher, and the classifiers list 3.10, 3.11, 3.12 and 3.13. The project is explicit that there is no 3.14 classifier because CI tests only 3.10 to 3.13, and the comment in the project file is blunt about the reason: dependency resolution is not a compatibility test for a compiled scientific stack, so a 3.14 job and behavioural tests would have to be added before advertising it. The build system is setuptools with a requirement of 77 or higher, needed for the PEP 639 SPDX licence string.

The 1.0 rewrite and the inputs it now rejects

Version 1.0 was a ground-up rewrite that kept a familiar API, added an optional interactive plotly backend and removed some long-deprecated arguments. Version 1.1 made hierarchical DataFrames with a MultiIndex a first-class input and, according to the changelog note in the project file, includes seven rejections of previously-accepted input that could not ship as a patch release. That is the sharpest edge for anyone upgrading. The project file even holds a test that keeps the version number and the top changelog heading equal, which tells you the maintainers treat the two as one contract. The changelog is described as having the complete list for both releases, including what changed for code and for saved data from earlier versions, and there is a `RELEASE_CHECKLIST.md` in the repository root alongside a `CHANGELOG.md`. The documentation also warns that the Jupyter notebooks from the original paper predate the 1.x API, and points to the example gallery for runnable current examples.

Editorial conclusion

Adopt HyperTools when you want a fast geometric look at high-dimensional data, especially several datasets that need to share a space, and you are on Python 3.10 to 3.13. Skip it if you need a specific reducer with production-grade control, since HyperTools chooses the projection for you behind one call, and treat the extras as a cost to review, since the plotly backend, HF text embeddings, the Laplace and Chronos forecasters, the autoencoder reducers and the gensim vectorizers all install themselves into your interpreter on first use. Before upgrading, read the changelog, because 1.1 rejects seven forms of input that earlier versions accepted and removed some long-deprecated arguments in 1.0.

Frequently asked questions

Official sources

1. ContextLab/hypertools on GitHub
2. License: MIT
3. Project website
4. README
5. Releases