romeo/README.qmd at main · Huber-group-EMBL/romeo · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
---
format:
  gfm:
    default-image-extension: ""
---

<!-- README.md is generated from README.qmd. Please edit that file -->

```{r}
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# romeo

<!-- badges: start -->
[![R-CMD-check](https://github.com/Huber-group-EMBL/romeo/actions/workflows/r-universe.yaml/badge.svg)](https://github.com/Huber-group-EMBL/romeo/actions/workflows/r-universe.yaml)
[![Codecov test coverage](https://codecov.io/gh/Huber-group-EMBL/romeo/graph/badge.svg)](https://app.codecov.io/gh/Huber-group-EMBL/romeo)
<!-- badges: end -->

**romeo** is a minimal R package to reading, writing and validating multiscale [OME-Zarr](https://ngff.openmicroscopy.org/index.html) images. **romeo** also provides helpers and methods to manipulate OME-Zarr images (realized as `ome_zarr` objects) in the same way one would manipulate traditional arrays in R. For example, you can subset an `ome_zarr` object using the `[` operator, and the subsetting will be applied to all levels of the multiscale OME-Zarr object.

## OME-Zarr

OME-Zarr is a cloud-friendly data format for storing large bioimaging datasets, such as microscopy images, that combines **Zarr**, a chunked, compressed array storage format ([https://zarr.dev/](https://zarr.dev/)) designed for scalable access to multidimensional data, together with **OME-NGFF** ([https://ngff.openmicroscopy.org/](https://ngff.openmicroscopy.org/)) metadata standards for describing multiscale images, labels, and coordinate transformations for bioimaging data formats.

## Installation

You can install the development version of **romeo** like so:

``` r
# install.packages("pak")
pak::pak("Huber-group-EMBL/romeo")
```

## Reading OME-Zarr images

This example shows how to read an OME-Zarr image of version 0.4.
By default, data are read lazily using `ZarrArray`.

```{r read}
#| label: read
library(romeo)
library(utils)
omezarrzip <- system.file("extdata", "test_ngff_image_v04.ome.zarr.zip", package = "romeo")
dir.create(td <- tempfile())
unzip(omezarrzip, exdir = td)

x <- ome_read(td)
plot(x, 1)
```

For remote OME-Zarr files, you can use the `paws.storage::s3` client to read the data directly from the S3 bucket without downloading it first:

```{r read_remote, eval=FALSE}
#| label: read_remote
#| eval: false
library(paws)
s3_client <- paws.storage::s3(
  config = list(
    credentials = list(anonymous = TRUE),
    region = "auto",
    endpoint = "https://uk1s3.embassy.ebi.ac.uk"
  )
)
x <- ome_read(
  "https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0076A/10501752.zarr",
  s3_client = s3_client,
)
```

## Writing OME-Zarr images

**romeo** is also capable of writing OME-Zarr images with respect to multiple OME-NGFF specifications (Versions 0.4 and 0.5). See [NGFF Specifications](https://ngff.openmicroscopy.org/specifications/) for more information.

We use `ome_write` to write image (or label) pyramids with custom scaling. Here, `scalefactors` argument specifies the relative scale factor of each space layer (x, y and z dimensions) to the previous layer, e.g. `scalefactors = c(2,2,3)` generates four layers with scales 1, 2, 4, and 12.

```{r write}
#| label: write
library(EBImage)
img_file <- system.file("extdata", "example_RGB.png", package="romeo")
img <- readImage(img_file)

ome_img <- ome_write(img,
                     path = tempfile(fileext = ".ome.zarr"),
                     version = "0.4",
                     scalefactors = c(2,2,3),
                     storage_options = list(chunk_dim = c(64,64,1)))
plot(ome_img)
```