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

list_material

R Documentation

List materials

Description

Materials in openBIS can represent a variety of objects. For the InfectX HTS setup, this is mainly limited to either compounds such as oligos or small molecule drugs and targeted genes. Three different objects are used to identify a material: MaterialGeneric, MaterialIdentifierGeneric and MaterialIdentifierScreening. Converting to id object types can be achieved with as_generic_mat_id() and as_screening_mat_id() while listing materials as MaterialGeneric objects is possible with list_material().

Usage

list_material(token, x, ...)

## S3 method for class 'MaterialIdentifierGeneric'
list_material(token, x, ...)

## S3 method for class 'MaterialIdentifierScreening'
list_material(token, x, ...)

## S3 method for class 'PlateIdentifier'
list_material(token, x, material_type = NULL,
  ...)

## S3 method for class 'PlateMetadata'
list_material(token, x, material_type = NULL,
  ...)

## S3 method for class 'Plate'
list_material(token, x, material_type = NULL, ...)

## S3 method for class 'Sample'
list_material(token, x, material_type = NULL, ...)

material_id(code, type = "gene", mode = c("screening", "generic"))

list_material_types(mode = c("screening", "generic"), types = NULL)

as_screening_mat_id(x, ...)

## S3 method for class 'MaterialGeneric'
as_screening_mat_id(x, ...)

## S3 method for class 'MaterialScreening'
as_screening_mat_id(x, ...)

## S3 method for class 'MaterialIdentifierGeneric'
as_screening_mat_id(x, ...)

## S3 method for class 'MaterialIdentifierScreening'
as_screening_mat_id(x, ...)

as_generic_mat_id(x, ...)

## S3 method for class 'MaterialGeneric'
as_generic_mat_id(x, ...)

## S3 method for class 'MaterialScreening'
as_generic_mat_id(x, ...)

## S3 method for class 'MaterialIdentifierGeneric'
as_generic_mat_id(x, ...)

## S3 method for class 'MaterialIdentifierScreening'
as_generic_mat_id(x, ...)

extract_well_material(x, row, col)

Arguments

`token`	Login token as created by `login_openbis()`.
`x`	A (vector of) `MaterialIdentifier` object(s).
`...`	Generic compatibility. Extra arguments will be passed to `make_requests()`.
`material_type`	A `MaterialTypeIdentifierScreening` object to restrict the material listing to a certain type of materials.
`code`	The material code for which an id object is created.
`type`	The material type (possible values depend on mode).
`mode`	Switch between generic and screening material id objects.
`types`	Select one or several material types for which to return the type id objects. NULL returns all available.
`row`	Either a single integer or a single character specifying a plate row.
`col`	A single integer specifying a plate column.

Details

Unfortunately in this version of the openBIS JSON-RPC API, there is no possibility for listing all available materials for a project or experiment. Methods that return MaterialGeneric objects include list_material(), which can be dispatched on material id objects and objects representing plates, and search_openbis() with the target selector target_object set to material. Coercing MaterialGeneric objects to material id objects is possible with as_generic_mat_id() and as_screening_mat_id() which do not incur an API call.

Instantiating material id objects is either done manually by calling material_id() or by querying openBIS for MaterialGeneric objects and converting to MaterialIdentifierGeneric or MaterialIdentifierScreening. A material id object is defined by a material code and a material type. Available types depend on whether generic or screening material objects are of interest. For generic material objects, possible ids are

compound
control
esirna
gene
mirna
mirna_inhibitor
mirna_mimic
pooled_sirna
sirna

and for screening materials, ids can be

compound
gene
oligo

Material type objects can be instantiated by calling list_material_types(), where the mode argument acts as a switch to choose between generic and screening objects. If only a subset of types are relevant, the output of list_material_types() can be limited by passing a character vector with type names as types argument. The second piece of information for constructing material id objects, material codes, depends on material type. Genes, for example are identified with Entrez gene ids (e.g. 2475 for MTOR), while for compounds, a manufacturer name is used (e.g. for Ambion and MTOR, AMBION_S602, AMBION_S603 and AMBION_S604).

Whenever list_material() is dispatched on a (set of) material id object(s), a (set of) MaterialGeneric object(s) is returned. However if the dispatch occurs on plate objects (Plate, PlateIdentifier or PlateMetadata), a (set of) PlateWellMaterialMapping objects is returned. If material_type is not specified (i.e. NULL), the mapping field in the returned object will contain NULL for each well. When passing a set of MaterialTypeIdentifierScreening objects, as returned by list_material_types(), the mapping fields will contain material type information where available. The convenience function extract_well_material() can be applied to a PlateWellMaterialMapping object and will return the selected MaterialIdentifierScreening object.

Value

Depending on the number of resulting objects, either a json_class (single object) or a json_vec (multiple objects), is returned. For list_material() and extract_well_material(), the additional class attribute MaterialGeneric is added and the utility functions as_generic_mat_id() and as_screening_mat_id() return MaterialIdentifierGeneric and MaterialIdentifierScreening objects, respectively, while material_id() can return either, depending on the mode argument. Finally, list_material_types() returns MaterialTypeIdentifierGeneric or MaterialTypeIdentifierScreening, again depending on the mode argument.

openBIS

\Sexpr[results=rd]{infx::docs_link("gis", "getMaterialByCodes")}
\Sexpr[results=rd]{infx::docs_link("sas", "listPlateMaterialMapping")}

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 material types
  types <- list_material_types()
  print(types)

  # list all gene targets on plate KB2-03-1I
  mat_map <- list_material(tok, samp, types[[2L]])
  print(mat_map, depth = 5, length = 20L)
  # there are maximally width x height entries arranged in a linear,
  # row-major fashion; missing entries are omitted, but original indices
  # are accessible as original_index attributes
  length(mat_map[["mapping"]])
  attr(mat_map[["mapping"]][[42L]], "original_index")
  # well A24 does not have a gene target as it is a MOCK control well
  extract_well_material(mat_map, "A", 24)
  # well A22 however has a gene target
  a_22 <- extract_well_material(mat_map, "A", 22)
  print(a_22, depth = 2L)

  # search for a material with material code 3480
  igf1r <- search_openbis(tok,
                          search_criteria(attribute_clause("code", 3480)),
                          target_object = "material")

  all.equal(as_screening_mat_id(igf1r), a_22, check.attributes = FALSE)
  identical(igf1r, list_material(tok, a_22))
  identical(igf1r, 
            search_openbis(tok,
                           search_criteria(
                             property_clause("gene_symbol", "IGF1R")
                           ),
                           target_object = "material"))

  # search for an experiment object corresponding to plate KB2-03-1I
  exp <- search_openbis(tok,
                        search_criteria(
                          attribute_clause(
                            "code",
                            samp[["experimentIdentifierOrNull"]]
                          )
                        ),
                        target_object = "experiment")

  # list all wells for the current material within the selected experiment
  wells <- list_wells(tok, a_22, experiment = exp)
  # this yields 3 plates, one of which is KB2-03-1I
  get_field(get_field(wells, "experimentPlateIdentifier"), "plateCode")
  # and the material of interest is in well A22 in each one
  unique(get_field(wells, "wellPosition"))

  logout_openbis(tok)

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