---
title: "_ZarrArray_ overview"
author:
- name: Hervé Pagès
  affiliation: CUNY Graduate School of Public Health and Health Policy, New York, NY USA
date: "Compiled `r BiocStyle::doc_date()`; Modified 3 April 2026"
package: ZarrArray
vignette: |
  %\VignetteIndexEntry{ZarrArray overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
output:
  BiocStyle::html_document
---


```{r setup, include=FALSE}
library(BiocStyle)
```


# Introduction


`r Biocpkg("ZarrArray")` is an infrastructure package that leverages
the `r Biocpkg("Rarr")` package to bring Zarr datasets in R as DelayedArray
objects.


# Install and load the package


Like any other Bioconductor package, `r Biocpkg("ZarrArray")` should
always be installed with `BiocManager::install()`:
```{r install, eval=FALSE}
if (!require("BiocManager", quietly=TRUE))
    install.packages("BiocManager")
BiocManager::install("ZarrArray")
```

Load the package:
```{r load, message=FALSE}
library(ZarrArray)
```


# ZarrArray objects


The main class in the package is the ZarrArray class. A ZarrArray
object is an array-like object that represents a Zarr dataset in R.

## Construction

To create a ZarrArray object, simply call the `ZarrArray()` constructor
function on the path to a Zarr dataset:
```{r construction}
zarr_path <- system.file(package="Rarr", "extdata",
                         "zarr_examples", "column-first", "int32.zarr")
A <- ZarrArray(zarr_path)
A
```

## Array and matrix operations

Note that ZarrArray objects are DelayedArray derivatives and
therefore support all operations (delayed or block-processed)
supported by DelayedArray objects:
```{r check_class}
class(A)

is(A, "DelayedArray")
```

This allows ZarrArray objects to "look and feel" like ordinary arrays or
matrices in R by mimicking their behavior. In particular, ZarrArray objects
suppport most of the "standard array API" defined in base R like `dim()`,
`length()`, `dimnames()`, `[`, `aperm()`, `max()`, `sum()`, arithmetic and
comparison operations, math functions, etc...
```{r basic_ops}
dim(A)
length(A)
A[1:5, , 1]
aperm(A)
max(A)
sum(A)
A - 0.5
A^3
A == 0L
sqrt(A)
```

In the 2D case, they also support the "standard matrix API" defined
in base R like `nrow()`, `ncol()`, `rownames()`, `colnames()`, `t()`,
`rbind()`, `cbind()`, `rowSums()`, `colSums()`, `%*%`, etc..., as well
as some row/column summarization operations from the `r CRANpkg("matrixStats")`
package like `rowMaxs()`, `colVars()`, etc...

## Other operations

Other operations are supported that are specific to DelayedArray objects
and their derivatives:
```{r other_ops}
path(A)
type(A)
chunkdim(A)
a <- as.array(A)
```

See `?ZarrArray` for more information.


# Write an array-like object to disk in Zarr format


The `writeZarrArray()` function can be used to write an array-like
object to disk in Zarr format.

For example we can write back A to disk but with a different physical
chunk geometry:
```{r writeZarrArray_1}
path1 <- tempfile(fileext=".zarr")
writeZarrArray(A, path1, chunkdim=c(3, 5, 2))
```
Or, we can transform A and then write it back to disk:
```{r writeZarrArray_2}
path2 <- tempfile(fileext=".zarr")
A2 <- sqrt(t(A[ , , 1]) + 1)  # all these operations are delayed
writeZarrArray(A2, path2)  # realizes the delayed operations block by block
```

Note that `writeZarrArray()` leverages lower-level functionality implemented
in the `r Biocpkg("Rarr")` package like `create_empty_zarr_array()`
and `update_zarr_array()`. See `?writeZarrArray` for more information.


# Session information


```{r session_info}
sessionInfo()
```