Skip to content

Commit a4131a4

Browse files
lucasimilucasimi
authored
Merge pull request #174 from lucasimi/develop
Develop
2 parents d03c7dc + a5fbcff commit a4131a4

14 files changed

Lines changed: 358 additions & 67 deletions

‎CODE_OF_CONDUCT.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, religion, or sexual identity
10+
and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
* Demonstrating empathy and kindness toward other people
21+
* Being respectful of differing opinions, viewpoints, and experiences
22+
* Giving and gracefully accepting constructive feedback
23+
* Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
* Focusing on what is best not just for us as individuals, but for the
26+
overall community
27+
28+
Examples of unacceptable behavior include:
29+
30+
* The use of sexualized language or imagery, and sexual attention or
31+
advances of any kind
32+
* Trolling, insulting or derogatory comments, and personal or political attacks
33+
* Public or private harassment
34+
* Publishing others' private information, such as a physical or email
35+
address, without their explicit permission
36+
* Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official e-mail address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
lucasimi90 [at] gmail [dot] com.
64+
All complaints will be reviewed and investigated promptly and fairly.
65+
66+
All community leaders are obligated to respect the privacy and security of the
67+
reporter of any incident.
68+
69+
## Enforcement Guidelines
70+
71+
Community leaders will follow these Community Impact Guidelines in determining
72+
the consequences for any action they deem in violation of this Code of Conduct:
73+
74+
### 1. Correction
75+
76+
**Community Impact**: Use of inappropriate language or other behavior deemed
77+
unprofessional or unwelcome in the community.
78+
79+
**Consequence**: A private, written warning from community leaders, providing
80+
clarity around the nature of the violation and an explanation of why the
81+
behavior was inappropriate. A public apology may be requested.
82+
83+
### 2. Warning
84+
85+
**Community Impact**: A violation through a single incident or series
86+
of actions.
87+
88+
**Consequence**: A warning with consequences for continued behavior. No
89+
interaction with the people involved, including unsolicited interaction with
90+
those enforcing the Code of Conduct, for a specified period of time. This
91+
includes avoiding interactions in community spaces as well as external channels
92+
like social media. Violating these terms may lead to a temporary or
93+
permanent ban.
94+
95+
### 3. Temporary Ban
96+
97+
**Community Impact**: A serious violation of community standards, including
98+
sustained inappropriate behavior.
99+
100+
**Consequence**: A temporary ban from any sort of interaction or public
101+
communication with the community for a specified period of time. No public or
102+
private interaction with the people involved, including unsolicited interaction
103+
with those enforcing the Code of Conduct, is allowed during this period.
104+
Violating these terms may lead to a permanent ban.
105+
106+
### 4. Permanent Ban
107+
108+
**Community Impact**: Demonstrating a pattern of violation of community
109+
standards, including sustained inappropriate behavior, harassment of an
110+
individual, or aggression toward or disparagement of classes of individuals.
111+
112+
**Consequence**: A permanent ban from any sort of public interaction within
113+
the community.
114+
115+
## Attribution
116+
117+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
118+
version 2.0, available at
119+
https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
120+
121+
Community Impact Guidelines were inspired by [Mozilla's code of conduct
122+
enforcement ladder](https://github.com/mozilla/diversity).
123+
124+
[homepage]: https://www.contributor-covenant.org
125+
126+
For answers to common questions about this code of conduct, see the FAQ at
127+
https://www.contributor-covenant.org/faq. Translations are available at
128+
https://www.contributor-covenant.org/translations.

‎CONTRIBUTING.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Contributing
2+
3+
Thank you for considering contributing to **tda-mapper**! We welcome
4+
contributions from everyone. To ensure a smooth and productive experience,
5+
please follow the guidelines below.
6+
7+
## Reporting Issues
8+
9+
Found a bug or have a feature request? Here's how to get started:
10+
11+
1. **Search for Existing Issues**. Check the
12+
[issue tracker](https://github.com/lucasimi/tda-mapper-python/issues) to see if
13+
the issue has already been reported.
14+
15+
2. **Open a New Issue**. If you can't find any open issue related to your
16+
problem, create a new issue and provide as much detail as possible, including
17+
steps to reproduce the problem or context for the feature request.
18+
19+
## Proposing Changes
20+
21+
Contribution comes in multiple forms and we value your feedback! If you have
22+
ideas or suggestions to improve the project, feel free to start a discussion in
23+
the issue tracker.
24+
25+
## Contributing Code
26+
27+
We encourage contributions to fix bugs, enhance documentation, improve testing,
28+
or address open issues. Contributions involving new algorithms or data
29+
structures are welcome but must first be discussed in an issue, especially when
30+
it comes to performance critical parts. Please include supporting theoretical
31+
or experimental evidence for such contributions.
32+
33+
Follow these steps to contribute:
34+
35+
1. **Fork the Repository**.
36+
Start by forking the repository and cloning it locally:
37+
38+
```bash
39+
git clone https://github.com/lucasimi/tda-mapper-python.git
40+
```
41+
42+
2. **Set Up Your Development Environment**.
43+
Navigate to the project directory, create a virtual environment and install
44+
the dev dependencies:
45+
46+
```bash
47+
cd tda-mapper-python
48+
python -m venv env
49+
source env/bin/activate # On Windows: env\Scripts\activate
50+
pip install -e .[dev]
51+
```
52+
53+
3. **Make Your Changes**.
54+
Work on a dedicated branch for your feature or bug fix:
55+
56+
```bash
57+
git checkout -b your-feature-branch
58+
```
59+
60+
Write clear, well-documented code. Add tests for any new functionality to
61+
ensure correctness. All performance critical commits should be covered by
62+
a benchmark test to avoid performance regressions. Unit tests should follow
63+
the naming convention `test_unit_*.py`, and benchmark tests should follow
64+
the naming convention `test_bench_*.py`.
65+
66+
4. **Run Tests**.
67+
Ensure your changes pass all tests before committing. We use `unittest` as
68+
test framework:
69+
70+
```bash
71+
python -m unittest discover -s tests -p 'test_*.py'
72+
```
73+
74+
Before each commit make sure to check code coverage:
75+
76+
```bash
77+
coverage run --source=src -m unittest discover -s tests -p 'test_*.py'
78+
```
79+
80+
5. **Commit and Push Your Changes**.
81+
Commit your changes with a descriptive message:
82+
83+
```bash
84+
git commit -m "Fixes bug with feature X"
85+
git push origin your-feature-branch
86+
```
87+
88+
6. **Submit a Pull Request**.
89+
Once your changes are ready, tested with adequate coverage, and documented,
90+
open a pull request (PR) on the repository's GitHub page. Be sure to:
91+
92+
- Provide a clear title and description for your PR.
93+
94+
- Reference any related issues by using #issue-number.
95+
96+
All pull requests will be reviewed by at least one core contributor. They
97+
may be subject to rejection or may require changes before merging.
98+
99+
### Backward Compatibility
100+
101+
We prioritize backward compatibility according to semantic versioning. Code
102+
contributions introducing breaking changes must be discussed and decided in a
103+
related issue. Every deprecation must be clearly warned to users calling
104+
deprecated APIs. New releases are decided from core contributors, based on the
105+
addition of new features, bug fixes, and deprecations. Deprecated APIs are
106+
removed whenever required by a new jump in major version.
107+
108+
### Code Style
109+
110+
We follow [PEP 8](https://peps.python.org/pep-0008/) for Python code style.
111+
You can run a linter to check your code:
112+
113+
```bash
114+
flake8
115+
```
116+
117+
### Documentation
118+
119+
Ensure that new features and APIs are documented in the code and that
120+
documentation is correctly generated. Documentation is generated from
121+
docstrings using sphinx, and docstrings should follow Sphinx format.
122+
To build the documentation locally:
123+
124+
```bash
125+
cd docs
126+
make html
127+
```
128+
129+
## Thank You!
130+
131+
We appreciate your contributions and are excited to collaborate with you on
132+
making **tda-mapper** better! If you have any questions, feel free to reach
133+
out via the issue tracker.

‎README.md‎

Lines changed: 27 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
![Logo](https://github.com/lucasimi/tda-mapper-python/raw/main/docs/source/logos/tda-mapper-logo-horizontal.png)
22

3+
[![Source Code](https://img.shields.io/badge/lucasimi-tda--mapper--python-blue?logo=github&logoColor=silver)](https://github.com/lucasimi/tda-mapper-python)
34
[![PyPI version](https://img.shields.io/pypi/v/tda-mapper?logo=python&logoColor=silver)](https://pypi.python.org/pypi/tda-mapper)
45
[![downloads](https://img.shields.io/pypi/dm/tda-mapper?logo=python&logoColor=silver)](https://pypi.python.org/pypi/tda-mapper)
56
[![test](https://img.shields.io/github/actions/workflow/status/lucasimi/tda-mapper-python/test.yml?logo=github&logoColor=silver&branch=main&label=test)](https://github.com/lucasimi/tda-mapper-python/actions/workflows/test.yml)
@@ -11,37 +12,40 @@
1112

1213
# tda-mapper
1314

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.
15+
**tda-mapper** is a Python library based on the Mapper algorithm, a key tool in
16+
Topological Data Analysis (TDA). Designed for efficient computations and backed
17+
by advanced spatial search techniques, it scales seamlessly to high dimensional
18+
data, making it suitable for applications in machine learning, data mining, and
19+
exploratory data analysis.
1820

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/).
21+
Further details in the
22+
[documentation](https://tda-mapper.readthedocs.io/en/main/)
23+
and in the
24+
[preprint](https://doi.org/10.5281/zenodo.10659651).
2225

23-
- **Efficient Mapper Computation**: Optimized for higher-dimensional lenses.
26+
### Main Features
2427

25-
- **Interactive Visualizations**: Multiple plotting backends for flexibility.
28+
- **Fast Mapper graph construction**: Accelerates computations with efficient spatial search, enabling analysis of large, high-dimensional datasets.
2629

27-
- **Interactive App**: Interactive tool for quick, in-depth data exploration.
30+
- **Scikit-learn compatibility**: Easily integrate Mapper as a part of your machine learning workflows.
31+
32+
- **Flexible visualization options**: Visualize Mapper graphs with multiple supported backends, tailored to your needs.
33+
34+
- **Interactive exploration**: Explore data interactively through a user-friendly app.
2835

2936
### Background
3037

31-
The Mapper algorithm is a well-known technique in the field of topological
32-
data analysis that allows data to be represented as a graph.
33-
Mapper is used in various fields such as machine learning, data mining, and
34-
social sciences, due to its ability to preserve topological features of the
35-
underlying space, providing a visual representation that facilitates
36-
exploration and interpretation. For an in-depth coverage of Mapper you can
37-
read
38+
The Mapper algorithm transforms complex datasets into graph representations
39+
that highlight clusters, transitions, and topological features. These insights
40+
reveal hidden patterns in data, applicable across fields like social sciences,
41+
biology, and machine learning. For an in-depth coverage of Mapper, including
42+
its mathematical foundations and applications, read the
3843
[the original paper](https://research.math.osu.edu/tgda/mapperPBG.pdf).
3944

40-
4145
| Step 1 | Step 2 | Step 3 | Step 4 |
4246
| ------ | ------ | ------ | ------ |
4347
| ![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) |
44-
| Chose lens | Cover image | Run clustering | Build graph |
48+
| Choose lens | Cover image | Run clustering | Build graph |
4549

4650
### Citations
4751

@@ -54,6 +58,7 @@ as well as the latest version of the preprint.
5458
For citation examples, refer to the
5559
[documentation](https://tda-mapper.readthedocs.io/en/main/#citations).
5660

61+
5762
## Quick Start
5863

5964
### Installation
@@ -102,9 +107,10 @@ More examples can be found in the
102107

103108
### Interactive App
104109

105-
You can explore a live demo of **tda-mapper** directly on
110+
Use our Streamlit app to visualize and explore your data without writing code.
111+
You can run a live demo directly on
106112
[Streamlit Cloud](https://tda-mapper-app.streamlit.app/),
107-
or run it locally using the following:
113+
or locally on your machine using the following:
108114

109115
```
110116
pip install -r app/requirements.txt

0 commit comments

Comments
 (0)