zarr.from_array

zarr.from_array

from_array(
    store: StoreLike,
    *,
    data: AnyArray | ArrayLike,
    write_data: bool = True,
    name: str | None = None,
    chunks: ChunksLike | Literal["auto", "keep"] = "keep",
    shards: ShardsLike | None | Literal["keep"] = "keep",
    filters: FiltersLike | Literal["keep"] = "keep",
    compressors: CompressorsLike | Literal["keep"] = "keep",
    serializer: SerializerLike | Literal["keep"] = "keep",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = None,
    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,
) -> AnyArray

Create an array from an existing array or array-like.

Parameters:

• store (StoreLike) –

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

• data (Array | array - like) –

  The array to copy.

• write_data (bool, default: True ) –

  Whether to copy the data from the input array to the new array. If write_data is False, the new array will be created with the same metadata as the input array, but without any data.

• 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.

• chunks (tuple[int, ...] or Sequence[Sequence[int]] or 'auto' or 'keep', default: 'keep' ) –

  Chunk shape of the array. Following values are supported:

  • "auto": Automatically determine the chunk shape based on the array's shape and dtype.
  • "keep": Retain the chunk grid of the data array if it is a zarr Array.
  • tuple[int, ...]: A tuple of integers representing the chunk shape (regular grid).
  • Sequence[Sequence[int]]: Per-dimension chunk edge lists (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.

  If not specified, defaults to "keep" if data is a zarr Array, otherwise "auto".

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

  Shard shape of the array. Following values are supported:

  • "auto": Automatically determine the shard shape based on the array's shape and chunk shape.
  • "keep": Retain the shard shape of the data array if it is a zarr Array.
  • tuple[int, ...]: A tuple of integers representing the shard shape.
  • None: No sharding.

  If not specified, defaults to "keep" if data is a zarr Array, otherwise None.

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

  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 "keep" instructs Zarr to infer filters from data. If that inference is not possible, Zarr will fall back to the behavior specified by "auto", which is to choose default filters 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 the empty tuple (). 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 is a tuple with 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] or 'auto' or 'keep', default: 'keep' ) –

  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.

  For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may be provided for Zarr format 2.

  Following values are supported:

  • Iterable[Codec]: List of compressors to apply to the array.
  • "auto": Automatically determine the compressors based on the array's dtype.
  • "keep": Retain the compressors of the input array if it is a zarr Array.

  If no compressors are provided, defaults to "keep" if data is a zarr Array, otherwise "auto".

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

  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.

  Following values are supported:

  • dict[str, JSON]: A dict representation of an ArrayBytesCodec.
  • ArrayBytesCodec: An instance of ArrayBytesCodec.
  • "auto": a default serializer will be used. These defaults can be changed by modifying the value of array.v3_default_serializer in zarr.config.
  • "keep": Retain the serializer of the input array if it is a zarr Array.
• fill_value (Any, default: DEFAULT_FILL_VALUE ) –

  Fill value for the array. If not specified, defaults to the fill value of the data 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 not specified, defaults to the memory order of the data array.

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

  The zarr format to use when saving. If not specified, defaults to the zarr format of the data array.

• attributes (dict, default: None ) –

  Attributes for the array. If not specified, defaults to the attributes of the data array.

