search_openbis: Assemble and execute openBIS search queries

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

Assemble and execute openBIS search queries

Description

Searching in openBIS presents a powerful alternative to iterative listing and selecting of objects. As an example, in order to find image data sets associated with an experiment, instead of first listing all experiments, selecting the one of interest, then listing all plates of that experiment, followed by listing image data sets for each of the plates, the requested data sets can be directly retrieved by constructing a search query with search_criteria() and executing the search by calling search_openbis().

Usage

search_openbis(token, criteria, target_object = c("data_set",
  "experiment", "material", "sample"), fetch_options = NULL, ...)

search_criteria(..., operator = "all", sub_criteria = NULL)

search_sub_criteria(criteria, type = "sample")

property_clause(property_code, value, ...)

any_property_clause(value, ...)

any_field_clause(value, ...)

attribute_clause(attribute = "code", value, ...)

time_attribute_clause(attribute = "registration", value = Sys.Date(),
  timezone = 0L, ...)

list_property_types(token, with_relations = FALSE, ...)

Arguments

token	Login token as created by login_openbis().
criteria	A single SearchCriteria object.
target_object	The object type the search is targeted at, i.e. DataSets, Experiments, etc.
fetch_options	If samples are searched for, additional fetch options can be specified.
...	For search_openbis() passed to make_request(), for search_criteria() a set of match clause objects, and for match clause constructors, the comparison mode can be passed as mode argument, which may be eq (==), lte (<=) or gte (>=).
operator	How to combine search clauses, either all or any have to be fulfilled.
sub_criteria	Optionally, one or several SearchSubCriteria objects can be used to create a SearchCriteria object.
type	The entity type, a SearchSubCriteria is applied to.
property_code	Code identifying a property to be used for the comparison.
value	The value used in the comparison.
attribute	Name of the attribute to be used for the comparison.
timezone	A string identifying the timezone of the specified date, examples include "+1", "-5", "0", etc.
with_relations	Logical switch indicating whether relations should be returned as well.

Details

Searching openBIS can be done by creating a SearchCriteria object and passing that to search_openbis(), alongside specifying what type of object is being searched for. In case of Samples being searched for, a further argument, fetch_options, can be specified for controlling the search, which can contain one or more of the strings

• ancestors: Ask for all ancestors.

• basic: Samples will have only basic attributes (id, code, type, space code, experiment identifier, registrator, registration date, modification date) but no properties.

• children: Samples contain also their children samples.

• contained: Ask for contained samples.

• descendants: Ask for all descendants.

• metaprojects: Ask for metaprojects this sample belongs to.

• parents: Samples contain also their parent samples.

• properties: Samples contain basic attributes and all properties.

A SearchCriteria object can be instantiated using the constructor search_criteria(), which takes one or several match clause objects, a search operator specifying whether to match all or any clauses, and optionally one or several SearchSubCriteria objects. SearchSubCriteria objects in turn can be created with search_sub_criteria(), which takes a single SearchCriteria object alongside a string specifying the entities, the sub criterion is applied to. Possibilities are

• data_set_container

• data_set_parent

• data_set_child

• experiment

• sample

• sample_container

• sample_child

• sample_parent

SearchCriteria objects, used for searching openBIS, contain one or several match clauses. A match clause, broadly speaking, consists of a desired value, a field to which this value is compared to and a comparison operator (e.g. equality). Match clauses can be constructed using any of attribute_clause(), time_attribute_clause(), property_clause(), any_property_clause(), and any_field_clause(). Attribute match clauses have a fixed set of attributes against which the match is performed:

• time attribute match clauses

  • registration_date

  • modification_date

• attribute match clauses

  • code

  • type

  • perm_id

  • space

  • project

  • project_perm_id

  • metaproject

  • registrator_user_id

  • registrator_first_name

  • registrator_last_name

  • registrator_email

  • modifier_user_id

  • modifier_first_name

  • modifier_last_name

  • modifier_email

In order to determine the possible values that can be supplied to property_clause() as property_codes, list_property_types() can be called. This function returns all property types available throughout the queried openBIS instance. As objects of several types (ControlledVocabularyPropertyType and PropertyType) are returned as property types by the API, the resulting object is a list with each entry corresponding to a type and holding a set of objects of the respective type.

The comparison operator (default is equality) can be any of the following

• equals

• less_than_or_equal, with alias lte

• greater_than_or_equal, with alias gte

All of the option matching is not case-sensitive and is performed with base::match.arg() and therefore options may be abbreviated (e.g. eq instead of equals).

Value

Depending on the number of resulting objects, either a json_class (single object) or a json_vec (multiple objects), is returned. The object specific sub-class for objects returned by search_openbis() depends on the target object type specified by the target_object argument. The remaining functions are used for constructing search queries and instantiate the required objects: search_criteria() returns a SearchCriteria and search_sub_criteria() a SearchSubCriteria object, while property_clause() returns a PropertyMatchClause, any_property_clause() an AnyPropertyMatchClause, any_field_clause() an AnyFieldMatchClause, attribute_clause() an AttributeMatchClause and time_attribute_clause() a TimeAttributeMatchClause object. Finally, list_property_types() returns a list with two slots, one holding a json_vec of sub-type ControlledVocabularyPropertyType and the other holding a json_vec of sub-type PropertyType.

openBIS

• \Sexpr[results=rd]{infx::docs_link("gis", "searchForDataSets")}
• \Sexpr[results=rd]{infx::docs_link("gis", "searchForExperiments")}
• \Sexpr[results=rd]{infx::docs_link("gis", "searchForMaterials")}
• \Sexpr[results=rd]{infx::docs_link("gis", "searchForSamples")}

Examples

  tok <- login_openbis()
  
  # search for an experiment, e.g. ADENO-AU-K1
  exp <- search_openbis(tok,
                        search_criteria(
                          property_clause("pathogen", "Adenovirus"),
                          property_clause("library", "Ambion"),
                          property_clause("geneset", "Kinome"),
                          property_clause("replicate", 1L)
                        ),
                        target_object = "experiment")

  # the same can be achieved using the code attribute
  identical(exp,
            search_openbis(tok,
                           search_criteria(
                             attribute_clause(value = "ADENO-AU-K1")
                           ),
                           target_object = "experiment"))

  # or using the perm_id attribute
  identical(exp,
            search_openbis(tok,
                           search_criteria(
                             attribute_clause("perm_id",
                                              "20111223100933426-318017")
                           ),
                           target_object = "experiment"))

  # a search with no matches returns an empty list
  search_openbis(tok,
                 search_criteria(attribute_clause(value = "foo_bar")),
                 target_object = "experiment")

  # search using sub-criteria: all plate samples of experiment ADENO-DU-K1
  sub <- search_sub_criteria(search_criteria(
                               attribute_clause(value = "ADENO-DU-K1")
                             ),
                             type = "experiment")
  all <- search_openbis(
    tok,
    search_criteria(
      attribute_clause("type", "PLATE"),
      sub_criteria = sub
    ),
    target_object = "sample"
  )
  length(as_json_vec(all))

  # now only include ADENO-DU-K1 plate samples registered after Feb 1st 2013
  some <- search_openbis(
    tok,
    search_criteria(
      attribute_clause("type", "PLATE"),
      time_attribute_clause(value = as.Date("2013-02-01"), mode = "gte"),
      sub_criteria = sub
    ),
    target_object = "sample"
  )
  length(as_json_vec(some))

  logout_openbis(tok)

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