`elwood_spatial.bins`

Value discretization. BinSpec maps continuous measurements into discrete bins for entropy-based analysis. Bins are inclusive on both ends: a value matches when low ≤ value ≤ high.

BinSpec

@dataclass(frozen=True)
class BinSpec:
    edges: tuple[tuple[float, float], ...]
    labels: tuple[str, ...] | None = None

Field	Type	Description
`edges`	`tuple[tuple[float, float], ...]`	Sequence of (low, high) bin boundaries
`labels`	`tuple[str, ...] \| None`	Optional human-readable label per bin

Properties

Property	Returns	Description
`num_bins`	`int`	Number of bins

Class Methods

`BinSpec.from_tuples(bins)`

Parameter	Type	Description
`bins`	`Sequence[tuple[float, float]]`	List of (low, high) pairs

bins = BinSpec.from_tuples([(0, 50), (51, 100), (101, 150)])

`BinSpec.from_dicts(bins, range_key="range", label_key="cat")`

Parameter	Type	Default	Description
`bins`	`Sequence[dict]`		List of dicts with range and label keys
`range_key`	`str`	`"range"`	Key for the [low, high] range
`label_key`	`str`	`"cat"`	Key for the category label

bins = BinSpec.from_dicts([
    {"cat": "Good", "range": [0, 50]},
    {"cat": "Moderate", "range": [51, 100]},
])

Instance Methods

`bin_index(value) → int`

Returns the bin index for a scalar value, or -1 if out of range, NaN, or None.

`bin_values(values) → np.ndarray`

Vectorized — returns an array of bin indices for a NumPy array of values.

Convenience Functions

`compute_bin_index(value, bins)`

Parameter	Type	Description
`value`	`float`	Scalar value
`bins`	`BinSpec`	Bin specification

Returns int — bin index or -1.

`compute_bin_indices(values, bins)`

Parameter	Type	Description
`values`	`np.ndarray`	Array of values
`bins`	`BinSpec`	Bin specification

Returns np.ndarray of integers.