list_datasets: List datasets and dataset reference objects

In nbenn/infx: OpenBIS API Access to the InfectX Data Repository

List datasets and dataset reference objects

Description

All available datasets for the specified experiment(s), sample(s) or dataset code(s) are retrieved as DataSet objects by list_datasets(). Each dataset has a type and all realized type identifiers can be listed using list_dataset_types(). A more compact object type, uniquely identifying a DataSet, is that of a DatasetIdentifier. Given either a set of DataSet objects or a character vector holding (a) dataset code(s), list_dataset_id() fetches the corresponding DatasetIdentifier objects. Behavior of the function list_references(), in particular the returned object type, depends on input types. For more information, please refer to the details section.

Usage

list_datasets(token, x, ...)

## S3 method for class 'Sample'
list_datasets(token, x, include = c(NA, "children",
  "parents", "all"), ...)

## S3 method for class 'Experiment'
list_datasets(token, x, include = c(NA, "children",
  "parents", "all"), ...)

## S3 method for class 'character'
list_datasets(token, x, include = c(NA, "children",
  "parents", "all"), ...)

list_dataset_ids(token, x, ...)

## S3 method for class 'character'
list_dataset_ids(token, x, ...)

## S3 method for class 'DataSet'
list_dataset_ids(token, x, ...)

list_references(token, x, ...)

## S3 method for class 'PlateIdentifier'
list_references(token, x, type = c("raw",
  "segmentation", "feature"), ...)

## S3 method for class 'Plate'
list_references(token, x, type = c("raw", "segmentation",
  "feature"), ...)

## S3 method for class 'PlateMetadata'
list_references(token, x, type = c("raw",
  "segmentation", "feature"), ...)

## S3 method for class 'Sample'
list_references(token, x, type = c("raw",
  "segmentation", "feature"), ...)

## S3 method for class 'MaterialGeneric'
list_references(token, x, experiment = NULL,
  ...)

## S3 method for class 'MaterialScreening'
list_references(token, x, experiment = NULL,
  ...)

## S3 method for class 'MaterialIdentifierGeneric'
list_references(token, x,
  experiment = NULL, ...)

## S3 method for class 'MaterialIdentifierScreening'
list_references(token, x,
  experiment = NULL, ...)

## S3 method for class 'DatasetIdentifier'
list_references(token, x, wells = NULL,
  channels, ...)

## S3 method for class 'DataSet'
list_references(token, x, wells = NULL, channels, ...)

## S3 method for class 'DatasetReference'
list_references(token, x, wells = NULL,
  channels, ...)

## S3 method for class 'FeatureVectorDatasetReference'
list_references(token, x,
  wells = NULL, channels, ...)

## S3 method for class 'FeatureVectorDatasetWellReference'
list_references(token, x,
  wells = NULL, channels, ...)

## S3 method for class 'ImageDatasetReference'
list_references(token, x, wells = NULL,
  channels, ...)

## S3 method for class 'MicroscopyImageReference'
list_references(token, x,
  wells = NULL, channels, ...)

## S3 method for class 'PlateImageReference'
list_references(token, x, wells = NULL,
  channels, ...)

list_dataset_types(token, ...)

Arguments

token	Login token as created by login_openbis().
x	Object to limit search for datasets/files with.
...	Generic compatibility. Extra arguments will be passed to make_requests().
include	String indicating whether to include parent/child datasets as well.
type	For listing image datasets, it can be specified, whether only raw image datasets, only segmentation image datasets or any kind of image datasets (default) are to be listed.
experiment	When searching for datasets associated with materials, the search can be limited to a single experiment.
wells	A (set of) WellPosition object(s) to limit the dataset listing to.
channels	A character vector with imaging channel names to limit the dataset listing to.

Details

list_datasets() is an s3 generic function that can be dispatched on Sample and Experiment objects, as well as character vectors containing dataset codes and it returns sets of DataSet objects. Additionally it can be requested that parent or child datasets are to be included as well.

