Support Block (Chunk) Indexing (#1428)

* add .venv to `.gitignore`

* add block indexing capabilities

* add release notes

* fix docstrings

* update tutorial

* fix missing codecov hit for read-only arrays

* add block selection to array tests

* lint

* move release notes to unreleased section

* update block indexing "as of" to 2.16

---------

Co-authored-by: Altay Sansal <altay.sansal@tgs.com>

Author: tasansal

.gitignore

@@ -8,6 +8,7 @@ __pycache__/
 # Distribution / packaging
 .Python
 env/
+.venv/
 build/
 develop-eggs/
 dist/

docs/api/core.rst

@@ -10,6 +10,8 @@ The Array class (``zarr.core``)
     .. automethod:: set_basic_selection
     .. automethod:: get_mask_selection
     .. automethod:: set_mask_selection
+    .. automethod:: get_block_selection
+    .. automethod:: set_block_selection
     .. automethod:: get_coordinate_selection
     .. automethod:: set_coordinate_selection
     .. automethod:: get_orthogonal_selection

docs/release.rst

@@ -23,6 +23,9 @@ Bug fixes
 
 * Add ``__contains__`` method to ``KVStore``. By :user:`Christoph Gohlke <cgohlke>` :issue:`1454`.
 
+    * **Block Indexing**: Implemented blockwise (chunk blocks) indexing to ``zarr.Array``.
+      By :user:`Altay Sansal <tasansal>` :issue:`1428`
+
 .. _release_2.15.0:
 
 2.15.0

docs/tutorial.rst

@@ -641,6 +641,84 @@ orthogonal indexing is also available directly on the array:
     >>> all(z.oindex[[0, 2], :] == z[[0, 2], :])
     True
 
+Block Indexing
+~~~~~~~~~~~~~~
+
+As of version 2.16.0, Zarr also support block indexing, which allows
+selections of whole chunks based on their logical indices along each dimension
+of an array. For example, this allows selecting a subset of chunk aligned rows and/or
+columns from a 2-dimensional array. E.g.::
+
+    >>> import zarr
+    >>> import numpy as np
+    >>> z = zarr.array(np.arange(100).reshape(10, 10), chunks=(3, 3))
+
+Retrieve items by specifying their block coordinates::
+
+    >>> z.get_block_selection(1)
+    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
+           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
+           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
+
+Equivalent slicing::
+
+    >>> z[3:6]
+    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
+           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
+           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
+
+
+For convenience, the block selection functionality is also available via the
+`blocks` property, e.g.::
+
+    >>> z.blocks[1]
+    array([[30, 31, 32, 33, 34, 35, 36, 37, 38, 39],
+           [40, 41, 42, 43, 44, 45, 46, 47, 48, 49],
+           [50, 51, 52, 53, 54, 55, 56, 57, 58, 59]])
+
+Block index arrays may be multidimensional to index multidimensional arrays.
+For example::
+
+    >>> z.blocks[0, 1:3]
+    array([[ 3,  4,  5,  6,  7,  8],
+           [13, 14, 15, 16, 17, 18],
+           [23, 24, 25, 26, 27, 28]])
+
+Data can also be modified. Let's start by a simple 2D array::
+
+    >>> import zarr
+    >>> import numpy as np
+    >>> z = zarr.zeros((6, 6), dtype=int, chunks=2)
+
+Set data for a selection of items::
+
+    >>> z.set_block_selection((1, 0), 1)
+    >>> z[...]
+    array([[0, 0, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0, 0],
+           [1, 1, 0, 0, 0, 0],
+           [1, 1, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0, 0],
+           [0, 0, 0, 0, 0, 0]])
+
+For convenience, this functionality is also available via the ``blocks`` property.
+E.g.::
+
+        >>> z.blocks[:, 2] = 7
+        >>> z[...]
+        array([[0, 0, 0, 0, 7, 7],
+               [0, 0, 0, 0, 7, 7],
+               [1, 1, 0, 0, 7, 7],
+               [1, 1, 0, 0, 7, 7],
+               [0, 0, 0, 0, 7, 7],
+               [0, 0, 0, 0, 7, 7]])
+
+Any combination of integer and slice can be used for block indexing::
+
+        >>> z.blocks[2, 1:3]
+        array([[0, 0, 7, 7],
+               [0, 0, 7, 7]])
+
 Indexing fields in structured arrays
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~