Additional Functions and Type Utilities¶

Functions¶

The following functions can also be used for computing with any of NDArray, C2Array, NDField and LazyExpr.

Their result is typically a LazyExpr instance, which can be evaluated (with compute or __getitem__) to get the actual values of the computation.

`clip`(x[, min, max])	Clamps each element x_i of the input array x to the range [min, max].
`conj`(ndarr, /)	Return the complex conjugate, element-wise.
`contains`(ndarr, value, /)	Check if the array contains a specified value.
`imag`(ndarr, /)	Return the imaginary part of the complex array, element-wise.
`real`(ndarr, /)	Return the real part of the complex array, element-wise.
`round`(x)	Rounds each element x_i of the input array x to the nearest integer-valued number.
`where`(condition[, x, y])	Return elements chosen from x or y depending on condition.

Clamps each element x_i of the input array x to the range [min, max].

Parameters:

x¶ (NDArray) – Input array. Should have a real-valued data type.
min¶ (int | float | NDArray | None) – Lower-bound of the range to which to clamp. If None, no lower bound must be applied. Default: None.
max¶ (int | float | NDArray | None) – Upper-bound of the range to which to clamp. If None, no upper bound must be applied. Default: None.

Returns:

out – An array containing element-wise results.

Return type:

NDArray

blosc2.conj(ndarr: NDArray | NDField | C2Array | LazyExpr, /) → LazyExpr[source]¶

Return the complex conjugate, element-wise.

Parameters:: ndarr¶ (NDArray or NDField or C2Array or LazyExpr) – The input array.
Returns:: out – A lazy expression representing the complex conjugate of the input array.
Return type:: LazyExpr

References

np.conj

Examples

>>> import numpy as np
>>> import blosc2
>>> values = np.array([1+2j, 3-4j, -5+6j, 7-8j])
>>> ndarray = blosc2.asarray(values)
>>> result_ = blosc2.conj(ndarray)
>>> result = result_[:]
>>> print("Original values:", values)
Original values: [ 1.+2.j  3.-4.j -5.+6.j  7.-8.j]
>>> print("Complex conjugates:", result)
Complex conjugates: [ 1.-2.j  3.+4.j -5.-6.j  7.+8.j]

Check if the array contains a specified value.

Parameters:

ndarr¶ (NDArray or NDField or C2Array) – The input array.
value¶ (str or bytes or NDArray or NDField or C2Array) – The value to be checked.

Returns:

out – A lazy expression that can be evaluated to check if the value is contained in the array.

Return type:

LazyExpr

Examples

>>> import numpy as np
>>> import blosc2
>>> values = np.array([b"apple", b"xxbananaxxx", b"cherry", b"date"])
>>> text_values = blosc2.asarray(values)
>>> value_to_check = b"banana"
>>> expr = blosc2.contains(text_values, value_to_check)
>>> result = expr.compute()
>>> print("Contains 'banana':", result[:])
Contains 'banana': [False  True False False]

blosc2.imag(ndarr: NDArray | NDField | C2Array | LazyExpr, /) → LazyExpr[source]¶

Return the imaginary part of the complex array, element-wise.

Parameters:: ndarr¶ (NDArray or NDField or C2Array or LazyExpr) – The input array.
Returns:: out – A lazy expression representing the imaginary part of the input array.
Return type:: LazyExpr

References

np.imag

Examples

>>> import numpy as np
>>> import blosc2
>>> complex_values = np.array([2+3j, -1+4j, 0-2j, 5+6j])
>>> ndarray = blosc2.asarray(complex_values)
>>> result_ = blosc2.imag(ndarray)
>>> result = result_[:]
>>> print("Original complex values:", complex_values)
Original complex values: [ 2.+3.j -1.+4.j  0.-2.j  5.+6.j]
>>> print("Imaginary parts:", result)
Imaginary parts: [ 3.  4. -2.  6.]

blosc2.real(ndarr: NDArray | NDField | C2Array | LazyExpr, /) → LazyExpr[source]¶

Return the real part of the complex array, element-wise.

Parameters:: ndarr¶ (NDArray or NDField or C2Array or LazyExpr) – The input array.
Returns:: out – A lazy expression representing the real part of the input array.
Return type:: LazyExpr

