Computes the three variance ratios of Violle et al. (2012) for each site (community) and
trait, from trait values of individuals such as those of sample_individuals():
Arguments
- individuals
Data frame with one row per individual, such as from
sample_individuals().- traits
Names of the columns with trait values.
- site, species
Names of the columns with the site and the species of each individual.
- method
"base"(the default), computed in base R, or"cati"forcati::Tstats(); it needs the package cati.- n_perm
Number of randomisations of the null models; 0 or
NULLfor the observed values only, much faster in simulation studies with many replicates.- alternative
Direction of the test of
method = "base":"less"(the default),"greater"or"two.sided".- null_ip
Null model of
T_IP.ICformethod = "base":"site"(the default), trait values permuted within each site as in Taudiere & Violle (2016), or"species", the means of populations exchanged among the populations of each species (see the section Null models).- ...
Further arguments to
cati::Tstats(), such asreg.poolorindependantTraits.- nperm
Deprecated; use
n_perm.
Value
With method = "base", a data frame with one row per site and trait and the columns
site, trait, n_populations, T_IP.IC, T_IC.IR and T_PC.PR; statistics that
cannot be computed, such as T_PC.PR for a site with one species, are NA. With
n_perm > 0, also ses_ and p_ columns for each statistic, and the attribute null,
an array (randomisation x row x statistic) with the null values. With method = "cati",
the Tstats object of cati::Tstats(), with the site names of individuals.
Details
T_IP.IC, the mean variance among individuals within the populations of the site over the variance among all individuals of the site. Low values mean that the populations of co-occurring species overlap little (niche differentiation within the community).T_IC.IR, the variance among individuals of the site over that among all individuals of the region. Low values mean that the site holds a narrow part of the regional trait range (environmental filtering of individuals).T_PC.PR, the variance among population means within the site over that among all population means of the region. Low values mean filtering of populations.
A population is a species at a site. Variances use n - 1, means of the variances within
populations are not weighted, and populations of a single individual have no variance and
are left out of T_IP.IC, as in cati::Tstats(). Individuals with a missing value of a
trait are left out for that trait.
Null models
With n_perm > 0, method = "base" compares each statistic with a null distribution, from
the three null models of Taudiere & Violle (2016), implemented in base R from their
description:
T_IP.IC: trait values are permuted among the individuals of each site, which keeps the variance of the site and breaks the structure of populations within it;T_IC.IR: each site receives as many individuals as it has, drawn without replacement from all individuals of the region;T_PC.PR: each individual takes the mean of its population, and each site then receives as many of these values as it has individuals, drawn without replacement from the region; population means are computed again from the values drawn.
The null model of T_IC.IR leaves the regional pool as it is, so its denominator (the
variance among all individuals) stays that of the observed data, and only the variance
within sites is randomised. Taking the denominator from the values drawn, which repeat
individuals across sites, biases the null and makes the test anti-conservative. In the null
model of T_PC.PR the population means are themselves computed from the values drawn, so
their regional variance is computed again from them, as in Taudiere & Violle (2016).
The standardised effect size is \((T_{obs} - \bar T_{null}) / s_{null}\), and the p-value is \((1 + r) / (1 + n)\),
with \(n\) = n_perm, where \(r\) is the number of null values at or below the observed
one (alternative = "less"), at or above it ("greater"), or twice the smaller of the two
("two.sided", at most 1). Low values of the three statistics are the usual hypotheses
(niche differentiation within communities for T_IP.IC, environmental filtering for the
others), so "less" tests them. Each trait is randomised on its own.
The null model of T_IP.IC asks only whether populations differ: permuting individuals
within a site removes its populations, so null values are near 1, and co-occurring species
with different means give a large negative effect size even when each population sits where
its species would be at any site. With null_ip = "species", the mean of each
population is instead exchanged at random with that of another population of the same
species, and its individuals keep their number and their deviations from the mean. Each site
keeps its species, their abundances and the variances within populations; only which mean of
a species sits at which site is broken. Moving whole populations instead would also break
the match between the abundance of a species at a site and its trait, which environmental
filtering of abundances creates, and would test that instead. The standardised effect size is near zero when the position of a population does not depend on
the site, positive when co-occurring populations are closer than expected from their species
(convergence, as under local adaptation to a shared environment), and negative when they are
further apart (divergence, as under character displacement); alternative = "two.sided"
tests both. Species found at a single site keep their mean. Means of populations with
different numbers of individuals carry different sampling error and are not fully
exchangeable, which makes the test conservative (effect sizes shrink toward zero and a test
at 5% rejects less often than 5% when nothing acts) but not anti-conservative. Local adaptation and character
displacement move this statistic in opposite directions and can cancel; see
population_shifts() to estimate both.
method = "cati" calls cati::Tstats() (Taudiere & Violle 2016) instead and returns its
object. Both methods give the same observed values. Two problems of cati 0.99.6 affect it:
cati::Tstats() finds the populations of a site by matching its name as a regular
expression, so a site called site1 would also take the populations of site10
(https://github.com/adrientaudiere/cati/issues/11); the sites are therefore passed
under labels of equal width (site01, site02, ...) and given back their names in the
result. And its null model for T_IP.IC puts together the permutations of different sites
in the wrong order, so that the null values of a site come from the individuals of other
sites; its standardised effect sizes for T_IP.IC are then wrong
(https://github.com/adrientaudiere/cati/issues/12). method = "base" is recommended.
Local adaptation and character displacement
With local_adaptation in sample_individuals(), population means move toward the
environment of their site, so co-occurring species become more alike and the region spreads
along the environment. The variance among populations within a site falls, so T_PC.PR and
T_IC.IR fall, and T_IP.IC rises, because the populations that remain overlap more. With
displacement, co-occurring populations diverge from one another instead, which raises the
variance among populations within sites and lowers T_IP.IC.
References
Taudiere, A., & Violle, C. (2016). cati: an R package using functional traits to detect and quantify multi-level community assembly processes. Ecography, 39, 699–708. doi:10.1111/ecog.01433
Violle, C., Enquist, B. J., McGill, B. J., Jiang, L., Albert, C. H., Hulshof, C., Jung, V., & Messier, J. (2012). The return of the variance: intraspecific variability in community ecology. Trends in Ecology & Evolution, 27, 244–252. doi:10.1016/j.tree.2011.11.014
See also
tstats_summary() to summarise the tests, sample_individuals(),
population_shifts().
Other trait variation among individuals:
community_index(),
drift_test(),
neighbour_metrics,
nested_variance(),
null_intervals(),
plot.mc_trait_gradient(),
plot.nested_variance(),
plot.trait_flex(),
plot.trait_rarefaction(),
plot.tstats(),
plot_population_traits(),
population_shifts(),
sample_individuals(),
subsample_individuals(),
trait_densities(),
trait_flex(),
trait_gradient(),
trait_gradient_bayes(),
trait_gradient_phylo(),
trait_gradient_test(),
trait_gradient_weights(),
trait_rarefaction(),
tstats_summary()
Examples
set.seed(1)
tree <- treeshapesim::sim_tree_shape(20)
sim <- simulate_metacommunity(landscape_implicit(15), species_traits(tree),
competition_matrix(tree, "none"), n_steps = 100,
seed_steps = 1:5)
ratios <- c("T_IP.IC", "T_IC.IR", "T_PC.PR")
none <- tstats(sample_individuals(sim, intraspecific_sd = 2), n_perm = 0)
local <- tstats(sample_individuals(sim, local_adaptation = 0.8, intraspecific_sd = 2),
n_perm = 0)
apart <- tstats(sample_individuals(sim, displacement = 2, intraspecific_sd = 2), n_perm = 0)
rbind(none = colMeans(none[ratios], na.rm = TRUE),
local = colMeans(local[ratios], na.rm = TRUE),
apart = colMeans(apart[ratios], na.rm = TRUE))
#> T_IP.IC T_IC.IR T_PC.PR
#> none 0.02299744 0.89106250 1.11059919
#> local 0.33914930 0.03219661 0.03057455
#> apart 0.01278061 0.91639355 1.13307743
# standardised effect sizes and p-values from the null models
res <- tstats(sample_individuals(sim, intraspecific_sd = 2), n_perm = 99)
head(res[c("site", "T_IP.IC", "ses_T_IP.IC", "p_T_IP.IC")])
#> site T_IP.IC ses_T_IP.IC p_T_IP.IC
#> 1 site1 0.016376543 -13.545376 0.01
#> 2 site2 0.079715195 -22.236577 0.01
#> 3 site3 0.012470128 -10.490671 0.01
#> 4 site4 0.019383034 -23.070752 0.01
#> 5 site5 0.056784711 -6.326309 0.01
#> 6 site6 0.005298958 -9.945998 0.01
