plotForest.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/AllGenerics.R, R/plotForest.R
\name{plotForest}
\alias{plotForest}
\alias{plotForest,TreeSummarizedExperiment-method}
\alias{plotForest,SummarizedExperiment-method}
\alias{plotForest,data.frame-method}
\title{Visualize estimated results with forest plots}
\usage{
plotForest(x, ...)

\S4method{plotForest}{TreeSummarizedExperiment}(
  x,
  by = 1L,
  effect.var = "effect",
  ci.lower.var = "lower",
  ci.upper.var = "upper",
  err.var = NULL,
  pval.var = "pval",
  id.var = "rownames",
  label.by = NULL,
  order.by = NULL,
  facet.by = NULL,
  color.by = colour.by,
  colour.by = NULL,
  conf.level = 0.95,
  tree.name = "phylo",
  show.tree = TRUE,
  ...
)

\S4method{plotForest}{SummarizedExperiment}(
  x,
  by = 1L,
  effect.var = "effect",
  ci.lower.var = "lower",
  ci.upper.var = "upper",
  err.var = NULL,
  pval.var = "pval",
  id.var = "rownames",
  label.by = NULL,
  order.by = NULL,
  facet.by = NULL,
  color.by = colour.by,
  colour.by = NULL,
  conf.level = 0.95
)

\S4method{plotForest}{data.frame}(
  x,
  effect.var = "effect",
  ci.lower.var = "lower",
  ci.upper.var = "upper",
  err.var = NULL,
  pval.var = "pval",
  id.var = "rownames",
  label.by = NULL,
  order.by = NULL,
  facet.by = NULL,
  color.by = colour.by,
  colour.by = NULL,
  conf.level = 0.95
)
}
\arguments{
\item{x}{a
\code{\link[SummarizedExperiment:SummarizedExperiment-class]{SummarizedExperiment}}
object, or a \code{data.frame} object containing statistical estimates.}

\item{...}{additional parameters passed to \code{\link{plotRowTree}}.}

\item{by}{\code{Character scalar}. Determines whether features or samples
data is used for the plot. (Default: \code{"rows"})}

\item{effect.var}{\code{Character scalar}. Specifies the variable of x which
corresponds to the effects or estimated results. (Default: \code{"effect"})}

\item{ci.lower.var}{\code{Character scalar}. Specifies the variable of x
which corresponds to the lower CI boundaries. (Default: \code{"lower"})}

\item{ci.upper.var}{\code{Character scalar}. Specifies the variable of x
which corresponds to the upper CI boundaries. (Default: \code{"upper"})}

\item{err.var}{\code{Character scalar}. Specifies the variable of x which
corresponds to the standard errors associated with \code{effect.var}.
When defined, it overwrites \code{ci.lower.var} and \code{ci.upper.var}.
(Default: \code{"pval"})}

\item{pval.var}{\code{Character scalar}. Specifies the variable of x which
corresponds to the p-values associated with \code{effect.var}.
(Default: \code{"pval"})}

\item{id.var}{\code{Character scalar}. Specifies the variable of x which
corresponds to the observation identifiers. When \code{"rownames"}),
the object rownames are used. (Default: \code{"rownames"})}

\item{label.by}{\code{Character vector}. Specifies the variables of x or
row/colData(x) by which the plot should be labelled. \code{"CI"} and
\code{"P-Value"} are special entries which require either \code{effect.var},
\code{ci.lower.var} and \code{ci.upper.var} or \code{pval.var} to be
specified, respectively. (Default: \code{NULL})}

\item{order.by}{\code{Character scalar}. Specifies the variable of x by which
observations are ordered. If \code{NULL}, the observations are ordered by
the tree structure if available. (Default: \code{NULL})}

\item{facet.by}{\code{Character scalar}. Specifies the variable of x by which
observations are divided into horizontal facets. (Default: \code{NULL})}

\item{color.by}{\code{Character scalar}. Alias to \code{colour.by}.}

\item{colour.by}{\code{Character scalar}. Specifies the variable of x by
which observations are coloured. (Default: \code{NULL})}

\item{conf.level}{\code{Numeric scalar}. Specifies the confidence level of
the interval when inferred from \code{err.var}. It is ignored when
\code{ci.lower.var} and \code{ci.upper.var} are defined.
(Default: \code{0.95})}

\item{tree.name}{\code{Character scalar}. Specifies a row/colTree from x.
(Default: \code{"phylo"})}

\item{show.tree}{\code{Logical scalar}. Should the tree structure of the data
be shown next to the forest plot?}
}
\value{
a \code{\link[ggplot2:ggplot]{ggplot}} object.
}
\description{
\code{plotForest()} creates a feature- or sample-wise forest plot, showing
estimated results from a statistical test with their confidence intervals.
Additionally, the plot can be enriched with the tree structure and labelled
with Confidence Intervals (CIs), p-values and other side information.
}
\examples{
library(mia)
library(maaslin3)

# Import dataset
data("Tengeler2020", package = "mia")
tse <- Tengeler2020

# Agglomerate by genus and subset by prevalence
tse <- subsetByPrevalent(tse, rank = "Genus", prevalence = 10/100)

# Transform count assay to relative abundances
tse <- transformAssay(tse, assay.type = "counts", method = "relabundance")

# Run maaslin3
maaslin3_out <- maaslin3(
    input_data = tse,
    output = "maaslin_results",
    formula = "~ patient_status",
)

# Retrieve abundance results
maaslin3_abund <- maaslin3_out$fit_data_abundance$results
maaslin3_abund <- maaslin3_abund[!is.na(maaslin3_abund$coef), ]

# Visualize abundance results
plotForest(
    maaslin3_abund,
    effect.var = "coef",
    err.var = "stderr",
    pval.var = "qval_joint",
    id.var = "feature",
    label.by = c("CI", "P-Value"),
    order.by = "coef"
)

# Add abundance results to TreeSE rowData
rownames(maaslin3_abund) <- maaslin3_abund$feature
tax_order <- match(rownames(tse), rownames(maaslin3_abund))
rowData(tse) <- cbind(rowData(tse), maaslin3_abund[tax_order, ])

# Visualise abundance results with tree structure
plotForest(
    tse,
    effect.var = "coef",
    err.var = "stderr",
    pval.var = "qval_joint",
    label.by = c("CI", "P-Value")
)

# Retrieve prevalence results
maaslin3_prev <- maaslin3_out$fit_data_prevalence$results
maaslin3_prev <- maaslin3_prev[!is.na(maaslin3_prev$coef), ]

# Combine abundance and prevalence results
maaslin3_res <- rbind(maaslin3_abund, maaslin3_prev)

maaslin3_res$association <- c(
    rep("Abundance", nrow(maaslin3_abund)),
    rep("Prevalence", nrow(maaslin3_prev))
)

# Visualize combined results
plotForest(
    maaslin3_res,
    effect.var = "coef",
    err.var = "stderr",
    pval.var = "qval_joint",
    id.var = "feature",
    label.by = c("CI", "P-Value"),
    order.by = "coef",
    facet.by = "association",
    colour.by = "association"
)

}