core.utils.array_utils

Array utils module

class gridr.core.utils.array_utils.ArrayProfile(shape, ndim, dtype)[source]

A class to define array attributes for mocking or descriptive purposes.

This class is designed to hold essential attributes of a NumPy array, such as its shape, number of dimensions, data type, and total size, allowing access to these members similar to a numpy.ndarray object without instantiating a full array.

classmethod from_dataset(ds)[source]

Creates an ArrayProfile object from a rasterio.io.DatasetReader.

This class method extracts relevant array attributes (shape, number of dimensions, and data type) from an opened Rasterio dataset. It adjusts the ndim and shape for single-band datasets to represent them as 2D arrays, consistent with typical image processing.

Parameters:

ds (rasterio.io.DatasetReader) – A Rasterio dataset reader object, typically obtained via ` rasterio.open()`.

Returns:

An instantiated ArrayProfile object populated with attributes derived from the provided Rasterio dataset.

Return type:

ArrayProfile

gridr.core.utils.array_utils.array_add(array, val_cond, val_add, add_on_true, array_cond=None, array_cond_val=None, win=None)[source]

Add a scalar to elements within an array in-place based on specified conditions.

This method is a Python wrapper around the Rust function py_array1_add_*, designed for efficient in-place modification of NumPy arrays. It allows conditional replacement based on either the array itself or an optional array_cond (condition array).

Parameters:

  • array (numpy.ndarray) – The array into which elements are replaced in-place. Must be C-contiguous and have a dtype of int8, uint8, float32, or float64.

  • val_cond (int or float) – The primary condition value. Elements in array (or array_cond if provided) equal to val_cond will be affected.

  • val_add (int or float) – The value to add to elements with respect to the condition and the behaviour defined by add_on_true.

  • add_on_true (bool) – The condition’s behaviour : determines whether to add on elements that satisfy the condition (true) or do not satisfy the condition (false).

  • array_cond (numpy.ndarray, optional) – An optional 1D or 2D array on which to apply the condition. If provided, the operation in array is based on the values in array_cond. Must have a dtype of int8 or uint8. Defaults to None, in which case the array itself is used for the condition.

  • array_cond_val (int or float, optional) – The condition value to use if array_cond is defined. This value is compared against elements in array_cond. This parameter is required if array_cond is provided. Defaults to None.

  • win (numpy.ndarray, optional) – A window win to restrict the operation to a specific region of the array. This is a 2D NumPy array where each row represents a dimension and contains (min_idx, max_idx). Both `min_idx` and `max_idx` are inclusive, adhering to the GridR’s “window” convention. The window’s dimensions must match those of the array. Defaults to None, meaning the operation applies to the entire array.

Returns:

This function modifies the array in-place and does not return any value.

Return type:

NoReturn

Raises:

  • AssertionError – If array’s dtype is not one of int8, uint8, float32, or float64.

  • AssertionError – If array is not C-contiguous (array.flags.c_contiguous is False).

  • AssertionError – If array_cond is provided and its dtype is not int8 or uint8.

  • AssertionError – If array_cond is provided but array_cond_val is None.

  • AssertionError – If array_cond_val is provided but array_cond is None.

gridr.core.utils.array_utils.array_convert(array_in, array_out, clip='auto', safe=True, rounding_method='round')[source]

Convert an input array to a target dtype with optional clipping and rounding.

The function performs type conversion from the input array to the output array, with optional clipping and rounding operations based on the specified parameters.

Parameters:

  • array_in (numpy.ndarray) – The input array containing the data to convert. The dtype of this array determines the source data type.

  • array_out (numpy.ndarray) – The output array that will contain the converted data. The dtype of this array determines the target data type.

  • clip (Union[Literal['auto'], Tuple[Any, Any]]]) –

    Controls value clipping behavior:

    • ’auto’: Automatic clipping based on the target dtype’s range

    • Tuple: Specific numeric range for clipping (e.g., (min_value, max_value)).

      The tuple values should correspond to the target dtype’s range

  • safe (bool) – If True, check are performed to garanty that the automatic clipping can be performed without overflow caused by floating point precision loss.

  • rounding_method (Optional[Literal['round', 'ceil', 'floor']], optional) –

    Specifies the rounding method to use when converting from float to integer:

    • ’round’: Standard rounding (default)

    • ’ceil’: Round up to nearest integer

    • ’floor’: Round down to nearest integer

    • None: No rounding is performed

