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

Rarr currently only works with [Zarr specification version 2](https://zarr-specs.readthedocs.io/en/latest/v2/v2.0.html).
Support for [version 3](https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html) is actively being worked on.

## 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; / &#x274C; | |
|`int8`     | &#x2714; / &#x274C; | |
|`uint8` | &#x2714; / &#x274C; | |
|`int16` | &#x2714; / &#x274C; | |
|`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; / &#x274C; | 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 |