Topological Assembly of Local Euclidean Models

This repository implements TALLEM - a topologically inspired non-linear dimensionality reduction method.

Given some data set X and a map onto some topological space B which captures the topology/nonlinearity of X, TALLEM constructs a map mapping X to a D-dimensional space.

TODO: describe TALLEM more

Dependencies

tallem's run-time dependencies are fairly minimal. They include:

1. Python >= 3.8.0
2. NumPy (>= 1.20) and SciPy (>=1.5)

Package requirement details are listed in the pyproject.toml. These are automatically downloaded using either of the installation methods described below.

Some functions which extend TALLEM's core functionality require additional dependencies to be called---they include autograd, pymanopt, scikit-learn, and bokeh. These packages are optional--they are not needed to get the embedding.

Installing from pre-built wheels

TODO: Make tallem pip-installeable by finishing wheel builds w/ cibuildwheels

Installing from source

The recommended way to build tallem distributions (source or built) is with Poetry. Once installed, navigate to tallem's directory and use:

poetry install -vvv

The default build script attempts to resolve all dependencies needed by the package at build-time. This includes possible source-installs of prerequisite C++ libraries and their associated build tools; tallem requires Armadillo (>= 10.5.2) for compilation of its extension modules, whose builds are managed with Meson and Ninja. Since these source files are written in C++17, so a C++17 compliant compiler will be needed.

If you plan on changing the code in any way, see the developer note about editeable installs. If you have an installation problems or questions, feel free to make a new issue.

Usage

Below is some example code showcasing TALLEMs ability to handle topological obstructions to dimensionality reduction like non-orientability.

from tallem import TALLEM
from tallem.cover import IntervalCover
from tallem.datasets import mobius_band

## Get mobius band data + its parameter space
X, B = mobius_band()
B_polar = B[:,[1]]

## Construct a cover over the polar coordinate
m_dist = lambda x,y: np.sum(np.minimum(abs(x - y), (2*np.pi) - abs(x - y)))
cover = IntervalCover(B_polar, n_sets = 10, overlap = 0.30, metric = m_dist)

## Parameterize TALLEM + transform the data to the obtain the coordinization
emb = TALLEM(cover=cover, local_map="cmds2", n_components=3).fit_transform(X, B_polar)

## Draw the coordinates via 3D projection, colored by the polar coordinate
import matplotlib.pyplot as plt
fig = plt.figure()
ax = fig.add_subplot(projection='3d')
ax.scatter(*emb.T, marker='o', c=B_polar)

Developer note

Installs from source using Poetry are done in editeable mode by default: thus one should be able to freely manipulate the source code once tallem is installed and see the changes immediately without restarting the session. If you're developing with Jupyter, be sure to add autoreload magics to the document:

%reload_ext autoreload
%autoreload 2 
# ... 

If you're developing with Microsoft's VSCode, you may want automating this via added the following to the settings.json file:

"jupyter.runStartupCommands": [
  "%load_ext autoreload", "%autoreload 2"
]

See here for more details on this.