[](https://badge.fury.io/py/dreimac)
[](https://pepy.tech/project/dreimac)
[](https://codecov.io/gh/scikit-tda/dreimac)
[](https://opensource.org/licenses/Apache-2.0)
[](https://dreimac.readthedocs.io/)
[](https://doi.org/10.21105/joss.05791)
# 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](http://dreimac.scikit-tda.org/).
## Basic usage
Here is a simple example; please check the Jupyter notebooks in the `notebooks` directory for further examples.
```python
# 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$"])
```
## More examples
For Jupyter notebooks with more examples, please check the [documentation](http://dreimac.scikit-tda.org/) or this repository's [docs/notebooks](https://github.com/scikit-tda/DREiMac/tree/master/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:
~~~~~ bash
pip install dreimac
~~~~~
To install directly from GitHub:
~~~~~ bash
pip install git+https://github.com/scikit-tda/DREiMac.git
~~~~~
## Documentation and support
You can find the documentation [here](http://dreimac.scikit-tda.org/), including the [API reference](https://dreimac.scikit-tda.org/en/latest/api.html).
If you have further questions, please [open an issue](https://github.com/scikit-tda/DREiMac/issues/new) 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.
```bash
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](https://joss.theoj.org/papers/10.21105/joss.05791), 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "dreimac",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.8",
"maintainer_email": "\"Jose A. Perea\" <joperea@gmail.com>, Luis Scoccola <luis.scoccola@gmail.com>, Chris Tralie <chris.tralie@gmail.com>",
"keywords": "dimensionality reduction, topological data analysis",
"author": null,
"author_email": "\"Jose A. Perea\" <joperea@gmail.com>, Luis Scoccola <luis.scoccola@gmail.com>, Chris Tralie <chris.tralie@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/55/5a/91dc044fa247e227e9c1fa7da100cd1b65933fedf4e55af559e006f3497a/dreimac-0.3.2.tar.gz",
"platform": null,
"description": "[](https://badge.fury.io/py/dreimac)\n[](https://pepy.tech/project/dreimac)\n[](https://codecov.io/gh/scikit-tda/dreimac)\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://dreimac.readthedocs.io/)\n[](https://doi.org/10.21105/joss.05791)\n\n# DREiMac: Dimensionality Reduction with Eilenberg-MacLane Coordinates\n\nDREiMac is a library for topological data coordinatization, visualization, and dimensionality reduction.\nCurrently, 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.\n\nIn 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.\nFor more information, please check the theory and examples in the [documentation](http://dreimac.scikit-tda.org/).\n\n\n## Basic usage\n\nHere is a simple example; please check the Jupyter notebooks in the `notebooks` directory for further examples.\n\n```python\n# basic imports\nfrom dreimac import CircularCoords\nfrom persim import plot_diagrams\nimport matplotlib.pyplot as plt\nimport numpy as np\n\n# prepare plot with 4 subplots\nf, (a0, a1, a2, a3) = plt.subplots(1, 4, width_ratios=[1, 1, 1, 0.2], figsize=(14,3))\n\n# 200 samples from a noisy circle\nn_samples = 200\nnp.random.seed(0)\nZ = np.random.random((n_samples, 2)) - 0.5\nX = Z / np.linalg.norm(Z, axis=1).reshape((n_samples, 1)) + (np.random.random((n_samples, 2)) - 0.5) * 0.2\n\n# plot point cloud\na0.scatter(X[:,0], X[:,1], s=10)\na0.set_title(\"Input point cloud\") ; a0.axis(\"off\") ; a0.set_aspect(\"equal\")\n\n# plot the persistence diagram, showing a single prominent class\ncc = CircularCoords(X, n_landmarks=200)\nplot_diagrams(cc._dgms, title=\"Persistence diagram\", ax=a1)\n\n# plot the data colored by the circle-valued map constructed by DREiMac\ncircular_coordinates = cc.get_coordinates()\na2.scatter(X[:,0], X[:,1], c=circular_coordinates, s=10, cmap=\"viridis\")\na2.set_title(\"Input colored by circular coordinate\") ; a2.axis(\"off\") ; a2.set_aspect(\"equal\")\n\n# plot colorbar\nimg = a3.imshow([[0,1]], cmap=\"viridis\"); a3.set_visible(False)\ncb = plt.colorbar(mappable=img,ticks=[0,0.5,1]) ; _ = cb.ax.set_yticklabels([\"0\",\"$\\pi$\",\"2$\\pi$\"])\n```\n\n\n\n## More examples\n\nFor Jupyter notebooks with more examples, please check the [documentation](http://dreimac.scikit-tda.org/) or this repository's [docs/notebooks](https://github.com/scikit-tda/DREiMac/tree/master/docs/notebooks) directory.\n\n## Installing\n\nMake sure your Python version is >=3.8 and <3.12.\nDREiMac depends on the following python packages, which will be installed automatically when you install with pip:\n`matplotlib`,\n`numba`,\n`numpy`,\n`persim`,\n`ripser`, and\n`scipy`.\n\nTo install the latest release:\n\n~~~~~ bash\npip install dreimac\n~~~~~\n\nTo install directly from GitHub:\n\n~~~~~ bash\npip install git+https://github.com/scikit-tda/DREiMac.git\n~~~~~\n\n## Documentation and support\n\nYou can find the documentation [here](http://dreimac.scikit-tda.org/), including the [API reference](https://dreimac.scikit-tda.org/en/latest/api.html).\nIf you have further questions, please [open an issue](https://github.com/scikit-tda/DREiMac/issues/new) and we will do our best to help you.\nPlease include as much information as possible, including your system's information, warnings, logs, screenshots, and anything else you think may be of use.\n\n## Running the tests\n\nIf 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.\n\n```bash\npip install pytest\npip install -r requirements.txt\npytest .\n```\n\n## Contributing\n\nTo contribute, you can fork the project, make your changes, and submit a pull request.\nIf you're looking for a way to contribute, you could consider:\n* adding documentation to existing functionality;\n* adding missing tests to improve coverage;\n* adding a Jupyter notebook with a tutorial or demo;\n* adding functionality and the corresponding documentation and tests;\n* responding to a bug or feature request in the Github issues.\n\n## Citing\n\nIf you use this package, please cite the JOSS paper found [here](https://joss.theoj.org/papers/10.21105/joss.05791), using the following bibtex entry.\n\n```\n@article{Perea2023,\n doi = {10.21105/joss.05791},\n url = {https://doi.org/10.21105/joss.05791},\n year = {2023},\n publisher = {The Open Journal},\n volume = {8},\n number = {91},\n pages = {5791},\n author = {Jose A. Perea and Luis Scoccola and Christopher J. Tralie},\n title = {DREiMac: Dimensionality Reduction with Eilenberg-MacLane Coordinates},\n journal = {Journal of Open Source Software}\n}\n```\n\n## Acknowledgements\n\nWe 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.\n\n## License\n\nThis software is published under Apache License Version 2.0.\n",
"bugtrack_url": null,
"license": null,
"summary": "DREiMac: Dimensionality reduction with Eilenberg-MacLane coordinates",
"version": "0.3.2",
"project_urls": {
"Documentation": "https://dreimac.scikit-tda.org",
"Homepage": "https://dreimac.scikit-tda.org",
"Issues": "https://github.com/scikit-tda/DREiMac/issues",
"Repository": "https://github.com/scikit-tda/DREiMac"
},
"split_keywords": [
"dimensionality reduction",
" topological data analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6d653e6a45a2fe854c0e31492ad178e0dfb6822bfaac5f3ad5cde7ef0b3d8c2d",
"md5": "76bb9ed6caff95abc9f6e7352c8563b9",
"sha256": "28f355b7a1bee4104a7ebff5a4877c9f9f77dbaf2164d598b7190c07f5dd9fdb"
},
"downloads": -1,
"filename": "dreimac-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "76bb9ed6caff95abc9f6e7352c8563b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.8",
"size": 37057,
"upload_time": "2024-09-10T19:05:36",
"upload_time_iso_8601": "2024-09-10T19:05:36.875278Z",
"url": "https://files.pythonhosted.org/packages/6d/65/3e6a45a2fe854c0e31492ad178e0dfb6822bfaac5f3ad5cde7ef0b3d8c2d/dreimac-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "555a91dc044fa247e227e9c1fa7da100cd1b65933fedf4e55af559e006f3497a",
"md5": "51f250fd9f7a1e3df737365230ba2f4a",
"sha256": "b60a42bfe8c209ea2f2baa40c38b5e7ef529b1930e087f8c237aac9da7b7bd34"
},
"downloads": -1,
"filename": "dreimac-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "51f250fd9f7a1e3df737365230ba2f4a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.8",
"size": 35502,
"upload_time": "2024-09-10T19:05:38",
"upload_time_iso_8601": "2024-09-10T19:05:38.205210Z",
"url": "https://files.pythonhosted.org/packages/55/5a/91dc044fa247e227e9c1fa7da100cd1b65933fedf4e55af559e006f3497a/dreimac-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 19:05:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scikit-tda",
"github_project": "DREiMac",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "dreimac"
}
JSON
