{"id":32633434,"url":"https://github.com/luisscoccola/persistable","last_synced_at":"2025-10-30T23:52:41.346Z","repository":{"id":37996793,"uuid":"383933350","full_name":"LuisScoccola/persistable","owner":"LuisScoccola","description":"density-based clustering for exploratory data analysis based on multi-parameter persistence","archived":false,"fork":false,"pushed_at":"2025-07-20T17:17:14.000Z","size":11883,"stargazers_count":41,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-10-25T15:47:15.598Z","etag":null,"topics":["cluster-analysis","clustering","clustering-algorithm","machine-learning","machine-learning-algorithms","topological-data-analysis","unsupervised-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LuisScoccola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":null}},"created_at":"2021-07-07T21:58:19.000Z","updated_at":"2025-08-06T00:17:29.000Z","dependencies_parsed_at":"2023-12-28T15:02:13.865Z","dependency_job_id":"ed9f9cca-69fd-463a-8e05-ca1af072c2c2","html_url":"https://github.com/LuisScoccola/persistable","commit_stats":{"total_commits":210,"total_committers":4,"mean_commits":52.5,"dds":0.05238095238095242,"last_synced_commit":"2381f480701f6eaaa4c3ed4ca0055548f7f910f4"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/LuisScoccola/persistable","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuisScoccola%2Fpersistable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuisScoccola%2Fpersistable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuisScoccola%2Fpersistable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuisScoccola%2Fpersistable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LuisScoccola","download_url":"https://codeload.github.com/LuisScoccola/persistable/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LuisScoccola%2Fpersistable/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281902523,"owners_count":26581164,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-30T02:00:06.501Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cluster-analysis","clustering","clustering-algorithm","machine-learning","machine-learning-algorithms","topological-data-analysis","unsupervised-learning"],"created_at":"2025-10-30T23:51:51.731Z","updated_at":"2025-10-30T23:52:41.339Z","avatar_url":"https://github.com/LuisScoccola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n[![PyPI](https://img.shields.io/pypi/v/persistable-clustering?color=green)](https://pypi.org/project/persistable-clustering)\n[![Downloads](https://static.pepy.tech/personalized-badge/persistable-clustering?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=green\u0026left_text=Downloads)](https://pepy.tech/project/persistable-clustering)\n[![tests](https://github.com/LuisScoccola/persistable/actions/workflows/run_tests.yaml/badge.svg)](https://github.com/LuisScoccola/persistable/actions/workflows/run_tests.yaml)\n[![coverage](https://codecov.io/gh/LuisScoccola/persistable/branch/main/graph/badge.svg)](https://codecov.io/gh/LuisScoccola/persistable)\n[![docs](https://readthedocs.org/projects/persistable/badge/?version=latest)](https://persistable.readthedocs.io/)\n[![status](https://joss.theoj.org/papers/63d612cd4730c3aa708e3a47eb2c50f3/status.svg)](https://joss.theoj.org/papers/63d612cd4730c3aa708e3a47eb2c50f3)\n[![license](https://img.shields.io/github/license/LuisScoccola/persistable)](https://github.com/LuisScoccola/persistable/blob/main/LICENSE)\n---\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/LuisScoccola/persistable/main/docs/pictures/logo.svg\" width=\"550\"\u003e\n\u003c/p\u003e\n\nPersistent and stable clustering (Persistable) is a density-based clustering algorithm intended for exploratory data analysis.\nWhat distinguishes Persistable from other clustering algorithms is its visualization capabilities.\nPersistable's interactive mode lets you visualize multi-scale and multi-density cluster structure present in the data.\nThis is used to guide the choice of parameters that lead to the final clustering.\n\n\n## Usage\n\nHere is a brief outline of the main functionality; see the [documentation](https://persistable.readthedocs.io/) for details, including the [API reference](https://persistable.readthedocs.io/en/latest/api.html).\n\nIn order to run Persistable's interactive mode from a Jupyter notebook, run the following in a Jupyter cell:\n\n```python\nimport persistable\nfrom sklearn.datasets import make_blobs\n\nX = make_blobs(2000, centers=4, random_state=1)[0]\n\np = persistable.Persistable(X)\npi = persistable.PersistableInteractive(p)\npi.start_ui()\n```\n\nThe last command returns the port in `localhost` serving the UI, which is `8050` by default.\nNow go to `localhost:8050` in your web browser to access the graphical user interface:\n\n![Alt text](https://raw.githubusercontent.com/LuisScoccola/persistable/main/docs/pictures/GUI.png)\n\nAfter choosing your parameters using the user interface, you can get your clustering in another Jupyter cell by running:\n\n```python\nclustering_labels = pi.cluster()\n```\n\n**Note:** You may use `pi.start_ui(jupyter_mode=\"inline\")` to have the graphical user interface display directly in the Jupyter notebook!\n\n\n## Installing\n\nMake sure you are using Python 3.\nPersistable depends on the following python packages, which will be installed automatically when you install with `pip`:\n`numpy`, `scipy`, `scikit-learn`, `cython`, `plotly`, `dash`, `diskcache`, `multiprocess`, `psutil`.\nTo install from pypi, simply run the following:\n\n```bash\npip install persistable-clustering\n```\n\n\n## Documentation and support\n\nYou can find the documentation at [persistable.readthedocs.io](https://persistable.readthedocs.io/).\nIf you have further questions, please [open an issue](https://github.com/LuisScoccola/persistable/issues/new) and we will do our best to help you.\nPlease include as much information as possible, including your system's information, warnings, logs, screenshots, and anything else you think may be of use.\nIf you do not wish to open an issue, you are also welcome to contact [Luis Scoccola](https://luisscoccola.github.io/) directly.\nPlease be patient if it takes us a bit to get back to you.\n\n\n\n## Running the tests\n\nYou can run the tests by running the following commands from the root directory of a clone of this repository.\nIf a test fails, please [report a bug](https://github.com/LuisScoccola/persistable/issues/new), trying to include as much information as possible, including your system's information, warnings, logs, screenshots, and anything else you think may be of use.\n\n```bash\npip install pytest playwright pytest-playwright\npython -m playwright install --with-deps\npip install -r requirements.txt\npython -m setup build_ext --inplace\npytest .\n```\n\n\n## Details about theory and implementation\n\nPersistable is based on multi-parameter persistence [[4]](#4), a method from topological data analysis.\nThe theory behind Persistable is developed in [[1]](#1), while this implementation uses the high performance algorithms for density-based clustering developed in [[2]](#2) and implemented in [[3]](#3).\nPersistable's interactive mode is inspired by RIVET [[5]](#5) and is implemented in [Dash](https://dash.plotly.com/).\n\n\n## Contributing\n\nTo contribute, you can fork the project, make your changes, and submit a pull request.\nYou may want to contact [Luis Scoccola](https://luisscoccola.github.io/) first, to make sure your work does not overlap with ongoing work.\n\n\n## Authors\n\n[Luis Scoccola](https://luisscoccola.github.io/) and [Alexander Rolle](https://alexanderrolle.github.io/).\n\n## Citing\n\nIf you use this package in your work, you may cite the corresponding paper using the following bibtex entry:\n\n```\n@article{Scoccola2023,\n    doi = {10.21105/joss.05022},\n    url = {https://doi.org/10.21105/joss.05022},\n    year = {2023},\n    publisher = {The Open Journal},\n    volume = {8},\n    number = {83},\n    pages = {5022},\n    author = {Luis Scoccola and Alexander Rolle},\n    title = {Persistable: persistent and stable clustering},\n    journal = {Journal of Open Source Software}\n}\n```\n\n## References\n\n\u003ca id=\"1\"\u003e[1]\u003c/a\u003e \n*Stable and consistent density-based clustering via multiparameter persistence*. A. Rolle and L. Scoccola. Journal of Machine Learning Research, 25(258):1-74, 2024\n\n\u003ca id=\"2\"\u003e[2]\u003c/a\u003e \n*Accelerated Hierarchical Density Based Clustering*. L. McInnes, J. Healy. 2017 IEEE International Conference on Data Mining Workshops (ICDMW), IEEE, pp 33-42. 2017\n\n\u003ca id=\"3\"\u003e[3]\u003c/a\u003e \n*hdbscan: Hierarchical density based clustering*. L. McInnes, J. Healy, S. Astels. Journal of Open Source Software, The Open Journal, volume 2, number 11. 2017\n\n\u003ca id=\"4\"\u003e[4]\u003c/a\u003e \n*An Introduction to Multiparameter Persistence*. M. B. Botnan, M. Lesnick. Proceedings of the 2020 International Conference on Representations of Algebras. 2022\n\n\u003ca id=\"5\"\u003e[5]\u003c/a\u003e \n*RIVET*. The RIVET Developers. [[Git]](https://github.com/rivetTDA/rivet) [[docs]](https://rivet.readthedocs.io/en/latest/index.html)\n\n\n## License\n\nThis software is published under the 3-clause BSD license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluisscoccola%2Fpersistable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluisscoccola%2Fpersistable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluisscoccola%2Fpersistable/lists"}