zarr.create_array

zarr.create_array

create_array(
    store: StoreLike,
    *,
    name: str | None = None,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: ndarray[Any, dtype[Any]] | None = None,
    chunks: ChunksLike | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = 3,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> AnyArray

Create an array.

This function wraps zarr.core.array.create_array.

Parameters:

• store (StoreLike) –

  StoreLike object to open. See the storage documentation in the user guide for a description of all valid StoreLike values.

• name (str or None, default: None ) –

  The name of the array within the store. If name is None, the array will be located at the root of the store.

• shape (ShapeLike, default: None ) –

  Shape of the array. Must be None if data is provided.

• dtype (ZDTypeLike | None, default: None ) –

  Data type of the array. Must be None if data is provided.

• data (ndarray, default: None ) –

  Array-like data to use for initializing the array. If this parameter is provided, the shape and dtype parameters must be None.

• chunks (tuple[int, ...] | Sequence[Sequence[int]] | Literal['auto'], default: "auto" ) –

  Chunk shape of the array. If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype. A nested list of per-dimension edge sizes creates a rectilinear grid. Rectilinear chunk grids are experimental and must be explicitly enabled with zarr.config.set({'array.rectilinear_chunks': True}) while the feature is stabilizing.

• shards (tuple[int, ...], default: None ) –

  Shard shape of the array. The default value of None results in no sharding at all.

• filters (Iterable[Codec] | Literal['auto'], default: 'auto' ) –

  Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes.

  For Zarr format 3, a "filter" is a codec that takes an array and returns an array,

  and these values must be instances of zarr.abc.codec.ArrayArrayCodec, or a dict representations of zarr.abc.codec.ArrayArrayCodec.

  For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter.

  The default value of "auto" instructs Zarr to use a default based on the data type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like zarr.dtype.VariableLengthUTF8 or zarr.dtype.VariableLengthUTF8. In these cases, the default filters contains a single element which is a codec specific to that particular data type.

  To create an array with no filters, provide an empty iterable or the value None.

• compressors (Iterable[Codec], default: 'auto' ) –

  List of compressors to apply to the array. Compressors are applied in order, and after any filters are applied (if any are specified) and the data is serialized into bytes.

  For Zarr format 3, a "compressor" is a codec that takes a bytestream, and returns another bytestream. Multiple compressors may be provided for Zarr format 3. If no compressors are provided, a default set of compressors will be used. These defaults can be changed by modifying the value of array.v3_default_compressors in zarr.config. Use None to omit default compressors.

  For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2. If no compressor is provided, a default compressor will be used. in zarr.config. Use None to omit the default compressor.

• serializer (dict[str, JSON] | ArrayBytesCodec, default: 'auto' ) –

  Array-to-bytes codec to use for encoding the array data. Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion. If no serializer is provided, a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.config.

• fill_value (Any, default: DEFAULT_FILL_VALUE ) –

  Fill value for the array.

• order (('C', 'F'), default: "C" ) –

  The memory order of the array (default is "C"). For Zarr format 2, this parameter sets the memory order of the array. For Zarr format 3, this parameter is deprecated, because memory order is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory order for Zarr format 3 arrays is via the config parameter, e.g. {'config': 'C'}. If no order is provided, a default order will be used. This default can be changed by modifying the value of array.order in zarr.config.

• zarr_format ((2, 3), default: 2 ) –

  The zarr format to use when saving.

• attributes (dict, default: None ) –

  Attributes for the array.

• chunk_key_encoding (ChunkKeyEncodingLike, default: None ) –

  A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is {"name": "default", "separator": "/"}}. For Zarr format 2, the default is {"name": "v2", "separator": "."}}.

• dimension_names (Iterable[str], default: None ) –

  The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter.

• storage_options (dict, default: None ) –

  If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise.

• overwrite (bool, default: False ) –

  Whether to overwrite an array with the same name in the store, if one exists. If True, all existing paths in the store will be deleted.

• config (ArrayConfigLike, default: None ) –

  Runtime configuration for the array.

• write_data (bool, default: True ) –

  If a pre-existing array-like object was provided to this function via the data parameter then write_data determines whether the values in that array-like object should be written to the Zarr array created by this function. If write_data is False, then the array will be left empty.

Returns:

• Array –

  The array.

Examples:

import zarr
store = zarr.storage.MemoryStore()
arr = zarr.create_array(
    store=store,
    shape=(100,100),
    chunks=(10,10),
    dtype='i4',
    fill_value=0)
# <Array memory://... shape=(100, 100) dtype=int32>

Source code in zarr/api/synchronous.py

