Overview
Most dimension estimation methods assume a dataset lies on (or near) a single manifold with one well-defined dimension. Real point clouds are often much messier. Imagine points drawn from a curve meeting a surface, two sheets crossing along a line, a branching structure, or a sensor network with singular points. These are all examples of stratified spaces, made up of pieces of different dimensions glued together along shared boundaries.
Dimmer is built to work with data like this directly. Rather than returning one dimension for an entire dataset, it estimates dimension locally for each data point by studying the nearby geometry of the dataset. Dimmer flags where this local geometry looks anomalous, like boundaries, intersections, and singularities. Information like this is used to decompose the point cloud into a stratification: a set of local charts, each internally consistent in dimension.
The challenge
Typical dimension estimators and standard manifold learning techniques report a single number, or fit a single embedding, for an entire dataset. Geospatial datasets, imagery datasets, sensor networks, and simulation outputs all tend to be a mix of pieces with different dimensions. Single dimension estimates average over the very structure an analyst is trying to find. This leads to poorly performing models, with both overfitting and underfitting regions in data space.
Manual approaches to recovering the underlying strata by hand do not scale either. This work requires inspecting local neighborhoods across the entire point cloud to spot where dimension changes or pieces intersect, and then stitching those observations into a consistent decomposition. Dimmer automates this end to end.
Cyclooctane Example
Here's an example of Dimmer applied to the real, well-studied example of the conformation space of cyclooctane. The conformation space is the set of all 3D shapes the ring molecule cyclooctane can take without changing its bond angles or lengths. This space has long been known to be a genuine stratified space. Topologically, it is a sphere and a Klein bottle glued together along two circles, which makes it a natural benchmark for methods that recover stratifications directly from point cloud data.
Drag to rotate, scroll to zoom.
The output of Dimmer here is the coloring by stratum in the scatterplot. Dimmer identifies these different strata using persistent homology. The strata of this stratification correspond to conformations with distinct energy properties. See the well-written Martin et al paper Topology of cyclooctane energy landscape for more details.
How it works
Dimmer breaks the stratification-finding problem into three stages, each usable on its own or chained together into a full pipeline.
- GAD (Geometric Anomaly Detection) — looks at the neighborhood around each point and flags where the local geometry doesn't behave like an ordinary, consistent patch — the signature of a boundary, singularity, or overlap with another stratum.
- Intersecter — zeroes in on points where two or more lower-dimensional pieces appear to cross rather than forming a single smooth patch, pinpointing exactly where distinct strata meet.
- Stratifier — takes that local information and stitches it into a full decomposition, partitioning the point cloud into pieces that are each internally consistent in dimension.
The result is a labeled decomposition of the point cloud, produced without hand-inspecting every neighborhood, and built to stay practical on point clouds far too large to analyze by hand.
Results
By estimating dimension locally instead of globally, Dimmer recovers structure that single-number estimators collapse away: boundaries between pieces of different dimension, intersections between sheets or manifolds, and singular points where the geometry itself is changing. Documentation and example notebooks walk through each method on synthetic examples — including a head-to-head comparison pipeline against scikit-dimension — as well as on the Intersecter and Stratifier workflows individually.
The result is a decomposition analysts can act on directly: knowing which points belong to which stratum makes it possible to model, reduce, or visualize each piece of a dataset on its own terms, rather than forcing the whole point cloud into a single dimensionality assumption.
Getting started
Dimmer is available as a Python package on PyPI. Install it with
pip install dimmer
Full documentation, API reference, and example notebooks are available at dimmer-211884.gitlab.io. Source code, issue tracking, and releases live in the GitLab repository.