Ancestor and Descendant Term Graphs — get_ancestors

get_ancestors_graph() and get_descendants_graph() returns a graph representation of all ancestors or descendants of term identifiers of interest.

olsr_graph() constructs an olsr_graph from R objects.

olsr_graph_edges(), olsr_graph_nodes(), olsr_graph_ontology(), and olsr_graph_ids() extract elements of an olsr_graph.

olsr_graph_as_visNetwork() converts an olsr_graph to the format used by the visNetwork package for interactive visualization.

olsr_graph_as_igraph() and igraph_as_olsr_graph() transform olsr_graph objects to and from igraph objects.

Usage

get_ancestors_graph(ontology, ids, terms = NULL)

get_descendants_graph(ontology, ids, terms = NULL)

olsr_graph(relation, ontology, ids, edges, nodes)

olsr_graph_ontology(x)

olsr_graph_ids(x)

olsr_graph_nodes(x)

olsr_graph_edges(x)

olsr_graph_as_visNetwork(graph)

olsr_graph_as_igraph(graph)

igraph_as_olsr_graph(igraph)

# S3 method for olsr_graph
print(x, ...)

Arguments

ontology: character(1) name of ontology; must be present in the id column of `get_ontologies().
ids: character() of identifiers used to construct the graph.
terms: a tibble from, e.g., terms(), containing a column obo_id and additional columns to annotated nodes of the returned graph.
relation: character(1) type of graph, either "ancestors" or "descendants".
edges: tibble() with columns from and to, containing OBO identifiers at the start and end of each node in the graph.
nodes: tibble() with column obo_id, one for each node in the graph. Arbitrary additional columns are allowed.
x: for print.olsr_graph(), an object of class olsr_graph.
graph: an olsr_graph object.
igraph: an object of class igraph, from the igraph package.
...: for print.olsr_graph(), ignored.

Value

get_ancestors_graph() and get_descendants_graph() return an olsr_graph object recording the ontology, ids, edges, and nodes implied by the ancestor or descendant graph. Nodes are annotated with information from terms, if available.

olsr_graph() returns an object of class olsr_graph.

olsr_graph_as_visNetwork() returns an object created by a call to visNetwork::visNetwork(). This object can be used for simple interactive visualization directly, or as input to subsequent visNetwork formatting.

olsr_graph_as_igraph() returns an igraph object; igraph_as_olsr_graph() returns an olsr_graph object.

Details

Ancestor and descendant graphs navigate from the ids of interest via parents or children, recursively, until either the ontology root or only leaf nodes remain. For descendant graphs, this can involve hundreds or even thousands of calls to the OLS API, and can be time consuming (e.g., a minute or so) on first invocation. API calls are memoized, so fast on subsequent invocations.

olsr_graph() provides a simple representation to coordinate information for ancestor and descendant graphs. The main purpose of this class is as a 'way-point' for further analysis of the graph, e.g., using the igraph package https://CRAN.R-project.org/package=igraph for analytic work or the visNetwork https://CRAN.R-project.org/package=visNetwork for interactive visualization.

olsr_graph_as_visNetwork() renames the obo_id column of nodes to id, consistent with visNetwork. The id column is copied to title, so that it is used in mouse-over text; a label (the short description of each term in the tibble returned by terms()) is used to label the node on the graph. Add a column color to nodes to color individual nodes

olsr_graph_as_igraph() includes information on relation (ancestors or descendants), ontology, and ids in the igraph object as a graph-level attribute available with graph_attr(ig, "olsr_graph"). Workflows that use olsr_graph_as_igraph(), perform igraph manipulations, and then use igraph_as_olsr_graph() generally preserve this information.

Examples

cl <- get_terms("cl")
b_cell <- "CL:0000236"
anc <- get_ancestors_graph("cl", b_cell, cl)     # 11 nodes
#> 0 relatives visited; 1 in queue
#> 10 relatives visited; 3 in queue
#> 13 relatives visited; 2 in queue
#> 20 relatives visited; 0 in queue
anc
#> class: ancestors_graph (21 nodes x 24 edges)
#> ontology: cl
#> ids (1): CL:0000236

desc <- get_descendants_graph("cl", b_cell, cl)  # 64 nodes
#> 0 relatives visited; 1 in queue
#> 21 relatives visited; 13 in queue
#> 27 relatives visited; 10 in queue
#> 38 relatives visited; 7 in queue
#> 53 relatives visited; 10 in queue
#> 63 relatives visited; 6 in queue
desc
#> class: descendants_graph (64 nodes x 66 edges)
#> ontology: cl
#> ids (1): CL:0000236

olsr_graph_ontology(anc)
#> [1] "cl"
olsr_graph_ids(anc)
#> [1] "CL:0000236"
olsr_graph_nodes(anc)
#> # A tibble: 21 × 13
#>    obo_id  label description iri   synonyms annotation   has_children short_form
#>    <chr>   <chr> <chr>       <chr> <list>   <list>       <lgl>        <chr>     
#>  1 CL:000… B ce… A lymphocy… http… <list>   <named list> TRUE         CL_0000236
#>  2 CL:000… lymp… A lymphocy… http… <NULL>   <named list> TRUE         CL_0000945
#>  3 CL:000… lymp… A lymphocy… http… <NULL>   <named list> TRUE         CL_0000542
#>  4 CL:000… mono… A leukocyt… http… <list>   <named list> TRUE         CL_0000842
#>  5 CL:000… leuk… An achroma… http… <list>   <named list> TRUE         CL_0000738
#>  6 CL:000… sing… A cell wit… http… <NULL>   <NULL>       TRUE         CL_0000226
#>  7 CL:000… nucl… A cell con… http… <NULL>   <named list> TRUE         CL_0002242
#>  8 CL:000… hema… A cell of … http… <list>   <named list> TRUE         CL_0000988
#>  9 CL:000… moti… A cell tha… http… <NULL>   <NULL>       TRUE         CL_0000219
#> 10 CL:000… NA    NA          NA    <NULL>   <NULL>       NA           NA        
#> # ℹ 11 more rows
#> # ℹ 5 more variables: in_subset <list>, obo_definition_citation <list>,
#> #   obo_xref <list>, obo_synonym <list>, `_links` <list>
olsr_graph_edges(anc)
#> # A tibble: 24 × 2
#>    from       to        
#>    <chr>      <chr>     
#>  1 CL:0000236 CL:0000945
#>  2 CL:0000945 CL:0000542
#>  3 CL:0000542 CL:0000842
#>  4 CL:0000842 CL:0000738
#>  5 CL:0000842 CL:0000226
#>  6 CL:0000738 CL:0002242
#>  7 CL:0000738 CL:0000988
#>  8 CL:0000738 CL:0000219
#>  9 CL:0000226 CL:0002242
#> 10 CL:0002242 CL:0000003
#> # ℹ 14 more rows

vis <- olsr_graph_as_visNetwork(anc)
if (interactive())   # visualize in RStudio  or browser
    vis

ig <- olsr_graph_as_igraph(anc)
ig
#> IGRAPH 0bea8ed DN-- 21 24 -- 
#> + attr: olsr_graph (g/x), name (v/c), label (v/c), description (v/c),
#> | iri (v/c), synonyms (v/x), annotation (v/x), has_children (v/l),
#> | short_form (v/c), in_subset (v/x), obo_definition_citation (v/x),
#> | obo_xref (v/x), obo_synonym (v/x), _links (v/x)
#> + edges from 0bea8ed (vertex names):
#>  [1] CL:0000236->CL:0000945 CL:0000945->CL:0000542 CL:0000542->CL:0000842
#>  [4] CL:0000842->CL:0000738 CL:0000842->CL:0000226 CL:0000738->CL:0002242
#>  [7] CL:0000738->CL:0000988 CL:0000738->CL:0000219 CL:0000226->CL:0002242
#> [10] CL:0002242->CL:0000003 CL:0000988->CL:0002371 CL:0000219->CL:0000003
#> [13] CL:0000003->CL:0000000 CL:0002371->CL:0000548
#> + ... omitted several edges
igraph_as_olsr_graph(ig)
#> class: ancestors_graph (21 nodes x 24 edges)
#> ontology: cl
#> ids (1): CL:0000236