CWMSNC_regressions: Weigthed averaging methods for pairwise trait-environment...

In CajoterBraak/TraitEnvMLMWA: Weighted Averaging (WA) and Multi-Level Methods (MLM) for Trait-Environment Association in Functional and Community Ecology

Weigthed averaging methods for pairwise trait-environment associations

Description

CWMSNC_regressions carries out weighted or unweighted CWM/SNC regression for each combition of trait and environmental variable with permutation testing via the max test and computation of the (un)weighted fourth-corner correlations. The output can be summarized and plotted using summary and plot.

Usage

CWMSNC_regressions(
  E,
  L,
  T,
  weighing = "N2",
  cutoff = 0,
  nrepet = 499,
  how_to_permute = list(sites = how(), species = how())
)

Arguments

E	a data frame, numeric n-vector, factor or n-by-p matrix, containing the values of the environmentalvariables in n sites, or a TE_obj object containing the trait, environment and abundance data,
L	a n by m matrix or data frame of abundance values of m species in n sites
T	a data frame, numeric m-vector, factor or m-by-q matrix, containing the values of the trait(s) for m species
weighing	type of weights used in the regression of CWM on E and SNC on T; "unw", "FC" or "N2" (default)
cutoff	minimal number of occurrences of species
nrepet	number of permutations
how_to_permute	a list for two how calls from the permute package, the first for site permutation, the second for species permutation. Default: completely random permuation.

Details

CWMSNC_regressions is for pairwise association between traits and environmental variables. Factors in E and T data frames are expanded in to dummy variable format. For p-values of an entire factor, use WA_p_max. Entering E and T as matrices or data frames has the advantage the variable names are retained.

The permutation test(s) are carried out by the max test. This test takes the maximum of the p-values of the CWM-E regression(s) and the SNC-T regression(s). Both p-values are obtained by permutation. In the former, the rows of E are permuted (i.e. the sites), in the latter the rows of T are permuted (i.e. the species).

Details of the weighing options: "FC" give the results of the unembellished fourth-corner correlation (which uses weighting by site and species totals); "unw" gives each site and species equal weight in the regression; "N2" weighs each site and species in proportion to its Hill number of order 2 (N2); i.e. the effective richness of the site and effective number of occurrences of the species. All weighing variants use the same CWM and SNC values (the weights in calculating CWM and SNC being the abundances in L).

The option nperm in how is overruled by nrepet.

Value

An object of class CWMSNCr which is a named list, among which,

p_values	three permutational p-values: site-based and species-based and the maximum of these two values
p_parametric	parametric p-values: site-based and species-based and the maximum of these two values (can be trusted only for weighing =='unw'). NA for more than one trait or one environmental variable.
wFC	(weighted) fourth-corner correlations for sites and species and its signed minimum.
lm_CWMe	lm-object of the (possibly multiple!) regression of CWM on E. This item is pairwise only for a single environmental variable.
lm_SNCt	lm-object of the (possibly multiple!) regression of SNC on T. This item is pairwise only for a single trait.

References

