Skip to content

Commit bfbe9f4

Browse files
lucasimilucasimi
committed
Improved documentation
1 parent 7e3749b commit bfbe9f4

5 files changed

Lines changed: 142 additions & 82 deletions

File tree

‎README.md‎

Lines changed: 32 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -17,21 +17,8 @@ It enables fast computation of Mapper graphs by using *vp-trees* to optimize
1717
the construction of open covers, improving both performance and scalability.
1818

1919
For further details, please refer to the
20-
[preprint](https://doi.org/10.5281/zenodo.10659651).
21-
22-
- **Installation**: `pip install tda-mapper`
23-
24-
- **Documentation**: [Online on Read the Docs](https://tda-mapper.readthedocs.io/en/main/).
25-
26-
- **Interactive App**: [Live Demo on Streamlit Cloud](https://tda-mapper-app.streamlit.app/),
27-
or run locally with:
28-
29-
```
30-
pip install -r app/requirements.txt
31-
streamlit run app/streamlit_app.py
32-
```
33-
34-
## Features
20+
[preprint](https://doi.org/10.5281/zenodo.10659651) and
21+
[online documentation](https://tda-mapper.readthedocs.io/en/main/).
3522

3623
- **Efficient Mapper Computation**: Optimized for higher-dimensional lenses.
3724

@@ -56,8 +43,29 @@ read
5643
| ![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) |
5744
| Chose lens | Cover image | Run clustering | Build graph |
5845

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+
5957
## Quick Start
6058

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+
6169
Here's a minimal example using the **circles dataset** from `scikit-learn` to
6270
demonstrate how to use **tda-mapper**:
6371

@@ -92,13 +100,13 @@ fig.show(config={'scrollZoom': True})
92100
More examples can be found in the
93101
[documentation](https://tda-mapper.readthedocs.io/en/main/examples.html).
94102

95-
## Citations
103+
## Interactive App
96104

97-
If you use **tda-mapper** in your work, please consider citing both the
98-
[library](https://doi.org/10.5281/zenodo.10642381), archived in a permanent
99-
Zenodo record, and the [preprint](https://doi.org/10.5281/zenodo.10659651),
100-
which provides a broader methodological overview.
101-
We recommend citing the specific version of the library used in your research,
102-
as well as the latest version of the preprint.
103-
For citation examples, refer to the
104-
[documentation](https://tda-mapper.readthedocs.io/en/main/citations.html).
105+
You can see a live demo of **tda-mapper** without installing anything on the
106+
[Live Demo on Streamlit Cloud](https://tda-mapper-app.streamlit.app/),
107+
or run Locally with:
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 & 39 deletions
This file was deleted.

‎docs/source/conf.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,12 @@
2626
html_logo = 'logos/tda-mapper-logo-horizontal.png'
2727
html_theme_options = {
2828
'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/',
2937
}

‎docs/source/index.rst‎

Lines changed: 53 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -35,24 +35,9 @@ It enables fast computation of Mapper graphs by using *vp-trees* to optimize
3535
the construction of open covers, improving both performance and scalability.
3636

3737
For further details, please refer to the
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-
--------
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 see a live demo of **tda-mapper** without installing anything on the
80+
`Live Demo on Streamlit Cloud <https://tda-mapper-app.streamlit.app/>`__,
81+
or run Locally with:
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)