Index

subsurfaceio.numpy_utils

Shared NumPy helpers.

from subsurfaceio.numpy_utils import find_nearest
import numpy as np

find_nearest(np.array([0.0, 1.0, 2.0]), 1.4)

Functions:

Name	Description
`find_nearest`	Find the array element closest to a given value.
`find_runs`	Find runs of consecutive, identical items in a 1D array.
`pd_like_shift`	Shift array elements, filling vacated positions like `pandas.Series.shift`.
`replace_from_mapping`	Replace array values using a key-to-value mapping.
`reverse_cumsum`	Compute a cumulative sum from the end of the array towards the start.
`rolling_mean`	Compute a centered rolling mean.
`round_half_up`	Round values half up for non-negative numbers (`floor(x + 0.5)`).

find_nearest

find_nearest(a: NDArray[number], value: float) -> Any

Find the array element closest to a given value.

Source: https://stackoverflow.com/a/2566508/10315746

Parameters:

Name	Type	Description	Default
`a`	`NDArray[number]`	Input array to search.	required
`value`	`float`	Target value to find the nearest match for.	required

Returns:

Type	Description
`Any`	The element of `a` closest to `value`.

find_runs

find_runs(
    a: NDArray[Any],
) -> tuple[
    npt.NDArray[Any],
    npt.NDArray[np.intp],
    npt.NDArray[np.intp],
]

Find runs of consecutive, identical items in a 1D array.

Source: https://gist.github.com/alimanfoo/c5977e87111abe8127453b21204c1065

Parameters:

Name	Type	Description	Default
`a`	`NDArray[Any]`	Input 1D array to scan for runs.	required

Returns:

Type	Description
`tuple[NDArray[Any], NDArray[intp], NDArray[intp]]`	A tuple `(run_values, run_starts, run_lengths)` where `run_values` holds the value of each run, `run_starts` holds the start index of each run, and `run_lengths` holds the length of each run. All three arrays are empty when `a` is empty.

Raises:

Type	Description
`ValueError`	If `a` is not 1-dimensional.

pd_like_shift

pd_like_shift(
    a: NDArray[Any], shift: int, fill_value: Any = np.nan
) -> npt.NDArray[Any]

Shift array elements, filling vacated positions like pandas.Series.shift.

Parameters:

Name	Type	Description	Default
`a`	`NDArray[Any]`	Input array to shift.	required
`shift`	`int`	Number of positions to shift. Positive values shift towards higher indices (pulling from the start); negative values shift towards lower indices (pulling from the end).	required
`fill_value`	`Any`	Value used to fill the positions vacated by the shift.	`nan`

Returns:

Type	Description
`NDArray[Any]`	The shifted array, with vacated positions set to `fill_value`.

replace_from_mapping

replace_from_mapping(
    a: NDArray[Any],
    mapping: Mapping[Any, Any],
    fill_value: Any | None = None,
) -> npt.NDArray[Any]

Replace array values using a key-to-value mapping.

Elements of a that match a key in mapping are replaced by the corresponding value. Elements with no matching key are set to fill_value.

Parameters:

Name	Type	Description	Default
`a`	`NDArray[Any]`	Input array whose values will be replaced.	required
`mapping`	`Mapping[Any, Any]`	Mapping from existing array values to their replacements.	required
`fill_value`	`Any \| None`	Value used for array elements that don't match any key in `mapping`. Defaults to `np.nan` for numeric replacement values, or `STRING_DTYPE_NA` for string replacement values.	`None`

Returns:

Type	Description
`NDArray[Any]`	A new array with the same shape as `a`, with values replaced according to `mapping`.

reverse_cumsum

reverse_cumsum(
    a: NDArray[number],
) -> npt.NDArray[np.number]

Compute a cumulative sum from the end of the array towards the start.

Parameters:

Name	Type	Description	Default
`a`	`NDArray[number]`	Input array to reverse-accumulate along its last axis.	required

Returns:

Type	Description
`NDArray[number]`	Array of the same shape as `a`, where each element is the sum of itself and all elements after it along the last axis.

rolling_mean

rolling_mean(
    a: NDArray[number], window_size: int
) -> npt.NDArray[np.floating]

Compute a centered rolling mean.

Parameters:

Name	Type	Description	Default
`a`	`NDArray[number]`	Input array of values to average.	required
`window_size`	`int`	Number of consecutive elements averaged per window.	required

Returns:

Type	Description
`NDArray[floating]`	Array of the same length as `a` containing the rolling mean, with edge effects from the `'same'` convolution mode.

round_half_up

round_half_up(a: Any, decimals: int = 0) -> Any

Round values half up for non-negative numbers (floor(x + 0.5)).

Matches the intended AASHTO group-index convention (0.5 rounds up). Preserves nan. Unlike Python's round, 50.5 becomes 51.

Note

ceil(x - 0.5) is incorrect for exact .5 floats because 50.5 - 0.5 is exactly 50.0.

Parameters:

Name	Type	Description	Default
`a`	`Any`	Scalar or array-like numeric values.	required
`decimals`	`int`	Number of decimal places to round to (default 0 = whole number).	`0`

Returns:

Type	Description
`Any`	Rounded scalar when `a` is a scalar; otherwise a float ndarray.