trans_mst: Create 'trans_mst' object for microbial source tracking (MST)...
In microeco: Microbial Community Ecology Data Analysis
trans_mst R Documentation
Create trans_mst object for microbial source tracking (MST) analysis.
Description
This class is a wrapper for microbial source tracking based on the FEAST algorithm
(Fast Expectation-maximization for microbial Source Tracking; Shenhav et al. 2019, Nature Methods, <doi:10.1038/s41592-019-0431-x>).
It estimates the contribution proportions of potential source environments to sink samples
(e.g., tracking the microbial transfer from bulk soil to rhizosphere soil and then to root).
The class automatically constructs the metadata (Env, SourceSink, id) required by FEAST
from the sample_table, runs the FEAST package, and provides ggplot2-based
visualization. Results of multiple runs (e.g., sequential transfer steps) can be stored
in the same object using different labels.
Methods
Public methods
-
-
-
-
-
-
Method new()
Usage
trans_mst$new(dataset = NULL, env_col = NULL, filter_thres = 0)
Arguments
datasetmicrotable object.
env_coldefault NULL; a column name in sample_table used as the environment
description (the "Env" information for FEAST), e.g., "Compartment".
If NULL, the environment of each sample is represented by its sample name when
cal_mst is called with explicit sample vectors (source_samples/sink_samples).
filter_thresdefault 0; the relative abundance threshold for filtering low-abundance taxa.
Taxa with total relative abundance < filter_thres will be removed.
This is delegated to dataset$filter_taxa(rel_abund = filter_thres).
Returns
dataset, sample_table, otu_table (taxa x samples counts),
env_col, n_samples, n_taxa stored in the object.
Examples
\dontrun{
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
}
Method cal_mst()
Run FEAST source tracking analysis.
Sources and sinks can be specified either by environment values (sources/sinks,
matched against the env_col column of sample_table) or by explicit sample names
(source_samples/sink_samples).
The function automatically generates the FEAST metadata:
in the same-sources mode (different_sources_flag = 0), all sinks share the same source pool;
in the different-sources mode (different_sources_flag = 1), each sink uses its own source
set defined by the pairing column id_col (samples sharing the same id_col value
belong to the same group, e.g., the same plant individual).
Usage
trans_mst$cal_mst(
sources = NULL,
sinks = NULL,
source_samples = NULL,
sink_samples = NULL,
different_sources_flag = 0,
id_col = NULL,
EM_iterations = 1000,
COVERAGE = NULL,
label = NULL
)
Arguments
sourcesdefault NULL; character vector of environment values (in the env_col column)
used as sources, e.g., c("Bulk soil", "Rhizosphere").
sinksdefault NULL; character vector of environment values used as sinks, e.g., "Endophyte".
source_samplesdefault NULL; character vector of sample names used as sources.
Alternative to sources; cannot be provided together with sources.
sink_samplesdefault NULL; character vector of sample names used as sinks.
Alternative to sinks; cannot be provided together with sinks.
different_sources_flagdefault 0; 0 (FALSE) means all sinks use the same source pool;
1 (TRUE) means each sink uses its own source set paired via id_col.
id_coldefault NULL; a column name in sample_table defining the pairing groups
for the different-sources mode (required when different_sources_flag = 1).
Samples sharing the same value are considered paired, e.g., "Plant_ID".
Each pairing group must contain exactly one sink sample; the sources in the group
constitute the source set of that sink.
EM_iterationsdefault 1000; the number of EM iterations passed to FEAST::FEAST.
COVERAGEdefault NULL; the rarefaction depth. If NULL, the minimum sequencing depth
across all involved source and sink samples is used, so all samples are uniformly downsampled.
labeldefault NULL; the label for storing the result, e.g., "bulk2rhizo".
If NULL, a label like "run1", "run2", ... is generated automatically.
Reusing an existing label overwrites the previous result with the same label.
Returns
res_mst[[label]]: Sink x Source contribution proportions matrix
(rownames: sink sample names; colnames: source sample names + "Unknown"; each row sums to 1);
res_mst_env[[label]]: contributions aggregated by source environment;
res_mst_param[[label]]: parameters and sample information of the run.
Examples
\dontrun{
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
# same sources for all sinks
t1$cal_mst(sources = "Bulk soil", sinks = "Rhizosphere", EM_iterations = 1000, label = "bulk2rhizo")
# different sources for each sink, paired by Plant_ID
t1$cal_mst(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID", label = "soil2root")
}
Method cal_mst_chain()
Run sequential source tracking steps (e.g., bulk soil -> rhizosphere soil -> root).
Usage
trans_mst$cal_mst_chain(steps = NULL)
Arguments
stepsdefault NULL; a list where each element is a list of arguments
passed to cal_mst (without label), e.g.,
list(list(sources = "Bulk soil", sinks = "Rhizosphere"),
list(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte")).
Each step is stored in res_mst[["step1"]], res_mst[["step2"]], ...
unless a custom label is provided inside the step.
Returns
results stored in res_mst, res_mst_env and res_mst_param.
Examples
\dontrun{
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
t1$cal_mst_chain(list(
list(sources = "Bulk soil", sinks = "Rhizosphere"),
list(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID")
))
}
Method plot_mst()
Plot the source tracking result as a stacked barplot.
Usage
trans_mst$plot_mst(
use_run = NULL,
use_env = TRUE,
group_sink = NULL,
show_unknown = TRUE,
colors = NULL,
unknown_color = "grey80",
legend_title = NULL,
bar_width = 0.8,
xtext_size = 10,
xtext_angle = 45,
facet_scales = "free_x"
)
Arguments
use_rundefault NULL; the label (or index) of the run stored in res_mst.
If NULL, the first run is used.
use_envdefault TRUE; whether to use the environment-level aggregated contributions
(res_mst_env). If FALSE, the sample-level contributions (res_mst) are shown.
group_sinkdefault NULL; a column name in sample_table used to group the sinks.
The plot is facetted by this column and the sinks are ordered accordingly, e.g., "Group".
show_unknowndefault TRUE; whether to show the "Unknown" contribution.
colorsdefault NULL; a vector of fill colors for the sources.
If NULL, the Dark2 (environment level) or Paired (sample level) palette of RColorBrewer is used.
unknown_colordefault "grey80"; the fill color for the "Unknown" source.
legend_titledefault NULL; the legend title. If NULL, "Source" is used.
bar_widthdefault 0.8; the bar width passed to geom_bar.
xtext_sizedefault 10; x-axis text size.
xtext_angledefault 45; x-axis text angle.
facet_scalesdefault "free_x"; the scales parameter of facet_wrap.
Returns
ggplot2 plot.
Examples
\dontrun{
t1$plot_mst()
t1$plot_mst(use_run = "soil2root", group_sink = "Group")
}
Method print()
Print the trans_mst object.
Usage
trans_mst$print()
Method clone()
The objects of this class are cloneable with this method.
Usage
trans_mst$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
## ------------------------------------------------
## Method `trans_mst$new`
## ------------------------------------------------
## Not run:
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
## End(Not run)
## ------------------------------------------------
## Method `trans_mst$cal_mst`
## ------------------------------------------------
## Not run:
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
# same sources for all sinks
t1$cal_mst(sources = "Bulk soil", sinks = "Rhizosphere", EM_iterations = 1000, label = "bulk2rhizo")
# different sources for each sink, paired by Plant_ID
t1$cal_mst(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID", label = "soil2root")
## End(Not run)
## ------------------------------------------------
## Method `trans_mst$cal_mst_chain`
## ------------------------------------------------
## Not run:
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
t1$cal_mst_chain(list(
list(sources = "Bulk soil", sinks = "Rhizosphere"),
list(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID")
))
## End(Not run)
## ------------------------------------------------
## Method `trans_mst$plot_mst`
## ------------------------------------------------
## Not run:
t1$plot_mst()
t1$plot_mst(use_run = "soil2root", group_sink = "Group")
## End(Not run)
microeco documentation built on Oct. 20, 2026, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| trans_mst | R Documentation |
Create trans_mst object for microbial source tracking (MST) analysis.
Description
This class is a wrapper for microbial source tracking based on the FEAST algorithm
(Fast Expectation-maximization for microbial Source Tracking; Shenhav et al. 2019, Nature Methods, <doi:10.1038/s41592-019-0431-x>).
It estimates the contribution proportions of potential source environments to sink samples
(e.g., tracking the microbial transfer from bulk soil to rhizosphere soil and then to root).
The class automatically constructs the metadata (Env, SourceSink, id) required by FEAST
from the sample_table, runs the FEAST package, and provides ggplot2-based
visualization. Results of multiple runs (e.g., sequential transfer steps) can be stored
in the same object using different labels.
Methods
Public methods
Method new()
Usage
trans_mst$new(dataset = NULL, env_col = NULL, filter_thres = 0)
Arguments
datasetmicrotableobject.env_coldefault NULL; a column name in
sample_tableused as the environment description (the "Env" information for FEAST), e.g., "Compartment". If NULL, the environment of each sample is represented by its sample name whencal_mstis called with explicit sample vectors (source_samples/sink_samples).filter_thresdefault 0; the relative abundance threshold for filtering low-abundance taxa. Taxa with total relative abundance < filter_thres will be removed. This is delegated to
dataset$filter_taxa(rel_abund = filter_thres).
Returns
dataset, sample_table, otu_table (taxa x samples counts),
env_col, n_samples, n_taxa stored in the object.
Examples
\dontrun{
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
}
Method cal_mst()
Run FEAST source tracking analysis.
Sources and sinks can be specified either by environment values (sources/sinks,
matched against the env_col column of sample_table) or by explicit sample names
(source_samples/sink_samples).
The function automatically generates the FEAST metadata:
in the same-sources mode (different_sources_flag = 0), all sinks share the same source pool;
in the different-sources mode (different_sources_flag = 1), each sink uses its own source
set defined by the pairing column id_col (samples sharing the same id_col value
belong to the same group, e.g., the same plant individual).
Usage
trans_mst$cal_mst( sources = NULL, sinks = NULL, source_samples = NULL, sink_samples = NULL, different_sources_flag = 0, id_col = NULL, EM_iterations = 1000, COVERAGE = NULL, label = NULL )
Arguments
sourcesdefault NULL; character vector of environment values (in the
env_colcolumn) used as sources, e.g., c("Bulk soil", "Rhizosphere").sinksdefault NULL; character vector of environment values used as sinks, e.g., "Endophyte".
source_samplesdefault NULL; character vector of sample names used as sources. Alternative to
sources; cannot be provided together withsources.sink_samplesdefault NULL; character vector of sample names used as sinks. Alternative to
sinks; cannot be provided together withsinks.different_sources_flagdefault 0; 0 (FALSE) means all sinks use the same source pool; 1 (TRUE) means each sink uses its own source set paired via
id_col.id_coldefault NULL; a column name in
sample_tabledefining the pairing groups for the different-sources mode (required whendifferent_sources_flag = 1). Samples sharing the same value are considered paired, e.g., "Plant_ID". Each pairing group must contain exactly one sink sample; the sources in the group constitute the source set of that sink.EM_iterationsdefault 1000; the number of EM iterations passed to
FEAST::FEAST.COVERAGEdefault NULL; the rarefaction depth. If NULL, the minimum sequencing depth across all involved source and sink samples is used, so all samples are uniformly downsampled.
labeldefault NULL; the label for storing the result, e.g., "bulk2rhizo". If NULL, a label like "run1", "run2", ... is generated automatically. Reusing an existing label overwrites the previous result with the same label.
Returns
res_mst[[label]]: Sink x Source contribution proportions matrix
(rownames: sink sample names; colnames: source sample names + "Unknown"; each row sums to 1);
res_mst_env[[label]]: contributions aggregated by source environment;
res_mst_param[[label]]: parameters and sample information of the run.
Examples
\dontrun{
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
# same sources for all sinks
t1$cal_mst(sources = "Bulk soil", sinks = "Rhizosphere", EM_iterations = 1000, label = "bulk2rhizo")
# different sources for each sink, paired by Plant_ID
t1$cal_mst(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID", label = "soil2root")
}
Method cal_mst_chain()
Run sequential source tracking steps (e.g., bulk soil -> rhizosphere soil -> root).
Usage
trans_mst$cal_mst_chain(steps = NULL)
Arguments
stepsdefault NULL; a list where each element is a list of arguments passed to
cal_mst(withoutlabel), e.g.,list(list(sources = "Bulk soil", sinks = "Rhizosphere"), list(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte")). Each step is stored inres_mst[["step1"]],res_mst[["step2"]], ... unless a customlabelis provided inside the step.
Returns
results stored in res_mst, res_mst_env and res_mst_param.
Examples
\dontrun{
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
t1$cal_mst_chain(list(
list(sources = "Bulk soil", sinks = "Rhizosphere"),
list(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID")
))
}
Method plot_mst()
Plot the source tracking result as a stacked barplot.
Usage
trans_mst$plot_mst( use_run = NULL, use_env = TRUE, group_sink = NULL, show_unknown = TRUE, colors = NULL, unknown_color = "grey80", legend_title = NULL, bar_width = 0.8, xtext_size = 10, xtext_angle = 45, facet_scales = "free_x" )
Arguments
use_rundefault NULL; the label (or index) of the run stored in
res_mst. If NULL, the first run is used.use_envdefault TRUE; whether to use the environment-level aggregated contributions (
res_mst_env). If FALSE, the sample-level contributions (res_mst) are shown.group_sinkdefault NULL; a column name in
sample_tableused to group the sinks. The plot is facetted by this column and the sinks are ordered accordingly, e.g., "Group".show_unknowndefault TRUE; whether to show the "Unknown" contribution.
colorsdefault NULL; a vector of fill colors for the sources. If NULL, the Dark2 (environment level) or Paired (sample level) palette of RColorBrewer is used.
unknown_colordefault "grey80"; the fill color for the "Unknown" source.
legend_titledefault NULL; the legend title. If NULL, "Source" is used.
bar_widthdefault 0.8; the bar width passed to
geom_bar.xtext_sizedefault 10; x-axis text size.
xtext_angledefault 45; x-axis text angle.
facet_scalesdefault "free_x"; the scales parameter of
facet_wrap.
Returns
ggplot2 plot.
Examples
\dontrun{
t1$plot_mst()
t1$plot_mst(use_run = "soil2root", group_sink = "Group")
}
Method print()
Print the trans_mst object.
Usage
trans_mst$print()
Method clone()
The objects of this class are cloneable with this method.
Usage
trans_mst$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
## ------------------------------------------------
## Method `trans_mst$new`
## ------------------------------------------------
## Not run:
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
## End(Not run)
## ------------------------------------------------
## Method `trans_mst$cal_mst`
## ------------------------------------------------
## Not run:
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
# same sources for all sinks
t1$cal_mst(sources = "Bulk soil", sinks = "Rhizosphere", EM_iterations = 1000, label = "bulk2rhizo")
# different sources for each sink, paired by Plant_ID
t1$cal_mst(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID", label = "soil2root")
## End(Not run)
## ------------------------------------------------
## Method `trans_mst$cal_mst_chain`
## ------------------------------------------------
## Not run:
data(soil_microb)
t1 <- trans_mst$new(dataset = soil_microb, env_col = "Compartment")
t1$cal_mst_chain(list(
list(sources = "Bulk soil", sinks = "Rhizosphere"),
list(sources = c("Bulk soil", "Rhizosphere"), sinks = "Endophyte",
different_sources_flag = 1, id_col = "Plant_ID")
))
## End(Not run)
## ------------------------------------------------
## Method `trans_mst$plot_mst`
## ------------------------------------------------
## Not run:
t1$plot_mst()
t1$plot_mst(use_run = "soil2root", group_sink = "Group")
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.