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.
blosc2.clip(x: Array, min: int | float | Array | None = None, max: int | float | Array | None = None, **kwargs: Any) → NDArray[source]

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

Parameters:

  • x (blosc2.Array) – Input array. Should have a real-valued data type.

  • min (int | float | blosc2.Array | None) – Lower-bound of the range to which to clamp. If None, no lower bound must be applied. Default: None.

  • max (int | float | blosc2.Array | None) – Upper-bound of the range to which to clamp. If None, no upper bound must be applied. Default: None.

  • kwargs (Any) – kwargs accepted by the empty() constructor

Returns:

out – An array containing element-wise results.

Return type:

NDArray

blosc2.conj(ndarr: Array, /) → 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]
blosc2.contains(ndarr: Array, value: str | bytes | Array, /) → LazyExpr[source]

Check if the array contains a specified value.

Parameters:
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: Array, /) → 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: Array, /) → 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: Array) → LazyExpr[source]

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.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[source]

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[source]

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

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 | blosc2.dtype) → blosc2.dtype[source]

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