PyPi version Conda version DOI

Persistent Leaves Spatial Clustering for Applications with Noise

This library provides a new clustering algorithm based on HDBSCAN*. The primary advantages of PLSCAN over the hdbscan and fast_hdbscan libraries are:

  • PLSCAN automatically finds the optimal minimum cluster size.
  • PLSCAN can easily use all available cores to speed up computation.
  • PLSCAN has much faster implementations of tree condensing and cluster extraction.
  • PLSCAN does not rely on JIT compilation.

To use PLSCAN, you only need to set the min_samples parameter. This parameter controls how many neighbors are considered when measuring distances between points. Setting a higher value for min_samples makes the algorithm group points into larger, smoother clusters, and usually results in fewer, more stable clusters.

import numpy as np
import matplotlib.pyplot as plt

from fast_plscan import PLSCAN

data = np.load("docs/data/data.npy")

clusterer = PLSCAN(
  min_samples = 5, # same as in HDBSCAN
).fit(data)

plt.figure()
plt.scatter(
  *data.T, c=clusterer.labels_ % 10, s=5, alpha=0.5, 
  edgecolor="none", cmap="tab10", vmin=0, vmax=9
)
plt.axis("off")
plt.subplots_adjust(left=0, right=1, top=1, bottom=0)
plt.show()

scatterplot

The algorithm creates a hierarchy of leaf-clusters by changing the minimum cluster size. As this parameter varies, clusters appear or disappear. For each minimum cluster size, the algorithm measures how long these leaf-clusters persist. It then selects the minimum cluster size where the total persistence is highest, giving the most stable clustering. You can visualize this hierarchy using the leaf_tree_ attribute, which provides an alternative to HDBSCAN*'s condensed cluster tree.

clusterer.leaf_tree_.plot(leaf_separation=0.1)
plt.show()

leaf tree

You can also explore how the clustering changes for other important values of the minimum cluster size. The cluster_layers method automatically finds the most persistent clusterings and returns their cluster labels and membership strengths.

layers = clusterer.cluster_layers(max_peaks=4)
for i, (size, labels, probs) in enumerate(layers):
  plt.subplot(2, 2, i + 1)
  plt.scatter(
    *data.T,
    c=labels % 10,
    alpha=np.maximum(0.1, probs),
    s=1,
    linewidth=0,
    cmap="tab10",
  )
  plt.title(f"min_cluster_size={int(size)}")
  plt.axis("off")
plt.subplots_adjust(left=0, right=1, top=1, bottom=0)
plt.show()

layers

Installation instructions

Pre-build binaries are available on pypi and conda-forge, so the package can be installed with pip, conda, and similar package managers on most systems:

conda install conda-forge::fast-plscan

or

pip install fast_plscan

See our documentation for instructions on compiling the package locally.

Citing

When using this work, please cite our preprint:

