Skip to main content

DREiMac: Dimensionality reduction with Eilenberg-MacLane coordinates

Project description

PyPI version Downloads codecov License docs DOI

DREiMac: Dimensionality Reduction with Eilenberg-MacLane Coordinates

DREiMac is a library for topological data coordinatization, visualization, and dimensionality reduction. Currently, DREiMac is able to find topology-preserving representations of point clouds taking values in the circle, in higher dimensional tori, in the real and complex projective space, and in lens spaces.

In a few words, DREiMac takes as input a point cloud together with a topological feature of the point cloud (in the form of a persistent cohomology class), and returns a map from the point cloud to a well-understood topological space (a circle, a product of circles, a projective space, or a lens space), which preserves the given topological feature in a precise sense. For more information, please check the theory and examples in the documentation.

Basic usage

Here is a simple example; please check the Jupyter notebooks in the notebooks directory for further examples.

# basic imports
from dreimac import CircularCoords
from persim import plot_diagrams
import matplotlib.pyplot as plt
import numpy as np

# prepare plot with 4 subplots
f, (a0, a1, a2, a3) = plt.subplots(1, 4, width_ratios=[1, 1, 1, 0.2], figsize=(14,3))

# 200 samples from a noisy circle
n_samples = 200
np.random.seed(0)
Z = np.random.random((n_samples, 2)) - 0.5
X = Z / np.linalg.norm(Z, axis=1).reshape((n_samples, 1)) + (np.random.random((n_samples, 2)) - 0.5) * 0.2

# plot point cloud
a0.scatter(X[:,0], X[:,1], s=10)
a0.set_title("Input point cloud") ; a0.axis("off") ; a0.set_aspect("equal")

# plot the persistence diagram, showing a single prominent class
cc = CircularCoords(X, n_landmarks=200)
plot_diagrams(cc._dgms, title="Persistence diagram", ax=a1)

# plot the data colored by the circle-valued map constructed by DREiMac
circular_coordinates = cc.get_coordinates()
a2.scatter(X[:,0], X[:,1], c=circular_coordinates, s=10, cmap="viridis")
a2.set_title("Input colored by circular coordinate") ; a2.axis("off") ; a2.set_aspect("equal")

# plot colorbar
img = a3.imshow([[0,1]], cmap="viridis"); a3.set_visible(False)
cb = plt.colorbar(mappable=img,ticks=[0,0.5,1]) ; _ = cb.ax.set_yticklabels(["0","$\pi$","2$\pi$"])

output

More examples

For Jupyter notebooks with more examples, please check the documentation or this repository's docs/notebooks directory.

Installing

Make sure your Python version is >=3.8 and <3.12. DREiMac depends on the following python packages, which will be installed automatically when you install with pip: matplotlib, numba, numpy, persim, ripser, and scipy.

To install the latest release:

pip install dreimac

To install directly from GitHub:

pip install git+https://github.com/scikit-tda/DREiMac.git

Documentation and support

You can find the documentation here, including the API reference. If you have further questions, please open an issue and we will do our best to help you. Please include as much information as possible, including your system's information, warnings, logs, screenshots, and anything else you think may be of use.

Running the tests

If you want to check that your machine is running DREiMac properly, you may run the tests by running the following commands from the root directory of a clone of this repository.

pip install pytest
pip install -r requirements.txt
pytest .

Contributing

To contribute, you can fork the project, make your changes, and submit a pull request. If you're looking for a way to contribute, you could consider:

  • adding documentation to existing functionality;
  • adding missing tests to improve coverage;
  • adding a Jupyter notebook with a tutorial or demo;
  • adding functionality and the corresponding documentation and tests;
  • responding to a bug or feature request in the Github issues.

Citing

If you use this package, please cite the JOSS paper found here, using the following bibtex entry.

@article{Perea2023,
  doi = {10.21105/joss.05791},
  url = {https://doi.org/10.21105/joss.05791},
  year = {2023},
  publisher = {The Open Journal},
  volume = {8},
  number = {91},
  pages = {5791},
  author = {Jose A. Perea and Luis Scoccola and Christopher J. Tralie},
  title = {DREiMac: Dimensionality Reduction with Eilenberg-MacLane Coordinates},
  journal = {Journal of Open Source Software}
}

Acknowledgements

We thank Tom Mease for contributions and discussions. J.A.P. and L.S. were partially supported by the National Science Foundation through grants CCF-2006661 and CAREER award DMS-1943758.

License

This software is published under Apache License Version 2.0.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

dreimac-0.3.2.tar.gz (35.5 kB view details)

Uploaded Source

Built Distribution

dreimac-0.3.2-py3-none-any.whl (37.1 kB view details)

Uploaded Python 3

File details

Details for the file dreimac-0.3.2.tar.gz.

File metadata

  • Download URL: dreimac-0.3.2.tar.gz
  • Upload date:
  • Size: 35.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for dreimac-0.3.2.tar.gz
Algorithm Hash digest
SHA256 b60a42bfe8c209ea2f2baa40c38b5e7ef529b1930e087f8c237aac9da7b7bd34
MD5 51f250fd9f7a1e3df737365230ba2f4a
BLAKE2b-256 555a91dc044fa247e227e9c1fa7da100cd1b65933fedf4e55af559e006f3497a

See more details on using hashes here.

Provenance

File details

Details for the file dreimac-0.3.2-py3-none-any.whl.

File metadata

  • Download URL: dreimac-0.3.2-py3-none-any.whl
  • Upload date:
  • Size: 37.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for dreimac-0.3.2-py3-none-any.whl
Algorithm Hash digest
SHA256 28f355b7a1bee4104a7ebff5a4877c9f9f77dbaf2164d598b7190c07f5dd9fdb
MD5 76bb9ed6caff95abc9f6e7352c8563b9
BLAKE2b-256 6d653e6a45a2fe854c0e31492ad178e0dfb6822bfaac5f3ad5cde7ef0b3d8c2d

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page