list_fetch_images: List image meta data and download images
In ropensci/infx: OpenBIS API Access to the InfectX Data Repository

fetch_images

R Documentation

List image meta data and download images

Description

Experiment level image meta data can be listed by passing experiment representing objects (Experiment or ExperimentIdentifier) to list_image_metadata() and data set level image meta data can be retrieved by passing data set identifying objects which can be associated with image data sets (data set id and data set reference objects). Images themselves can be retrieved using fetch_images(). As with meta data listing, this function can be dispatched on objects referencing or identifying data sets associated with image data.

Usage

fetch_images(token, x, ...)

## S3 method for class 'DatasetIdentifier'
fetch_images(token, x, channels,
  well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...)

## S3 method for class 'DatasetReference'
fetch_images(token, x, channels,
  well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...)

## S3 method for class 'ImageDatasetReference'
fetch_images(token, x, channels,
  well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...)

## S3 method for class 'MicroscopyImageReference'
fetch_images(token, x,
  well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...)

## S3 method for class 'PlateImageReference'
fetch_images(token, x, image_size = NULL,
  force_png = FALSE, format = NULL, thumbnails = FALSE, ...)

list_image_metadata(token, x, ...)

## S3 method for class 'ExperimentIdentifier'
list_image_metadata(token, x, ...)

## S3 method for class 'Experiment'
list_image_metadata(token, x, ...)

## S3 method for class 'DatasetIdentifier'
list_image_metadata(token, x,
  type = c("metadata", "format"), ...)

## S3 method for class 'DatasetReference'
list_image_metadata(token, x,
  type = c("metadata", "format"), ...)

## S3 method for class 'ImageDatasetReference'
list_image_metadata(token, x,
  type = c("metadata", "format"), ...)

## S3 method for class 'MicroscopyImageReference'
list_image_metadata(token, x,
  type = c("metadata", "format"), ...)

## S3 method for class 'PlateImageReference'
list_image_metadata(token, x,
  type = c("metadata", "format"), ...)

Arguments

`token`	Login token as created by `login_openbis()`.
`x`	Object to limit the number of returned images
`...`	Generic compatibility. Extra arguments will be passed to `make_requests()`.
`channels`	A character vector of imaging channels
`well_positions`	A (list of) `WellPosition` objects. If the object passed as argument x already contains well position information this can be NULL.
`image_size`	Either a single `ImageSize` object or NULL, in which case images are returned in full size.
`thumbnails`	Logical switch; if TRUE, thumbnail images are retrieved in which case the arguments `well_positions` and `image_size` are expected to be at their default values.
`force_png`	Logical switch for making sure the returned image is a png. If NULL or FALSE, the image is returned in the format it is stored.
`format`	If not NULL, a single `ImageRepresentationFormat` object. Cannot be combined with non-default `image_size`, `force_png` and `format` arguments.
`type`	Switch to specify the type of meta data objects to be returned.

Details

Data set level image meta data can be listed by passing objects, which implement the IDatasetIdentifier interface and are connected to image data sets (this rules out feature data set references and leaves DatasetIdentifier, DatasetReference, ImageDatasetReference, MicroscopyImageReference and PlateImageReference objects). Two different types of meta data objects are returned, depending on the type argument: if it is set to metadata (default), objects of type ImageDatasetMetadata and if it is set to format, objects of type DatasetImageRepresentationFormats are returned. For experiment-level image meta data, ExperimentImageMetadata objects are returned.

Dispatch of fetch_images() is available for the same object types as data set-level image meta data listing: DatasetIdentifier, DatasetReference, ImageDatasetReference, MicroscopyImageReference and PlateImageReference. The highest level of control over which images are retrieved is achieved with PlateImageReference objects, which specify an image data set, a well, a tile and a channel. The returned image format can be modified by either passing an ImageRepresentationFormat object as the format argument, by passing a single/list of format selection criterion objects, which will be used to filter the available image representation format objects or by specifying one or both of the image_size (expects an ImageSize object) and force_png (logical switch) arguments.

