Author: Daniel Greene
Date: 2024-02-20

# Plotting Ontological Terms

#### Daniel Greene

#### 2024-02-20

`ontologyPlot` is part of the ‘ontologyX’ family of packages (see the ‘Introduction to ontologyX’ vignette supplied with the `ontologyIndex` package). It enables visualisation of ontological terms and ontological annotation as subgraphs of the full ontology, rendered using the `Rgraphviz` package. The package makes use of `ontology_index` objects, provided by the `ontologyIndex` package. To make full use of the features in `ontologyPlot`, the user is encouraged to gain familiarity of the functions in `ontologyIndex` which enable various transformations of sets of ontological that are useful for selecting those to add to diagrams.

Note: `Rgraphviz` must be obtained from the Bioconductor repository.

We start by loading both packages, and an example ontology - the Human Phenotype Ontology (HPO).

    library(ontologyIndex)
    library(ontologyPlot)
    data(hpo)

## Plotting Terms

A set of terms (character vector of term IDs) can be plotted as a subgraph of the ontology by calling `onto_plot`:

    onto_plot(hpo, terms=c("HP:0001873", "HP:0011877"))

To include all ancestral terms, use the `get_ancestors` function:

    onto_plot(hpo, terms=get_ancestors(hpo, c("HP:0001873", "HP:0011877")))

The function `remove_links` can be used to remove terms simply linking two terms together, thus the structure of the given part of the ontology can be retained whilst simplifying the figure:

    onto_plot(hpo, terms=remove_links(hpo, get_ancestors(hpo, c("HP:0001873", "HP:0011877"))))

## Graphical parameters

Graphical attributes to assign to each node can be passed to `onto_plot`. The graphical attributes can be specified as:

- a single value, thus setting the attribute to the given value for all nodes,
- a vector the same length as the `terms` argument, so the `i`th term gets the `i`th attribute value,
- a function which returns the desired attribute value for each term.

Node attributes which affect the plot generated include those supported by the Rgraphviz package. Some of these include:

- `fillcolor` - the colour to use for each node,
- `color` - the colour for the border of the node (defaults to `"transparent"`),
- `label` - a character vector of term IDs to be used as the labels,
- `fontsize` - font size of `label` text printed in each term,
- `width` - the relative width of the nodes.

In this example, we pass the term IDs as the labels and a character vector of colours generated with `rainbow` to colour the nodes.

    terms <- remove_links(hpo, get_ancestors(hpo, c("HP:0001873", "HP:0011877")))
    onto_plot(hpo, terms=terms, label=terms, fillcolor=rainbow(length(terms)))

`ontologyPlot` contains several functions for setting the graphical parameters which can be passed to `onto_plot`. These include for example `label_by_frequency`, `official_labels` and `label_by_term_set` (see individual help files for more details).

These functions must accept an `ontology` and `terms` argument. They can optionally accept:

- `frequencies`: a numeric vector of population frequencies named by term,
- `term_sets`: a `list` of character vectors of terms [i.e. annotated objects] arguments.

If any of the given functions require these additional arguments, they must be passed to `onto_plot`.

## Frequencies

A `frequencies` argument giving a population frequency of terms can be passed to `onto_plot`. If this argument is passed, functions which make use of it in determining graphical parameters can be passed to `onto_plot`, for instance `colour_by_population_frequency`.

    frequencies <- seq(from=0, to=1, by=1/length(terms))
    names(frequencies) <- terms
    onto_plot(hpo, terms=terms, frequencies=frequencies,
        fillcolor=colour_by_population_frequency)

## Term sets

Another argument which can be passed to `onto_plot` is `term_sets`, a list of sets of ontological terms (e.g. a set of HPO encoded phenotypes). If `terms_sets` is given, the `terms` parameter of `onto_plot` defaults to the value of `remove_uninformative_terms(ontology, term_sets)`, which removes terms which are annotated to exactly the same objects as all of their children (with the effect of greatly simplifying the resulting diagram - see `?remove_uninformative_terms` for more details).

    hpo_phenotypes <- list(
        A=c("HP:0001382","HP:0004272","HP:0007917","HP:0004912","HP:0001596"),
        B=c("HP:0001382","HP:0004272","HP:0002165","HP:0004800","HP:0004912"),
        C=c("HP:0004800","HP:0001382","HP:0004912","HP:0007917","HP:0008743")
    )

    onto_plot(hpo, term_sets=hpo_phenotypes, label=label_by_term_set)

To further decorate the plot, we could use the frequency of each term in `hpo_phenotypes` them to colour them.

    onto_plot(
        hpo,
        frequencies=get_term_frequencies(hpo, hpo_phenotypes),
        term_sets=hpo_phenotypes,
        label=label_by_term_set,
        fillcolor=colour_by_frequency)

## Edge attributes

Edge attributes recognised by `Rgraphviz` can also be supplied by the `edge_attributes` argument.

    onto_plot(
        hpo,
        frequencies=get_term_frequencies(hpo, hpo_phenotypes),
        term_sets=hpo_phenotypes,
        label=label_by_term_set,
        edge_attributes=list(color="red", lty="dashed"))

## Plots for publications

To get the highest quality plots and fine-grained control over the node and edge attributes, the best option is to create the `ontological_plot` with `onto_plot` and write it to a file in `dot` format using the `write_dot` function. The file can then be opened using a layout program, for example the graphviz program (https://www.graphviz.org/), to visualise/export as an image. Individual node and edge attributes can then be modified by editing the file.