trans_niche: Create 'trans_niche' object for niche breadth and niche...
In microeco: Microbial Community Ecology Data Analysis
trans_niche R Documentation
Create trans_niche object for niche breadth and niche overlap analysis.
Description
This class is a wrapper for niche breadth and niche overlap calculations,
including Levins' niche breadth, Pianka's niche overlap, and environment/trait-based
methods: OMI (Outlying Mean Index) based on Doledec et al. (2000) <doi:10.1890/0012-9658(2000)081[2914:NSICAA]2.0.CO;2>,
N-dimensional Hypervolume based on Blonder et al. (2014) <doi:10.1111/geb.12146> and Blonder (2018) <doi:10.1111/ecog.03187>,
and TPD (Trait Probability Density) based on Carmona et al. (2016) <doi:10.1016/j.tree.2016.02.003>.
Methods
Public methods
-
-
-
-
-
-
-
Method new()
Usage
trans_niche$new(
dataset = NULL,
filter_thres = 0,
env_cols = NULL,
add_data = NULL,
taxa_level = NULL,
taxa_name = NULL
)
Arguments
datasetmicrotable object.
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).
env_colsdefault NULL; character vector of column names in dataset$sample_table
to be used as environmental variables. Only numeric columns are supported.
Passed to trans_env for processing (NA check and auto-fill).
add_datadefault NULL; a data.frame of environmental variables with sample names as row names.
If provided, it takes priority over env_cols.
Passed to trans_env for processing (NA check and auto-fill).
taxa_leveldefault NULL; a taxonomic rank in tax_table used for filtering taxa at object creation.
taxa_namedefault NULL; a character vector of taxa names at taxa_level used for filtering.
Must be provided together with taxa_level. Useful when feature number is large.
Returns
data_rel_abund, n_samples, n_taxa, dataset, sample_table
and optionally data_env stored in the object.
Examples
\dontrun{
data(dataset)
t1 <- trans_niche$new(dataset = dataset)
}
Method cal_niche_breadth()
Calculate niche breadth for each taxon.
Usage
trans_niche$cal_niche_breadth(
method = c("levins", "OMI", "hypervolume", "TPD")[1],
...
)
Arguments
methoddefault "levins"; the method for niche breadth calculation.
Options:
- 'levins'
Levins' niche breadth
- 'OMI'
Outlying Mean Index via ade4 package; Doledec et al. (2000) <doi:10.1890/0012-9658(2000)081[2914:NSICAA]2.0.CO;2>
- 'hypervolume'
N-dimensional hypervolume via hypervolume package; Blonder et al. (2014) <doi:10.1111/geb.12146>; Blonder (2018) <doi:10.1111/ecog.03187>
- 'TPD'
Trait Probability Density via TPD package; Carmona et al. (2016) <doi:10.1016/j.tree.2016.02.003>
...additional parameters passed to the specific method:
- OMI:
n_axis default 2; number of niche axes to retain.
- hypervolume:
dims default 3; number of PCA dimensions for hypervolume construction.
min_points default 5; minimum number of occurrence samples required.
kde.bandwidth default "silverman"; bandwidth for kernel density estimation.
quantile.requested default 0.95; probability density quantile threshold.
samples.per.point default NULL; samples per point for hypervolume construction.
- TPD:
dims default 2; number of PCA dimensions for TPD calculation.
alpha default 0.95; probability density quantile threshold.
Returns
res_niche_breadth stored in the object. For OMI/hypervolume/TPD methods,
intermediate objects are also stored in res_omi, res_hypervolume, or res_TPD.
Examples
\dontrun{
t1$cal_niche_breadth()
}
Method cal_niche_overlap()
Calculate niche overlap matrix among taxa.
Usage
trans_niche$cal_niche_overlap(
method = c("pianka", "OMI", "hypervolume", "TPD")[1],
...
)
Arguments
methoddefault "pianka"; the method for niche overlap calculation.
Options:
- 'pianka'
Pianka's niche overlap
- 'OMI'
based on OMI axes; Doledec et al. (2000) <doi:10.1890/0012-9658(2000)081[2914:NSICAA]2.0.CO;2>
- 'hypervolume'
based on hypervolume intersection; Blonder et al. (2014) <doi:10.1111/geb.12146>; Blonder (2018) <doi:10.1111/ecog.03187>
- 'TPD'
based on TPD probability density overlap; Carmona et al. (2016) <doi:10.1016/j.tree.2016.02.003>
...additional parameters passed to the specific method:
- OMI:
n_axis default 2; number of OMI axes used for overlap calculation.
- hypervolume:
overlap_metric default "jaccard"; overlap metric,
either "jaccard" or "sorensen".
- TPD:
symmetric default TRUE; whether to compute symmetric overlap.
When TRUE, the geometric mean of the two directional overlaps is used (analogous
to Pianka's symmetric formulation). When FALSE, the raw directional overlaps
O(i,j) and O(j,i) are stored in the upper and lower triangles respectively,
producing an asymmetric matrix.
Returns
res_niche_overlap stored in the object, a matrix of dimension Taxa x Taxa.
For TPD method with symmetric = FALSE, the matrix is asymmetric where
overlap[i,j] represents the proportion of taxon i's niche overlapped by taxon j.
Examples
\dontrun{
t1$cal_niche_overlap()
}
Method plot_niche_breadth()
Plot the niche breadth result as a horizontal bar plot.
Usage
trans_niche$plot_niche_breadth(
measure = NULL,
ntaxa = 20,
add_prefix = TRUE,
taxa_level = "Genus",
sep = " : ",
color = RColorBrewer::brewer.pal(8, "Dark2")[2],
barwidth = 0.7,
ytext_size = 11
)
Arguments
measuredefault NULL; a column name in res_niche_breadth used as the bar length or an integer to select the column name.
If NULL, the first numeric column except Taxa is used automatically.
ntaxadefault 20; number of top taxa to show, ordered by measure from high to low.
add_prefixdefault TRUE; whether prepend the taxonomic name to the y-axis taxa labels.
taxa_leveldefault "Genus"; the taxonomic level used when add_prefix is TRUE
sepdefault " : "; separator between genus name and taxa name.
colordefault RColorBrewer::brewer.pal(8, "Dark2")[2]; bar fill color.
barwidthdefault 0.7; bar width passed to geom_bar.
ytext_sizedefault 11; y-axis text size.
Returns
ggplot2 plot.
Examples
\dontrun{
t1$plot_niche_breadth()
}
Method plot_niche_overlap()
Plot the niche overlap matrix as a heatmap.
Usage
trans_niche$plot_niche_overlap(
taxa_level = NULL,
taxa_name = NULL,
color_low = "white",
color_high = RColorBrewer::brewer.pal(8, "Dark2")[2],
plot_breaks = NULL,
withmargin = TRUE,
margincolor = "white",
xtext_size = 9,
ytext_size = 9,
add_anno = FALSE,
add_anno_level = "Phylum",
anno_color = "grey60",
anno_text_size = 9,
anno_line_size = 0.5
)
Arguments
taxa_leveldefault NULL; a taxonomic rank in tax_table used for filtering taxa.
taxa_namedefault NULL; a character vector of taxa names at taxa_level used for filtering.
Must be provided together with taxa_level.
color_lowdefault "white"; color for low overlap values.
color_highdefault RColorBrewer::brewer.pal(8, "Dark2")[2]; color for high overlap values.
plot_breaksdefault NULL; breaks for the color scale.
withmargindefault TRUE; whether draw tile margins.
margincolordefault "white"; margin color when withmargin = TRUE.
xtext_sizedefault 9; x-axis text size.
ytext_sizedefault 9; y-axis text size.
add_annodefault FALSE; whether add taxonomic group annotation lines and labels to x and y axes.
When it is TRUE, the feature names will not be shown.
add_anno_leveldefault "Phylum"; the taxonomic rank used for axis annotation.
anno_colordefault "grey60"; color of the annotation lines and labels.
anno_text_sizedefault 9; text size of the annotation labels.
anno_line_sizedefault 0.5; line width of the annotation lines.
Returns
ggplot2 plot.
Examples
\dontrun{
t1$plot_niche_overlap()
}
Method print()
Print the trans_niche object.
Usage
trans_niche$print()
Method clone()
The objects of this class are cloneable with this method.
Usage
trans_niche$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
## ------------------------------------------------
## Method `trans_niche$new`
## ------------------------------------------------
## Not run:
data(dataset)
t1 <- trans_niche$new(dataset = dataset)
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$cal_niche_breadth`
## ------------------------------------------------
## Not run:
t1$cal_niche_breadth()
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$cal_niche_overlap`
## ------------------------------------------------
## Not run:
t1$cal_niche_overlap()
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$plot_niche_breadth`
## ------------------------------------------------
## Not run:
t1$plot_niche_breadth()
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$plot_niche_overlap`
## ------------------------------------------------
## Not run:
t1$plot_niche_overlap()
## 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_niche | R Documentation |
Create trans_niche object for niche breadth and niche overlap analysis.
Description
This class is a wrapper for niche breadth and niche overlap calculations, including Levins' niche breadth, Pianka's niche overlap, and environment/trait-based methods: OMI (Outlying Mean Index) based on Doledec et al. (2000) <doi:10.1890/0012-9658(2000)081[2914:NSICAA]2.0.CO;2>, N-dimensional Hypervolume based on Blonder et al. (2014) <doi:10.1111/geb.12146> and Blonder (2018) <doi:10.1111/ecog.03187>, and TPD (Trait Probability Density) based on Carmona et al. (2016) <doi:10.1016/j.tree.2016.02.003>.
Methods
Public methods
Method new()
Usage
trans_niche$new( dataset = NULL, filter_thres = 0, env_cols = NULL, add_data = NULL, taxa_level = NULL, taxa_name = NULL )
Arguments
datasetmicrotableobject.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).env_colsdefault NULL; character vector of column names in
dataset$sample_tableto be used as environmental variables. Only numeric columns are supported. Passed totrans_envfor processing (NA check and auto-fill).add_datadefault NULL; a data.frame of environmental variables with sample names as row names. If provided, it takes priority over
env_cols. Passed totrans_envfor processing (NA check and auto-fill).taxa_leveldefault NULL; a taxonomic rank in
tax_tableused for filtering taxa at object creation.taxa_namedefault NULL; a character vector of taxa names at
taxa_levelused for filtering. Must be provided together withtaxa_level. Useful when feature number is large.
Returns
data_rel_abund, n_samples, n_taxa, dataset, sample_table
and optionally data_env stored in the object.
Examples
\dontrun{
data(dataset)
t1 <- trans_niche$new(dataset = dataset)
}
Method cal_niche_breadth()
Calculate niche breadth for each taxon.
Usage
trans_niche$cal_niche_breadth(
method = c("levins", "OMI", "hypervolume", "TPD")[1],
...
)Arguments
methoddefault "levins"; the method for niche breadth calculation. Options:
- 'levins'
Levins' niche breadth
- 'OMI'
Outlying Mean Index via ade4 package; Doledec et al. (2000) <doi:10.1890/0012-9658(2000)081[2914:NSICAA]2.0.CO;2>
- 'hypervolume'
N-dimensional hypervolume via hypervolume package; Blonder et al. (2014) <doi:10.1111/geb.12146>; Blonder (2018) <doi:10.1111/ecog.03187>
- 'TPD'
Trait Probability Density via TPD package; Carmona et al. (2016) <doi:10.1016/j.tree.2016.02.003>
...additional parameters passed to the specific method:
- OMI:
n_axisdefault 2; number of niche axes to retain.- hypervolume:
dimsdefault 3; number of PCA dimensions for hypervolume construction.min_pointsdefault 5; minimum number of occurrence samples required.kde.bandwidthdefault "silverman"; bandwidth for kernel density estimation.quantile.requesteddefault 0.95; probability density quantile threshold.samples.per.pointdefault NULL; samples per point for hypervolume construction.- TPD:
dimsdefault 2; number of PCA dimensions for TPD calculation.alphadefault 0.95; probability density quantile threshold.
Returns
res_niche_breadth stored in the object. For OMI/hypervolume/TPD methods,
intermediate objects are also stored in res_omi, res_hypervolume, or res_TPD.
Examples
\dontrun{
t1$cal_niche_breadth()
}
Method cal_niche_overlap()
Calculate niche overlap matrix among taxa.
Usage
trans_niche$cal_niche_overlap(
method = c("pianka", "OMI", "hypervolume", "TPD")[1],
...
)Arguments
methoddefault "pianka"; the method for niche overlap calculation. Options:
- 'pianka'
Pianka's niche overlap
- 'OMI'
based on OMI axes; Doledec et al. (2000) <doi:10.1890/0012-9658(2000)081[2914:NSICAA]2.0.CO;2>
- 'hypervolume'
based on hypervolume intersection; Blonder et al. (2014) <doi:10.1111/geb.12146>; Blonder (2018) <doi:10.1111/ecog.03187>
- 'TPD'
based on TPD probability density overlap; Carmona et al. (2016) <doi:10.1016/j.tree.2016.02.003>
...additional parameters passed to the specific method:
- OMI:
n_axisdefault 2; number of OMI axes used for overlap calculation.- hypervolume:
overlap_metricdefault "jaccard"; overlap metric, either "jaccard" or "sorensen".- TPD:
symmetricdefault TRUE; whether to compute symmetric overlap. When TRUE, the geometric mean of the two directional overlaps is used (analogous to Pianka's symmetric formulation). When FALSE, the raw directional overlaps O(i,j) and O(j,i) are stored in the upper and lower triangles respectively, producing an asymmetric matrix.
Returns
res_niche_overlap stored in the object, a matrix of dimension Taxa x Taxa.
For TPD method with symmetric = FALSE, the matrix is asymmetric where
overlap[i,j] represents the proportion of taxon i's niche overlapped by taxon j.
Examples
\dontrun{
t1$cal_niche_overlap()
}
Method plot_niche_breadth()
Plot the niche breadth result as a horizontal bar plot.
Usage
trans_niche$plot_niche_breadth( measure = NULL, ntaxa = 20, add_prefix = TRUE, taxa_level = "Genus", sep = " : ", color = RColorBrewer::brewer.pal(8, "Dark2")[2], barwidth = 0.7, ytext_size = 11 )
Arguments
measuredefault NULL; a column name in
res_niche_breadthused as the bar length or an integer to select the column name. If NULL, the first numeric column exceptTaxais used automatically.ntaxadefault 20; number of top taxa to show, ordered by
measurefrom high to low.add_prefixdefault TRUE; whether prepend the taxonomic name to the y-axis taxa labels.
taxa_leveldefault "Genus"; the taxonomic level used when
add_prefixisTRUEsepdefault " : "; separator between genus name and taxa name.
colordefault RColorBrewer::brewer.pal(8, "Dark2")[2]; bar fill color.
barwidthdefault 0.7; bar width passed to
geom_bar.ytext_sizedefault 11; y-axis text size.
Returns
ggplot2 plot.
Examples
\dontrun{
t1$plot_niche_breadth()
}
Method plot_niche_overlap()
Plot the niche overlap matrix as a heatmap.
Usage
trans_niche$plot_niche_overlap( taxa_level = NULL, taxa_name = NULL, color_low = "white", color_high = RColorBrewer::brewer.pal(8, "Dark2")[2], plot_breaks = NULL, withmargin = TRUE, margincolor = "white", xtext_size = 9, ytext_size = 9, add_anno = FALSE, add_anno_level = "Phylum", anno_color = "grey60", anno_text_size = 9, anno_line_size = 0.5 )
Arguments
taxa_leveldefault NULL; a taxonomic rank in
tax_tableused for filtering taxa.taxa_namedefault NULL; a character vector of taxa names at
taxa_levelused for filtering. Must be provided together withtaxa_level.color_lowdefault "white"; color for low overlap values.
color_highdefault RColorBrewer::brewer.pal(8, "Dark2")[2]; color for high overlap values.
plot_breaksdefault NULL; breaks for the color scale.
withmargindefault TRUE; whether draw tile margins.
margincolordefault "white"; margin color when
withmargin = TRUE.xtext_sizedefault 9; x-axis text size.
ytext_sizedefault 9; y-axis text size.
add_annodefault FALSE; whether add taxonomic group annotation lines and labels to x and y axes. When it is TRUE, the feature names will not be shown.
add_anno_leveldefault "Phylum"; the taxonomic rank used for axis annotation.
anno_colordefault "grey60"; color of the annotation lines and labels.
anno_text_sizedefault 9; text size of the annotation labels.
anno_line_sizedefault 0.5; line width of the annotation lines.
Returns
ggplot2 plot.
Examples
\dontrun{
t1$plot_niche_overlap()
}
Method print()
Print the trans_niche object.
Usage
trans_niche$print()
Method clone()
The objects of this class are cloneable with this method.
Usage
trans_niche$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Examples
## ------------------------------------------------
## Method `trans_niche$new`
## ------------------------------------------------
## Not run:
data(dataset)
t1 <- trans_niche$new(dataset = dataset)
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$cal_niche_breadth`
## ------------------------------------------------
## Not run:
t1$cal_niche_breadth()
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$cal_niche_overlap`
## ------------------------------------------------
## Not run:
t1$cal_niche_overlap()
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$plot_niche_breadth`
## ------------------------------------------------
## Not run:
t1$plot_niche_breadth()
## End(Not run)
## ------------------------------------------------
## Method `trans_niche$plot_niche_overlap`
## ------------------------------------------------
## Not run:
t1$plot_niche_overlap()
## 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.