get_ontologies() queries the OLS for information on
all available ontologies.
get_ontology() retrieves
information on a single ontology.
get_roots() and get_terms() return all 'roots' and
terms in an ontology.
get_term() returns a tibble with detailed
information about a single term.
get_parents(), get_ancestors(), get_children(),
and get_descendants() retrieve parents, ancestors, children
and descedants of a single term.
Usage
get_ontologies()
get_ontology(ontology)
get_roots(ontology)
get_terms(ontology, all_ontologies = FALSE)
get_term(ontology, id, form = c("id", "obo_id", "short_form", "iri"))
get_parents(ontology, id, all_ontologies = FALSE)
get_ancestors(ontology, id, all_ontologies = FALSE)
get_children(ontology, id, all_ontologies = FALSE)
get_descendants(ontology, id, all_ontologies = FALSE)Arguments
- ontology
character(1)
id(fromget_ontologies()) of the ontology of interst.- all_ontologies
logical(1) when
FALSE(default), only terms, parents, etc., defined inontologyare returned. WhenTRUE, terms from all ontologies are associated with terms inontologyare returned.- id
character(1) the term identifier, usually 'obo_id' (e.g., "CL:0002494") but for
get_term()as specified byform.- form
character(1) the form of the identifier, as describe in Details.
Value
The get_*() functions return tibbles summarizing information
retrieved from the OLS. The meaning of individual columns is as in
the service; columns are not renamed, but have been re-ordered to
prioritize useful information.
Details
The functions documented on this page provide a programmatic interface to the EMBL-EBI Ontology Lookup Service at https://www.ebi.ac.uk/ols4/. The API is described at https://www.ebi.ac.uk/ols4/help
The functions use an on-disk cache of results retrieved from the internet to speed interactive analysis. Generally, initial queries are 'slow', but subsequent identical queries are very fast. Details of the cache, some edge cases where the cache can get in the way of current results, and strategies for cache management are summarized in the 'Cache Management' section of the vignette.
In an attempt to simplify navigation of results, values returned
from API calls are presented as a tibble with invariant columns
removed.
Data returned by the OLS is often hierarchical, resulting in list
columns in the tibble. In some cases (e.g., get_ontologies()) the
list columns have been un-nested (using tidyr::unnest_wider()) to
provide users with relevant information. Downstream processing
steps may also find it beneficial to understand 'tidy' approaches
to working with hierarchical data in tibbles, as outlined in
chapter 23 of 'R For Data Science' (2e),
https://r4ds.hadley.nz/rectangling. This is illustrated in
the "Hierarchical Data" section of the vignette.
For get_term(), the identifier id can be one of three
forms. The id and obo_id forms are synonyms and follow the
pattern ontology abbrevation, :, and term id, e.g., "CL:0002494".
The short_form is typically like obo_id but with : replaced
by _. An iri is the purl resource locator, typically
"http://purl.obolibrary.org/...".
When no relatives are found, get_parents() etc. return a tibble
with 0 rows (and sometimes 0 columns).
Examples
onto <- get_ontologies()
onto
#> # A tibble: 265 × 31
#> id title description version numberOfTerms numberOfProperties
#> <chr> <chr> <chr> <chr> <int> <int>
#> 1 ado Alzheimer's D… Alzheimer'… 2.0.1 1963 186
#> 2 afpo African Popul… AfPO is an… 2024-0… 473 62
#> 3 agro Agronomy Onto… AgrO is an… NA 4162 293
#> 4 aism Ontology for … The ontolo… 2024-0… 8540 567
#> 5 amphx Amphioxus Dev… An ontolog… NA 403 10
#> 6 apo Ascomycete Ph… A structur… 2024-1… 619 27
#> 7 apollo_sv Apollo Struct… An OWL2 on… 2024-1… 1715 396
#> 8 aro Antibiotic Re… Antibiotic… NA 8526 25
#> 9 bco Biological Co… An ontolog… 2021-1… 253 472
#> 10 bfo Basic Formal … The upper … NA 35 22
#> # ℹ 255 more rows
#> # ℹ 25 more variables: numberOfIndividuals <int>, languages <list>,
#> # loaded <chr>, updated <chr>, versionIri <chr>, namespace <chr>,
#> # preferredPrefix <chr>, homepage <chr>, mailingList <chr>, tracker <chr>,
#> # logo <lgl>, creators <lgl>, annotations <lgl>, fileLocation <chr>,
#> # oboSlims <lgl>, labelProperty <chr>, definitionProperties <list>,
#> # synonymProperties <list>, hierarchicalProperties <list>, baseUris <list>, …
get_ontology("cl") |>
glimpse()
#> Rows: 1
#> Columns: 16
#> $ languages <list> "en"
#> $ lang <chr> "en"
#> $ ontologyId <chr> "cl"
#> $ loaded <chr> "2025-01-20T23:16:05.759253163"
#> $ updated <chr> "2025-01-20T23:16:05.759253163"
#> $ status <chr> "LOADED"
#> $ message <chr> ""
#> $ version <chr> "2025-01-07"
#> $ fileHash <lgl> NA
#> $ loadAttempts <int> 0
#> $ numberOfTerms <int> 16637
#> $ numberOfProperties <int> 394
#> $ numberOfIndividuals <int> 18
#> $ config <list> "cl"
#> $ baseUris <list> <NULL>
#> $ `_links` <list> ["https://www.ebi.ac.uk/ols4/api/ontologies/cl?la…
get_roots("cl")
#> # A tibble: 138 × 13
#> obo_id label description iri synonyms annotation has_children short_form
#> <chr> <chr> <chr> <chr> <list> <list> <lgl> <chr>
#> 1 GO:001… regu… Any proces… http… <NULL> <named list> TRUE GO_0010817
#> 2 GO:001… resp… Any proces… http… <list> <named list> TRUE GO_0019236
#> 3 GO:005… regu… Any proces… http… <NULL> <named list> TRUE GO_0050803
#> 4 GO:005… regu… Any proces… http… <NULL> <named list> TRUE GO_0050878
#> 5 GO:009… cell… Any proces… http… <NULL> <named list> TRUE GO_0097237
#> 6 IAO:00… info… NA http… <NULL> <NULL> TRUE IAO_00000…
#> 7 NCBITa… root NA http… <list> <named list> TRUE NCBITaxon…
#> 8 SO:000… SO_0… NA http… <NULL> <NULL> TRUE SO_0000704
#> 9 SO:000… sequ… NA http… <NULL> <NULL> TRUE SO_0001260
#> 10 UBERON… proc… An occurre… http… <NULL> <named list> TRUE UBERON_00…
#> # ℹ 128 more rows
#> # ℹ 5 more variables: in_subset <list>, obo_definition_citation <list>,
#> # obo_xref <list>, obo_synonym <list>, `_links` <list>
terms <- get_terms("cl")
#> Querying OLS ■■ 3% | ETA: 36s
#> Querying OLS ■■■ 6% | ETA: 34s
#> Querying OLS ■■■■■ 15% | ETA: 27s
#> Querying OLS ■■■■■■■■ 24% | ETA: 24s
#> Querying OLS ■■■■■■■■■■■■ 35% | ETA: 20s
#> Querying OLS ■■■■■■■■■■■■■ 41% | ETA: 19s
#> Querying OLS ■■■■■■■■■■■■■■■ 47% | ETA: 19s
#> Querying OLS ■■■■■■■■■■■■■■■■■ 53% | ETA: 17s
#> Querying OLS ■■■■■■■■■■■■■■■■■■■■ 62% | ETA: 14s
#> Querying OLS ■■■■■■■■■■■■■■■■■■■■■■ 71% | ETA: 11s
#> Querying OLS ■■■■■■■■■■■■■■■■■■■■■■■■ 76% | ETA: 9s
#> Querying OLS ■■■■■■■■■■■■■■■■■■■■■■■■■■ 82% | ETA: 7s
#> Querying OLS ■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 91% | ETA: 3s
#> Querying OLS ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ 100% | ETA: 0s
terms
#> # A tibble: 2,861 × 13
#> label obo_id description iri synonyms annotation has_children short_form
#> <chr> <chr> <chr> <chr> <list> <list> <lgl> <chr>
#> 1 mesen… CL:40… Any mesenc… http… <list> <named list> FALSE CL_4040004
#> 2 mesen… CL:40… A mesenchy… http… <list> <named list> FALSE CL_4040005
#> 3 derma… CL:40… A chromato… http… <NULL> <named list> FALSE CL_4040006
#> 4 TAC3-… CL:40… A GABAergi… http… <list> <named list> FALSE CL_4042001
#> 5 TAC3-… CL:40… A nucleus … http… <list> <named list> FALSE CL_4042002
#> 6 borde… CL:40… A central … http… <list> <named list> TRUE CL_4042003
#> 7 choro… CL:40… A choroid … http… <list> <named list> FALSE CL_4042004
#> 8 strom… CL:40… A choroid … http… <list> <named list> FALSE CL_4042005
#> 9 dural… CL:40… A border a… http… <list> <named list> FALSE CL_4042006
#> 10 proto… CL:40… An astrocy… http… <NULL> <named list> FALSE CL_4042007
#> # ℹ 2,851 more rows
#> # ℹ 5 more variables: in_subset <list>, obo_definition_citation <list>,
#> # obo_xref <list>, obo_synonym <list>, `_links` <list>
CL0002494 <- get_term("cl", "CL:0002494")
CL0002494 |>
glimpse()
#> Rows: 1
#> Columns: 22
#> $ obo_id <chr> "CL:0002494"
#> $ label <chr> "cardiocyte"
#> $ description <chr> "A cell located in the heart, including both m…
#> $ iri <chr> "http://purl.obolibrary.org/obo/CL_0002494"
#> $ lang <chr> "en"
#> $ synonyms <list> ["heart cell"]
#> $ annotation <list> [["https://orcid.org/0000-0003-1980-3228"], ["…
#> $ ontology_name <chr> "cl"
#> $ ontology_prefix <chr> "CL"
#> $ ontology_iri <chr> "http://purl.obolibrary.org/obo/cl.owl"
#> $ is_obsolete <lgl> FALSE
#> $ term_replaced_by <lgl> NA
#> $ is_defining_ontology <lgl> TRUE
#> $ has_children <lgl> TRUE
#> $ is_root <lgl> FALSE
#> $ short_form <chr> "CL_0002494"
#> $ in_subset <list> ["human_subset", "mouse_subset"]
#> $ obo_definition_citation <list> [["A cell located in the heart, including both…
#> $ obo_xref <list> [["BTO", "0001539", <NULL>, "http://purl.oboli…
#> $ obo_synonym <lgl> NA
#> $ is_preferred_root <lgl> FALSE
#> $ `_links` <list> [["https://www.ebi.ac.uk/ols4/api/ontologies/c…
get_parents("cl", "CL:0002350")
#> # A tibble: 1 × 14
#> obo_id label description iri synonyms annotation has_children is_root
#> <chr> <chr> <chr> <chr> <lgl> <list> <lgl> <lgl>
#> 1 CL:0010008 cardi… "Any endot… http… NA <named list> TRUE FALSE
#> # ℹ 6 more variables: short_form <chr>, in_subset <list>,
#> # obo_definition_citation <list>, obo_xref <list>, obo_synonym <lgl>,
#> # `_links` <list>
get_ancestors("cl", "CL:0002494")
#> # A tibble: 2 × 14
#> obo_id label description iri synonyms annotation has_children is_root
#> <chr> <chr> <chr> <chr> <list> <list> <lgl> <lgl>
#> 1 CL:0000255 eukar… Any cell t… http… <NULL> <named list> TRUE FALSE
#> 2 CL:0000000 cell A material… http… <NULL> <named list> TRUE FALSE
#> # ℹ 6 more variables: short_form <chr>, in_subset <list>,
#> # obo_definition_citation <list>, obo_xref <list>, obo_synonym <list>,
#> # `_links` <list>
get_ancestors("cl", "CL:0002350")
#> # A tibble: 7 × 14
#> obo_id label description iri synonyms annotation has_children is_root
#> <chr> <chr> <chr> <chr> <list> <list> <lgl> <lgl>
#> 1 CL:0010008 cardi… "Any endot… http… <NULL> <named list> TRUE FALSE
#> 2 CL:0000115 endot… "An endoth… http… <list> <named list> TRUE FALSE
#> 3 CL:0000213 linin… "A cell wi… http… <list> <named list> TRUE FALSE
#> 4 CL:0000215 barri… "A cell wh… http… <NULL> <named list> TRUE FALSE
#> 5 CL:0000000 cell "A materia… http… <NULL> <named list> TRUE FALSE
#> 6 CL:0000255 eukar… "Any cell … http… <NULL> <named list> TRUE FALSE
#> 7 CL:0002494 cardi… "A cell lo… http… <list> <named list> TRUE FALSE
#> # ℹ 6 more variables: short_form <chr>, in_subset <list>,
#> # obo_definition_citation <list>, obo_xref <list>, obo_synonym <list>,
#> # `_links` <list>
get_children("cl", "CL:0002494")
#> # A tibble: 12 × 14
#> obo_id label description iri synonyms annotation has_children is_root
#> <chr> <chr> <chr> <chr> <list> <list> <lgl> <lgl>
#> 1 CL:2000022 card… "Any nativ… http… <NULL> <named list> TRUE FALSE
#> 2 CL:1000309 epic… "An adipoc… http… <list> <named list> TRUE FALSE
#> 3 CL:0011019 meso… "A mesothe… http… <NULL> <named list> FALSE FALSE
#> 4 CL:1000147 card… "A cell th… http… <list> <named list> TRUE FALSE
#> 5 CL:0010020 card… "Any glial… http… <NULL> <NULL> FALSE FALSE
#> 6 CL:0010008 card… "Any endot… http… <NULL> <named list> TRUE FALSE
#> 7 CL:0010007 His-… "Any cell … http… <NULL> <NULL> TRUE FALSE
#> 8 CL:0002548 fibr… "A fibrobl… http… <list> <named list> TRUE FALSE
#> 9 CL:0002592 smoo… "A smooth … http… <NULL> <named list> FALSE FALSE
#> 10 CL:0000746 card… "Cardiac m… http… <list> <named list> TRUE FALSE
#> 11 CL:0000513 card… "A precurs… http… <list> <named list> FALSE FALSE
#> 12 CL:0008022 endo… "A mesench… http… <NULL> <NULL> FALSE FALSE
#> # ℹ 6 more variables: short_form <chr>, in_subset <list>,
#> # obo_definition_citation <list>, obo_xref <list>, obo_synonym <list>,
#> # `_links` <list>
get_children("cl", "CL:0002350") # no children, 0 x 0 tibble
#> # A tibble: 0 × 0
get_descendants("cl", "CL:0002494")
#> # A tibble: 68 × 14
#> obo_id label description iri synonyms annotation has_children is_root
#> <chr> <chr> <chr> <chr> <list> <list> <lgl> <lgl>
#> 1 CL:0008022 endo… "A mesench… http… <NULL> <NULL> FALSE FALSE
#> 2 CL:0000513 card… "A precurs… http… <list> <named list> FALSE FALSE
#> 3 CL:0000746 card… "Cardiac m… http… <list> <named list> TRUE FALSE
#> 4 CL:0000193 card… "A striate… http… <NULL> <NULL> FALSE FALSE
#> 5 CL:0002086 spec… "A cardiac… http… <NULL> <named list> TRUE FALSE
#> 6 CL:0002068 Purk… "Specializ… http… <list> <named list> TRUE FALSE
#> 7 CL:1000376 Purk… "A Purkinj… http… <NULL> <named list> FALSE FALSE
#> 8 CL:1000479 Purk… "A Purkinj… http… <NULL> <named list> FALSE FALSE
#> 9 CL:1000483 Purk… "A Purkinj… http… <NULL> <named list> FALSE FALSE
#> 10 CL:1000484 Purk… "A Purkinj… http… <NULL> <named list> FALSE FALSE
#> # ℹ 58 more rows
#> # ℹ 6 more variables: short_form <chr>, in_subset <list>,
#> # obo_definition_citation <list>, obo_xref <list>, obo_synonym <list>,
#> # `_links` <list>
get_descendants("cl", "CL:0002350") # no descedants, 0 x 0 tibble
#> # A tibble: 0 × 0