hopkins_statistic ¶

Compute the Hopkins statistic to assess clustering tendency.

Functions:

Name	Description
`hopkins`	Compute the Hopkins statistic.
`hopkins_test`	Perform a Hopkins test.

hopkins ¶

hopkins(
    X,
    *,
    m=0.1,
    frame="bbox",
    toroidal=False,
    power=None,
    rng=None
)

Compute the Hopkins statistic.

The Hopkins statistic measures clustering tendency by comparing nearest-neighbor distances of sampled data points with those of points placed uniformly at random in the sampling frame.

Parameters:

Name	Type	Description	Default
`X`	`ArrayLike`	Array-like of shape `(n, d)`, with `n >= 3` observations in `d >= 1` dimensions. Must contain only finite real values.	required
`m`	`int \| float`	Sample size, or its fraction of the `n_in` points in the `frame`. If `int`, this must satisfy `1 <= m <= n_in`. If `float`, this must satisfy `0 < m <= 1`, and the sample size is `ceil(m * n_in)`.	`0.1`
`frame`	`Frame`	Area sampling frame. Must be one of: Literal `'bbox'` to use the axis-aligned bounding box of `X`, or Literal `'hull'` to use the convex hull of `X`, or Pair `(lower, upper)` defining the bounds of a rectangular sampling frame. Both must be broadcastable to shape `(d,)`. While data points outside a given frame are ignored during sampling, they can still be nearest neighbors.	`'bbox'`
`toroidal`	`bool`	If True, compute distances with periodic boundary conditions.	`False`
`power`	`int \| float \| None`	Exponent applied to Euclidean distances. Defaults to `d`. Must be positive and finite.	`None`
`rng`	`ToRNG`	Random number generator or seed to be passed to `numpy.random.default_rng`. Specify for reproducibility.	`None`

Returns:

Type	Description
`float`	The Hopkins statistic, a value between 0 and 1 (NaN if undefined).

hopkins_test ¶

hopkins_test(
    X,
    *,
    m=0.1,
    frame="bbox",
    toroidal=False,
    alternative="clustered",
    rng=None
)

Perform a Hopkins test.

The Hopkins test tests the null hypothesis of complete spatial randomness (CSR) by comparing the observed Hopkins statistic to its Beta(m, m) null distribution.

Parameters:

Name	Type	Description	Default
`X`	`ArrayLike`	Array-like of shape `(n, d)`, with `n >= 3` observations in `d >= 1` dimensions. Must contain only finite real values.	required
`m`	`int \| float`	Sample size, or its fraction of the `n_in` points in the `frame`. If `int`, this must satisfy `1 <= m <= n_in`. If `float`, this must satisfy `0 < m <= 1`, and the sample size is `ceil(m * n_in)`.	`0.1`
`frame`	`Frame`	Area sampling frame. Must be one of: Literal `'bbox'` to use the axis-aligned bounding box of `X`, or Literal `'hull'` to use the convex hull of `X`, or Pair `(lower, upper)` defining the bounds of a rectangular sampling frame. Both must be broadcastable to shape `(d,)`. While data points outside a given frame are ignored during sampling, they can still be nearest neighbors.	`'bbox'`
`toroidal`	`bool`	If `True`, compute distances with periodic boundary conditions.	`False`
`alternative`	`Alternative`	Alternative hypothesis of departure from CSR toward more `'clustered'` or `'regular'` data, or in either direction: `'two-sided'`.	`'clustered'`
`rng`	`ToRNG`	Random number generator or seed to be passed to `numpy.random.default_rng`. Specify for reproducibility.	`None`

Returns:

Type	Description
`HopkinsTestResult`	The result of the Hopkins test (statistic and p-value).

HopkinsTestResult ¶

Bases: NamedTuple

Result of a Hopkins test.

Attributes:

Name	Type	Description
`statistic`	`float`	The Hopkins statistic.
`pvalue`	`float`	The p-value associated with the given alternative.

Alternative `module-attribute` ¶

Alternative = Literal['clustered', 'regular', 'two-sided']

Alternative hypothesis for [hopkins_test][].

Frame `module-attribute` ¶

Frame = (
    Literal["bbox", "hull"]
    | tuple[ArrayLike, ArrayLike]
    | ArrayLike
)

Sampling frame for [hopkins][] and [hopkins_test][].

ToRNG `module-attribute` ¶

ToRNG = (
    Generator
    | BitGenerator
    | int
    | integer[Any]
    | Sequence[int]
    | SeedSequence
    | ndarray[Any, dtype[integer[Any]]]
    | None
)

Random number generator or seed to be passed to numpy.random.default_rng.