Metadata-Version: 2.4
Name: hopkins-statistic
Version: 0.6.0
Summary: Compute the Hopkins statistic to assess clustering tendency.
Keywords: cluster-analysis,clusterability,clustering-tendency,data-mining,data-science,data-analysis,hopkins-statistic,machine-learning,spatial-randomness,statistics
Author: Johann Philipp Gorzny
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Dist: numpy>=2.0.0
Requires-Dist: scipy>=1.13.0
Requires-Python: >=3.11
Project-URL: Documentation, https://jo-phil.github.io/hopkins-statistic/
Project-URL: Repository, https://github.com/jo-phil/hopkins-statistic
Project-URL: Issues, https://github.com/jo-phil/hopkins-statistic/issues
Project-URL: Changelog, https://github.com/jo-phil/hopkins-statistic/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# hopkins-statistic

[![CI](https://github.com/jo-phil/hopkins-statistic/actions/workflows/ci.yml/badge.svg)](https://github.com/jo-phil/hopkins-statistic/actions/workflows/ci.yml "View workflow runs")
[![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/jo-phil/dd436ee381602e21922433dfcdd0b9ec/raw/coverage.json)](https://github.com/jo-phil/hopkins-statistic/actions/workflows/ci.yml?query=branch%3Amain+event%3Apush "View coverage report")
[![PyPI - Version](https://img.shields.io/pypi/v/hopkins-statistic)](https://pypi.org/project/hopkins-statistic/ "View latest release on PyPI")
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/hopkins-statistic)](https://pypi.org/project/hopkins-statistic/ "View supported Python versions on PyPI")
[![Docs](https://github.com/jo-phil/hopkins-statistic/actions/workflows/docs.yml/badge.svg)](https://jo-phil.github.io/hopkins-statistic/ "Read the documentation")
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.18172791-blue)](https://doi.org/10.5281/zenodo.18172791 "View on Zenodo")

[//]: # (--8<-- [start:opener])

hopkins-statistic is a library for computing the Hopkins statistic to assess
clustering tendency (also known as clusterability) by testing for departure from
complete spatial randomness (CSR) in point patterns.

This implementation defaults to the [Cross and Jain (1982)] formulation, raising
distances to the power of the data dimension. In two dimensions, this matches
the original definition by [Hopkins and Skellam (1954)]. Because the resulting
statistic follows a beta distribution under the null hypothesis, *p*-values can
be computed analytically, avoiding the need for Monte Carlo simulations.

[Cross and Jain (1982)]: https://doi.org/10.1016/S1474-6670(17)63365-2 "Measurement of Clustering Tendency"
[Hopkins and Skellam (1954)]: https://doi.org/10.1093/oxfordjournals.aob.a083391 "A New Method for determining the Type of Distribution of Plant Individuals"

[//]: # (--8<-- [end:opener])

## Installation

```bash
pip install hopkins-statistic
```

## Usage

```python
import numpy as np
from hopkins_statistic import hopkins

rng = np.random.default_rng(42)
X = rng.uniform(size=(100, 2))

statistic = hopkins(X, rng=rng)
print(f"{statistic:.3f}")
#> 0.514
```

## License

This project is licensed under the terms of the MIT license.
