Skip to content

Updated tutorial docs #1217

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 7 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions docs/tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,56 @@
Tutorial
========

.. _tutorial_what_is_zarr?:

What is Zarr?
-------------

Zarr is a format used to create N-dimensional arrays with any NumPy `dtype <https://numpy.org/doc/stable/reference/arrays.dtypes.html#arrays-dtypes>`_

* Chunk arrays along any dimension
* Compress and/or filter chunks using any NumCodecs codec
* Flexible storage of arrays
* Read or write an array concurrently from multiple threads or processes

Zarr provides classes and functions for working with N-dimensional arrays that
behave like NumPy arrays but whose data is divided into chunks and each chunk is
compressed. If you are already familiar with HDF5 then Zarr arrays provide
similar functionality, but with some additional flexibility.

.. _tutorial_on_version_2:

Tutorials Focused on Zarr Version 2
===================================


.. _tutorial_prerequisites:

Prerequisites
-------------

You'll need to know a bit of Python. For a refresher, see the `Python tutorial <https://docs.python.org/tutorial/>`_.

You'll need to know a bit of linux command line. For a refresher, see the `Linux command line tutorial <https://ubuntu.com/tutorials/command-line-for-beginners#1-overview>`_

Zarr depends on NumPy. You'll need to `install NumPy <https://numpy.org/doc/stable/user/install.html>`_.

.. _tutorial_understanding_the_example_code:

Understanding the Example Code
------------------------------

If you see ``>>>``, you're looking at an input, or the code that you would enter.
Any line that doesn't start with ``>>>`` is an output, or the results of running the code entered.
When running python on the command line, this is it's representation.

.. _tutorial_what_is_an_n-dimensional_array?:

What is an N-dimensional array?
-------------------------------

An ndarray is a (usually fixed-size) multidimensional container of items of the same type and size. The number of dimensions and items in an array is defined by its shape, which is a tuple of N positive integers that specify the sizes of each dimension. `Read more about N-dimensional arrays here <https://numpy.org/doc/stable/reference/arrays.ndarray.html>`_.

.. _tutorial_create:

Creating an array
Expand Down Expand Up @@ -774,6 +819,13 @@ ends with `.n5`::

>>> root = zarr.open('data/example.n5', mode='w')

.. _tutorial_non_version_2:

Tutorials NOT Focused on zarr version 2
=======================================



Distributed/cloud storage
~~~~~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -1602,3 +1654,9 @@ automatic switching, set ``blosc.use_threads`` to ``None``.
Please note that if Zarr is being used within a multi-process program, Blosc may not
be safe to use in multi-threaded mode and may cause the program to hang. If using Blosc
in a multi-process program then it is recommended to set ``blosc.use_threads = False``.


.. _tutorial_on_interoperability:

Tutorials on Interoperability of zarr
=====================================