References

np.real

Examples

>>> import numpy as np
>>> import blosc2
>>> complex_values = np.array([1+2j, 3-4j, -5+6j, 7-8j])
>>> ndarray = blosc2.asarray(complex_values)
>>> result_ = blosc2.real(ndarray)
>>> result = result_[:]
>>> print("Original complex values:", complex_values)
Original values: [ 1.+2.j  3.-4.j -5.+6.j  7.-8.j]
>>> print("Real parts:", result)
Real parts: [ 1.  3. -5.  7.]

blosc2.round(x: NDArray | NDField | C2Array | LazyExpr) → LazyExpr[source]¶

Rounds each element x_i of the input array x to the nearest integer-valued number.

Parameters:: x¶ (NDArray | NDField | blosc2.C2Array | blosc2.LazyExpr) – First input array. May have any numeric data type.
Returns:: out – A LazyArray containing the element-wise results (-1, 0 or 1).
Return type:: LazyExpr

References

np.round

Return elements chosen from x or y depending on condition.

Parameters:

condition¶ (LazyExpr) – Where True, yield x, otherwise yield y.
x¶ (NDArray or NDField or np.ndarray or scalar or bytes) – Values from which to choose when condition is True.
y¶ (NDArray or NDField or np.ndarray or scalar or bytes) – Values from which to choose when condition is False.

References

np.where

Type Utilities¶

The following functions are useful for working with datatypes.

`astype`(array, dtype[, casting, copy])	Copy of the array, cast to a specified type.
`can_cast`(from_, to)	Determines if one data type can be cast to another data type according to (NumPy) type promotion rules.
`isdtype`(dtype, kind)	Determine if a provided dtype is of a specified data type `kind`.
`result_type`(*arrays_and_dtypes)	Returns the dtype that results from applying type promotion rules (see Type Promotion Rules) to the arguments.

blosc2.astype(array: Sequence | np.ndarray | NDArray | blosc2.C2Array, dtype, casting: str = 'unsafe', copy: bool = True, **kwargs: Any) → NDArray[source]¶

Copy of the array, cast to a specified type. Does not support copy = False.

Parameters:

array¶ (Sequence | np.ndarray | NDArray | blosc2.C2Array) – The array to be cast to a different type.
dtype¶ (DType-like) – The desired data type to cast to.
casting¶ (str = 'unsafe') – Controls what kind of data casting may occur. Defaults to ‘unsafe’ for backwards compatibility. * ‘no’ means the data types should not be cast at all. * ‘equiv’ means only byte-order changes are allowed. * ‘safe’ means only casts which can preserve values are allowed. * ‘same_kind’ means only safe casts or casts within a kind, like float64 to float32, are allowed. * ‘unsafe’ means any data conversions may be done.
copy¶ (bool = True) – Must always be True as copy is made by default. Will be changed in a future version

Returns:

out – New array with specified data type.

Return type:

NDArray

blosc2.can_cast(from_: blosc2.dtype | blosc2.NDArray, to: blosc2.dtype) → bool[source]¶

Determines if one data type can be cast to another data type according to (NumPy) type promotion rules.

Parameters:

from_¶ (dtype | NDArray) – Input data type or array from which to cast.
to¶ (dtype)
type. (Desired _sphinx_paramlinks_blosc2.can_cast.data)

Returns:

out – True if the cast can occur according to type promotion rules; otherwise, False.

Return type:

bool

blosc2.isdtype(dtype, kind)[source]¶

Determine if a provided dtype is of a specified data type kind.

This function only supports built-in NumPy’s data types. Third-party dtypes are not yet supported.

Parameters:

dtype¶ (dtype) – The input dtype.
kind¶ (dtype or str or tuple of dtypes/strs.) – dtype or dtype kind. Allowed dtype kinds are: * 'bool' : boolean kind * 'signed integer' : signed integer data types * 'unsigned integer' : unsigned integer data types * 'integral' : integer data types * 'real floating' : real-valued floating-point data types * 'complex floating' : complex floating-point data types * 'numeric' : numeric data types

Returns:

out

Return type:

bool