Generate Beta Ordination Plots
Source:R/generate_beta_ordination_long.R
generate_beta_ordination_long.Rd
This function generates beta ordination plots using the specified distance measure. The plots can be stratified by a given variable and the color and shape aesthetics can be mapped to groups and time variables, respectively. The function also supports saving the plots as PDF files.
Usage
generate_beta_ordination_long(
data.obj = NULL,
dist.obj = NULL,
pc.obj = NULL,
subject.var,
time.var,
t0.level = NULL,
ts.levels = NULL,
group.var = NULL,
strata.var = NULL,
adj.vars = NULL,
dist.name = c("BC", "Jaccard"),
base.size = 16,
theme.choice = "bw",
custom.theme = NULL,
palette = NULL,
pdf = TRUE,
file.ann = NULL,
pdf.wid = 11,
pdf.hei = 8.5,
...
)
Arguments
- data.obj
A list object in a format specific to MicrobiomeStat, which can include components such as feature.tab (matrix), feature.ann (matrix), meta.dat (data.frame), tree, and feature.agg.list (list). The data.obj can be converted from other formats using several functions from the MicrobiomeStat package, including: 'mStat_convert_DGEList_to_data_obj', 'mStat_convert_DESeqDataSet_to_data_obj', 'mStat_convert_phyloseq_to_data_obj', 'mStat_convert_SummarizedExperiment_to_data_obj', 'mStat_import_qiime2_as_data_obj', 'mStat_import_mothur_as_data_obj', 'mStat_import_dada2_as_data_obj', and 'mStat_import_biom_as_data_obj'. Alternatively, users can construct their own data.obj. Note that not all components of data.obj may be required for all functions in the MicrobiomeStat package.
- dist.obj
Distance matrix between samples, usually calculated using
mStat_calculate_beta_diversity
function. If NULL, beta diversity will be automatically computed fromdata.obj
usingmStat_calculate_beta_diversity
.- pc.obj
A list containing the results of dimension reduction/Principal Component Analysis. This should be the output from functions like
mStat_calculate_PC
, containing the PC coordinates and other metadata. If NULL (default), dimension reduction will be automatically performed using metric multidimensional scaling (MDS) viamStat_calculate_PC
. The pc.obj list structure should contain:- points
A matrix with samples as rows and PCs as columns containing the coordinates.
- eig
Eigenvalues for each PC dimension.
- vectors
Loadings vectors for features onto each PC.
- Other metadata
like method, dist.name, etc.
See
mStat_calculate_PC
function for details on output format.- subject.var
Character string specifying the column name in metadata containing the subject IDs. This should uniquely identify each subject in the study. Required for connecting samples from the same subject.
- time.var
Character string specifying the column name in metadata containing the time variable. This should contain time points for each sample. Required for ordering and connecting samples for the same subject over time.
- t0.level
Character or numeric, baseline time point for longitudinal analysis, e.g. "week_0" or 0. Required.
- ts.levels
Character vector, names of follow-up time points, e.g. c("week_4", "week_8"). Required.
- group.var
Character string specifying the column name in metadata containing the grouping variable. This will be mapped to color aesthetic in the plot. Optional, can be NULL.
- strata.var
Character string specifying the column name in metadata containing the stratification variable. This will be used for nested faceting in the plots. Optional, can be NULL.
- adj.vars
Character vector specifying column names in metadata to include as covariates in multivariate adjustment of the distance matrix before ordination. Can be empty or NULL if no adjustment needed.
- dist.name
A character vector specifying which beta diversity indices to calculate. Supported indices are "BC" (Bray-Curtis), "Jaccard", "UniFrac" (unweighted UniFrac), "GUniFrac" (generalized UniFrac), "WUniFrac" (weighted UniFrac), and "JS" (Jensen-Shannon divergence). If a name is provided but the corresponding object does not exist within dist.obj, it will be computed internally. If the specific index is not supported, an error message will be returned.
- base.size
a numeric value specifying the base size for the plot text.
- theme.choice
Plot theme choice. Specifies the visual style of the plot. Can be one of the following pre-defined themes: - "prism": Utilizes the ggprism::theme_prism() function from the ggprism package, offering a polished and visually appealing style. - "classic": Applies theme_classic() from ggplot2, providing a clean and traditional look with minimal styling. - "gray": Uses theme_gray() from ggplot2, which offers a simple and modern look with a light gray background. - "bw": Employs theme_bw() from ggplot2, creating a classic black and white plot, ideal for formal publications and situations where color is best minimized. - "light": Implements theme_light() from ggplot2, featuring a light theme with subtle grey lines and axes, suitable for a fresh, modern look. - "dark": Uses theme_dark() from ggplot2, offering a dark background, ideal for presentations or situations where a high-contrast theme is desired. - "minimal": Applies theme_minimal() from ggplot2, providing a minimalist theme with the least amount of background annotations and colors. - "void": Employs theme_void() from ggplot2, creating a blank canvas with no axes, gridlines, or background, ideal for custom, creative plots. Each theme option adjusts various elements like background color, grid lines, and font styles to match the specified aesthetic. Default is "bw", offering a universally compatible black and white theme suitable for a wide range of applications.
- custom.theme
A custom ggplot theme provided as a ggplot2 theme object. This allows users to override the default theme and provide their own theme for plotting. Custom themes are useful for creating publication-ready figures with specific formatting requirements.
To use a custom theme, create a theme object with ggplot2::theme(), including any desired customizations. Common customizations for publication-ready figures might include adjusting text size for readability, altering line sizes for clarity, and repositioning or formatting the legend. For example:
“`r my_theme <- ggplot2::theme( axis.title = ggplot2::element_text(size=14, face="bold"), # Bold axis titles with larger font axis.text = ggplot2::element_text(size=12), # Slightly larger axis text legend.position = "top", # Move legend to the top legend.background = ggplot2::element_rect(fill="lightgray"), # Light gray background for legend panel.background = ggplot2::element_rect(fill="white", colour="black"), # White panel background with black border panel.grid.major = ggplot2::element_line(colour = "grey90"), # Lighter color for major grid lines panel.grid.minor = ggplot2::element_blank(), # Remove minor grid lines plot.title = ggplot2::element_text(size=16, hjust=0.5) # Centered plot title with larger font ) “`
Then pass `my_theme` to `custom.theme`. If `custom.theme` is NULL (the default), the theme is determined by `theme.choice`. This flexibility allows for both easy theme selection for general use and detailed customization for specific presentation or publication needs.
- palette
An optional parameter specifying the color palette to be used for the plot. It can be either a character string specifying the name of a predefined palette or a vector of color codes in a format accepted by ggplot2 (e.g., hexadecimal color codes). Available predefined palettes include 'npg', 'aaas', 'nejm', 'lancet', 'jama', 'jco', and 'ucscgb', inspired by various scientific publications and the `ggsci` package. If `palette` is not provided or an unrecognized palette name is given, a default color palette will be used. Ensure the number of colors in the palette is at least as large as the number of groups being plotted.
a logical value indicating whether to save the plots as PDF files. Defaults to TRUE.
- file.ann
a character string specifying an annotation to add to the file names of the saved plots.
- pdf.wid
a numeric value specifying the width of the saved PDF files.
- pdf.hei
a numeric value specifying the height of the saved PDF files.
- ...
further arguments to be passed to the underlying functions.
See also
mStat_calculate_beta_diversity
for creating the distance object, mStat_calculate_PC
for computing the principal coordinates, and geom_point
, geom_boxplot
for the underlying plot functions used, and mStat_convert_DGEList_to_data_obj
, mStat_convert_DESeqDataSet_to_data_obj
, mStat_convert_phyloseq_to_data_obj
, mStat_convert_SummarizedExperiment_to_data_obj
, mStat_import_qiime2_as_data_obj
, mStat_import_mothur_as_data_obj
, mStat_import_dada2_as_data_obj
, mStat_import_biom_as_data_obj
for data conversion.
Examples
if (FALSE) { # \dontrun{
data(subset_T2D.obj)
generate_beta_ordination_long(
data.obj = subset_T2D.obj,
dist.obj = NULL,
pc.obj = NULL,
subject.var = "subject_id",
time.var = "visit_number_num",
t0.level = NULL,
ts.levels = NULL,
group.var = "subject_race",
strata.var = NULL,
adj.vars = NULL,
dist.name = 'BC',
base.size = 12,
theme.choice = "bw",
custom.theme = NULL,
palette = NULL,
pdf = TRUE,
file.ann = NULL,
pdf.wid = 11,
pdf.hei = 8.5
)
generate_beta_ordination_long(
data.obj = subset_T2D.obj,
dist.obj = NULL,
pc.obj = NULL,
subject.var = "subject_id",
time.var = "visit_number_num",
t0.level = NULL,
ts.levels = NULL,
group.var = "subject_race",
strata.var = "subject_gender",
adj.vars = NULL,
dist.name = 'BC',
base.size = 12,
theme.choice = "bw",
custom.theme = NULL,
palette = NULL,
pdf = TRUE,
file.ann = NULL,
pdf.wid = 11,
pdf.hei = 8.5
)
generate_beta_ordination_long(
data.obj = subset_T2D.obj,
dist.obj = NULL,
pc.obj = NULL,
subject.var = "subject_id",
time.var = "visit_number_num",
t0.level = NULL,
ts.levels = NULL,
group.var = NULL,
strata.var = NULL,
adj.vars = NULL,
dist.name = 'BC',
base.size = 12,
theme.choice = "bw",
custom.theme = NULL,
palette = NULL,
pdf = TRUE,
file.ann = NULL,
pdf.wid = 11,
pdf.hei = 8.5
)
data(ecam.obj)
dist.obj <- mStat_calculate_beta_diversity(ecam.obj, "BC")
pc.obj <- mStat_calculate_PC(dist.obj)
generate_beta_ordination_long(
data.obj = ecam.obj,
dist.obj = dist.obj,
pc.obj = pc.obj,
subject.var = "subject.id",
time.var = "month",
t0.level = "0",
ts.levels = as.character(sort(as.numeric(unique(ecam.obj$meta.dat$month))))[2:10],
group.var = "diet",
strata.var = NULL,
adj.vars = NULL,
dist.name = 'BC',
base.size = 16,
theme.choice = "bw",
custom.theme = NULL,
palette = NULL,
pdf = TRUE,
file.ann = NULL,
pdf.wid = 11,
pdf.hei = 8.5
)
generate_beta_ordination_long(
data.obj = ecam.obj,
dist.obj = dist.obj,
pc.obj = pc.obj,
subject.var = "subject.id",
time.var = "month_num",
t0.level = NULL,
ts.levels = NULL,
group.var = NULL,
strata.var = NULL,
adj.vars = NULL,
dist.name = 'BC',
base.size = 16,
theme.choice = "bw",
custom.theme = NULL,
palette = NULL,
pdf = TRUE,
file.ann = NULL,
pdf.wid = 11,
pdf.hei = 8.5
)
} # }