{"id":37067650,"url":"https://github.com/lucasimi/tda-mapper-python","last_synced_at":"2026-01-14T07:56:59.086Z","repository":{"id":104380620,"uuid":"545083679","full_name":"lucasimi/tda-mapper-python","owner":"lucasimi","description":"A simple and efficient Python implementation of Mapper algorithm for Topological Data Analysis","archived":false,"fork":false,"pushed_at":"2025-09-22T07:58:23.000Z","size":9756,"stargazers_count":15,"open_issues_count":9,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-10-27T04:06:20.803Z","etag":null,"topics":["mapper","mapper-algorithm","tda","topological-data-analysis","topological-machine-learning","topology","topology-visualization"],"latest_commit_sha":null,"homepage":"https://tda-mapper.readthedocs.io/en/main/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucasimi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":".zenodo.json","notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-10-03T18:54:08.000Z","updated_at":"2025-09-22T07:58:25.000Z","dependencies_parsed_at":null,"dependency_job_id":"5583d811-f0a1-4bfa-aaea-27bc551f025e","html_url":"https://github.com/lucasimi/tda-mapper-python","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/lucasimi/tda-mapper-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasimi%2Ftda-mapper-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasimi%2Ftda-mapper-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasimi%2Ftda-mapper-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasimi%2Ftda-mapper-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucasimi","download_url":"https://codeload.github.com/lucasimi/tda-mapper-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucasimi%2Ftda-mapper-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mapper","mapper-algorithm","tda","topological-data-analysis","topological-machine-learning","topology","topology-visualization"],"created_at":"2026-01-14T07:56:58.300Z","updated_at":"2026-01-14T07:56:59.078Z","avatar_url":"https://github.com/lucasimi.png","language":"Python","readme":"![Logo](https://github.com/lucasimi/tda-mapper-python/raw/main/docs/source/logos/tda-mapper-logo-horizontal.png)\n\n[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n\n[![PyPI version](https://img.shields.io/pypi/v/tda-mapper?logo=python\u0026logoColor=silver)](https://pypi.python.org/pypi/tda-mapper)\n[![downloads](https://img.shields.io/pypi/dm/tda-mapper?logo=python\u0026logoColor=silver)](https://pypi.python.org/pypi/tda-mapper)\n[![codecov](https://img.shields.io/codecov/c/github/lucasimi/tda-mapper-python?logo=codecov\u0026logoColor=silver)](https://codecov.io/github/lucasimi/tda-mapper-python)\n[![test](https://img.shields.io/github/actions/workflow/status/lucasimi/tda-mapper-python/test-unit.yml?logo=github\u0026logoColor=silver\u0026branch=main\u0026label=test)](https://github.com/lucasimi/tda-mapper-python/actions/workflows/test-unit.yml)\n[![publish](https://img.shields.io/github/actions/workflow/status/lucasimi/tda-mapper-python/publish-pypi.yml?logo=github\u0026logoColor=silver\u0026label=publish)](https://github.com/lucasimi/tda-mapper-python/actions/workflows/publish-pypi.yml)\n[![docs](https://img.shields.io/readthedocs/tda-mapper/main?logo=readthedocs\u0026logoColor=silver)](https://tda-mapper.readthedocs.io/en/main/)\n[![DOI](https://img.shields.io/badge/DOI-10.5281/zenodo.10642381-blue?logo=doi\u0026logoColor=silver)](https://doi.org/10.5281/zenodo.10642381)\n\n# tda-mapper\n \n**tda-mapper** is a Python library built around the Mapper algorithm, a core\ntechnique in Topological Data Analysis (TDA) for extracting topological\nstructure from complex data. Designed for computational efficiency and\nscalability, it leverages optimized spatial search methods to support\nhigh-dimensional datasets. The library is well-suited for integration into\nmachine learning pipelines, unsupervised learning tasks, and exploratory data\nanalysis.\n\nFurther details in the\n[documentation](https://tda-mapper.readthedocs.io/en/main/)\nand in the\n[paper](https://openreview.net/pdf?id=lTX4bYREAZ).\n\n### Core Features\n\n- **Efficient construction**\n    \n    Leverages optimized spatial search techniques and parallelization to\n    accelerate the construction of Mapper graphs, supporting the analysis of\n    high-dimensional datasets.\n\n- **Scikit-learn integration**\n\n    Provides custom estimators that are fully compatible with scikit-learn's\n    API, enabling seamless integration into scikit-learn pipelines for tasks\n    such as dimensionality reduction, clustering, and feature extraction.\n\n- **Flexible visualization**\n\n    Multiple visualization backends supported (Plotly, Matplotlib, PyVis) for\n    generating high-quality Mapper graph representations with adjustable \n    layouts and styling.\n\n- **Interactive app**\n\n    Provides an interactive web-based interface for dynamic exploration of\n    Mapper graph structures, offering real-time adjustments to parameters and\n    visualizations.\n\n## Background\n\nThe Mapper algorithm extracts topological features from complex datasets,\nrepresenting them as graphs that highlight clusters, transitions, and key\nstructural patterns. These insights reveal hidden data relationships and are\napplicable across diverse fields, including social sciences, biology, and\nmachine learning. For an in-depth overview of Mapper, including its\nmathematical foundations and practical applications, read \n[the original paper](https://research.math.osu.edu/tgda/mapperPBG.pdf).\n\n| Step 1 | Step 2 | Step 3 | Step 4 |\n| ------ | ------ | ------ | ------ |\n| ![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) |\n| Choose lens | Cover image | Run clustering | Build graph |\n\n## Quick Start\n\n### Installation\n\nTo install the latest version uploaded on PyPI\n\n```bash\npip install tda-mapper\n```\n\n### How to Use\n\nHere's a minimal example using the **circles dataset** from `scikit-learn` to\ndemonstrate how to use **tda-mapper**. This example demonstrates how to apply\nthe Mapper algorithm on a synthetic dataset (concentric circles). The goal is\nto extract a topological graph representation using `PCA` as a lens and\n`DBSCAN` for clustering. We proceed as follows:\n\n```python\nimport matplotlib.pyplot as plt\nfrom sklearn.datasets import make_circles\n\nimport numpy as np\nfrom sklearn.decomposition import PCA\nfrom sklearn.cluster import DBSCAN\n\nfrom tdamapper.learn import MapperAlgorithm\nfrom tdamapper.cover import CubicalCover\nfrom tdamapper.plot import MapperPlot\n\n# Generate toy dataset\nX, labels = make_circles(n_samples=5000, noise=0.05, factor=0.3, random_state=42)\nplt.figure(figsize=(5, 5))\nplt.scatter(X[:,0], X[:,1], c=labels, s=0.25, cmap=\"jet\")\nplt.axis(\"off\")\nplt.show()\n\n# Apply PCA as lens\ny = PCA(2, random_state=42).fit_transform(X)\n\n# Mapper pipeline\ncover = CubicalCover(n_intervals=10, overlap_frac=0.3)\nclust = DBSCAN()\ngraph = MapperAlgorithm(cover, clust).fit_transform(X, y)\n\n# Visualize the Mapper graph\nfig = MapperPlot(graph, dim=2, seed=42, iterations=60).plot_plotly(colors=labels)\nfig.show(config={\"scrollZoom\": True})\n```\n\n| Original Dataset | Mapper Graph |\n| ---------------- | ------------ |\n| ![Original Dataset](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_dataset_v2.png) | ![Mapper Graph](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/circles_mean_v2.png) |\n\nLeft: the original dataset consisting of two concentric circles with noise,\ncolored by class label. Right: the resulting Mapper graph, built from the PCA\nprojection and clustered using DBSCAN. The two concentric circles are well\nidentified by the connected components in the Mapper graph.\n\nMore examples can be found in the\n[documentation](https://tda-mapper.readthedocs.io/en/main/examples.html).\n\n## Interactive App\n\nUse our app to interactively visualize and explore your data without writing\ncode. You can try it right away using \n[our live demo](https://tda-mapper-app.up.railway.app/),\nor run it locally on your machine.\n\nTo run it locally:\n\n1. Install the app and its dependencies:\n\n    ```bash\n    pip install tda-mapper[app]\n    ```\n\n2. Launch the app:\n\n    ```bash\n    tda-mapper-app\n    ```\n\n![tda-mapper-app](https://github.com/lucasimi/tda-mapper-python/raw/main/resources/tda-mapper-app.png)\n\n## Citations\n\nIf you use **tda-mapper** in your work, please consider citing both the\n[library](https://doi.org/10.5281/zenodo.10642381), archived in a permanent\nZenodo record, and the [paper](https://openreview.net/pdf?id=lTX4bYREAZ),\nwhich provides a broader methodological overview. We recommend citing the\nspecific version of the library used in your research, along with the paper.\nFor citation examples, please refer to the\n[documentation](https://tda-mapper.readthedocs.io/en/main/#citations).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasimi%2Ftda-mapper-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucasimi%2Ftda-mapper-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucasimi%2Ftda-mapper-python/lists"}