plotTree {miaViz} | R Documentation

## Plotting tree information enriched with information

### Description

Based on the stored data in a `TreeSummarizedExperiment` a tree can be plotted. From the `rowData`, the `assays` as well as the `colData` information can be taken for enriching the tree plots with additional information.

### Usage

    plotRowTree(object, ...)

    plotColTree(object, ...)

    ## S4 method for signature 'TreeSummarizedExperiment'
    plotColTree(
      object,
      relabel_tree = FALSE,
      order_tree = FALSE,
      remove_levels = FALSE,
      show_label = FALSE,
      show_highlights = FALSE,
      show_highlight_label = FALSE,
      abbr_label = FALSE,
      add_legend = TRUE,
      layout = "circular",
      edge_colour_by = NULL,
      edge_size_by = NULL,
      tip_colour_by = NULL,
      tip_shape_by = NULL,
      tip_size_by = NULL,
      node_colour_by = NULL,
      node_shape_by = NULL,
      node_size_by = NULL,
      colour_highlights_by = NULL,
      by_exprs_values = "counts",
      other_fields = list(),
      ...
    )

    ## S4 method for signature 'TreeSummarizedExperiment'
    plotRowTree(
      object,
      relabel_tree = FALSE,
      order_tree = FALSE,
      remove_levels = FALSE,
      show_label = FALSE,
      show_highlights = FALSE,
      show_highlight_label = FALSE,
      abbr_label = FALSE,
      add_legend = TRUE,
      layout = "circular",
      edge_colour_by = NULL,
      edge_size_by = NULL,
      tip_colour_by = NULL,
      tip_shape_by = NULL,
      tip_size_by = NULL,
      node_colour_by = NULL,
      node_shape_by = NULL,
      node_size_by = NULL,
      colour_highlights_by = NULL,
      by_exprs_values = "counts",
      other_fields = list(),
      ...
    )

### Arguments

`object` | a `TreeSummarizedExperiment` object.
`...` | additional arguments for plotting. See `mia-plot-args` for more details i.e. call `help("mia-plot-args")`
`relabel_tree` | logical scalar, Should the tip labels be relabeled using the output of `getTaxonomyLabels(object, with_rank = TRUE)`? (default: `relabel_tree = FALSE`)
`order_tree` | logical scalar, Should the tree be ordered based on alphabetic order of taxonomic levels? (default: `order_tree = FALSE`)
`remove_levels` | logical scalar, Should taxonomic level information be removed from labels? (default: `relabel_tree = FALSE`)
`show_label, show_highlights, show_highlight_label, abbr_label` | `logical` (scalar), `integer` or `character` vector. If a `logical` scalar is given, should tip labels be plotted or if a logical vector is provided, which labels should be shown? If an `integer` or `character` vector is provided, it will be converted to a logical vector. The `integer` values must be in the range of 1 and number of nodes, whereas the values of a `character` vector must match values of the `label` column in the node data. In case of a `character` vector only values corresponding to actual labels will be plotted and if no labels are provided no labels will be shown. (default: `FALSE`)
`add_legend` | logical scalar. Should legends be plotted? (default: `add_legend = TRUE`)
`layout` | layout for the plotted tree. See `ggtree` for details.
`edge_colour_by` | Specification of a column metadata field or a feature to colour tree edges by, see the by argument in `?retrieveCellInfo` for possible values.
`edge_size_by` | Specification of a column metadata field or a feature to size tree edges by, see the by argument in `?retrieveCellInfo` for possible values.
`tip_colour_by` | Specification of a column metadata field or a feature to colour tree tips by, see the by argument in `?retrieveCellInfo` for possible values.
`tip_shape_by` | Specification of a column metadata field or a feature to shape tree tips by, see the by argument in `?retrieveCellInfo` for possible values.
`tip_size_by` | Specification of a column metadata field or a feature to size tree tips by, see the by argument in `?retrieveCellInfo` for possible values.
`node_colour_by` | Specification of a column metadata field or a feature to colour tree nodes by. Must be a field from `other_fields`.
`node_shape_by` | Specification of a column metadata field or a feature to shape tree nodes by. Must be a field from `other_fields`.
`node_size_by` | Specification of a column metadata field or a feature to size tree nodes by. Must be a field from `other_fields`.
`colour_highlights_by` | Should the highlights be colour differently? If `show_highlights = TRUE`, `colour_highlights` will be set to `TRUE` as default. (default: `colour_highlights = FALSE`)
`by_exprs_values` | A string or integer scalar specifying which assay to obtain expression values from, for use in point aesthetics - see the `exprs_values` argument in `?retrieveCellInfo`.
`other_fields` | Additional fields to include in the node information without plotting them.

