Merge pull request #172 from alimanfoo/advanced-indexing-20171028

Advanced indexing

Author: alimanfoo

docs/api/codecs.rst

@@ -2,27 +2,22 @@ Compressors and filters (``zarr.codecs``)
 =========================================
 .. module:: zarr.codecs
 
-This module contains compressor and filter classes for use with Zarr.
+This module contains compressor and filter classes for use with Zarr. Please note that this module
+is provided for backwards compatibility with previous versions of Zarr. From Zarr version 2.2
+onwards, all codec classes have been moved to a separate package called Numcodecs_. The two
+packages (Zarr and Numcodecs_) are designed to be used together. For example, a Numcodecs_ codec
+class can be used as a compressor for a Zarr array::
 
-Other codecs can be registered dynamically with Zarr. All that is required
-is to implement a class that provides the same interface as the classes listed
-below, and then to add the class to the ``codec_registry``. See the source
-code of this module for details.
+    >>> import zarr
+    >>> from numcodecs import Blosc
+    >>> z = zarr.zeros(1000000, compressor=Blosc(cname='zstd', clevel=1, shuffle=Blosc.SHUFFLE)
 
-.. autoclass:: Codec
+Codec classes can also be used as filters. See the tutorial section on :ref:`tutorial_filters`
+for more information.
 
-    .. automethod:: encode
-    .. automethod:: decode
-    .. automethod:: get_config
-    .. automethod:: from_config
+Please note that it is also relatively straightforward to define and register custom codec
+classes. See the Numcodecs `codec API <http://numcodecs.readthedocs.io/en/latest/abc.html>`_ and
+`codec registry <http://numcodecs.readthedocs.io/en/latest/registry.html>`_ documentation for more
+information.
 
-.. autoclass:: Blosc
-.. autoclass:: Zlib
-.. autoclass:: BZ2
-.. autoclass:: LZMA
-.. autoclass:: Delta
-.. autoclass:: AsType
-.. autoclass:: FixedScaleOffset
-.. autoclass:: Quantize
-.. autoclass:: PackBits
-.. autoclass:: Categorize
+.. _Numcodecs: http://numcodecs.readthedocs.io/

docs/api/core.rst

@@ -6,6 +6,14 @@ The Array class (``zarr.core``)
 
     .. automethod:: __getitem__
     .. automethod:: __setitem__
+    .. automethod:: get_basic_selection
+    .. automethod:: set_basic_selection
+    .. automethod:: get_mask_selection
+    .. automethod:: set_mask_selection
+    .. automethod:: get_coordinate_selection
+    .. automethod:: set_coordinate_selection
+    .. automethod:: get_orthogonal_selection
+    .. automethod:: set_orthogonal_selection
     .. automethod:: resize
     .. automethod:: append
     .. automethod:: view

docs/index.rst

@@ -12,27 +12,25 @@ Highlights
 
 * Create N-dimensional arrays with any NumPy dtype.
 * Chunk arrays along any dimension.
-* Compress chunks using the fast Blosc_ meta-compressor or alternatively using zlib, BZ2 or LZMA.
+* Compress and/or filter chunks using any numcodecs_ codec.
 * Store arrays in memory, on disk, inside a Zip file, on S3, ...
 * Read an array concurrently from multiple threads or processes.
 * Write to an array concurrently from multiple threads or processes.
 * Organize arrays into hierarchies via groups.
-* Use filters to preprocess data and improve compression.
 
 Status
 ------
 
-Zarr is still in an early phase of development. Feedback and bug
-reports are very welcome, please get in touch via the `GitHub issue
-tracker <https://github.com/alimanfoo/zarr/issues>`_.
+Zarr is still a young project. Feedback and bug reports are very welcome, please get in touch via
+the `GitHub issue tracker <https://github.com/alimanfoo/zarr/issues>`_.
 
 Installation
 ------------
 
 Zarr depends on NumPy. It is generally best to `install NumPy
-<http://docs.scipy.org/doc/numpy/user/install.html>`_ first using
-whatever method is most appropriate for you operating system and
-Python distribution.
+<http://docs.scipy.org/doc/numpy/user/install.html>`_ first using whatever method is most
+appropriate for you operating system and Python distribution. Other dependencies should be
+installed automatically if using one of the installation methods below.
 
 Install Zarr from PyPI::
 
@@ -41,26 +39,18 @@ Install Zarr from PyPI::
 Alternatively, install Zarr via conda::
 
     $ conda install -c conda-forge zarr
-  
-Zarr includes a C extension providing integration with the Blosc_
-library. Installing via conda will install a pre-compiled binary distribution. 
-However, if you have a newer CPU that supports the AVX2 instruction set (e.g., 
-Intel Haswell, Broadwell or Skylake) then installing via pip is preferable, 
-because this will compile the Blosc library from source with optimisations 
-for AVX2.
-  
+
 To work with Zarr source code in development, install from GitHub::
 
     $ git clone --recursive https://github.com/alimanfoo/zarr.git
     $ cd zarr
     $ python setup.py install
 
-To verify that Zarr has been fully installed (including the Blosc
-extension) run the test suite::
+To verify that Zarr has been fully installed, run the test suite::
 
     $ pip install nose
     $ python -m nose -v zarr
-  
+
 Contents
 --------
 
@@ -75,13 +65,20 @@ Contents
 Acknowledgments
 ---------------
 
-Zarr bundles the `c-blosc <https://github.com/Blosc/c-blosc>`_
-library and uses it as the default compressor.
+The following people have contributed to the development of Zarr, by contributing code and/or
+providing ideas, feedback and advice:
+
+* `Francesc Alted <https://github.com/FrancescAlted>`_
+* `Stephan Hoyer <https://github.com/shoyer>`_
+* `John Kirkham <https://github.com/jakirkham>`_
+* `Alistair Miles <https://github.com/alimanfoo>`_
+* `Matthew Rocklin <https://github.com/mrocklin>`_
+* `Vincent Schut <https://github.com/vincentschut>`_
 
 Zarr is inspired by `HDF5 <https://www.hdfgroup.org/HDF5/>`_, `h5py
 <http://www.h5py.org/>`_ and `bcolz <http://bcolz.blosc.org/>`_.
 
-Development of this package is supported by the
+Development of Zarr is supported by the
 `MRC Centre for Genomics and Global Health <http://www.cggh.org>`_.
 
 Indices and tables
@@ -91,4 +88,4 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
-.. _Blosc: http://www.blosc.org/
+.. _numcodecs: http://numcodecs.readthedocs.io/