Extracts ecological memory features from the output of computeMemory.

Computes the following features of the ecological memory patterns returned by computeMemory:

memory strength maximum difference in relative importance between each component (endogenous, exogenous, and concurrent) and the median of the random component. This is computed for exogenous, endogenous, and concurrent effect.
memory length proportion of lags over which the importance of a memory component is above the median of the random component. This is only computed for endogenous and exogenous memory.
dominance proportion of the lags above the median of the random term over which a memory component has a higher importance than the other component. This is only computed for endogenous and exogenous memory.

Usage

extractMemoryFeatures(
  memory.pattern = NULL,
  exogenous.component = NULL,
  endogenous.component = NULL,
  scale.strength = TRUE
)

Arguments

memory.pattern: either a list resulting from computeMemory, or a dataframe with memory patterns of several taxa generated by experimentToTable. When using output from experimentToTable, filter to a specific sampling resolution before calling this function (e.g., data[data$sampling == 25, ]). Default: NULL.
exogenous.component: character string or character vector, name of the variable or variables defining the exogenous component. When memory.pattern is output from computeMemory, this is automatically extracted from the $drivers slot if not provided. Required when input is from experimentToTable. Default: NULL.
endogenous.component: character string, name of the variable defining the endogenous component. When memory.pattern is output from computeMemory, this is automatically extracted from the $response slot if not provided. Required when input is from experimentToTable. Default: NULL.
scale.strength: boolean. If TRUE, the strength of the ecological memory components, which has the same units as the importance scores yielded by random Forest (percentage of increment in mean squared error when a variable is permuted), is scaled between 0 and 1. Default: TRUE.

Value

A dataframe with 8 columns and 1 row if memory.pattern is the output of computeMemory and 13 columns and as many rows as taxa are in the input if it is the output of experimentToTable. The columns are:

label character string to identify the taxon. It either inherits its values from experimentToTable, or sets the default ID as "1".
strength.endogenous numeric, difference between the maximum importance of the endogenous component at any lag and the median of the random component (see details in computeMemory). When scale.strength = TRUE (default), values are scaled to [0, 1]; otherwise values are in importance units (percentage of increment in MSE).
strength.exogenous numeric, same as above, but for the exogenous component.
strength.concurrent numeric, same as above, but for the concurrent component (driver at lag 0).
length.endogenous numeric in the range [0, 1], proportion of lags over which the importance of the endogenous memory component is above the median of the random component.
length.exogenous numeric in the range [0, 1], same as above but for the exogenous memory component.
dominance.endogenous numeric in the range [0, 1], proportion of the lags above the median of the random term over which a the endogenous memory component has a higher importance than the exogenous component.
dominance.exogenous, opposite as above.
maximum.age, numeric. As every column after this one, only provided if memory.pattern is the output of experimentToTable. Trait of the given taxon.
fecundity numeric, trait of the given taxon.
niche.mean numeric, trait of the given taxon.
niche.sd numeric, trait of the given taxon.

Details

Warning: this function only works when only one exogenous component (driver) is used to define the model in computeMemory. If more than one driver is provided through the argument exogenous.component, the maximum importance scores of all exogenous variables is considered. In other words, the importance of exogenous variables is not additive.

Author

Blas M. Benito <blasbenito@gmail.com>

Examples


# Loading example data (output of computeMemory)
data(palaeodataMemory)

# Simplified call - components auto-detected from computeMemory output
memory.features <- extractMemoryFeatures(
  memory.pattern = palaeodataMemory
)

# Explicit call - still supported for backwards compatibility
memory.features <- extractMemoryFeatures(
  memory.pattern = palaeodataMemory,
  exogenous.component = c(
    "climate.temperatureAverage",
    "climate.rainfallAverage"
  ),
  endogenous.component = "pollen.pinus"
)

Extracts ecological memory features from the output of `computeMemory`.