Skip to content

Commit b6c013a

Browse files
lucasimilucasimi
authored
Merge pull request #160 from lucasimi/develop
Develop
2 parents f3c3513 + 797df4c commit b6c013a

31 files changed

+2207
-1513
lines changed

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@
1515
**/*.dll
1616
**/*.dylib
1717

18+
**/*.js
19+
**/*.html
20+
**/*.css
21+
1822
.coverage
1923
.vscode
2024
.idea

‎README.md‎

Lines changed: 69 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,31 @@
1111

1212
# tda-mapper
1313

14-
A simple and efficient Python implementation of Mapper algorithm for
15-
Topological Data Analysis
14+
**tda-mapper** is a simple and efficient Python library implementing the Mapper algorithm for Topological Data Analysis (TDA).
15+
It enables fast computation of Mapper graphs using *vp-trees* to optimize the construction of open covers for enhanced performance and scalability.
1616

17-
* **Installation**: `pip install tda-mapper`
17+
For further details, please refer to our [preprint](https://doi.org/10.5281/zenodo.10659651).
1818

19-
* **Documentation**: https://tda-mapper.readthedocs.io/en/main/
19+
- **Installation**: `pip install tda-mapper`
2020

21-
* **Demo App**: https://tda-mapper-app.streamlit.app/
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+
```
29+
30+
## Features
31+
32+
- **Efficient Mapper Computation**: Optimized for higher-dimensional lenses.
33+
34+
- **Interactive Visualizations**: Multiple plotting backends for flexibility.
35+
36+
- **Interactive App**: Interactive tool for quick, in-depth data exploration.
37+
38+
## Background
2239
2340
The Mapper algorithm is a well-known technique in the field of topological
2441
data analysis that allows data to be represented as a graph.
@@ -29,22 +46,15 @@ exploration and interpretation. For an in-depth coverage of Mapper you can
2946
read
3047
[the original paper](https://research.math.osu.edu/tgda/mapperPBG.pdf).
3148
32-
This library contains an implementation of Mapper, where the construction
33-
of open covers is based on *vp-trees* for improved performance and scalability.
34-
The details about this methodology are contained in
35-
[our preprint](https://doi.org/10.5281/zenodo.10659651).
3649
3750
| Step 1 | Step 2 | Step 3 | Step 4 |
3851
| ------ | ------ | ------ | ------ |
3952
| ![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) |
4053
| Chose lens | Cover image | Run clustering | Build graph |
4154
42-
## Example
55+
## Quick Start
4356
44-
[Here](https://github.com/lucasimi/tda-mapper-python/raw/main/tests/example.py)
45-
you can find an example to use to kickstart your analysis. In this toy-example
46-
we use a two-dimensional dataset of two concentric circles. The Mapper graph
47-
is a topological summary of the whole point cloud.
57+
Here's a minimal example using the **circles dataset** from `scikit-learn` to demonstrate how to use **tda-mapper**:
4858
4959
```python
5060
import numpy as np
@@ -55,68 +65,56 @@ from sklearn.cluster import DBSCAN
5565
5666
from tdamapper.core import MapperAlgorithm
5767
from tdamapper.cover import CubicalCover
58-
from tdamapper.plot import MapperLayoutInteractive
59-
60-
X, y = make_circles( # load a labelled dataset
61-
n_samples=5000,
62-
noise=0.05,
63-
factor=0.3,
64-
random_state=42)
65-
lens = PCA(2).fit_transform(X)
66-
67-
mapper_algo = MapperAlgorithm(
68-
cover=CubicalCover(
69-
n_intervals=10,
70-
overlap_frac=0.3),
71-
clustering=DBSCAN())
72-
mapper_graph = mapper_algo.fit_transform(X, lens)
73-
74-
mapper_plot = MapperLayoutInteractive(
75-
mapper_graph,
76-
colors=y, # color according to categorical values
77-
cmap='jet', # Jet colormap, for classes
78-
agg=np.nanmean, # aggregate on nodes according to mean
79-
dim=2,
80-
iterations=60,
81-
seed=42,
82-
width=600,
83-
height=600)
84-
85-
fig_mean = mapper_plot.plot()
86-
fig_mean.show(config={'scrollZoom': True})
87-
88-
mapper_plot.update( # reuse the plot with the same positions
89-
colors=y,
90-
cmap='viridis', # viridis colormap, for ranges
91-
agg=np.nanstd, # aggregate on nodes according to std
92-
)
93-
94-
fig_std = mapper_plot.plot()
95-
fig_std.show(config={'scrollZoom': True})
96-
```
68+
from tdamapper.plot import MapperPlot
9769
98-
| Dataset | Mapper graph (average) | Mapper graph (deviation) |
99-
| ------- | ---------------------- | ------------------------ |
100-
| ![Dataset](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_dataset.png) | ![Mapper graph (average)](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_mean.png) | ![Mapper graph (standard deviation)](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_std.png) |
70+
# load a labelled dataset
71+
X, labels = make_circles(n_samples=5000, noise=0.05, factor=0.3, random_state=42)
72+
y = PCA(2, random_state=42).fit_transform(X)
10173
102-
More examples can be found in the
103-
[documentation](https://tda-mapper.readthedocs.io/en/main/).
74+
cover = CubicalCover(n_intervals=10, overlap_frac=0.3)
75+
clust = DBSCAN()
76+
graph = MapperAlgorithm(cover, clust).fit_transform(X, y)
10477
105-
### Demo App
78+
# color according to labels
79+
fig = MapperPlot(graph, dim=2, seed=42, iterations=60).plot_plotly(colors=labels)
80+
fig.show(config={'scrollZoom': True})
81+
```
10682

107-
You can also run a demo app locally by running
83+
| Original Dataset | Mapper Graph |
84+
| ---------------- | ------------ |
85+
| ![Original Dataset](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_dataset.png) | ![Mapper Graph](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_mean.png) |
10886

109-
```
110-
pip install -r app/requirements.txt
111-
streamlit run app/streamlit_app.py
112-
```
87+
More examples can be found in the
88+
[documentation](https://tda-mapper.readthedocs.io/en/main/).
11389

11490
## Citations
11591

116-
If you want to use **tda-mapper** in your work or research, you can cite the
117-
[archive uploaded on Zenodo](https://doi.org/10.5281/zenodo.10642381),
118-
pointing to the specific version of the software used in your work.
119-
120-
If you want to cite the methodology on which **tda-mapper** is based, you can
121-
use the
122-
[preprint](https://doi.org/10.5281/zenodo.10659651).
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+
}
105+
```
106+
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/tdamapper.rst renamed to docs/source/apiref.rst

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
tdamapper
2-
=========
1+
API Reference
2+
=============
33

44
tdamapper.core
55
--------------
@@ -17,14 +17,6 @@ tdamapper.cover
1717
:undoc-members:
1818
:show-inheritance:
1919

20-
tdamapper.proximity
21-
-------------------
22-
23-
.. automodule:: tdamapper.proximity
24-
:members:
25-
:undoc-members:
26-
:show-inheritance:
27-
2820
tdamapper.clustering
2921
--------------------
3022

@@ -55,4 +47,4 @@ tdamapper.plot
5547
.. automodule:: tdamapper.plot
5648
:members:
5749
:undoc-members:
58-
:show-inheritance:
50+
:show-inheritance:

‎docs/source/citations.rst‎

Lines changed: 28 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,36 @@
11
Citations
22
=========
33

4-
If you want to use **tda-mapper** in your work or research, you can cite the
5-
`archive uploaded on Zenodo <https://doi.org/10.5281/zenodo.10642381>`__,
6-
pointing to the specific version of the software used in your work, for example:
4+
- **tda-mapper**: To cite this library, reference the Zenodo
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:
78

8-
.. code:: RST
9+
.. code:: bibtex
910
10-
@software{simi_2024_10883941,
11-
author = {Simi, Luca},
12-
title = {tda-mapper},
13-
month = mar,
14-
year = 2024,
15-
publisher = {Zenodo},
16-
version = {v0.5.2},
17-
doi = {10.5281/zenodo.10883941},
18-
url = {https://doi.org/10.5281/zenodo.10883941}
19-
}
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+
}
2021
21-
If you want to cite the methodology on which **tda-mapper** is based,
22-
you can use the
23-
`preprint <https://doi.org/10.5281/zenodo.10659651>`__:
22+
- **Methodology**: To cite our methodological foundation, refer to the
23+
`preprint <https://doi.org/10.5281/zenodo.10659651>`__.
2424

25-
.. code:: RST
25+
.. code:: bibtex
2626
27-
@misc{simi_2024_10659652,
28-
author = {Simi, Luca},
29-
title = {A Scalable Approach for Mapper via Vantage Point Trees},
30-
month = feb,
31-
year = 2024,
32-
publisher = {Zenodo},
33-
doi = {10.5281/zenodo.10659651},
34-
url = {https://doi.org/10.5281/zenodo.10659651}
35-
}
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+
}

0 commit comments

Comments
 (0)