Other sites

OncoTree Tidygraph

[This article was first published on Posts | Joshua Cook, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Introduction

Cancers are often first classified by their tissue of origin, but there
are several types of cancer for each tissue. Further, each of these can
have several subdivisions. For example, head and neck cancers can be
further divided into seven cancers, including head and neck squamous
cell carcinoma (HNSC). HNSC itself has six subtypes, too. This hierarchy
can be represented in a directed acyclic graph (DAG), as shown below.

For one of my projects in lab, I am dealing
with many types of cancers from a variety of studies. Thus, I want to
use OncoTree to organize the types and provide relational information of
the cancers. For instance, depending on what I want to analyze, I may
want the most specific subtype of cancer possible, or maybe I want the
cancer grouped by their first level on the OncoTree (e.g. “Head and
Neck”).

Therefore, I decided to parse the OncoTree into a‘tidygraph’,
a “tidy” way to manage graph structures. The following is a tutorial on
how I did this. The GitHub repository for this analysis is available atjhrcook/tidygraph-oncotree.

Setup

I will load the packages ‘tidyverse’, ‘tidygraph’, and ‘ggraph’, and
also use ‘httr’ and ‘jsonlite’, but call functions directly from their
namespace. The ‘ggraph’ package is a “grammar of graphics” for graph
structures – it is used for plotting graphs at the end of this tutorial.

Almost all of the parts of oncotree_json$TISSUE contain information
about the first level of the graph. The children section, though,
contains all of the tissues that we can see on the OncoTree web
application.

Therefore, we can tell that the JSON is a nested list of the nodes in
the DAG. And all we need to do is implement a graph-traversing function
to extract all of the information. Since it is nested and we are
building a graph, this strongly suggests we will need a recursive
algorithm.

Building the Tidygraph

Data needed for the tidygraph

To figure out what to do first, I often find it helpful to figure out
what my output should look like. To make a tidygraph, I will need anedge list and a node list. The first is a two-column table with
names “from” and “to” populated by names of the nodes where each row
indicates an edge of the graph. The node list is optional and contains
any other information about each node, one row per node.

Here is a mock example of the data frames we want out of our recursive
algorithm.

To add the node information, I join the node list table by the “name”
column. The %N>% infix operates just like the ‘magrittr’ pipe %>%
except it also activates the nodes of the tidygraph object so that thefull_join() operates on the nodes and not the edges. I am not able to
fully describe the ‘tidygraph’ API in this tutorial, but see vignettes
by the creator, Thomas Pedersen
(@thomasp85), for a good introduction:Data Imaginist –
tidygraph.

Now we just need to figure out how to build an edge list and node list
from the nested JSON.

Extracting OncoTree from the JSON

Note: Below I demonstrate how to create the final algorithm as if it
was a linear process – it in fact took me about and hour and a half of
toying with the functions to get the desired result. If it is not easy
to grasp right away, don’t worry, it wasn’t for me either.

So we know our algorithm will be recursive, which means we will pass the
first node to a function once and this function will call itself from
within. Therefore, let’s create a function add_children_to_dag() that
takes a node and an edge list and returns an edge list.

add_children_to_dag

Extracting node information

First, we can deal with the node information becasue that can be
extracted right away and stashed in a global variable, no recursion
needed.

# The node information.
NODE_INFO

Now, the node information is extracted and added to a global variableNODE_INFO using the extract_node_info() function. It just pulls out
some of the useful information from the JSON for each node and binds it
with the existing data frame.

Now we can run the first experiment to make sure everything is working
properly. The initial edge list is just an empty tibble().

add_children_to_dag(oncotree_json[[1]], tibble())

#> # A tibble: 0 x 0

Nothing is done to the el variable in add_children_to_dag() function
yet, so it returns an empty data frame. However, the NODE_INFO data
frame should have the information for the first level of OncoTree.

Add the node’s children to the edge list

Now we need to start on the hard part, the recursive traversal of the
DAG in the JSON. To begin, we should add an if-statement to check if the
node has children. If it does, then we need to add the connections from
this node to the children to the edge list el.

This is easily done by binding the existing el with a new tibble with
“from” and “to” columns containing the name of the current node (from)
and the names of the children (to).

Let’s start with that and make sure it works.

add_children_to_dag 0) {
# Add this node and children to edge list.
el

Great! We can see that the connections from "TISSUE" to each of the
top-level cancer groups were successfully added to the edge list.

Now we need to apply this function to each of the children of this node.
I do this with map() from the ‘purrr’ package (attached along with
‘tidyverse’). It works similarly to lapply() from base R, but is a
bit easier to manage, in my opinon (and it has some other useful helpers
and capabilities that we don’t use here.)

Basically, each child node is passed to add_children_to_dag() along
with the edge list. The node information for each child will be
extracted and, if they have children, they will be sent throughadd_children_to_dag(), too. Each time, an edge list is returned.

This is a recursive process and will naturally visit every node,
building up the edge list through every “leaf” on the tree.

add_children_to_dag 0) {
# Add this node and children to edge list.
nodes_el

Finally, we can use the ‘ggraph’ package to create some visualizations
of the DAG. Again, I am unable to fully explain ‘ggraph’ here, but the
package vignettes are very good: Data Imaginist –
ggraph.

The first plot below shows the OncoTree graph spreading radially from
the center, each layer representing a further subdivision of the cancer
type. The colors roughly correspond to the tissue of origin.