search_openbis.Rd
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()
.
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, ...)
token | Login token as created by |
---|---|
criteria | A single |
target_object | The object type the search is targeted at, i.e.
|
fetch_options | If samples are searched for, additional fetch options can be specified. |
... | For |
operator | How to combine search clauses, either |
sub_criteria | Optionally, one or several |
type | The entity type, a |
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. |
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
.
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 Sample
s 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_code
s, 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
).
# \donttest{ 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"))#> [1] TRUE# or using the perm_id attribute identical(exp, search_openbis(tok, search_criteria( attribute_clause("perm_id", "20111223100933426-318017") ), target_object = "experiment"))#> [1] TRUE# a search with no matches returns an empty list search_openbis(tok, search_criteria(attribute_clause(value = "foo_bar")), target_object = "experiment")#> list()# 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))#> [1] 14# 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))#> [1] 1