ter Braak (2019) New robust weighted averaging- and model-based methods for assessing trait-environment relationships. Methods in Ecology and Evolution (https://doi.org/10.1111/2041-210X.13278)

ter Braak, C.J.F., Peres-Neto, P.R. & Dray, S. (2018) Simple parametric tests for trait–environment association. Journal of Vegetation Science, 29, 801-811. https://doi.org//10.1111/jvs.12666

Peres-Neto, P.R., Dray, S. & ter Braak, C.J.F. (2017) Linking trait variation to the environment: critical issues with community-weighted mean correlation resolved by the fourth-corner approach. Ecography, 40, 806-816. https://doi.org/10.1111/ecog.02302

See Also

plot.CWMSNCr and summary.CWMSNCr.

Examples

# Aravo data set ----------------------------------------------------------
data("aravo",  package = "ade4")
Y <- aravo$spe
SLA <- aravo$traits$SLA
Snow <- aravo$env$Snow
nrepet <- 19 # change to e.g. 499 or 999
result <- CWMSNC_regressions(Snow, Y, SLA, weighing = "N2", nrepet = nrepet)
result$p_values
summary(result)
plot(result)

# untransformed analysis of all pairs. See TutorialWA_Aravo_Multi.r
#                                      for transformations that appear useful
#  data frames E,L,T
result <- CWMSNC_regressions(aravo$env, aravo$spe, aravo$traits, weighing = "N2", nrepet = nrepet)
#result$p_values # contains all pairwise p-values
#                  for site-based, species-based and max-based permutations
#result$wFC      # contains all pairwise weighted fourth-corner correlations
# (site-based, species-based, and signed min-based)
summary(result, type = "max", p_value_adjust_method = "fdr", significance_level = 0.05)
# in the  E or T matrix or data frame case, you cannot choose your own labels;
# names shoud refer to names of variables or labels of factors
(nam.list <- plot(result, trait = "", env = "" ))
plot(result, trait = "Spread", env = "Snow" )
## All plots
# for (trait in nam.list$trait.names){
#   for (env in nam.list$env.names){
#     print(plot(result, trait = trait, env = env ))
#   }
# }

# get Revisit data ---------------------------------------------------
data("Revisit")
## adapt dataframe dat for WA-based analyses
n_sites <- with(Revisit, nlevels(factor(site)))
n_species <- with(Revisit, nlevels(factor(species)))
species <- Revisit$species[seq(from  = 1, by = n_sites, length.out = n_species)]
sites <- Revisit$site[1:n_sites]
trait <- Revisit$trait[seq(from  = 1, by = n_sites, length.out = n_species)]
env <- Revisit$env[1:n_sites]
Y <- matrix(Revisit$value, nrow = n_sites,ncol = n_species,
            dimnames = list(sites= sites,species=species))
# #Alternative using the function dat4MLM2TE_obj
# TE_obj <- dat4MLM2TE_obj(Revisit)
# trait <- TE_obj$T; env <- TE_obj$E; Y <- TE_obj$L
#  CWM/SNC regressions ------------------------------------------
set.seed(1231)
result <- CWMSNC_regressions(env, Y, trait, weighing = "N2", nrepet = nrepet)
summary(result)
plot(result)



# Comparison of two versions of the max test------------------------------------
obj <- make_obj_for_traitenv(env,Y, trait, cutoff=0)
set.seed(1231)
# slow
system.time(aa<- WA_p_max(obj, nrepet = nrepet, fast = FALSE))
round(aa$p_values,4)

set.seed(1231)
# default
system.time(bb<- WA_p_max(obj, nrepet = nrepet, fast = TRUE))
round(bb$p_values,4)
# illustrating their equality
or1<- order(aa$sim.row)
or2<- order(bb$sim.row)
all.equal(or1,or2)
or1<- order(aa$sim.col)
or2<- order(bb$sim.col)
all.equal(or1,or2)


# fast, all three weighings   --------------------------------------------------

system.time(bb<- WA_p_max(obj, weighing = "N2", nrepet = nrepet))
round(bb$p_values,5)

system.time(FC<- WA_p_max(obj, weighing = "FC", nrepet = nrepet))
round(FC$p_values,5)

system.time(cc<- WA_p_max(obj, weighing = "unw", nrepet = nrepet))
round(cc$p_values,5)

# comparion with fourtcorner in ade4  ---------------------------------------

ade4::fourthcorner(data.frame(env),as.data.frame(Y),data.frame(trait), nrepet = nrepet)
result <- CWMSNC_regressions(env, Y, trait, weighing = "FC", nrepet = nrepet)
summary(result,digits = 4)

CajoterBraak/TraitEnvMLMWA documentation built on Jan. 25, 2023, 7:36 p.m.