An R interface to the Ontology Lookup Service

nonto <- length(ol <- Ontologies())



r Biocpkg("rols") is a Bioconductor package and should hence be installed using the dedicated functionality

## try http:// if https:// URLs are not supported
if (!requireNamespace("BiocManager", quietly=TRUE))

Getting help

To get help, either post your question on the Bioconductor support site or open an issue on the r Biocpkg("rols") github page.

The resource

The Ontology Lookup Service (OLS) [1, 2] is originally spin-off of the PRoteomics IDEntifications database (PRIDE) service, located at the EBI, and is now developed and maintained by the Samples, Phenotypes and Ontologies team at EMBL-EBI.

The package

The OLS provides a REST interface to hundreds of ontologies from a single location with a unified output format. The r Biocpkg("rols") package make this possible from within R. Do do so, it relies on the r CRANpkg("httr") package to query the REST interface, and access and retrieve data.

There are r nonto ontologies available in the OLS, listed in the table below. Their name is to be use to defined which ontology to query.

datatable(as(ol, "data.frame"))

A Brief rols overview

The r Biocpkg('rols') package is build around a few classes that enable to query the OLS and retrieve, store and manipulate data. Each of these classes are described in more details in their respective manual pages. We start by loading the package.



The Ontology and Ontologies classes can store information about single of multiple ontologies. The latter can be easily subset using [ and [[, as one would for lists.

ol <- Ontologies()

It is also possible to initialise a single ontology

go <- Ontology("go")


Single ontology terms are stored in Term objects. When more terms need to be manipulated, they are stored as Terms objects. It is easy to obtain all terms of an ontology of interest, and the resulting Terms object can be subset using [ and [[, as one would for lists.

gotrms <- terms(go) ## or terms("go")

It is also possible to initialise a single term

trm <- term(go, "GO:0090575")

It is then possible to extract the ancestors, descendants, parents and children terms. Each of these functions return a Terms object


Similarly, the partOf and derivesFrom functions return, for an input term, the terms it is a part of and derived from.

Finally, a single term or terms object can be coerced to a data.frame using as(x, "data.frame").


Properties (relationships) of single or multiple terms or complete ontologies can be queries with the properties method, as briefly illustrated below.

trm <- term("uberon", "UBERON:0002107")
p <- properties(trm)

Use case

alltgns <- OlsSearch(q = "trans-golgi network")

A researcher might be interested in the trans-Golgi network. Searching the OLS is assured by the OlsSearch and olsSearch classes/functions. The first step is to defined the search query with OlsSearch, as shown below. This creates an search object of class OlsSearch that stores the query and its parameters. In records the number of requested results (default is 20) and the total number of possible results (there are r alltgns@numFound results across all ontologies, in this case). At this stage, the results have not yet been downloaded, as shown by the r nrow(alltgns@response) responses.

OlsSearch(q = "trans-golgi network")

r alltgns@numFound results are probably too many to be relevant. Below we show how to perform an exact search by setting exact = TRUE, and limiting the search the the GO ontology by specifying ontology = "GO", or doing both.

OlsSearch(q = "trans-golgi network", exact = TRUE)
OlsSearch(q = "trans-golgi network", ontology = "GO")
OlsSearch(q = "trans-golgi network", ontology = "GO", exact = TRUE)

One case set the rows argument to set the number of desired results.

OlsSearch(q = "trans-golgi network", ontology = "GO", rows = 200)

Alternatively, one can call the allRows function to request all results.

(tgnq <- OlsSearch(q = "trans-golgi network", ontology = "GO"))
(tgnq <- allRows(tgnq))
qry <- OlsSearch(q = "trans-golgi network", exact = TRUE)

Let's proceed with the exact search and retrieve the results. Even if we request the default 20 results, only the r qry@numFound relevant result will be retrieved. The olsSearch function updates the previously created object (called qry below) by adding the results to it.

qry <- OlsSearch(q = "trans-golgi network", exact = TRUE)
(qry <- olsSearch(qry))

We can now transform this search result object into a fully fledged Terms object or a data.frame.

(qtrms <- as(qry, "Terms"))
str(qdrf <- as(qry, "data.frame"))

In this case, we can see that we actually retrieve the same term used across different ontologies. In such cases, it might be useful to keep only non-redundant term instances. Here, this would have been equivalent to searching the r termOntology(unique(qtrms)) ontology

qtrms <- unique(qtrms)

Below, we execute the same query using the r Biocpkg("GO.db") package.


On-line vs. off-line data

It is possible to observe different results with r Biocpkg("rols") and r Biocpkg("GO.db"), as a result of the different ways they access the data. r Biocpkg("rols") or r Biocpkg("biomaRt") perform direct online queries, while r Biocpkg("GO.db") and other annotation packages use database snapshot that are updated every release.

Both approaches have advantages. While online queries allow to obtain the latest up-to-date information, such approaches rely on network availability and quality. If reproducibility is a major issue, the version of the database to be queried can easily be controlled with off-line approaches. In the case of r Biocpkg("rols"), although the load date of a specific ontology can be queried with olsVersion, it is not possible to query a specific version of an ontology.

Changes in version 2.0

r Biocpkg("rols") 2.0 has substantially changed. While the table below shows some correspondence between the old and new interface, this is not always the case. The new interface relies on the Ontology/Ontologies, Term/Terms and OlsSearch classes, that need to be instantiated and can then be queried, as described above.

| version < 1.99 | version >= 1.99 | |--------------------|-----------------| | ontologyLoadDate | olsLoaded and olsUpdated | | ontologyNames | Ontologies | | olsVersion | olsVersion | | allIds | terms | | isIdObsolete | isObsolete | | rootId | olsRoot | | olsQuery | OlsSearch and olsSearch |

Not all functionality is currently available. If there is anything that you need but not available in the new version, please contact the maintained by opening an issue on the package development site.


The CVParam class is used to handle controlled vocabulary. It can be used for user-defined parameters

CVParam(name = "A user param", value = "the value")

or official controlled vocabulary (which triggers a query to the OLS service)

CVParam(label = "MS", accession = "MS:1000073")
CVParam(label = "MS", name ="electrospray ionization")
CVParam(label = "MS", name ="ESI") ## using a synonym

See ?CVParam for more details and examples.

Session information

print(sessionInfo(), locale = FALSE)

Try the rols package in your browser

Any scripts or data that you put into this service are public.

rols documentation built on April 1, 2021, 6:01 p.m.