• chunk_key_encoding (ChunkKeyEncoding, 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": "."}}. If not specified and the data array has the same zarr format as the target array, the chunk key encoding of the data array is used.

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

  The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter. If not specified, defaults to the dimension names of the data array.

• 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.

• config (ArrayConfig or ArrayConfigLike, default: None ) –

  Runtime configuration for the array.

Returns:

• Array –

  The array.

Examples:

Create an array from an existing Array:

>>> import asyncio
>>> import zarr
>>> store = zarr.storage.LocalStore("example_from_array.zarr")
>>> arr = zarr.create_array(
...     store={},
...     shape=(100,100),
...     chunks=(10,10),
...     dtype="int32",
...     fill_value=0
... )
>>> arr2 = zarr.from_array(store, data=arr, overwrite=True)
>>> arr2
<Array file://example_from_array.zarr shape=(100, 100) dtype=int32>
>>> asyncio.run(store.clear())  # Remove files generated by test

Create an array from an existing NumPy array:

>>> import numpy as np
>>> zarr.from_array({}, data=np.arange(10000, dtype="i4").reshape(100, 100))
<Array memory://... shape=(100, 100) dtype=int32>

Create an array from any array-like object:

>>> arr3 = zarr.from_array({}, data=[[1, 2], [3, 4]])
>>> arr3
<Array memory://... shape=(2, 2) dtype=int64>
>>> arr3[...]
array([[1, 2], [3, 4]])

Create an array from an existing Array without copying the data:

>>> arr4 = zarr.from_array({}, data=[[1, 2], [3, 4]])
>>> arr5 = zarr.from_array({}, data=arr4, write_data=False)
>>> arr5
<Array memory://... shape=(2, 2) dtype=int64>
>>> arr5[...]
array([[0, 0], [0, 0]])

Source code in zarr/api/synchronous.py

def from_array(
    store: StoreLike,
    *,
    data: AnyArray | npt.ArrayLike,
    write_data: bool = True,
    name: str | None = None,
    chunks: ChunksLike | Literal["auto", "keep"] = "keep",
    shards: ShardsLike | None | Literal["keep"] = "keep",
    filters: FiltersLike | Literal["keep"] = "keep",
    compressors: CompressorsLike | Literal["keep"] = "keep",
    serializer: SerializerLike | Literal["keep"] = "keep",
    fill_value: Any | None = DEFAULT_FILL_VALUE,
    order: MemoryOrder | None = None,
    zarr_format: ZarrFormat | None = None,
    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,
) -> AnyArray:
    """Create an array from an existing array or array-like.

    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.
    data : Array | array-like
        The array to copy.
    write_data : bool, default True
        Whether to copy the data from the input array to the new array.
        If ``write_data`` is ``False``, the new array will be created with the same metadata as the
        input array, but without any data.
    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.
    chunks : tuple[int, ...] or Sequence[Sequence[int]] or "auto" or "keep", optional
        Chunk shape of the array.
        Following values are supported:

        - "auto": Automatically determine the chunk shape based on the array's shape and dtype.
        - "keep": Retain the chunk grid of the data array if it is a zarr Array.
        - tuple[int, ...]: A tuple of integers representing the chunk shape (regular grid).
        - Sequence[Sequence[int]]: Per-dimension chunk edge lists (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.

        If not specified, defaults to "keep" if data is a zarr Array, otherwise "auto".
    shards : tuple[int, ...], optional
        Shard shape of the array.
        Following values are supported:

        - "auto": Automatically determine the shard shape based on the array's shape and chunk shape.
        - "keep": Retain the shard shape of the data array if it is a zarr Array.
        - tuple[int, ...]: A tuple of integers representing the shard shape.
        - None: No sharding.

        If not specified, defaults to "keep" if data is a zarr Array, otherwise None.
    filters : Iterable[Codec] | Literal["auto", "keep"], 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 ``"keep"`` instructs Zarr to infer ``filters`` from ``data``.
        If that inference is not possible, Zarr will fall back to the behavior specified by ``"auto"``,
        which is to choose default filters 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 the empty tuple ``()``.
        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 is a tuple with 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] or "auto" or "keep", 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.

        For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
        be provided for Zarr format 2.

        Following values are supported:

        - Iterable[Codec]: List of compressors to apply to the array.
        - "auto": Automatically determine the compressors based on the array's dtype.
        - "keep": Retain the compressors of the input array if it is a zarr Array.

        If no ``compressors`` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto".
    serializer : dict[str, JSON] | ArrayBytesCodec or "auto" or "keep", 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.

        Following values are supported:

        - dict[str, JSON]: A dict representation of an ``ArrayBytesCodec``.
        - ArrayBytesCodec: An instance of ``ArrayBytesCodec``.
        - "auto": 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].
        - "keep": Retain the serializer of the input array if it is a zarr Array.

    fill_value : Any, optional
        Fill value for the array.
        If not specified, defaults to the fill value of the data 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 not specified, defaults to the memory order of the data array.
    zarr_format : {2, 3}, optional
        The zarr format to use when saving.
        If not specified, defaults to the zarr format of the data array.
    attributes : dict, optional
        Attributes for the array.
        If not specified, defaults to the attributes of the data array.
    chunk_key_encoding : ChunkKeyEncoding, 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": "."}}``.
        If not specified and the data array has the same zarr format as the target array,
        the chunk key encoding of the data array is used.
    dimension_names : Iterable[str | None] | None
        The names of the dimensions (default is None).
        Zarr format 3 only. Zarr format 2 arrays should not use this parameter.
        If not specified, defaults to the dimension names of the data array.
    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.
    config : ArrayConfig or ArrayConfigLike, optional
        Runtime configuration for the array.

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

    Examples
    --------
    Create an array from an existing Array:

    >>> import asyncio
    >>> import zarr
    >>> store = zarr.storage.LocalStore("example_from_array.zarr")
    >>> arr = zarr.create_array(
    ...     store={},
    ...     shape=(100,100),
    ...     chunks=(10,10),
    ...     dtype="int32",
    ...     fill_value=0
    ... )
    >>> arr2 = zarr.from_array(store, data=arr, overwrite=True)
    >>> arr2
    <Array file://example_from_array.zarr shape=(100, 100) dtype=int32>
    >>> asyncio.run(store.clear())  # Remove files generated by test

    Create an array from an existing NumPy array:

    >>> import numpy as np
    >>> zarr.from_array({}, data=np.arange(10000, dtype="i4").reshape(100, 100))
    <Array memory://... shape=(100, 100) dtype=int32>

    Create an array from any array-like object:

    >>> arr3 = zarr.from_array({}, data=[[1, 2], [3, 4]])
    >>> arr3
    <Array memory://... shape=(2, 2) dtype=int64>
    >>> arr3[...]
    array([[1, 2], [3, 4]])

    Create an array from an existing Array without copying the data:

    >>> arr4 = zarr.from_array({}, data=[[1, 2], [3, 4]])
    >>> arr5 = zarr.from_array({}, data=arr4, write_data=False)
    >>> arr5
    <Array memory://... shape=(2, 2) dtype=int64>
    >>> arr5[...]
    array([[0, 0], [0, 0]])
    """

    return Array(
        sync(
            zarr.core.array.from_array(
                store,
                data=data,
                write_data=write_data,
                name=name,
                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,
            )
        )
    )