Skip to content

Commit 354ffb8

Browse files
lucasimilucasimi
committed
Improved README and docs
1 parent d03be7f commit 354ffb8

File tree

5 files changed

+215
-160
lines changed

5 files changed

+215
-160
lines changed

‎README.md‎

Lines changed: 60 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,44 @@ It enables fast computation of Mapper graphs using *vp-trees* to optimize the co
1717
For further details, please refer to our [preprint](https://doi.org/10.5281/zenodo.10659651).
1818

1919
- **Installation**: `pip install tda-mapper`
20-
- **Documentation**: [online on readthedocs](https://tda-mapper.readthedocs.io/en/main/)
20+
21+
- **Documentation**: [Online on Read the Docs](https://tda-mapper.readthedocs.io/en/main/).
22+
23+
- **Interactive App**: [Live Demo on Streamlit Cloud](https://tda-mapper-app.streamlit.app/), or run locally with:
24+
25+
```
26+
pip install -r app/requirements.txt
27+
streamlit run app/streamlit_app.py
28+
```
2129
2230
## Features
2331
2432
- **Efficient Mapper Computation**: Optimized for higher-dimensional lenses.
33+
2534
- **Interactive Visualizations**: Multiple plotting backends for flexibility.
26-
- **Data Exploration App**: Interactive tool for quick, in-depth data exploration.
35+
36+
- **Interactive App**: Interactive tool for quick, in-depth data exploration.
37+
38+
## Background
39+
40+
The Mapper algorithm is a well-known technique in the field of topological
41+
data analysis that allows data to be represented as a graph.
42+
Mapper is used in various fields such as machine learning, data mining, and
43+
social sciences, due to its ability to preserve topological features of the
44+
underlying space, providing a visual representation that facilitates
45+
exploration and interpretation. For an in-depth coverage of Mapper you can
46+
read
47+
[the original paper](https://research.math.osu.edu/tgda/mapperPBG.pdf).
48+
49+
50+
| Step 1 | Step 2 | Step 3 | Step 4 |
51+
| ------ | ------ | ------ | ------ |
52+
| ![Step 1](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_1.png) | ![Step 2](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_2.png) | ![Step 3](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_3.png) | ![Step 2](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_4.png) |
53+
| Chose lens | Cover image | Run clustering | Build graph |
2754
2855
## Quick Start
2956
30-
Here's a minimal example using the **circles dataset** from `scikit-learn` to demonstrate Mapper with **tda-mapper**:
57+
Here's a minimal example using the **circles dataset** from `scikit-learn` to demonstrate how to use **tda-mapper**:
3158
3259
```python
3360
import numpy as np
@@ -42,7 +69,7 @@ from tdamapper.plot import MapperPlot
4269
4370
# load a labelled dataset
4471
X, labels = make_circles(n_samples=5000, noise=0.05, factor=0.3, random_state=42)
45-
y = PCA(2).fit_transform(X)
72+
y = PCA(2, random_state=42).fit_transform(X)
4673
4774
cover = CubicalCover(n_intervals=10, overlap_frac=0.3)
4875
clust = DBSCAN()
@@ -60,31 +87,34 @@ fig.show(config={'scrollZoom': True})
6087
More examples can be found in the
6188
[documentation](https://tda-mapper.readthedocs.io/en/main/).
6289

63-
## Demo App
64-
65-
To assess the features of **tda-mapper** you can start from the demo app.
66-
67-
- **Live demo:** [tda-mapper-app on Streamlit Cloud](https://tda-mapper-app.streamlit.app/)
68-
69-
- **Run locally:** use the following commands
70-
90+
## Citations
91+
92+
- **tda-mapper**: To cite this library, reference the Zenodo [archive](https://doi.org/10.5281/zenodo.10642381), pointing to the specific version of the release used in your work. For example to cite version 0.7.3 you can use:
93+
94+
``` bibtex
95+
@software{simi_2024_12729251,
96+
author = {Simi, Luca},
97+
title = {tda-mapper},
98+
month = jul,
99+
year = 2024,
100+
publisher = {Zenodo},
101+
version = {v0.7.3},
102+
doi = {10.5281/zenodo.12729251},
103+
url = {https://doi.org/10.5281/zenodo.12729251}
104+
}
71105
```
72-
pip install -r app/requirements.txt
73-
streamlit run app/streamlit_app.py
74-
```
75-
76-
## References and Citations
77-
78-
The Mapper algorithm is a well-known technique in the field of topological
79-
data analysis that allows data to be represented as a graph.
80-
Mapper is used in various fields such as machine learning, data mining, and
81-
social sciences, due to its ability to preserve topological features of the
82-
underlying space, providing a visual representation that facilitates
83-
exploration and interpretation. For an in-depth coverage of Mapper you can
84-
read
85-
[the original paper](https://research.math.osu.edu/tgda/mapperPBG.pdf).
86-
87-
- **tda-mapper**: To cite this library reference the Zenodo [archive](https://doi.org/10.5281/zenodo.10642381),
88-
pointing to the specific version of the release used in your work.
89106
90-
- **Methodology**: To cite our methodological foundation, refer to [our preprint](https://doi.org/10.5281/zenodo.10659651).
107+
- **Methodology**: To cite our methodological foundation, refer to the [preprint](https://doi.org/10.5281/zenodo.10659651).
108+
109+
``` bibtex
110+
@misc{simi_2024_11187959,
111+
author = {Simi, Luca},
112+
title = {{A Scalable Approach for Mapper via Vantage Point
113+
Trees}},
114+
month = may,
115+
year = 2024,
116+
publisher = {Zenodo},
117+
doi = {10.5281/zenodo.11187959},
118+
url = {https://doi.org/10.5281/zenodo.11187959}
119+
}
120+
```

‎docs/source/citations.rst‎

Lines changed: 33 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,59 +1,36 @@
1-
References
2-
==========
3-
4-
The Mapper algorithm is a well-known technique in the field of topological
5-
data analysis that allows data to be represented as a graph.
6-
Mapper is used in various fields such as machine learning, data mining, and
7-
social sciences, due to its ability to preserve topological features of the
8-
underlying space, providing a visual representation that facilitates
9-
exploration and interpretation. For an in-depth coverage of Mapper you can
10-
read
11-
`the original paper <https://research.math.osu.edu/tgda/mapperPBG.pdf>`__.
12-
13-
+-----------------+-----------------+-----------------+-----------------+
14-
| Step 1 | Step 2 | Step 3 | Step 4 |
15-
+=================+=================+=================+=================+
16-
| |Step 1| | |Step 2| | |Step 3| | |Step 4| |
17-
+-----------------+-----------------+-----------------+-----------------+
18-
19-
.. |Step 1| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_1.png
20-
.. |Step 2| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_2.png
21-
.. |Step 3| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_3.png
22-
.. |Step 4| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_4.png
23-
241
Citations
25-
---------
2+
=========
263

274
- **tda-mapper**: To cite this library, reference the Zenodo
28-
`archive <https://doi.org/10.5281/zenodo.10642381>`__,
29-
pointing to the specific version of the release used in your work.
30-
For example to cite version 0.7.3 you can use:
31-
32-
.. code-block:: bibtex
33-
34-
@software{simi_2024_12729251,
35-
author = {Simi, Luca},
36-
title = {tda-mapper},
37-
month = jul,
38-
year = 2024,
39-
publisher = {Zenodo},
40-
version = {v0.7.3},
41-
doi = {10.5281/zenodo.12729251},
42-
url = {https://doi.org/10.5281/zenodo.12729251}
43-
}
44-
45-
- **Methodology**: To cite our methodological foundation, refer to
46-
`our preprint <https://doi.org/10.5281/zenodo.10659651>`__.
47-
48-
.. code-block:: bibtex
49-
50-
@misc{simi_2024_11187959,
51-
author = {Simi, Luca},
52-
title = {{A Scalable Approach for Mapper via Vantage Point
53-
Trees}},
54-
month = may,
55-
year = 2024,
56-
publisher = {Zenodo},
57-
doi = {10.5281/zenodo.11187959},
58-
url = {https://doi.org/10.5281/zenodo.11187959}
59-
}
5+
`archive <https://doi.org/10.5281/zenodo.10642381>`__, pointing to the
6+
specific version of the release used in your work. For example to cite
7+
version 0.7.3 you can use:
8+
9+
.. code:: bibtex
10+
11+
@software{simi_2024_12729251,
12+
author = {Simi, Luca},
13+
title = {tda-mapper},
14+
month = jul,
15+
year = 2024,
16+
publisher = {Zenodo},
17+
version = {v0.7.3},
18+
doi = {10.5281/zenodo.12729251},
19+
url = {https://doi.org/10.5281/zenodo.12729251}
20+
}
21+
22+
- **Methodology**: To cite our methodological foundation, refer to the
23+
`preprint <https://doi.org/10.5281/zenodo.10659651>`__.
24+
25+
.. code:: bibtex
26+
27+
@misc{simi_2024_11187959,
28+
author = {Simi, Luca},
29+
title = {{A Scalable Approach for Mapper via Vantage Point
30+
Trees}},
31+
month = may,
32+
year = 2024,
33+
publisher = {Zenodo},
34+
doi = {10.5281/zenodo.11187959},
35+
url = {https://doi.org/10.5281/zenodo.11187959}
36+
}

‎docs/source/index.rst‎

Lines changed: 81 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,92 @@
1-
.. tda-mapper documentation master file, created by
2-
sphinx-quickstart on Fri Jan 26 21:56:08 2024.
3-
You can adapt this file completely to your liking, but it should at least
4-
contain the root `toctree` directive.
5-
6-
########################
7-
tda-mapper documentation
8-
########################
9-
10-
|Logo|
11-
12-
|PyPI version| |downloads| |test| |deploy| |docs| |codecov| |DOI|
13-
14-
Contents
15-
========
16-
17-
.. toctree::
18-
:maxdepth: 1
19-
20-
overview
21-
examples
22-
citations
23-
apiref
24-
25-
.. |Logo| image:: logos/tda-mapper-logo-horizontal.png
26-
:alt: tda-mapper
27-
:target: https://github.com/lucasimi/tda-mapper-python
281
.. |PyPI version| image:: https://badge.fury.io/py/tda-mapper.svg
292
:target: https://badge.fury.io/py/tda-mapper
303
.. |downloads| image:: https://img.shields.io/pypi/dm/tda-mapper
314
:target: https://pypi.python.org/pypi/tda-mapper/
325
.. |test| image:: https://github.com/lucasimi/tda-mapper-python/actions/workflows/test.yml/badge.svg
336
:target: https://github.com/lucasimi/tda-mapper-python/actions/workflows/test.yml
34-
.. |deploy| image:: https://github.com/lucasimi/tda-mapper-python/actions/workflows/deploy.yml/badge.svg
35-
:target: https://github.com/lucasimi/tda-mapper-python/actions/workflows/deploy.yml
7+
.. |publish| image:: https://github.com/lucasimi/tda-mapper-python/actions/workflows/publish.yml/badge.svg
8+
:target: https://github.com/lucasimi/tda-mapper-python/actions/workflows/publish.yml
369
.. |docs| image:: https://readthedocs.org/projects/tda-mapper/badge/?version=main
3710
:target: https://tda-mapper.readthedocs.io/en/main/?badge=main
3811
.. |codecov| image:: https://codecov.io/github/lucasimi/tda-mapper-python/graph/badge.svg?token=FWSD8JUG6R
3912
:target: https://codecov.io/github/lucasimi/tda-mapper-python
4013
.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.10642381.svg
41-
:target: https://doi.org/10.5281/zenodo.10642381
14+
:target: https://doi.org/10.5281/zenodo.10642381
15+
.. |Streamlit App| image:: https://static.streamlit.io/badges/streamlit_badge_black_white.svg
16+
:target: https://tda-mapper-app.streamlit.app/
17+
.. |Step 1| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_1.png
18+
.. |Step 2| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_2.png
19+
.. |Step 3| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_3.png
20+
.. |Step 4| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/mapper_4.png
21+
22+
.. figure::
23+
https://github.com/lucasimi/tda-mapper-python/raw/main/docs/source/logos/tda-mapper-logo-horizontal.png
24+
:alt: Logo
25+
26+
|PyPI version| |downloads| |test| |publish| |docs| |codecov| |DOI|
27+
|Streamlit App|
28+
29+
tda-mapper
30+
==========
31+
32+
**tda-mapper** is a simple and efficient Python library implementing the
33+
Mapper algorithm for Topological Data Analysis (TDA). It enables fast
34+
computation of Mapper graphs using *vp-trees* to optimize the
35+
construction of open covers for enhanced performance and scalability.
36+
37+
For further details, please refer to our
38+
`preprint <https://doi.org/10.5281/zenodo.10659651>`__.
39+
40+
- **Installation**: ``pip install tda-mapper``
41+
42+
- **Documentation**:
43+
`Online on Read the Docs <https://tda-mapper.readthedocs.io/en/main/>`__.
44+
45+
- **Interactive App**:
46+
`Live Demo on Streamlit Cloud <https://tda-mapper-app.streamlit.app/>`__,
47+
or run Locally with:
48+
49+
::
50+
51+
pip install -r app/requirements.txt
52+
streamlit run app/streamlit_app.py
53+
54+
Features
55+
--------
56+
57+
- **Efficient Mapper Computation**: Optimized for higher-dimensional
58+
lenses.
59+
60+
- **Interactive Visualizations**: Multiple plotting backends for
61+
flexibility.
62+
63+
- **Interactive App**: Interactive tool for quick, in-depth data
64+
exploration.
65+
66+
Background
67+
----------
68+
69+
The Mapper algorithm is a well-known technique in the field of
70+
topological data analysis that allows data to be represented as a graph.
71+
Mapper is used in various fields such as machine learning, data mining,
72+
and social sciences, due to its ability to preserve topological features
73+
of the underlying space, providing a visual representation that
74+
facilitates exploration and interpretation. For an in-depth coverage of
75+
Mapper you can read `the original
76+
paper <https://research.math.osu.edu/tgda/mapperPBG.pdf>`__.
77+
78+
+-----------------+-----------------+-----------------+-----------------+
79+
| Step 1 | Step 2 | Step 3 | Step 4 |
80+
+=================+=================+=================+=================+
81+
| |Step 1| | |Step 2| | |Step 3| | |Step 4| |
82+
+-----------------+-----------------+-----------------+-----------------+
83+
| Chose lens | Cover image | Run clustering | Build graph |
84+
+-----------------+-----------------+-----------------+-----------------+
85+
86+
.. toctree::
87+
:maxdepth: 1
88+
89+
quickstart
90+
examples
91+
citations
92+
apiref

‎docs/source/overview.rst‎

Lines changed: 0 additions & 44 deletions
This file was deleted.

0 commit comments

Comments
 (0)