Several classes in addition to DatasetIdentifier implement the IDatasetIdentifier interface, including

• DatasetReference

• FeatureVectorDatasetReference

• FeatureVectorDatasetWellReference

• ImageDatasetReference

• MicroscopyImageReference

• PlateImageReference

The return type of list_references() depends on dispatch object type and in some cases on additional arguments. If the s3 generic function list_references() is dispatched on plate objects (Plate, PlateIdentifier or PlateMetadata or Sample objects, representing plates), ImageDatasetReference objects are returned (except if the type argument is set to feature, in which case, if MaterialIdentifierScreening objects are used as input, PlateWellReferenceWithDatasets objects are returned, which each contain ImageDatasetReference and FeatureVectorDatasetReference objects.

Whenever list_references() is dispatched on dataset ids or dataset reference objects, the resulting object type depends on whether a (set of) WellPosition object(s) were specified as wells argument. For its default value (NULL), a set of MicroscopyImageReference objects is returned, while PlateImageReference objects are returned otherwise.

Value

Depending on the number of resulting objects, either a json_class (single object) or a json_vec (multiple objects), is returned. For the specific sub-class, refer to the Details section.

Implementation note

The API function listDataSetsForSample() has a parameter areOnlyDirectlyConnectedIncluded, which is currently fixed to TRUE. The documentation contains the following explanation:

If true, only datasets that are directly connected to the sample are included, otherwise datasets of child samples are included as well.

This does however not seem to correspond to including child datasets in the API call to listDataSets() via its connectionsToGet argument. As long as it is not entirely clear how the inclusion of child/parent datasets differs from setting areOnlyDirectlyConnectedIncluded to FALSE, this option is not exposed to the user.

openBIS

• \Sexpr[results=rd]{infx::docs_link("gis", "listDataSetsForSample")}
• \Sexpr[results=rd]{infx::docs_link("gis", "listDataSets")}

• \Sexpr[results=rd]{infx::docs_link("gis", "listDataSetsForExperiments")}

• \Sexpr[results=rd]{infx::docs_link("gis", "getDataSetMetaData")}

• \Sexpr[results=rd]{infx::docs_link("sas", "getDatasetIdentifiers")}

• \Sexpr[results=rd]{infx::docs_link("sas", "listRawImageDatasets")}
• \Sexpr[results=rd]{infx::docs_link("sas", "listSegmentationImageDatasets")}
• \Sexpr[results=rd]{infx::docs_link("sas", "listFeatureVectorDatasets")}

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

• \Sexpr[results=rd]{infx::docs_link("gis", "listDataSetTypes")}

See Also

Other object listing functions: list_experiments, list_material, list_plates, list_projects, list_samples

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

  # list all datasets associated with this plate
  ds <- list_datasets(tok, samp)

  # select a feature dataset, note how the fields "parentCodes" and
  # "childrenCodes" both are not set
  feat_ds <- ds[[grep("FEATURES_CC_MAT",
                      get_field(ds, "dataSetTypeCode"))]]

  # fetch parent and child datasets and now both the "parentCodes" and
  # "childrenCodes" fields are populated with the corresponding codes
  feat_ds <- list_datasets(tok, get_field(feat_ds, "code"), include = "all")

  # re-using the plate sample from above, an ImageDatasetReference object
  # corresponding to the associated raw imaging dataset is listed
  raw_ref <- list_references(tok, samp)
  # available imaging channels are
  get_field(raw_ref, "properties")[["IMAGE.CHANNEL.LIST"]]

  # a more specific image reference object can be retrieved by passing a
  # well specification to list_references()
  well_ref <- list_references(tok, raw_ref,
                              wells = well_pos(name = "A2"),
                              channel = "DAPI")
  # a reference to 9 images is returned, as there are 3 x 3 imaging tiles
  # per well
  length(well_ref)

  logout_openbis(tok)

nbenn/infx documentation built on May 20, 2022, 7:44 a.m.