MicroscopyImageReference objects contain channel information (as well as tile information, which is not taken into account though). Therefore a (list of) WellPosition object(s) has/have to be specified, for which then all tiles are fetched for the given imaging channel. If the passed list of MicroscopyImageReference objects contain instances that only differ in tile number, redundancies are filtered out. An API call is necessary for each non-redundant object.

Finally, DatasetIdentifier, DatasetReference and ImageDatasetReference objects are all handled identically. For each of the specified data sets, an imaging channel has to be provided and whenever the data set is associated with an entire plate, a (list of) WellPosition object(s) as well. If the data set is associated with a single well, the well_positions can be left at its default value (NULL). If several data sets are passed, an API call is necessary per data set. Possible redundancies are not filtered.

Images are retrieved as Base64 encoded strings, which are converted to binary using base64enc::base64decode() and subsequently read by magick::image_read(). Attached to the images is the information, based on which they were retrieved, including data set object, well positions (where applicable) and channel (where applicable). This results in a list with length corresponding to the number of API calls that were necessary.

Value

For list_image_metadata(), either a json_class (single object) or a json_vec (multiple objects), is returned. For the specific sub-class, refer to the Details section. Image data retrieved with fetch_images() is read by magick::image_read() and returned as (possibly nested) list of magick-image objects.

Implementation notes

For dispatch on PlateImageReference objects, currently the only options controlling the returned images are an argument for image size and a flag for forcing the returned format to png. OpenBIS also supports pre-defined image transformations to be applied to the images before they are sent to the requesting party. These transformations can be requested by a code (options are listed in ImageRepresentationFormat objects or in ImageChannel objects attached to ImageDatasetMetadata objects). However, as no such transformations appear to be defined, this is currently not implemented.
When filtering ImageRepresentationFormat objects associated with a data set, only SizeCriterion objects can be used. The remaining criteria (ColorDepthCriterion, FileTypeCriterion and OriginalCriterion) are currently disabled as they extend the abstract class AbstractFormatSelectionCriterion, which causes an issue with JSON deserialization.

openBIS

\Sexpr[results=rd]{infx::docs_link("dsrs", "loadImagesBase64")}
\Sexpr[results=rd]{infx::docs_link("dsrs", "loadThumbnailImagesBase64")}

\Sexpr[results=rd]{infx::docs_link("dsrs", "loadPhysicalThumbnailsBase64")}

\Sexpr[results=rd]{infx::docs_link("sas", "getExperimentImageMetadata")}
\Sexpr[results=rd]{infx::docs_link("dsrs", "listImageMetadata")}
\Sexpr[results=rd]{infx::docs_link("dsrs", "listAvailableImageRepresentationFormats")}

Examples


  tok <- login_openbis()

  # search for a sample object corresponding to plate KB2-03-1I
  samp <- search_openbis(tok,
                         search_criteria(
                           attribute_clause("code",
                                            "/INFECTX_PUBLISHED/KB2-03-1I")
                         ),
                         target_object = "sample")
  # for the plate sample object, list raw image data set references
  ds_ref <- list_references(tok, samp)

  # the returned image dataset reference can be used to list image meta data
  img_meta <- list_image_metadata(tok, ds_ref)
  channels <- img_meta[["channelCodes"]]

  imgs <- fetch_images(tok, ds_ref,
                       channels = channels[[1L]],
                       well_positions = well_pos(1, 1),
                       image_size = json_class(width = 300, height = 300,
                                               class = "ImageSize"))
  # this yields 9 images, one per tile
  length(imgs[[1L]]) == img_meta[["numberOfTiles"]]
  # and each image is scaled to fit within 300 x 300 pixels
  magick::image_info(imgs[[1L]][[1L]])

  # if not the entire well is of interest, but only certain tiles
  img_ref <- list_references(tok, ds_ref,
                             wells = well_pos(1, 1),
                             channels = channels[[1L]])
  # this yields 9 objects, one reference per tile
  length(img_ref)
  # select a tile, for example the center one
  img <- fetch_images(tok, img_ref[[5L]],
                      image_size = json_class(width = 300, height = 300,
                                              class = "ImageSize"))
  identical(as.raster(img[[1L]]), as.raster(imgs[[1L]][[5L]]))

  logout_openbis(tok)

ropensci/infx documentation built on May 14, 2022, 5:51 p.m.