Indexing and Manipulation Functions and Utilities¶

The following functions are useful for performing indexing and other associated operations.

`argsort`(array[, order])	Return the indices that would sort the array.
`broadcast_to`(arr, shape)	Broadcast an array to a new shape.
`concat`(arrays, /[, axis])	Concatenate a list of arrays along a specified axis.
`count_nonzero`(ndarr[, axis])	Return number of nonzero values along axes.
`expand_dims`(array[, axis])	Expand the shape of an array by adding new axes at the specified positions.
`meshgrid`(*arrays[, indexing])	Returns coordinate matrices from coordinate vectors.
`sort`(array[, order])	Return a sorted array following the specified order.
`squeeze`(x, axis)	Remove single-dimensional entries from the shape of the array.
`stack`(arrays[, axis])	Stack multiple arrays, creating a new axis.
`take`(x, indices[, axis])	Return elements selected by integer indices.
`take_along_axis`(x, indices[, axis])	Returns elements of an array along an axis.

blosc2.argsort(array: Array, order: str | list[str] | None = None, **kwargs: Any) → NDArray[source]¶

Return the indices that would sort the array.

This mirrors numpy.argsort() for 1-D arrays. Plain arrays sort by their values. Structured arrays sort by order when provided, or by their dtype field order when order=None. Expression orders such as "abs(x)" are also supported when a matching full expression index exists.

Parameters:

