tiledbsoma.SparseNDArray.read

SparseNDArray.read(coords: Sequence[None | int | Slice[int] | Sequence[int] | ndarray[tuple[int, ...], dtype[integer]] | IntegerArray | ChunkedArray] = (), *, result_order: ResultOrder | Literal['auto', 'row-major', 'column-major'] = ResultOrder.AUTO, batch_size: BatchSize = BatchSize(count=None, bytes=None), partitions: ReadPartitions | None = None, platform_config: Dict[str, Mapping[str, Any]] | object | None = None) → SparseNDArrayRead

Reads a user-defined slice of the SparseNDArray.

Parameters:

coords – A per-dimension Sequence of scalar, slice, sequence of scalar or Arrow IntegerArray <https://arrow.apache.org/docs/python/generated/pyarrow.IntegerArray.html> values defining the region to read.

Returns:

A SparseNDArrayRead to access result iterators in various formats.

Raises:

SOMAError – If the object is not open for reading.

Lifecycle

Maturing.

Notes

Acceptable ways to index:

  • A sequence of coordinates is accepted, one per dimension.

  • Sequence length must be <= number of dimensions.

  • If the sequence contains missing coordinates (length < number of dimensions), then slice(None) – i.e. no constraint – is assumed for the remaining dimensions.

  • Per-dimension, explicitly specified coordinates can be one of: None, a value, a list/numpy.ndarray/pyarrow.Array/etc of values, a slice, etc.

  • Slices are doubly inclusive: slice(2,4) means [2,3,4] not [2,3]. Slice steps can only be +1. Slices can be slice(None), meaning select all in that dimension, and may be half-specified, e.g. slice(2,None) or slice(None,4).

  • Negative indexing is unsupported.