Standardized effect sizes

In SESraster: Raster Randomization for Null Hypothesis Testing

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Contents

• Standardized effect sizes
• Calculating SES
  • Random species generation
  • SES with spatial randomization
  • SES from species trait randomization
• Conclusion
• References

After understanding how the spatial null model algorithms work (vignette("spatial-null-models")), let's see how to create multiple null models and test for the effect size using SESraster().

Standardized effect size {#ses}

Standardized effect size (SES) is a measure of the magnitude of the studied effect. It indicates the direction and the degree that the effect departures from the null model. SESraster uses Cohen's d [@cohen1988], which is measured as the difference between the observed pattern and the average of n randomized observations divided by the standard deviation of the randomized observations $SES = (Obs-mean(Null))/sd(Null)$.

Calculating SES {#analysis}

Random species generation {#randsp}

First, we will create some random species distributions using the package terra.

library(SESraster)
library(terra)
# creating random species distributions
f <- system.file("ex/elev.tif", package="terra")
r <- rast(f)
set.seed(510)
r <- rast(lapply(1:18,
                function(i, r, mn, mx){
                  app(r, function(x, t){
                    sapply(x, function(x, t){
                       x<max(t) & x>min(t)
                    }, t = t)
                  }, t = sample(seq(mn, mx), 2))
                }, r = r, mn = minmax(r)[1]+10, mx = minmax(r)[2]-10))

names(r) <- paste("sp", 1:nlyr(r))
plot(r)

With the distributions in hand, we can perform the spatial randomizations.

SES with spatial randomization {#ses-spat}

First we need a function that computes the desired metric. The function must work with spatial data. Just to exemplify, we are creating a function to compute the mean of presences and absences (1/0) within each cell. You probably wants to use a more ecologically meaningful function, but here is just an example of use.

appmean <- function(x, ...){
                      terra::app(x, "mean", ...)
}

Now, to compute SES, we will compute our desired metric by sending our function appmean() to SESraster() through FUN argument. We also randomize the original data by species using the bootspat_naive() algorithm and passing the argument random="species" through spat_alg_args.

ses.sp <- SESraster(r, FUN = appmean, 
                    spat_alg = "bootspat_naive", spat_alg_args = list(random = "species"),
                    aleats = 5)
plot(ses.sp)

Compute metric and SES using bootspat_naive() and randomize by site changing the argument to random="site" in spat_alg_args.

ses.st <- SESraster(r, FUN = appmean,
                    spat_alg = "bootspat_naive", spat_alg_args = list(random = "site"),
                    aleats = 5)
plot(ses.st)

Passing arguments to FUN {#ses-fun-arg}

It is also possible to send arguments to the function that calculates the desired metric (FUN). It can be done by sending a list of arguments through FUN_args.

## let's create some missing values for layer/species 1
r2 <- r
set.seed(10)
cellsNA <- terra::spatSample(r2, 30, na.rm = TRUE, cells = TRUE, values = FALSE)
r2[cellsNA][1] <- NA
# plot(r)
set.seed(10)
sesNA <- SESraster(r2, FUN = appmean, FUN_args = list(na.rm = FALSE),
                   spat_alg = "bootspat_naive", spat_alg_args=list(random = "species"),
                   aleats = 5)
head(sesNA[cellsNA])
plot(sesNA)

Notice that NAs can be ignored by the appmean() function by using FUN_args = list(na.rm = TRUE):

set.seed(10)
ses.woNA <- SESraster(r2, FUN = appmean, FUN_args = list(na.rm = TRUE), 
                      spat_alg = "bootspat_naive", spat_alg_args=list(random = "species"),
                      aleats = 5)
head(ses.woNA[cellsNA])
plot(ses.woNA)

SES from species trait randomization {#ses-trait}

In addition to the spatial randomizations, it is possible to create a null model by randomizing a parameter (i.e. argument) of the metric passed to FUN. This is useful, for example, to randomize a species trait (e.g. branch length) that is used to compute the metric. In the example below the function appsv() uses the argument lyrv to compute the fictional metric. We also create some fictional values for the trait.

## example with `Fa_alg`
appsv <- function(x, lyrv, na.rm = FALSE, ...){
                      sumw <- function(x, lyrv, na.rm, ...){
                        ifelse(all(is.na(x)), NA,
                               sum(x*lyrv, na.rm=na.rm, ...))
                      }
                      stats::setNames(terra::app(x, sumw, lyrv = lyrv, na.rm=na.rm, ...), "sumw")
}

set.seed(10)
trait  <- sample(100:2000, nlyr(r))
trait

In this exapmle, no spatial randomization will be performed, only trait randomization. To select the trait to be randomized, pick the desired argument of FUN_args using Fa_sample and the name of the desired argument (here "lyrv"). Then select a function, here "sample" is used. It is also possible to send arguments to the function in Fa_alg through Fa_alg_args. It works in the same way that arguments are sent to FUN and spat_alg through FUN_args and spat_alg_args.
In this first example it is performed a trait sampling without replacement.

set.seed(10)
ses <- SESraster(r, FUN = appsv,
                 FUN_args = list(lyrv = trait, na.rm = TRUE),
                    Fa_sample = "lyrv",
                    Fa_alg = "sample", Fa_alg_args = list(replace = FALSE),
                    aleats = 5)
plot(ses)

In this second example it is performed a trait sampling with replacement by passing replace = TRUE through Fa_alg_args.

set.seed(10)
ses <- SESraster(r, FUN = appsv,
                 FUN_args = list(lyrv = trait, na.rm = TRUE),
                    Fa_sample = "lyrv",
                    Fa_alg = "sample", Fa_alg_args = list(replace = TRUE),
                    aleats = 5)
plot(ses)

Conclusion {#concl}

The SESraster R package aims to simplify the randomization of raster data and the calculation of standardized effect sizes for spatial data. We hope it is useful to analize the vast amount of raster data generated for the analysis of biogeographycal and macroecological patterns.

References {#references}

SESraster documentation built on Oct. 30, 2024, 9:16 a.m.