### Details

If `show_label` or `show_highlight_label` have the same length as the number of nodes, the vector will be used to relabel the nodes.

### Value

a `ggtree` plot

### See Also

`splitByRanks`

### Examples

    library(scater)
    library(mia)
    # preparation of some data
    data(GlobalPatterns)
    altExps(GlobalPatterns) <- splitByRanks(GlobalPatterns)
    altExp(GlobalPatterns,"Genus") <- addPerFeatureQC(altExp(GlobalPatterns,"Genus"))
    rowData(altExp(GlobalPatterns,"Genus"))$log_mean <-
      log(rowData(altExp(GlobalPatterns,"Genus"))$mean)
    rowData(altExp(GlobalPatterns,"Genus"))$detected <-
       rowData(altExp(GlobalPatterns,"Genus"))$detected / 100
    top_genus <- getTopTaxa(altExp(GlobalPatterns,"Genus"),
                            method="mean",
                            top=100L,
                            abund_values="counts")
    #
    x <- altExp(GlobalPatterns,"Genus")
    plotRowTree(x[rownames(x) %in% top_genus,],
                tip_colour_by = "log_mean",
                tip_size_by = "detected")

    # plot with tip labels
    plotRowTree(x[rownames(x) %in% top_genus,],
                tip_colour_by = "log_mean",
                tip_size_by = "detected",
                show_label = TRUE)
    # plot with selected labels
    labels <- c("Genus:Providencia", "Genus:Morganella", "0.961.60")
    plotRowTree(x[rownames(x) %in% top_genus,],
                tip_colour_by = "log_mean",
                tip_size_by = "detected",
                show_label = labels,
                layout="rectangular")

    # plot with labeled edges
    plotRowTree(x[rownames(x) %in% top_genus,],
                edge_colour_by = "Phylum",
                tip_colour_by = "log_mean")
    # if edges are sized, colours might disappear depending on plotting device
    plotRowTree(x[rownames(x) %in% top_genus,],
                edge_colour_by = "Phylum",
                edge_size_by = "detected",
                tip_colour_by = "log_mean")

    # aggregating data over the taxonomic levels for plotting a taxonomic tree
    # please note that the original tree of GlobalPatterns is dropped by
    # unsplitByRanks
    altExps(GlobalPatterns) <- splitByRanks(GlobalPatterns)
    top_phyla <- getTopTaxa(altExp(GlobalPatterns,"Phylum"),
                            method="mean",
                            top=10L,
                            abund_values="counts")
    altExps(GlobalPatterns) <- lapply(altExps(GlobalPatterns), addPerFeatureQC)
    altExps(GlobalPatterns) <-
       lapply(altExps(GlobalPatterns),
              function(y){
                  rowData(y)$log_mean <- log(rowData(y)$mean)
                  rowData(y)$detected <- rowData(y)$detected / 100
                  y
              })
    x <- unsplitByRanks(GlobalPatterns)
    x <- addTaxonomyTree(x)

    highlights <- c("Phylum:Firmicutes","Phylum:Bacteroidetes",
                    "Family:Pseudomonadaceae","Order:Bifidobacteriales")
    plotRowTree(x[rowData(x)$Phylum %in% top_phyla,],
                tip_colour_by = "log_mean",
                node_colour_by = "log_mean",
                show_highlights = highlights,
                show_highlight_label = highlights,
                colour_highlights_by = "Phylum")

    plotRowTree(x[rowData(x)$Phylum %in% top_phyla,],
                edge_colour_by = "Phylum",
                edge_size_by = "detected",
                tip_colour_by = "log_mean",
                node_colour_by = "log_mean")

[Package miaViz version 1.2.1 Index]