def create_array(
    store: StoreLike,
    *,
    name: str | None = None,
    shape: ShapeLike | None = None,
    dtype: ZDTypeLike | None = None,
    data: np.ndarray[Any, np.dtype[Any]] | None = None,
    chunks: ChunksLike | Literal["auto"] = "auto",
    shards: ShardsLike | None = None,
    filters: FiltersLike = "auto",
    compressors: CompressorsLike = "auto",
    serializer: SerializerLike = "auto",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = 3,
    attributes: dict[str, JSON] | None = None,
    chunk_key_encoding: ChunkKeyEncodingLike | None = None,
    dimension_names: DimensionNamesLike = None,
    storage_options: dict[str, Any] | None = None,
    overwrite: bool = False,
    config: ArrayConfigLike | None = None,
    write_data: bool = True,
) -> AnyArray:
    """Create an array.

    This function wraps [zarr.core.array.create_array][].

    Parameters
    ----------
    store : StoreLike
        StoreLike object to open. See the
        [storage documentation in the user guide][user-guide-store-like]
        for a description of all valid StoreLike values.
    name : str or None, optional
        The name of the array within the store. If ``name`` is ``None``, the array will be located
        at the root of the store.
    shape : ShapeLike, optional
        Shape of the array. Must be ``None`` if ``data`` is provided.
    dtype : ZDTypeLike | None
        Data type of the array. Must be ``None`` if ``data`` is provided.
    data : np.ndarray, optional
        Array-like data to use for initializing the array. If this parameter is provided, the
        ``shape`` and ``dtype`` parameters must be ``None``.
    chunks : tuple[int, ...] | Sequence[Sequence[int]] | Literal["auto"], default="auto"
        Chunk shape of the array.
        If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype.
        A nested list of per-dimension edge sizes creates a rectilinear grid.
        Rectilinear chunk grids are experimental and must be explicitly enabled
        with ``zarr.config.set({'array.rectilinear_chunks': True})`` while the
        feature is stabilizing.
    shards : tuple[int, ...], optional
        Shard shape of the array. The default value of ``None`` results in no sharding at all.
    filters : Iterable[Codec] | Literal["auto"], optional
        Iterable of filters to apply to each chunk of the array, in order, before serializing that
        chunk to bytes.

        For Zarr format 3, a "filter" is a codec that takes an array and returns an array,

        and these values must be instances of [`zarr.abc.codec.ArrayArrayCodec`][], or a
        dict representations of [`zarr.abc.codec.ArrayArrayCodec`][].

        For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
        order of your filters is consistent with the behavior of each filter.

        The default value of ``"auto"`` instructs Zarr to use a default based on the data
        type of the array and the Zarr format specified. For all data types in Zarr V3, and most
        data types in Zarr V2, the default filters are empty. The only cases where default filters
        are not empty is when the Zarr format is 2, and the data type is a variable-length data type like
        [`zarr.dtype.VariableLengthUTF8`][] or [`zarr.dtype.VariableLengthUTF8`][]. In these cases,
        the default filters contains a single element which is a codec specific to that particular data type.

        To create an array with no filters, provide an empty iterable or the value ``None``.
    compressors : Iterable[Codec], optional
        List of compressors to apply to the array. Compressors are applied in order, and after any
        filters are applied (if any are specified) and the data is serialized into bytes.

        For Zarr format 3, a "compressor" is a codec that takes a bytestream, and
        returns another bytestream. Multiple compressors may be provided for Zarr format 3.
        If no ``compressors`` are provided, a default set of compressors will be used.
        These defaults can be changed by modifying the value of ``array.v3_default_compressors``
        in [`zarr.config`][zarr.config].
        Use ``None`` to omit default compressors.

        For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
        be provided for Zarr format 2.
        If no ``compressor`` is provided, a default compressor will be used.
        in [`zarr.config`][zarr.config].
        Use ``None`` to omit the default compressor.
    serializer : dict[str, JSON] | ArrayBytesCodec, optional
        Array-to-bytes codec to use for encoding the array data.
        Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion.
        If no ``serializer`` is provided, a default serializer will be used.
        These defaults can be changed by modifying the value of ``array.v3_default_serializer``
        in [`zarr.config`][zarr.config].
    fill_value : Any, optional
        Fill value for the array.
    order : {"C", "F"}, optional
        The memory order of the array (default is "C").
        For Zarr format 2, this parameter sets the memory order of the array.
        For Zarr format 3, this parameter is deprecated, because memory order
        is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory
        order for Zarr format 3 arrays is via the ``config`` parameter, e.g. ``{'config': 'C'}``.
        If no ``order`` is provided, a default order will be used.
        This default can be changed by modifying the value of ``array.order`` in [`zarr.config`][zarr.config].
    zarr_format : {2, 3}, optional
        The zarr format to use when saving.
    attributes : dict, optional
        Attributes for the array.
    chunk_key_encoding : ChunkKeyEncodingLike, optional
        A specification of how the chunk keys are represented in storage.
        For Zarr format 3, the default is ``{"name": "default", "separator": "/"}}``.
        For Zarr format 2, the default is ``{"name": "v2", "separator": "."}}``.
    dimension_names : Iterable[str], optional
        The names of the dimensions (default is None).
        Zarr format 3 only. Zarr format 2 arrays should not use this parameter.
    storage_options : dict, optional
        If using an fsspec URL to create the store, these will be passed to the backend implementation.
        Ignored otherwise.
    overwrite : bool, default False
        Whether to overwrite an array with the same name in the store, if one exists.
        If ``True``, all existing paths in the store will be deleted.
    config : ArrayConfigLike, optional
        Runtime configuration for the array.
    write_data : bool
        If a pre-existing array-like object was provided to this function via the ``data`` parameter
        then ``write_data`` determines whether the values in that array-like object should be
        written to the Zarr array created by this function. If ``write_data`` is ``False``, then the
        array will be left empty.

    Returns
    -------
    Array
        The array.

    Examples
    --------
    ```python
    import zarr
    store = zarr.storage.MemoryStore()
    arr = zarr.create_array(
        store=store,
        shape=(100,100),
        chunks=(10,10),
        dtype='i4',
        fill_value=0)
    # <Array memory://... shape=(100, 100) dtype=int32>
    ```
    """
    return Array(
        sync(
            zarr.core.array.create_array(
                store,
                name=name,
                shape=shape,
                dtype=dtype,
                data=data,
                chunks=chunks,
                shards=shards,
                filters=filters,
                compressors=compressors,
                serializer=serializer,
                fill_value=fill_value,
                order=order,
                zarr_format=zarr_format,
                attributes=attributes,
                chunk_key_encoding=chunk_key_encoding,
                dimension_names=dimension_names,
                storage_options=storage_options,
                overwrite=overwrite,
                config=config,
                write_data=write_data,
            )
        )
    )