trans_beta {microeco} | R Documentation |
Create trans_beta
object for beta-diversity analysis
Description
This class is a wrapper for a series of beta-diversity related analysis,
including ordination analysis based on An et al. (2019) <doi:10.1016/j.geoderma.2018.09.035>, group distance comparision,
clustering, perMANOVA based on Anderson al. (2008) <doi:10.1111/j.1442-9993.2001.01070.pp.x>, ANOSIM and PERMDISP.
Note that the beta diversity analysis methods related with environmental variables are encapsulated within the trans_env
class.
Methods
Public methods
Method new()
Usage
trans_beta$new(dataset = NULL, measure = NULL, group = NULL)
Arguments
dataset
an object of
microtable
class.measure
default NULL; a matrix name stored in
microtable$beta_diversity
list, such as "bray" or "jaccard", or a customized matrix; used for ordination, manova, group distance comparision, etc.; Please seecal_betadiv
function ofmicrotable
class for more details.group
default NULL; a column name of
sample_table
in the input dataset; group information will be used for manova, betadisper or distance comparision.
Returns
measure
, group
and dataset
stored in the object.
Examples
data(dataset) t1 <- trans_beta$new(dataset = dataset, measure = "bray", group = "Group")
Method cal_ordination()
Unconstrained ordination.
Usage
trans_beta$cal_ordination( method = "PCoA", ncomp = 2, taxa_level = NULL, NMDS_matrix = TRUE, trans = FALSE, scale_species = FALSE, scale_species_ratio = 0.8, orthoI = NA, ordination = deprecated(), ... )
Arguments
method
default "PCoA"; "PCoA", "NMDS", "PCA", "DCA", "PLS-DA" or "OPLS-DA". PCoA: principal coordinates analysis; NMDS: non-metric multidimensional scaling, PCA: principal component analysis; DCA: detrended correspondence analysis; PLS-DA: partial least squares discriminant analysis; OPLS-DA: orthogonal partial least squares discriminant analysis. For the methods details, please refer to the papers <doi:10.1111/j.1574-6941.2007.00375.x> (for PCoA, NMDS, PCA and DCA) and <doi:10.1186/s12859-019-3310-7> (for PLS-DA or OPLS-DA).
ncomp
default 2; dimensions in the result. For the
method
option "PCA", "PCoA" or "DCA", the corresponding dimension information will be selected from the original model based on this parameter.. For all the dimension information, please refer tomodel
in the results. For themethod
option "NMDS", this argument will be passed to thek
parameter in thevegan::metaMDS
function.taxa_level
default NULL; available for PCA, DCA or NMDS (
NMDS_matrix = TRUE
). Default NULL means using theotu_table
in the microtable object. For other options, please provide the taxonomic rank names intax_table
, such as "Phylum" or "Genus". In such cases, the data will be merged according to the provided taxonomic levels to generated a new abundance table.NMDS_matrix
default TRUE; For the NMDS method, whether use a distance matrix as input like PCoA. If it is FALSE, the input will be the abundance table like PCA.
trans
default FALSE; whether species abundance will be square root transformed; only available when
method
is "PCA" or "DCA". For method "NMDS" andNMDS_matrix = FALSE
, please set theautotransform
parameter, which will be passed tovegan::metaMDS
function directly.scale_species
default FALSE; whether species loading in PCA, DCA or NMDS (
NMDS_matrix = FALSE
) is scaled.scale_species_ratio
default 0.8; the ratio to scale up the loading; multiply by the maximum distance between samples and origin. Only available when
scale_species = TURE
.orthoI
default NA; number of orthogonal components (for OPLS-DA only). Default NA means the number of orthogonal components is automatically computed. Please also see
orthoI
parameter inopls
function of ropls package.ordination
deprecated. Please use
method
argument instead....
parameters passed to
vegan::rda
function whenmethod = "PCA"
, orvegan::decorana
function whenmethod = "DCA"
, orape::pcoa
function whenmethod = "PCoA"
, orvegan::metaMDS
function whenmethod = "NMDS"
, orropls::opls
function whenmethod = "PLS-DA"
ormethod = "OPLS-DA"
.
Returns
res_ordination
list stored in the object.
In the list, model
is the original analysis results; scores
is the sample scores table; loading
is the feature loading table.
Examples
t1$cal_ordination(method = "PCoA")
Method plot_ordination()
Plot the ordination result.
Usage
trans_beta$plot_ordination( plot_type = "point", choices = c(1, 2), color_values = RColorBrewer::brewer.pal(8, "Dark2"), shape_values = c(16, 17, 7, 8, 15, 18, 11, 10, 12, 13, 9, 3, 4, 0, 1, 2, 14), plot_color = NULL, plot_shape = NULL, plot_group_order = NULL, add_sample_label = NULL, point_size = 3, point_alpha = 0.8, centroid_segment_alpha = 0.6, centroid_segment_size = 1, centroid_segment_linetype = 3, ellipse_chull_fill = TRUE, ellipse_chull_alpha = 0.1, ellipse_level = 0.9, ellipse_type = "t", NMDS_stress_pos = c(1, 1), NMDS_stress_text_prefix = "", loading_arrow = FALSE, loading_taxa_num = 10, loading_text_taxlevel = NULL, loading_text_color = "black", loading_arrow_color = "grey30", loading_text_size = 3, loading_text_prefix = FALSE, loading_text_italic = FALSE )
Arguments
plot_type
default "point"; one or more elements of "point", "ellipse", "chull" and "centroid".
- 'point'
add sample points
- 'ellipse'
add confidence ellipse for points of each group
- 'chull'
add convex hull for points of each group
- 'centroid'
add centroid line for points in each group
choices
default c(1, 2); selected axis for the visualization; must be numeric vector. The maximum value must not exceed the parameter
ncomp
in thecal_ordination
function.color_values
default
RColorBrewer::brewer.pal
(8, "Dark2"); colors palette for different groups.shape_values
default c(16, 17, 7, 8, 15, 18, 11, 10, 12, 13, 9, 3, 4, 0, 1, 2, 14); a vector for point shape types of groups, see
ggplot2
tutorial.plot_color
default NULL; a colname of
sample_table
to assign colors to different groups in plot.plot_shape
default NULL; a colname of
sample_table
to assign shapes to different groups in plot.plot_group_order
default NULL; a vector used to order the groups in the legend of plot.
add_sample_label
default NULL; a column name in
sample_table
; If provided, show the point name in plot.point_size
default 3; point size when "point" is in
plot_type
parameter.point_size
can also be a variable name insample_table
, such as "pH".point_alpha
default .8; point transparency in plot when "point" is in
plot_type
parameter.centroid_segment_alpha
default 0.6; segment transparency in plot when "centroid" is in
plot_type
parameter.centroid_segment_size
default 1; segment size in plot when "centroid" is in
plot_type
parameter.centroid_segment_linetype
default 3; the line type related with centroid in plot when "centroid" is in
plot_type
parameter.ellipse_chull_fill
default TRUE; whether fill colors to the area of ellipse or chull.
ellipse_chull_alpha
default 0.1; color transparency in the ellipse or convex hull depending on whether "ellipse" or "centroid" is in
plot_type
parameter.ellipse_level
default .9; confidence level of ellipse when "ellipse" is in
plot_type
parameter.ellipse_type
default "t"; ellipse type when "ellipse" is in
plot_type
parameter; see type instat_ellipse
.NMDS_stress_pos
default c(1, 1); a numerical vector with two values used to represent the insertion position of the stress text. The first one denotes the x-axis, while the second one corresponds to the y-axis. The assigned position is determined by multiplying the respective value with the maximum point on the corresponding coordinate axis. Thus, the x-axis position is equal to
max(points of x axis) * NMDS_stress_pos[1]
, and the y-axis position is equal tomax(points of y axis) * NMDS_stress_pos[2]
. Negative values can also be utilized for the negative part of the axis.NMDS_stress_pos = NULL
denotes no stress text to show.NMDS_stress_text_prefix
default ""; If NMDS_stress_pos is not NULL, this parameter can be used to add text in front of the stress value.
loading_arrow
default FALSE; whether show the loading using arrow.
loading_taxa_num
default 10; the number of taxa used for the loading. Only available when
loading_arrow = TRUE
.loading_text_taxlevel
default NULL; which level of taxonomic table will be used. Default NULL means using the
taxa_level
parameter in the previouscal_ordination
function.loading_text_color
default "black"; the color of taxa text. Only available when
loading_arrow = TRUE
.loading_arrow_color
default "grey30"; the color of taxa arrow. Only available when
loading_arrow = TRUE
.loading_text_size
default 3; the size of taxa text. Only available when
loading_arrow = TRUE
.loading_text_prefix
default FALSE; whether show the prefix (e.g., g__) in the taxa text. Only available when
loading_arrow = TRUE
.loading_text_italic
default FALSE; whether using italic for the taxa text. Only available when
loading_arrow = TRUE
.
Returns
ggplot
.
Examples
t1$plot_ordination(plot_type = "point") t1$plot_ordination(plot_color = "Group", plot_shape = "Group", plot_type = "point") t1$plot_ordination(plot_color = "Group", plot_type = c("point", "ellipse")) t1$plot_ordination(plot_color = "Group", plot_type = c("point", "centroid"), centroid_segment_linetype = 1)
Method cal_manova()
Calculate perMANOVA (Permutational Multivariate Analysis of Variance) based on the adonis2
function of vegan package <doi:10.1111/j.1442-9993.2001.01070.pp.x>.
Usage
trans_beta$cal_manova( manova_all = TRUE, manova_set = NULL, group = NULL, by_group = NULL, p_adjust_method = "fdr", by = "terms", by_auto_set = TRUE, permutations = 999, ... )
Arguments
manova_all
default TRUE; TRUE represents test for all the groups, i.e. the overall test; FALSE represents test for all the paired groups.
manova_set
default NULL; other specified group set for manova, such as
"Group + Type"
and"Group*Type"
. Please also see theformula
parameter (only right-hand side) inadonis2
function of vegan package. The parameter manova_set has higher priority than manova_all parameter. If manova_set is provided; manova_all is disabled.group
default NULL; a column name of
sample_table
used for manova. If NULL, searchgroup
variable stored in the object. Available whenmanova_set
is not provided.by_group
default NULL; one column name in
sample_table
; used to perform paired comparisions within each group. Only available whenmanova_all = FALSE
andmanova_set
is not provided.p_adjust_method
default "fdr"; p.adjust method; available when
manova_all = FALSE
; seemethod
parameter ofp.adjust
function for available options.by
default "terms"; same with the
by
parameter inadonis2
function of vegan package.by_auto_set
default TRUE; Whether automatically set the options for
by
parameter ("marginal" or "terms") whenmanova_set
is provided. The primary reason for setting this parameter is that using marginal effects (also known as "Type III" effects) is more robust for unbalanced experimental designs. Since the optionby = "margin"
in theadonis2
function ignores main effects when interaction effects are present, we automatically setby = "margin"
when there are no interaction effects, and setby = "terms"
when interaction effects exist. If the user wants to use parameterby
, please setby_auto_set = FALSE
. Note that this parameter is only available whenmanova_set
is provided.permutations
default 999; same with the
permutations
parameter inadonis2
function of vegan package....
parameters passed to
adonis2
function ofvegan
package.
Returns
res_manova
stored in object with data.frame
class.
Examples
t1$cal_manova(manova_all = TRUE)
Method cal_anosim()
Analysis of similarities (ANOSIM) based on the anosim
function of vegan package.
Usage
trans_beta$cal_anosim( paired = FALSE, group = NULL, by_group = NULL, p_adjust_method = "fdr", permutations = 999, ... )
Arguments
paired
default FALSE; whether perform paired test between any two combined groups from all the input groups.
group
default NULL; a column name of
sample_table
. If NULL, searchgroup
variable stored in the object.by_group
default NULL; one column name in
sample_table
; used to perform paired comparisions within each group. Only available whenpaired = TRUE
.p_adjust_method
default "fdr"; p.adjust method; available when
paired = TRUE
; see method parameter ofp.adjust
function for available options.permutations
default 999; same with the
permutations
parameter inanosim
function of vegan package....
parameters passed to
anosim
function ofvegan
package.
Returns
res_anosim
stored in object with data.frame
class.
Examples
t1$cal_anosim()
Method cal_betadisper()
Multivariate homogeneity test of groups dispersions (PERMDISP) based on betadisper
function in vegan package.
Usage
trans_beta$cal_betadisper(...)
Arguments
...
parameters passed to
betadisper
function.
Returns
res_betadisper
stored in object.
Examples
t1$cal_betadisper()
Method cal_group_distance()
Convert symmetric distance matrix to distance table of paired samples that are within groups or between groups.
Usage
trans_beta$cal_group_distance( within_group = TRUE, by_group = NULL, ordered_group = NULL, sep = " vs " )
Arguments
within_group
default TRUE; whether obtain distance table of paired samples within groups; if FALSE, obtain distances of paired samples between any two groups.
by_group
default NULL; one colname name of
sample_table
inmicrotable
object. If provided, transform distances by the providedby_group
parameter. This is especially useful for ordering and filtering values further. Whenwithin_group = TRUE
, the result of by_group parameter is the format of paired groups. Whenwithin_group = FALSE
, the result of by_group parameter is the format same with the group information insample_table
.ordered_group
default NULL; a vector representing the ordered elements of
group
parameter; only useful when within_group = FALSE.sep
default TRUE; a character string to separate the group names after merging them into a new name.
Returns
res_group_distance
stored in object.
Examples
\donttest{ t1$cal_group_distance(within_group = TRUE) }
Method cal_group_distance_diff()
Differential test of converted distances across groups.
Usage
trans_beta$cal_group_distance_diff( group = NULL, by_group = NULL, by_ID = NULL, ... )
Arguments
group
default NULL; a column name of
object$res_group_distance
used for the statistics; If NULL, use thegroup
inside the object.by_group
default NULL; a column of
object$res_group_distance
used to perform the differential test among elements ingroup
parameter for each element inby_group
parameter. Soby_group
has a larger scale thangroup
parameter. Thisby_group
is very different from theby_group
parameter in thecal_group_distance
function.by_ID
default NULL; a column of
object$res_group_distance
used to perform paired t test or paired wilcox test for the paired data, such as the data of plant compartments for different plant species (ID). Soby_ID
should be the smallest unit of sample collection without any repetition in it....
parameters passed to
cal_diff
function oftrans_alpha
class.
Returns
res_group_distance_diff
stored in object.
Examples
\donttest{ t1$cal_group_distance_diff() }
Method plot_group_distance()
Plot the distances of paired groups within or between groups.
Usage
trans_beta$plot_group_distance(plot_group_order = NULL, ...)
Arguments
plot_group_order
default NULL; a vector used to order the groups in the plot.
...
parameters (except measure) passed to
plot_alpha
function oftrans_alpha
class.
Returns
ggplot
.
Examples
\donttest{ t1$plot_group_distance() }
Method plot_clustering()
Plot clustering result based on the ggdendro
package.
Usage
trans_beta$plot_clustering( color_values = RColorBrewer::brewer.pal(8, "Dark2"), measure = NULL, group = NULL, replace_name = NULL )
Arguments
color_values
default RColorBrewer::brewer.pal(8, "Dark2"); color palette for the text.
measure
default NULL; beta diversity index; If NULL, using the measure when creating object
group
default NULL; if provided, use this group to assign color.
replace_name
default NULL; if provided, use this as label.
Returns
ggplot
.
Examples
t1$plot_clustering(group = "Group", replace_name = c("Saline", "Type"))
Method clone()
The objects of this class are cloneable with this method.
Usage
trans_beta$clone(deep = FALSE)
Arguments
deep
Whether to make a deep clone.
Examples
## ------------------------------------------------
## Method `trans_beta$new`
## ------------------------------------------------
data(dataset)
t1 <- trans_beta$new(dataset = dataset, measure = "bray", group = "Group")
## ------------------------------------------------
## Method `trans_beta$cal_ordination`
## ------------------------------------------------
t1$cal_ordination(method = "PCoA")
## ------------------------------------------------
## Method `trans_beta$plot_ordination`
## ------------------------------------------------
t1$plot_ordination(plot_type = "point")
t1$plot_ordination(plot_color = "Group", plot_shape = "Group", plot_type = "point")
t1$plot_ordination(plot_color = "Group", plot_type = c("point", "ellipse"))
t1$plot_ordination(plot_color = "Group", plot_type = c("point", "centroid"),
centroid_segment_linetype = 1)
## ------------------------------------------------
## Method `trans_beta$cal_manova`
## ------------------------------------------------
t1$cal_manova(manova_all = TRUE)
## ------------------------------------------------
## Method `trans_beta$cal_anosim`
## ------------------------------------------------
t1$cal_anosim()
## ------------------------------------------------
## Method `trans_beta$cal_betadisper`
## ------------------------------------------------
t1$cal_betadisper()
## ------------------------------------------------
## Method `trans_beta$cal_group_distance`
## ------------------------------------------------
t1$cal_group_distance(within_group = TRUE)
## ------------------------------------------------
## Method `trans_beta$cal_group_distance_diff`
## ------------------------------------------------
t1$cal_group_distance_diff()
## ------------------------------------------------
## Method `trans_beta$plot_group_distance`
## ------------------------------------------------
t1$plot_group_distance()
## ------------------------------------------------
## Method `trans_beta$plot_clustering`
## ------------------------------------------------
t1$plot_clustering(group = "Group", replace_name = c("Saline", "Type"))