---
title: "Supported Zarr features in Rarr"
date: "`r BiocStyle::doc_date()`"
package: "`r BiocStyle::pkg_ver('Rarr')`"
vignette: >
  %\VignetteIndexEntry{"Supported Zarr features in Rarr"}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document
---

```{css, echo=FALSE}
.main-container {
  max-width: 1600px;
  margin-left: auto;
  margin-right: auto;
}
```

## Zarr version

Support for [Zarr version 3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html) is actively being worked on, and some features are likely to be missing.

It is currently known that reading only is supported, not writing, and that the sharding codec is not supported.

## Reading and Writing

Reading Zarr arrays is reasonably well supported. Writing is available, but is more limited.  Both aspects are under active development.

### Data Types

Currently there is only support for reading and writing a subset of the possible datatypes
that can be found in a Zarr array.  In some instances there are also limitations on the
datatypes natively supported by R, requiring conversion from the Zarr datatype.  The table below summarises the current status of
datatype support.  It will be updated as progress is made.

| Zarr Data Type | Status<br/>(reading / writing) | Notes |
|-----------|:--------------:|-------|
|`boolean`  | &#x2714; / &#x2714; | |
|`int8`     | &#x2714; / &#x274C; | |
|`uint8` | &#x2714; / &#x2714; | |
|`int16` | &#x2714; / &#x2714; | |
|`uint16`| &#x2714; / &#x274C; | |
|`int32` | &#x2714; / &#x2714; | |
|`uint32`| &#x2714; / &#x274C; | Values outside the range of `int32` are converted to `NA`.  Future plan is to allow conversion to `double` or use the [bit64](https://cran.r-project.org/package=bit64) package. |
|`int64` | &#x2714; / &#x274C; | Values outside the range of `int32` are converted to `NA`. Future plan is to allow conversion to `double` or use the [bit64](https://cran.r-project.org/package=bit64) package. |
|`uint64`| &#x2714; / &#x274C; | Values outside the range of `int32` are converted to `NA`. Future plan is to allow conversion to `double` or use the [bit64](https://cran.r-project.org/package=bit64) package. |
|`half` / `float16`   | &#x2714; / &#x274C; | Converted to `double` in R.  No effort is made to assess loss of precision due to conversion.  |
|`single` / `float32` | &#x2714; / &#x2714; | Converted to `double` in R.  No effort is made to assess loss of precision due to conversion. |
|`double` / `float64` | &#x2714; / &#x2714; | |
|`complex`            | &#x274C; / &#x274C; | |
|`timedelta`          | &#x274C; / &#x274C; | |
|`datetime`           | &#x274C; / &#x274C; | |
|`string`             | &#x2714; / &#x2714; | |
|`Unicode`            | &#x2714; / &#x2714; | |
|`void *`             | &#x274C; / &#x274C; | |
| Structured data types | &#x274C; / &#x274C; | |

### Codecs

#### Compression codecs

| Data Type   | Status<br/>(reading / writing) | Notes |
|-------------|:-------------------:|-------|
|`zlib / gzip`| &#x2714; / &#x2714; | Only system default compression level (normally 6) is enabled for writing. |
|`bzip2`      | &#x2714; / &#x2714; | Only compression level 9 is enabled for writing. |
|`blosc`      | &#x2714; / &#x2714; | Only `lz4` compression level 5 is enabled for writing. |
|`LZMA `      | &#x2714; / &#x2714; | |
|`LZ4`        | &#x2714; / &#x2714; | |
|`Zstd`       | &#x2714; / &#x2714; | |

Please open an [issue](https://github.com/Huber-group-EMBL/Rarr/issues) if support for a required compression codec is missing.

#### Other codecs

| Codec     | Status<br/>(reading / writing) | Notes |
|-----------|:------------------------------:|-------|
|`endian`   | &#x2714; / &#x274C;            |       |
|`transpose`| &#x2714; / &#x2714;            | Only the simple T/C case defined in v2 |