@misc{bot2025plscan,
  title         = {Persistent Multiscale Density-based Clustering},
  author        = {Dani{\"{e}}l Bot and Leland McInnes and Jan Aerts},
  year          = {2025},
  eprint        = {2512.16558},
  archiveprefix = {arXiv},
  primaryclass  = {cs.LG},
  url           = {https://arxiv.org/abs/2512.16558}
}

Licensing

The fast-plscan package has a 3-Clause BSD license.

Project links

Data verified by PyPI on Aug 8, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for dmbot from gravatar.com dmbot

Credits

Author/Maintainer: Jelmer Bot

GitHub Statistics

Data verified by PyPI on Aug 8, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.10

Tags

density cluster clustering hierarchical persistent

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fast_plscan-0.2.1.tar.gz (478.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

fast_plscan-0.2.1-cp312-abi3-win_amd64.whl (487.5 kB view details)

Uploaded CPython 3.12+Windows x86-64

fast_plscan-0.2.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (335.2 kB view details)

Uploaded CPython 3.12+manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

fast_plscan-0.2.1-cp312-abi3-macosx_26_0_arm64.whl (430.4 kB view details)

Uploaded CPython 3.12+macOS 26.0+ ARM64

fast_plscan-0.2.1-cp311-cp311-win_amd64.whl (487.7 kB view details)

Uploaded CPython 3.11Windows x86-64

fast_plscan-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (338.5 kB view details)

Uploaded CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

fast_plscan-0.2.1-cp311-cp311-macosx_26_0_arm64.whl (430.7 kB view details)

Uploaded CPython 3.11macOS 26.0+ ARM64

fast_plscan-0.2.1-cp310-cp310-win_amd64.whl (488.0 kB view details)

Uploaded CPython 3.10Windows x86-64

fast_plscan-0.2.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (339.0 kB view details)

Uploaded CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

fast_plscan-0.2.1-cp310-cp310-macosx_26_0_arm64.whl (431.2 kB view details)

Uploaded CPython 3.10macOS 26.0+ ARM64

File details

Details for the file fast_plscan-0.2.1.tar.gz.

File metadata

  • Download URL: fast_plscan-0.2.1.tar.gz
  • Upload date:
  • Size: 478.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for fast_plscan-0.2.1.tar.gz
Algorithm Hash digest
SHA256 01ff39bb1cb941406d8cb3f42ef7a2c1999159775e0199f4795cbd092b193a8c
MD5 ff300cce12eb16e0fbc48de34128c18c
BLAKE2b-256 e69accce1ede676e889ed7d47fda86da8d416121499ad6d1f381d9c48ca547b7

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1.tar.gz:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp312-abi3-win_amd64.whl.

File metadata

  • Download URL: fast_plscan-0.2.1-cp312-abi3-win_amd64.whl
  • Upload date:
  • Size: 487.5 kB
  • Tags: CPython 3.12+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for fast_plscan-0.2.1-cp312-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 a18d9594856cadbb4d1820d869e64035f3feffe9b41e6588587e101378f079c9
MD5 d58b7dd97bb6947ba0adee8f4c1a9e32
BLAKE2b-256 6d96cfa27e9bd4ad7b8aa946f5c05ce9b5541965c6f1c9283c147fbcbf467319

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp312-abi3-win_amd64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for fast_plscan-0.2.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 c4878108c5cdf4ce1d2bb12f823cf66ddca64e2f0687505be6c9c7d774fda395
MD5 9c23717103cbe209a0ebd86be5c14c5e
BLAKE2b-256 103178dfec58e0a5417efd5bad23be90eef52d6f55a7d88436b55c771b39220f

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp312-abi3-macosx_26_0_arm64.whl.

File metadata

File hashes

Hashes for fast_plscan-0.2.1-cp312-abi3-macosx_26_0_arm64.whl
Algorithm Hash digest
SHA256 363bf3e2e6f7fd74deb86de4f27ba27c12b317da4871ab1c46af7bb6ad2956fe
MD5 dfcbcf6663cdfae77b2b90f7a1cec1c0
BLAKE2b-256 98b0c0de5d35a9e582615c9772bdeb27db7a846dacc7818144e41aff353f9a0d

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp312-abi3-macosx_26_0_arm64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: fast_plscan-0.2.1-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 487.7 kB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for fast_plscan-0.2.1-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 6c1079acc348ca1bdda50ce16786f2e6a729b3e9862c76f98b78a0f27a92e97f
MD5 e35fddcd8ff17dbd72b6da50b0c01a6d
BLAKE2b-256 dd22191fe752cc5af20a1de22c4845fe3eaa955b2270b2a99128631316a6e951

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp311-cp311-win_amd64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for fast_plscan-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 e664c36a0dceb88124784aeb117ecf651f1d8871b92d30c6588c64f0aef77bd0
MD5 35d82090d6cd52a98d7ea27c3731ac74
BLAKE2b-256 71ec763d978945b68eb8d29980a131e6086a731c171490cfd8a3a868f065901f

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp311-cp311-macosx_26_0_arm64.whl.

File metadata

File hashes

Hashes for fast_plscan-0.2.1-cp311-cp311-macosx_26_0_arm64.whl
Algorithm Hash digest
SHA256 4c6344afe018482f3ee58afaac8550f632438826807502087bde8c8f75f5c61e
MD5 634b53fa74330e36660c2443fa8be687
BLAKE2b-256 91c6bcd94ac01c03427e3212a83de0d8665af163a744351d1ec0105550efd50a

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp311-cp311-macosx_26_0_arm64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp310-cp310-win_amd64.whl.

File metadata

  • Download URL: fast_plscan-0.2.1-cp310-cp310-win_amd64.whl
  • Upload date:
  • Size: 488.0 kB
  • Tags: CPython 3.10, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for fast_plscan-0.2.1-cp310-cp310-win_amd64.whl
Algorithm Hash digest
SHA256 2dc6abba4f518078624663a18cf0f7f16276bc9c43bb9a1ff05225c0053bc13b
MD5 5175aeeaf419b3fc06ddafae81ea5a66
BLAKE2b-256 4d1bf285d0535112f39309fd19fce5d90475fd9e871d8ceefe235a60e1618320

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp310-cp310-win_amd64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for fast_plscan-0.2.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 ab47adf723341a7673a6d5d4aefac0adf78006f7cfb98ff0a2efe2d8b8343c77
MD5 8085ade8415f82b852b8f9ed6e492c95
BLAKE2b-256 b6508aab9faf07a9840efe4342488b61f2c2d6159e715cd95035818afa0679fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file fast_plscan-0.2.1-cp310-cp310-macosx_26_0_arm64.whl.

File metadata

File hashes

Hashes for fast_plscan-0.2.1-cp310-cp310-macosx_26_0_arm64.whl
Algorithm Hash digest
SHA256 cfe4ffb59e0cf9818d8a83d74f4794eacd1cd33afd59956f983d6e85b9d9673f
MD5 170d59ca14540c2c0b69ac161668754e
BLAKE2b-256 e1e608794cb7ad4dd09ebc44aee8140f7359db5317438c95b1d00a332073da15

See more details on using hashes here.

Provenance

The following attestation bundles were made for fast_plscan-0.2.1-cp310-cp310-macosx_26_0_arm64.whl:

Publisher: release.yml on JelmerBot/fast_plscan

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.1 This release

10 files

0.2.0

10 files

0.1.0.post2

10 files

0.1.0.post1

10 files

0.1.0

10 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page