Skip to content

Commit 3d231e1

Browse files
lucasimilucasimi
authored
Merge pull request #168 from lucasimi/develop
Develop
2 parents 4ec1a8f + 9e6bf98 commit 3d231e1

File tree

9 files changed

+313
-152
lines changed

9 files changed

+313
-152
lines changed

‎README.md‎

Lines changed: 43 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -11,31 +11,22 @@
1111

1212
# tda-mapper
1313

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.
14+
**tda-mapper** is a simple and efficient Python library implementing the
15+
Mapper algorithm for Topological Data Analysis (TDA).
16+
It enables fast computation of Mapper graphs by using *vp-trees* to optimize
17+
the construction of open covers, improving both performance and scalability.
1618

17-
For further details, please refer to our [preprint](https://doi.org/10.5281/zenodo.10659651).
18-
19-
- **Installation**: `pip install tda-mapper`
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-
```
29-
30-
## Features
19+
For further details, please refer to the
20+
[preprint](https://doi.org/10.5281/zenodo.10659651) and
21+
[online documentation](https://tda-mapper.readthedocs.io/en/main/).
3122

3223
- **Efficient Mapper Computation**: Optimized for higher-dimensional lenses.
3324

3425
- **Interactive Visualizations**: Multiple plotting backends for flexibility.
3526

3627
- **Interactive App**: Interactive tool for quick, in-depth data exploration.
3728

38-
## Background
29+
### Background
3930

4031
The Mapper algorithm is a well-known technique in the field of topological
4132
data analysis that allows data to be represented as a graph.
@@ -52,9 +43,31 @@ read
5243
| ![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) |
5344
| Chose lens | Cover image | Run clustering | Build graph |
5445

46+
### Citations
47+
48+
If you use **tda-mapper** in your work, please consider citing both the
49+
[library](https://doi.org/10.5281/zenodo.10642381), archived in a permanent
50+
Zenodo record, and the [preprint](https://doi.org/10.5281/zenodo.10659651),
51+
which provides a broader methodological overview.
52+
We recommend citing the specific version of the library used in your research,
53+
as well as the latest version of the preprint.
54+
For citation examples, refer to the
55+
[documentation](https://tda-mapper.readthedocs.io/en/main/citations.html).
56+
5557
## Quick Start
5658

57-
Here's a minimal example using the **circles dataset** from `scikit-learn` to demonstrate how to use **tda-mapper**:
59+
### Installation
60+
61+
To install the latest version uploaded on PyPI
62+
63+
```bash
64+
pip install tda-mapper
65+
```
66+
67+
### How to Use
68+
69+
Here's a minimal example using the **circles dataset** from `scikit-learn` to
70+
demonstrate how to use **tda-mapper**:
5871

5972
```python
6073
import numpy as np
@@ -85,36 +98,15 @@ fig.show(config={'scrollZoom': True})
8598
| ![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) |
8699

87100
More examples can be found in the
88-
[documentation](https://tda-mapper.readthedocs.io/en/main/).
89-
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-
}
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-
```
101+
[documentation](https://tda-mapper.readthedocs.io/en/main/examples.html).
102+
103+
### Interactive App
104+
105+
You can explore a live demo of **tda-mapper** directly on
106+
[Streamlit Cloud](https://tda-mapper-app.streamlit.app/),
107+
or run it locally using the following:
108+
109+
```
110+
pip install -r app/requirements.txt
111+
streamlit run app/streamlit_app.py
112+
```

‎docs/source/citations.rst‎

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

‎docs/source/conf.py‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
# -- General configuration ---------------------------------------------------
1414
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
1515

16-
extensions = ['sphinx.ext.autodoc', 'sphinx_rtd_theme', 'nbsphinx']
16+
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_rtd_theme', 'nbsphinx']
1717

1818
templates_path = ['_templates']
1919
exclude_patterns = []
@@ -23,9 +23,15 @@
2323
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
2424

2525
html_theme = 'sphinx_rtd_theme'
26-
html_static_path = ['_static']
2726
html_logo = 'logos/tda-mapper-logo-horizontal.png'
28-
2927
html_theme_options = {
3028
'sticky_navigation': True,
29+
'vcs_pageview_mode': 'blob',
30+
}
31+
html_context = {
32+
'display_github': True,
33+
'github_user': 'lucasimi',
34+
'github_repo': 'tda-mapper-python',
35+
'github_version': 'main',
36+
'conf_py_path': '/docs/source/',
3137
}

‎docs/source/index.rst‎

Lines changed: 57 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -30,29 +30,14 @@ tda-mapper
3030
==========
3131

3232
**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.
33+
Mapper algorithm for Topological Data Analysis (TDA).
34+
It enables fast computation of Mapper graphs by using *vp-trees* to optimize
35+
the construction of open covers, improving both performance and scalability.
3636

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-
--------
37+
For further details, please refer to the
38+
`preprint <https://doi.org/10.5281/zenodo.10659651>`__,
39+
and
40+
`online documentation <https://tda-mapper.readthedocs.io/en/main/>`__.
5641

5742
- **Efficient Mapper Computation**: Optimized for higher-dimensional
5843
lenses.
@@ -63,6 +48,7 @@ Features
6348
- **Interactive App**: Interactive tool for quick, in-depth data
6449
exploration.
6550

51+
6652
Background
6753
----------
6854

@@ -83,10 +69,58 @@ paper <https://research.math.osu.edu/tgda/mapperPBG.pdf>`__.
8369
| Chose lens | Cover image | Run clustering | Build graph |
8470
+-----------------+-----------------+-----------------+-----------------+
8571

72+
73+
Citations
74+
---------
75+
76+
If you use **tda-mapper** in your work, please consider citing both the
77+
`library <https://doi.org/10.5281/zenodo.10642381>`__,
78+
archived in a permanent Zenodo record, and the
79+
`preprint <https://doi.org/10.5281/zenodo.10659651>`__,
80+
which provides a broader methodological overview.
81+
We recommend citing the specific version of the library used in your research, as well as the latest version of the preprint.
82+
83+
- **tda-mapper**: For example to cite version 0.7.3 you can use:
84+
85+
.. code:: bibtex
86+
87+
@software{simi_2024_12729251,
88+
author = {Simi, Luca},
89+
title = {tda-mapper},
90+
month = jul,
91+
year = 2024,
92+
publisher = {Zenodo},
93+
version = {v0.7.3},
94+
doi = {10.5281/zenodo.12729251},
95+
url = {https://doi.org/10.5281/zenodo.12729251}
96+
}
97+
98+
- **Methodology**: For the preprint, you can use:
99+
100+
.. code:: bibtex
101+
102+
@misc{simi_2024_11187959,
103+
author = {Simi, Luca},
104+
title = {{A Scalable Approach for Mapper via Vantage Point
105+
Trees}},
106+
month = may,
107+
year = 2024,
108+
publisher = {Zenodo},
109+
doi = {10.5281/zenodo.11187959},
110+
url = {https://doi.org/10.5281/zenodo.11187959}
111+
}
112+
113+
86114
.. toctree::
115+
:caption: User's Guide
87116
:maxdepth: 1
88117

89118
quickstart
90119
examples
91-
citations
120+
121+
122+
.. toctree::
123+
:caption: API Reference
124+
:maxdepth: 1
125+
92126
apiref

‎docs/source/quickstart.rst‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,42 @@
11
Quick Start
2+
===========
3+
4+
5+
Installation
6+
------------
7+
8+
To install the latest version uploaded on PyPI
9+
10+
.. code:: bash
11+
12+
pip install tda-mapper
13+
14+
15+
Development
216
-----------
317

18+
- To install the latest version with dev dependencies
19+
20+
.. code:: bash
21+
22+
pip install tda-mapper[dev]
23+
24+
- To install from the latest commit on main branch
25+
26+
.. code:: bash
27+
28+
pip install git+https://github.com/lucasimi/tda-mapper-python
29+
30+
- To install from the latest commit of develop branch
31+
32+
.. code:: bash
33+
34+
pip install git+https://github.com/lucasimi/tda-mapper-python@develop
35+
36+
37+
How To Use
38+
----------
39+
440
Here's a minimal example using the **circles dataset** from
541
``scikit-learn`` to demonstrate how to use **tda-mapper**:
642

@@ -37,5 +73,18 @@ Here's a minimal example using the **circles dataset** from
3773
More examples can be found in the
3874
`documentation <https://tda-mapper.readthedocs.io/en/main/>`__.
3975

76+
Interactive App
77+
---------------
78+
79+
You can explore a live demo of **tda-mapper** directly on
80+
`Streamlit Cloud <https://tda-mapper-app.streamlit.app/>`__,
81+
or run it locally using the following:
82+
83+
.. code:: bash
84+
85+
pip install -r app/requirements.txt
86+
streamlit run app/streamlit_app.py
87+
88+
4089
.. |Original Dataset| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_dataset.png
4190
.. |Mapper Graph| image:: https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_mean.png

0 commit comments

Comments
 (0)