list_fetch_features: List and download feature data

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

List and download feature data

Description

In openBIS, features are datasets that are treated differently from generic datasets. Briefly put, tabular datasets where columns correspond to features and rows to wells can be marked as feature datasets which makes it possible to query openBIS for individual feature values for selected wells instead of having to download the entire table for a plate. The relevant object types for handling feature data are FeatureVectorDatasetReference and FeatureVectorDatasetWellReference, where the former represents feature data at plate level and the latter at well level. The function list_features() can be used to enumerate available features and fetch_features() will download feature data.

Usage

list_features(token, x, ...)

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

## S3 method for class 'FeatureVectorDatasetWellReference'
list_features(token, x, ...)

list_feature_codes(token, x, ...)

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

## S3 method for class 'FeatureVectorDatasetWellReference'
list_feature_codes(token, x,
  ...)

fetch_features(token, x, feature_codes = NA, ...)

## S3 method for class 'FeatureVectorDatasetReference'
fetch_features(token, x,
  feature_codes = NA, wells = NULL, ...)

## S3 method for class 'FeatureVectorDatasetWellReference'
fetch_features(token, x,
  feature_codes = NA, ...)

Arguments

token	Login token as created by login_openbis().
x	Object to specify the set of feature vector datasets of interest.
...	Generic compatibility. Extra arguments will be passed to make_request().
wells	Set of WellPosition objects used to limit the returned feature data.
feature_codes	A character vector of feature codes or NA (all available feature codes).

Details

Listing of features can be performed by calling list_features() on FeatureVectorDatasetReference or FeatureVectorDatasetWellReference objects. Plate-level references of feature datasets can for example be retrieved using list_references() and well-level references are created whenever a wells argument is supplied to list_features(), using the internal function feat_ds_well_ref(). The returned objects are of type FeatureInformation and each contain code, label and description of each feature. If for different datasets different sets of features are available, list_features() provides the union of the features of all datasets.

Similarly, list_feature_codes() provides the list of all available features as character vector of feature codes. As for list_features(), either plate-level or well-level feature dataset reference may be passed and if a wells argument is supplied together with a plate-level reference, the corresponding well-level references are constructed using the internal function feat_ds_well_ref(). If for different datasets different sets of features are available, list_feature_codes() provides the union of the features of all datasets.

For a given set of feature vector datasets, fetch_features() fetches feature data for the specified feature codes, or for all available features in case the argument feature_codes is not specified (or NA). The behavior regarding well selection is the same as in list_features() and list_feature_codes(). Either plate-level or well-level dataset references are passed and whenever plate-level references are passed in combination with WellPosition object, the corresponding well-level references are created and used. If for different datasets different sets of features are available, the union of the features of all datasets is searched for. The returned object is of type FeatureVectorDataset, which for each entry contains a FeatureVectorDatasetReference and a set of FeatureVector(s), one for each well.

Value

list_feature_codes() returns a character vector of feature codes, while list_features() and fetch_features() return either json_class (single object) or a json_vec (multiple objects), dependent on the number of resulting objects. The sub-type is FeatureInformation for list_features() and FeatureVectorDataset for fetch_features().

openBIS

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

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

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

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

Implementation note

Even though there exists a constructor for FeatureVectorDatasetWellReference objects, which takes two arguments, one for the corresponding FeatureVectorDatasetReference object and one for a WellPosition objects, this does not work. Furthermore, class information cannot be supplied as this will cause an error as well (hence the use of rm_json_class()). Why the function loadFeaturesForDatasetWellReferences behaves this way is currently unclear.

See Also

Other resource listing/downloading functions: fetch_images, list_download_urls, list_files

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 all feature data sets
  feat_ref <- list_references(tok, samp, type = "feature")

  # several data set types can act as feature data sets
  get_field(feat_ref, "dataSetType")
  feat_ref <- feat_ref[[7L]]

  # for a feature data set, list all features
  feat_info <- list_features(tok, feat_ref)
  feat_info <- feat_info[c(2L, 6L)]

  # for a feature data set, a set of feature codes and a set of wells,
  # retrieve the corresponding feature data
  feats <- fetch_features(tok, feat_ref,
                          feature_codes = get_field(feat_info, "code"),
                          wells = well_pos(1:6, 3:8))

  well_pos <- get_field(feats, "wellPosition")
  values <- get_field(feats, "values")
  tibble::tibble(
    well_row = get_field(well_pos, "wellRow"),
    well_col = get_field(well_pos, "wellColumn"),
    cell_count = as.integer(values[1L, ]),
    cell_area = as.integer(values[2L, ])
  )

  logout_openbis(tok)

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