binny.correlations.metrics module#

Pairwise metrics for curve comparisons.

These helpers build (i, j) -> scalar callables from collections of curves. Even when used alongside tuple machinery, these metrics are pairwise: they compare one curve selected by i to one curve selected by j.

binny.correlations.metrics.metric_from_curves(*, curves: Sequence[Mapping[int, ndarray[tuple[Any, ...], dtype[float64]]]], kernel: Callable[[...], float]) → Callable[[...], float]#

Construct an index metric from a curve-level kernel.

The returned metric evaluates index tuples by applying the provided kernel to the corresponding curve arrays.

With two curve mappings, the callable is pairwise (i, j). With three, it is (i, j, k), and so on.

Parameters:

  • curves – Sequence of curve mappings, one per index slot.

  • kernel – Callable computing a scalar value from N curve arrays.

Returns:

Callable metric function taking N indices and returning a scalar value.

Raises:

  • KeyError – If a requested index is not present in the curve mappings.

  • TypeError – If the returned callable is called with the wrong number of indices.

binny.correlations.metrics.metric_min_overlap_fraction(*, z: ndarray[tuple[Any, ...], dtype[float64]], curves: Sequence[Mapping[int, ndarray[tuple[Any, ...], dtype[float64]]]]) → Callable[[...], float]#

Construct a normalized minimum-overlap metric for curve tuples.

The returned metric evaluates the fractional overlap between N curves as the integral of their pointwise minimum divided by the product of their individual integrals.

For N=2 this reduces to the usual pairwise overlap fraction. Supplying three curve mappings yields a triple-overlap fraction, and so on.

Parameters:

  • z – One-dimensional coordinate grid.

  • curves – Sequence of curve mappings, one per index slot.

Returns:

Callable metric function taking N indices and returning a scalar overlap fraction.

Raises:

  • ValueError – If curves is empty or if any curve does not match the shape of z.

  • KeyError – If a requested index is not present in the curve mappings.

  • TypeError – If the returned callable is called with the wrong number of indices.

binny.correlations.metrics.metric_overlap_coefficient(*, z: ndarray[tuple[Any, ...], dtype[float64]], curves: Sequence[Mapping[int, ndarray[tuple[Any, ...], dtype[float64]]]]) → Callable[[...], float]#

Construct an overlap coefficient metric for curve tuples.

The overlap coefficient is defined as the integral of the pointwise minimum of N curves divided by the smallest of their individual integrals.

For N=2 this reduces to the usual overlap coefficient. Supplying three curve mappings yields a triple-overlap coefficient, and so on.

Parameters:

  • z – One-dimensional coordinate grid.

  • curves – Sequence of curve mappings, one per index slot.

Returns:

Callable metric function taking N indices and returning a scalar overlap coefficient.

Raises:

  • ValueError – If curves is empty or if any curve does not match the shape of z.

  • KeyError – If a requested index is not present in the curve mappings.

  • TypeError – If the returned callable is called with the wrong number of indices.