array¶ (blosc2.Array) – The 1-D array to be ordered.
order¶ (str, list of str, optional) – Primary and optional secondary order keys for structured arrays. When omitted, NumPy’s default record order is used for structured dtypes and the array values themselves are used for plain dtypes.
kwargs¶ (Any, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – The ordered logical positions as int64.

Return type:

NDArray

Notes

When the primary order key has a matching full field or expression index, the permutation is returned directly from that index in ascending stable order. Secondary keys refine ties after the primary indexed order. Without a matching full index, argsort() falls back to materializing the input values and delegating ordering to numpy.argsort().

The result is always a new array materialization. For persistent inputs, the returned permutation is in memory by default; pass storage kwargs such as urlpath (and typically mode="w") if the permutation should also be persisted on disk.

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

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.concat(arrays: list[NDArray], /, axis=0, **kwargs: Any) → NDArray[source]¶

Concatenate a list of arrays along a specified axis.

Parameters:

arrays¶ (list of NDArray) – A list containing two or more NDArray instances to be concatenated.
axis¶ (int, optional) – The axis along which the arrays will be concatenated. Default is 0.
kwargs¶ (dict, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – A new NDArray containing the concatenated data.

Return type:

NDArray

Examples

>>> import blosc2
>>> import numpy as np
>>> arr1 = blosc2.arange(0, 5, dtype=np.int32)
>>> arr2 = blosc2.arange(5, 10, dtype=np.int32)
>>> result = blosc2.concat([arr1, arr2])
>>> print(result[:])
[0 1 2 3 4 5 6 7 8 9]

blosc2.count_nonzero(ndarr: blosc2.Array, axis: int | Sequence[int] | None = None) → int[source]¶

Return number of nonzero values along axes.

Parameters:

ndarr¶ (NDArray or NDField or C2Array or LazyExpr) – The input array.
axis¶ (int | Sequence[int] | None) – Axes along which to count nonzero entries. If None, sum over whole array. Default: None.

Returns:

out – Number of nonzero elements.

Return type:

int

References

np.count_nonzero

blosc2.expand_dims(array: NDArray, axis=0) → NDArray[source]¶

Expand the shape of an array by adding new axes at the specified positions.

Parameters:

array¶ (NDArray) – The array to be expanded.
axis¶ (int or list of int, optional) – Position in the expanded axes where the new axis (or axes) is placed. Default is 0.

Returns:

out – A new NDArray with the expanded shape.

Return type:

NDArray

blosc2.meshgrid(*arrays: blosc2.Array, indexing: str = 'xy') → Sequence[NDArray][source]¶

Returns coordinate matrices from coordinate vectors.

Parameters:

*arrays¶ (blosc2.Array) – An arbitrary number of one-dimensional arrays representing grid coordinates. Each array should have the same numeric data type.
indexing¶ (str) – Cartesian ‘xy’ or matrix ‘ij’ indexing of output. If provided zero or one one-dimensional vector(s) the indexing keyword is ignored. Default: ‘xy’.

Returns:

out – List of N arrays, where N is the number of provided one-dimensional input arrays, with same dtype. For N one-dimensional arrays having lengths Ni = len(xi),

if matrix indexing ij, then each returned array has shape (N1, N2, N3, …, Nn).
if Cartesian indexing xy, then each returned array has shape (N2, N1, N3, …, Nn).

Return type:

(List[NDArray])

blosc2.sort(array: Array, order: str | list[str] | None = None, **kwargs: Any) → NDArray[source]¶

Return a sorted array following the specified order.

This is only valid for 1-dim structured arrays.

Parameters:

array¶ (blosc2.Array) – The (structured) array to be sorted.
order¶ (str, list of str, optional) – Specifies which fields to compare first, second, etc. A single field can be specified as a string. The primary order key may also be an indexed expression such as "abs(x)" when a matching full expression index exists. Not all fields need to be specified, only the ones by which the array is to be sorted.
kwargs¶ (Any, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – The sorted array.

Return type:

NDArray

Notes

If the primary order key has a matching full field or expression index, rows are gathered directly in ascending stable index order. Secondary keys refine ties after the primary indexed order. Field-based orders without a matching full index fall back to a scan-plus-sort path.

Sorting never mutates the input array in place. The result is always a new array materialization. For persistent inputs, the sorted rows are returned as a new in-memory NDArray by default; pass storage kwargs such as urlpath (and typically mode="w") if the sorted output should also be persisted on disk.

blosc2.squeeze(x: Array, axis: int | Sequence[int]) → NDArray[source]¶

Remove single-dimensional entries from the shape of the array.

This method modifies the array in-place.

Parameters:

x¶ (Array) – input array.
axis¶ (int | Sequence[int]) – Axis (or axes) to squeeze.

Returns:

out – An output array having the same data type and elements as x.

Return type:

Array

Examples

>>> import blosc2
>>> shape = [1, 23, 1, 11, 1]
>>> # Create an array
>>> b = blosc2.full(shape, 2**30)
>>> b.shape
(1, 23, 1, 11, 1)
>>> # Squeeze the array
>>> blosc2.squeeze(b)
>>> b.shape
(23, 11)

blosc2.stack(arrays: list[NDArray], axis=0, **kwargs: Any) → NDArray[source]¶

Stack multiple arrays, creating a new axis.

Parameters:

arrays¶ (list of NDArray) – A list containing two or more NDArray instances to be stacked.
axis¶ (int, optional) – The new axis along which the arrays will be stacked. Default is 0.
kwargs¶ (dict, optional) – Keyword arguments that are supported by the empty() constructor.

Returns:

out – A new NDArray containing the stacked data.

Return type:

NDArray

Examples

>>> import blosc2
>>> import numpy as np
>>> arr1 = blosc2.arange(0, 6, dtype=np.int32, shape=(2,3))
>>> arr2 = blosc2.arange(6, 12, dtype=np.int32, shape=(2,3))
>>> result = blosc2.stack([arr1, arr2])
>>> print(result.shape)
(2, 2, 3)

blosc2.take(x: Array, indices: Array, axis: int | None = None)[source]¶

Return elements selected by integer indices.

For array inputs, this follows the Array API take shape rules: when axis is None, x is conceptually flattened and the output shape is indices.shape; otherwise the indexed axis is replaced by indices.shape. For CTable and Column inputs, indices select logical rows/values and axis is not supported.

Parameters:

x¶ (blosc2.Array, CTable, Column, or array-like) – Input object. NDArray inputs return an NDArray; CTable inputs return a CTable; Column inputs return a Column. Other array-like inputs are converted to a Blosc2 NDArray result.
indices¶ (array-like) – Integer indices. Negative indices are normalized relative to the selected axis (or to the flattened array when axis is None). For array inputs, indices may have any shape.
axis¶ (int | None) – Axis over which to select values for array inputs. If None, the input array is flattened before selection. Must be None for CTable and Column inputs.

Returns:

out – Selected values, preserving the container type for NDArray, CTable and Column inputs.

Return type:

NDArray | CTable | Column

blosc2.take_along_axis(x: Array, indices: Array, axis: int = -1) → NDArray[source]¶

Returns elements of an array along an axis.

Parameters:

x¶ (blosc2.Array) – Input array. Should have one or more dimensions (axes).
indices¶ (array-like) – Array indices. The array must have same number of dimensions as x and have an integer data type.
axis¶ (int) – Axis over which to select values. Default: -1.

Returns:

out – Selected indices of x.

Return type:

NDArray