Returns:

The function modifies both the input array and the output array inplace and returns nothing.

Return type:

None

Notes

  • The function checks if clipping is required based on the input and output dtypes and the specified clipping range.

  • When ‘auto’ clipping is specified, the function automatically clips to the range of the output dtype.

  • The function currently raises an Exception if clipping from input type to output type is not safe.

  • The function raises ValueError if the specified clipping range is invalid for the output dtype.

  • No safety check is performed when the clipping range is not automatic

gridr.core.utils.array_utils.array_replace(array, val_cond, val_true, val_false, array_cond=None, array_cond_val=None, win=None)[source]

Replaces elements within an array in-place based on specified conditions.

This method is a Python wrapper around the Rust function py_array1_replace_*, designed for efficient in-place modification of NumPy arrays. It allows conditional replacement based on either the array itself or an optional array_cond (condition array).

Parameters:

  • array (numpy.ndarray) – The array into which elements are replaced in-place. Must be C-contiguous and have a dtype of int8, uint8, float32, or float64.

  • val_cond (int or float) – The primary condition value. Elements in array (or array_cond if provided) equal to val_cond will be affected.

  • val_true (int or float) – The value to replace elements that satisfy the condition (i.e., input value equals val_cond).

  • val_false (int or float) – The value to replace elements that do not satisfy the condition (i.e., input value does not equal val_cond).

  • array_cond (numpy.ndarray, optional) – An optional 1D or 2D array on which to apply the condition. If provided, the replacement in array is based on the values in array_cond. Must have a dtype of int8 or uint8. Defaults to None, in which case the array itself is used for the condition.

  • array_cond_val (int or float, optional) – The condition value to use if array_cond is defined. This value is compared against elements in array_cond. This parameter is required if array_cond is provided. Defaults to None.

  • win (numpy.ndarray, optional) – A window win to restrict the operation to a specific region of the array. This is a 2D NumPy array where each row represents a dimension and contains (min_idx, max_idx). Both `min_idx` and `max_idx` are inclusive, adhering to the GridR’s “window” convention. The window’s dimensions must match those of the array. Defaults to None, meaning the operation applies to the entire array.

Returns:

This function modifies the array in-place and does not return any value.

Return type:

NoReturn

Raises:

  • AssertionError – If array’s dtype is not one of int8, uint8, float32, or float64.

  • AssertionError – If array is not C-contiguous (array.flags.c_contiguous is False).

  • AssertionError – If array_cond is provided and its dtype is not int8 or uint8.

  • AssertionError – If array_cond is provided but array_cond_val is None.

  • AssertionError – If array_cond_val is provided but array_cond is None.

gridr.core.utils.array_utils.is_clip_required(in_dtype, out_dtype)[source]

Determines if clipping is required when converting between data types.

Parameters:

  • in_dtype (dtype) – The source data type

  • out_dtype (dtype) – The destination data type

Returns:

True if clipping is required, False otherwise

Return type:

bool

Raises:

ValueError – If the conversion between types is not managed

gridr.core.utils.array_utils.is_clip_to_dtype_limits_safe(in_dtype, out_dtype)[source]

Determines whether clipping from an input type to the type limits of a target data type is safe.

This function checks if converting from a data type to a target data type and clipping it to the target type’s limits will preserve all values without overflow.

Parameters:

  • in_dtype (np.dtype) – The input type to be checked for safe clipping.

  • out_dtype (np.dtype) – The target data type to which the array would be converted.

Returns:

True if clipping to the target type limits is safe (no overflow will occur and the target limit can be expressed in the input data type with precision), False otherwise.

Return type:

bool

Notes

This function is necessary when performing type conversions between different numerical data types, especially when converting between floating-point and integer types or between different floating-point precisions. The main concern is to prevent overflow when clipping values to the target type’s limits.

The function performs the following checks:

  1. Only floating-point input types are considered for this check (integer inputs are assumed to be safe by default).

  2. Checks if clipping is actually required between the input and output types.

  3. Attempts to convert the maximum value of the output type to the input type and convert it back to the output type.

  4. If this conversion results in an OverflowError or if the converted value doesn’t match the expected maximum value of the output type, returns False.

The function is particularly important when processing numerical data where preserving the integrity of values is critical, such as in scientific computing, financial applications, or any domain where numerical precision matters.

The test is only performed on the max as the min of an integer type is a power of 2 and can safely expressed when clipping is required.