Skip to contents

Read a multiplex image (QPTIFF, OME-TIFF, or OME-Zarr)

Source: R/read_qptiff.R
read_qptiff.Rd

Reads a multiplex image into R without Java, auto-detecting the container:

  • QPTIFF from Akoya PhenoCycler-Fusion (formerly CODEX), Cell DIVE, or Vectra / Polaris scanners - brightfield RGB, Polaris ScanBand XML, and Fusion per-page JSON+XML variants.

  • OME-TIFF (as written by tifffile, Bio-Formats, or QuPath) - channel names are read from the <Channel Name="..."> attributes of the OME-XML.

  • OME-Zarr (OME-NGFF) stores - requires the Rarr package; channel names / colours are read from omero.channels.

Usage

read_qptiff(path, channels = NULL, level = 1L, as_integer = TRUE, lazy = FALSE)

Arguments

path

Character, path to the image. A QPTIFF / OME-TIFF file, or an OME-Zarr store (a directory, or a path ending in .zarr).

channels

Character vector of channel names to load, an integer vector of 1-based channel indices, or NULL (default) to load all channels.

level

Integer, pyramid resolution level. 1 = full resolution (default), 2 = half resolution, etc. OME-TIFF sub-resolution pyramids (SubIFDs) are not supported; use level = 1.

as_integer

Logical; return raw 16-bit integers (0-65535) rather than normalised [0, 1] doubles? Default TRUE.

lazy

Logical; if TRUE return a DelayedArray backed by a QPTIFFArraySeed that reads pages from disk on demand. If FALSE (default) load all requested channels into memory and return a QPTIFFImage.

Value

lazy = FALSE

A QPTIFFImage - a 3-D numeric array [height, width, channels] with class c("QPTIFFImage", "array"). Channel names are stored in dimnames(img)[[3]]. Standard array subscripting works: img[, , "DAPI"] extracts a single channel as a matrix; img[1:512, 1:512, ] crops spatially. Rich metadata is in attr(img, "metadata").

lazy = TRUE

A DelayedArray with dim = c(H, W, C). Individual channel pages are read from disk only when accessed. The seed is a QPTIFFArraySeed accessible via DelayedArray::seed(arr).

Details

Channel names and rich per-channel metadata (fluorophore, exposure time, wavelengths, filters, colour) are parsed into an OME-organised QPTIFFMetadata object, available via metadata.

The native, Java-free TIFF/QPTIFF reader and writer implemented here was translated from the bioio-tifffile fork by Rafael Tubelleza.

Examples

path <- system.file("extdata", "PA_HNC_sample.ome.tiff", package = "bgnormR")
img  <- read_qptiff(path)
#> Reading TIFF directory structure ...
#> Reading OME-TIFF metadata ...
#> Reading IFD page layouts ...
#> Loading 5 channel(s) ...
#> Loading 5 channel(s) ...
dim(img)                      # c(H, W, n_channels)
#> [1] 550 800   5
names(img)                    # channel names
#> [1] "CD20"     "CD3e"     "CD8"      "PanCK"    "Vimentin"
cd20 <- img[, , "CD20"]      # extract one channel as a 2-D matrix

# Load specific channels only
img2 <- read_qptiff(path, channels = c("CD20", "PanCK"))
#> Reading TIFF directory structure ...
#> Reading OME-TIFF metadata ...
#> Reading IFD page layouts ...
#> Loading 2 channel(s) ...
#> Loading 2 channel(s) ...
names(img2)
#> [1] "CD20"  "PanCK"

# \donttest{
# Lazy / out-of-core load (backed by DelayedArray)
arr <- read_qptiff(path, lazy = TRUE)
#> Reading TIFF directory structure ...
#> Reading OME-TIFF metadata ...
#> Reading IFD page layouts ...
#> Loading 5 channel(s) ...
# }