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.

broadcast_to(arr, shape)	Broadcast an array to a new shape.
clip(*args, **kwargs)
contains(*args, **kwargs)
endswith(*args, **kwargs)
imag(ndarr, /)	Return the imaginary part of the complex array, element-wise.
lower(*args, **kwargs)
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.
startswith(*args, **kwargs)
upper(*args, **kwargs)
where(condition[, x, y])	Return elements chosen from x or y depending on condition.

blosc2.broadcast_to(arr: Array, shape: tuple[int, ...]) → NDArray

Broadcast an array to a new shape. Warning: Computes a lazyexpr, so probably a bit suboptimal

Parameters:

• arr (blosc2.Array) – The array to broadcast.

• shape (tuple) – The shape of the desired array.

Returns:

• broadcast (NDArray)

• A new array with the given shape.

blosc2.clip(*args, **kwargs)

blosc2.contains(*args, **kwargs)

blosc2.endswith(*args, **kwargs)

blosc2.imag(ndarr: Array, /) → LazyExpr

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.lower(*args, **kwargs)

blosc2.real(ndarr: Array, /) → LazyExpr

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: Array) → LazyExpr

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

Parameters:

x (blosc2.Array) – 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

blosc2.startswith(*args, **kwargs)

blosc2.upper(*args, **kwargs)

blosc2.where(condition: LazyExpr | NDArray, x: Array | int | float | complex | bool | str | bytes | None = None, y: Array | int | float | complex | bool | str | bytes | None = None) → LazyExpr

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(a_dtype, kind)	Returns a boolean indicating whether 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 | blosc2.Array, dtype, casting: str = 'unsafe', copy: bool = True, **kwargs: Any) → NDArray

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

Parameters:

• array (Sequence | blosc2.Array) – 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

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(a_dtype: dtype, kind: str | dtype | tuple)

Returns a boolean indicating whether a provided dtype is of a specified data type “kind”.

Parameters:

• dtype (dtype) – The input dtype.

• kind (str | dtype | Tuple[str, dtype]) –

  Data type kind.

  If kind is a dtype, return boolean indicating whether the input dtype is equal to the dtype specified by kind.

  If kind is a string, return boolean indicating whether the input dtype is of a specified data type kind. The following dtype kinds are supporte:

  • ’bool’: boolean data types (e.g., bool).

  • ’signed integer’: signed integer data types (e.g., int8, int16, int32, int64).

  • ’unsigned integer’: unsigned integer data types (e.g., uint8, uint16, uint32, uint64).

  • ’integral’: integer data types. Shorthand for (‘signed integer’, ‘unsigned integer’).

  • ’real floating’: real-valued floating-point data types (e.g., float32, float64).

  • ’complex floating’: complex floating-point data types (e.g., complex64, complex128).

  • ’numeric’: numeric data types. Shorthand for (‘integral’, ‘real floating’, ‘complex floating’).

Returns:

out – Boolean indicating whether a provided dtype is of a specified data type kind.

Return type:

bool

blosc2.result_type(*arrays_and_dtypes: blosc2.NDArray | int | float | complex | bool | str | blosc2.dtype) → blosc2.dtype

Returns the dtype that results from applying type promotion rules (see Type Promotion Rules) to the arguments.

Parameters:

arrays_and_dtypes (Sequence[NDarray | int | float | complex | bool | blosc2.dtype])) – An arbitrary number of input arrays, scalars, and/or dtypes.

Returns:

out – The dtype resulting from an operation involving the input arrays, scalars, and/or dtypes.

Return type:

blosc2.dtype