.. _array_creation:

Array Creation
==============
.. **intro start**

| JZarr has several functions for creating arrays.
| Arrays can be created with or without a given storage.
| If no storage is given a store in memory is used as default.
| Arrays can be created with or without additional user defined attributes.

| The shape is the only mandatory information which must be given to create arrays.

.. _simple_small_array:

Simple small array
------------------

.. highlight:: java

.. literalinclude:: ./examples/java/ArrayCreation_rtd.java
  :caption: `example 1 from ArrayCreation_rtd.java <https://github.com/bcdev/jzarr/blob/master/docs/examples/java/ArrayCreation_rtd.java>`_
  :start-after: void example_1
  :end-before: createOutput
  :dedent: 8

.. highlight:: none

A :code:`System.out.println(array);` then creates the following output

.. literalinclude:: ./examples/output/ArrayCreation_rtd.txt
   :start-after: example_1_output_start
   :end-before: __output_end__


The output describes that an array with the following characteristics has been created

===========  ==========================================
property     value
===========  ==========================================
shape        y:10 x:8
chunks       y:10 x:8
data type    :ref:`f8 <data-types>` :code:`default`
data type    :ref:`f8 <dtype>` :code:`default`
fill value   :code:`0` :code:`default`
compressor   blosc compressor with default settings :code:`default`
store        InMemoryStore :code:`default`
byte order   BIG_ENDIAN :code:`default`
===========  ==========================================

Why are chunks dimensions the same as shape dimension?
  | If chunks is not given, a default chunks size of 512 in each dimension, will be applied.
  | If a chunk dimension is bigger than the corresponding shape dimension, the chunk dimension will be trimmed to shape dimension.
  | For detailed explanation see :ref:`Array Parameter explanation <array_params>`

.. _array_with_automatically_computed_chunk_size:

Array with automatically computed chunk size
--------------------------------------------
.. highlight:: java

.. literalinclude:: ./examples/java/ArrayCreation_rtd.java
  :caption: `example 2 from ArrayCreation_rtd.java <https://github.com/bcdev/jzarr/blob/master/docs/examples/java/ArrayCreation_rtd.java>`_
  :start-after: void example_2
  :end-before: createOutput
  :dedent: 8

.. highlight:: none

A :code:`System.out.println(array);` then creates the following output

.. literalinclude:: ./examples/output/ArrayCreation_rtd.txt
   :start-after: example_2_output_start
   :end-before: __output_end__

As you can see now, the chunk size in both dimensions is 500. This is an autogenerated chunk size.

.. _array_with_disabled_chunking:

Array with disabled chunking
----------------------------
.. highlight:: java

.. literalinclude:: ./examples/java/ArrayCreation_rtd.java
  :caption: `example 3 from ArrayCreation_rtd.java <https://github.com/bcdev/jzarr/blob/master/docs/examples/java/ArrayCreation_rtd.java>`_
  :start-after: void example_3
  :end-before: createOutput
  :dedent: 8

.. highlight:: none

A :code:`System.out.println(array);` then creates the following output

.. literalinclude:: ./examples/output/ArrayCreation_rtd.txt
   :start-after: example_3_output_start
   :end-before: __output_end__

Now you can see, the chunk size ins the same as shape size.

.. _array_with_user_defined_chunks:

Array with user defined chunks
------------------------------
.. highlight:: java

.. literalinclude:: ./examples/java/ArrayCreation_rtd.java
  :caption: `example 4 from ArrayCreation_rtd.java <https://github.com/bcdev/jzarr/blob/master/docs/examples/java/ArrayCreation_rtd.java>`_
  :start-after: void example_4
  :end-before: createOutput
  :dedent: 8

.. highlight:: none

A :code:`System.out.println(array);` then creates the following output

.. literalinclude:: ./examples/output/ArrayCreation_rtd.txt
   :start-after: example_4_output_start
   :end-before: __output_end__

Chunk size now are user defined [400, 350] .