Searching the Ontology Lookup Service is done first by creating an object `OlsSearch` using the `OlsSearch()` constructor. Query responses are then retrieved with the `olsSearch()` function.
Note that OLS4 omits empty fields from its search responses. The columns of the `data.frame` produced by `as(object, "data.frame")` therefore reflect the fields that are populated in that particular response, and two queries against the same ontology can return different sets of columns. Match or combine results on a column that is always present, such as `obo_id` or `iri`, rather than assuming a fixed set of columns.
OlsSearch(
q,
ontology = "",
type = "",
slim = "",
fieldList = "",
queryFields = "",
exact = FALSE,
groupField = FALSE,
obsoletes = FALSE,
local = TRUE,
childrenOf = "",
rows = 20L,
start = 0L
)
olsSearch(object, all = FALSE)
# S4 method for class 'OlsSearch'
show(object)
olsRows(object)
olsRows(object) <- value
allRows(object)`characher(1)` containing the search query.
`character()` defining the ontology to be queried. Default is the empty character, to search all ontologies.
`character()` restricting the search to an entity type, one of `"class"`, `"property"`, `"individual"` or `"ontology"`.
`character()` restricts the search to an particular set of slims by name.
`character()` specifcies the fields to return. The defaults are iri, label, short_form, obo_id, ontology_name, ontology_prefix, description and type. Default is `""` for all fields.
`character()` specifcies the fields to query, the defaults are label, synonym, description, short_form, obo_id, annotations, logical_description, iri. Default is `""` for all fields.
`logical(1)` defining if exact matches should be returned. Default is `FALSE`.
`logical(1)`, set to `TRUE` to group results by unique id (IRI).
`logical(1)` defining whether obsolete terms should be queried. Default is `FALSE`.
`character(1)`, default is `FALSE`. Set to `TRUE` to only return terms that are in a defining ontology e.g. only return matches to gene ontology terms in the gene ontology, and exclude ontologies where those terms are also referenced.
`character()` to restrict a search to children of a given term. Supply a list of IRI for the terms that you want to search under.
`integer(1)` defining the number of query returns. Default is 20L. OLS3 capped this at 1000; OLS4 lifts that restriction and returns as many rows as are requested, so use [allRows()] with care on queries with many matches. To page through results, set `start`. See example below.
`integer(1)` defining the results page. number. Default is 0L.
`OlsSeach` result object.
`logical(1)` Should all rows be retrieved. Default is `FALSE`. Can also be set in the queary object directly with `allRows()`.
replacement value
- OLS3 API (the OLS4 API should function identically to the OLS3): <http://www.ebi.ac.uk/ols4/ols3help>
- REST API for OLS: <https://www.ebi.ac.uk/ols4/swagger-ui/index.html>
## Many results across all ontologies
OlsSearch(q = "trans-golgi")
#> Object of class 'OlsSearch':
#> query: trans-golgi
#> requested: 20 (out of 1610)
#> response(s): 0
## Exact matches
OlsSearch(q = "trans-golgi", exact = TRUE)
#> Object of class 'OlsSearch':
#> query: trans-golgi
#> requested: 20 (out of 311)
#> response(s): 0
## Exact match in the gene ontology (go or GO) only
OlsSearch(q = "trans-golgi", exact = TRUE, ontology = "go")
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: trans-golgi
#> requested: 20 (out of 39)
#> response(s): 0
OlsSearch(q = "trans-golgi", exact = TRUE, ontology = "GO")
#> Object of class 'OlsSearch':
#> ontolgy: GO
#> query: trans-golgi
#> requested: 20 (out of 39)
#> response(s): 0
## Exact match in the GO and Uberon
OlsSearch(q = "trans-golgi", exact = TRUE,
ontology = c("GO", "Uberon"))
#> Object of class 'OlsSearch':
#> ontolgies: GO, Uberon
#> query: trans-golgi
#> requested: 20 (out of 44)
#> response(s): 0
## Testing different ESI queries
OlsSearch(q = "electrospray", ontology = "MS")
#> Object of class 'OlsSearch':
#> ontolgy: MS
#> query: electrospray
#> requested: 20 (out of 10)
#> response(s): 0
OlsSearch(q = "ionization", ontology = "MS")
#> Object of class 'OlsSearch':
#> ontolgy: MS
#> query: ionization
#> requested: 20 (out of 68)
#> response(s): 0
OlsSearch(q = "electrospray ionization", ontology = "MS")
#> Object of class 'OlsSearch':
#> ontolgy: MS
#> query: electrospray ionization
#> requested: 20 (out of 6)
#> response(s): 0
OlsSearch(q = "electrospray ionization", ontology = "MS", exact=TRUE)
#> Object of class 'OlsSearch':
#> ontolgy: MS
#> query: electrospray ionization
#> requested: 20 (out of 6)
#> response(s): 0
## Request 5 results instead of 20 (default)
OlsSearch(q = "plasma,membrane", ontology = "go", rows = 5)
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: plasma,membrane
#> requested: 5 (out of 817)
#> response(s): 0
## Same as above
OlsSearch(q = "plasma membrane", ontology = "go", rows = 5)
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: plasma membrane
#> requested: 5 (out of 817)
#> response(s): 0
## or, once the object was created
(res <- OlsSearch(q = "plasma,membrane", ontology = "go"))
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: plasma,membrane
#> requested: 20 (out of 817)
#> response(s): 0
olsRows(res) <- 5
res
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: plasma,membrane
#> requested: 5 (out of 817)
#> response(s): 0
## all results
res <- allRows(res)
res
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: plasma,membrane
#> requested: 817 (out of 817)
#> response(s): 0
res <- OlsSearch(q = "trans-golgi", ontology = "go", rows = 5)
res
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: trans-golgi
#> requested: 5 (out of 134)
#> response(s): 0
res <- olsSearch(res)
res
#> Object of class 'OlsSearch':
#> ontolgy: go
#> query: trans-golgi
#> requested: 5 (out of 134)
#> response(s): 5
as(res, "data.frame")
#> iri ontology_name ontology_prefix
#> 1 http://purl.obolibrary.org/obo/GO_1902953 go GO
#> 2 http://purl.obolibrary.org/obo/GO_0006888 go GO
#> 3 http://purl.obolibrary.org/obo/GO_0030134 go GO
#> 4 http://purl.obolibrary.org/obo/GO_0006890 go GO
#> 5 http://purl.obolibrary.org/obo/GO_2000156 go GO
#> short_form description narrow_synonyms
#> 1 GO_1902953 Any proc.... activati....
#> 2 GO_0006888 The dire....
#> 3 GO_0030134 A vesicl....
#> 4 GO_0006890 The dire....
#> 5 GO_2000156 Any proc....
#> label
#> 1 positive regulation of ER to Golgi vesicle-mediated transport
#> 2 endoplasmic reticulum to Golgi vesicle-mediated transport
#> 3 COPII-coated ER to Golgi transport vesicle
#> 4 retrograde vesicle-mediated transport, Golgi to endoplasmic reticulum
#> 5 regulation of retrograde vesicle-mediated transport, Golgi to ER
#> obo_id type exact_synonyms related_synonyms
#> 1 GO:1902953 class positive....
#> 2 GO:0006888 class ER to Go....
#> 3 GO:0030134 class COPII-as.... COPII ve....
#> 4 GO:0006890 class cis-Golg....
#> 5 GO:2000156 class regulati.... regulati....
trms <- as(res, "olsTerms")
trms
#> Object of class 'olsTerms' with 5 entries
#> From the GO ontology
#> GO:1902953, GO:0006888 ... GO:0006890, GO:2000156
termPrefix(trms)
#> GO:1902953 GO:0006888 GO:0030134 GO:0006890 GO:2000156
#> "GO" "GO" "GO" "GO" "GO"
termId(trms)
#> GO:1902953 GO:0006888 GO:0030134 GO:0006890 GO:2000156
#> "GO:1902953" "GO:0006888" "GO:0030134" "GO:0006890" "GO:2000156"
## Setting rows and start parameters
tg1 <- OlsSearch(q = "trans-golgi", rows = 5, start = 0) |>
olsSearch() |>
as("data.frame")
tg2 <- OlsSearch(q = "trans-golgi", rows = 5, start = 5) |>
olsSearch() |>
as("data.frame")
tg3 <- OlsSearch(q = "trans-golgi", rows = 10, start = 0) |>
olsSearch() |>
as("data.frame")
## The terms returned by two consecutive small queries are
## identical to those returned by the larger query. Only the term
## identifiers are compared here: OLS4 omits empty fields from its
## responses, so the columns of the individual data frames depend
## on which fields happen to be populated in that batch, and
## `rbind()` may fail with "numbers of columns of arguments do not
## match".
identical(c(tg1$obo_id, tg2$obo_id), tg3$obo_id)
#> [1] TRUE