ecospace (version 1.4.2)

expansion: Use Expansion Rule to Simulate Ecological Diversification of a Biota.

Description

Implement Monte Carlo simulation of a biota undergoing ecological diversification using the expansion rule.

Usage

expansion(nreps = 1, Sseed, Smax, ecospace, method = "Euclidean", strength = 1)

Arguments

nreps

Vector of integers (such as a sequence) specifying sample number produced. Only used when function is applied within lapply or related function. Default nreps=1 or any other integer produces a single sample.

Sseed

Integer giving number of species (or other taxa) to use at start of simulation.

Smax

Maximum number of species (or other taxa) to include in simulation.

ecospace

An ecospace framework (functional trait space) of class ecospace.

method

Distance measure to use when calculating functional distances between species. Default is Euclidean using stats::dist. Gower or any other value uses Gower distance (using FD::gowdis). Presence of factor or ordered factor character types forces use of Gower distance.

strength

Strength parameter controlling probability that expansion rule is followed during simulation. Values must range between strength = 1 (default, rules always implemented) and strength = 0 (rules never implemented).

Value

Returns a data frame with Smax rows (representing species) and as many columns as specified by number of characters/states (functional traits) in the ecospace framework. Columns will have the same data type (numeric, factor, ordered numeric, or ordered factor) as specified in the ecospace framework.

Details

Simulations are implemented as Monte Carlo processes in which species are added iteratively to assemblages, with all added species having their character states specified by the model rules, here the 'expansion' rule. Simulations begin with the seeding of Sseed number of species, chosen at random (with replacement) from either the species pool (if provided in the weight.file when building the ecospace framework using create_ecospace) or following the neutral-rule algorithm (if a pool is not provided). Once seeded, the simulations proceed iteratively (character-by-character, species-by-species) by following the appropriate algorithm, as explained below, until terminated at Smax.

Expansion rule algorithm: Measure distances between all pairs of species, using Euclidean or Gower distance method specified by method argument. Identify species pair that is maximally distant. If multiple pairs are equally maximally distant, one pair is chosen at random. The newly added species has traits that are equal to or more extreme than those in this species pair, with probability of following the expansion rule determined by the strength parameter. Default strength = 1 always implements the rule, whereas strength = 0 never implements it (essentially making the simulation follow the neutral rule.)

Each newly assigned character is compared with the ecospace framework (ecospace) to confirm that it is an allowed state combination before proceeding to the next character. If the newly built character is disallowed from the ecospace framework (i.e., because it has "dual absences" [0,0], has been excluded based on the species pool [weight.file in create_ecospace], or is not allowed by the ecospace constraint parameter), then the character-selection algorithm is repeated until an allowable character is selected. When simulations proceed to very large sample sizes (>100), this confirmatory process can require long computational times, and produce "new" species that are functionally identical to pre-existing species. This can occur, for example, when no life habits, or perhaps only one, exist that forms an allowable novelty between the selected neighbors.

Expansion rules tend to produce ecospaces that progressively expand into more novel regions. Additional details on the expansion simulation are provided in Novack-Gottshall (2016a,b), including sensitivity to ecospace framework (functional trait space) structure, recommendations for model selection, and basis in ecological and evolutionary theory.

References

Bush, A. and P.M. Novack-Gottshall. 2012. Modelling the ecological-functional diversification of marine Metazoa on geological time scales. Biology Letters 8: 151-155.

Novack-Gottshall, P.M. 2016a. General models of ecological diversification. I. Conceptual synthesis. Paleobiology 42: 185-208.

Novack-Gottshall, P.M. 2016b. General models of ecological diversification. II. Simulations and empirical applications. Paleobiology 42: 209-239.

See Also

create_ecospace, neutral, redundancy, partitioning

Examples

# NOT RUN {
# Create an ecospace framework with 15 3-state factor characters
# Can also accept following character types: "numeric", "ord.num", "ord.fac"
nchar <- 15
ecospace <- create_ecospace(nchar = nchar, char.state = rep(3, nchar),
  char.type = rep("factor", nchar))

# Single (default) sample produced by expansion function (with strength = 1):
Sseed <- 5
Smax <- 40
x <- expansion(Sseed = Sseed, Smax = Smax, ecospace = ecospace)
head(x, 10)

# Plot results, showing order of assembly
# (Seed species in red, next 5 in black, remainder in gray)
# Notice that new life habits progressively expand outward into previously
#   unoccupied portions of ecospace
seq <- seq(nchar)
types <- sapply(seq, function(seq) ecospace[[seq]]$type)
if(any(types == "ord.fac" | types == "factor")) pc <- prcomp(FD::gowdis(x)) else
  pc <- prcomp(x)
plot(pc$x, type = "n", main = paste("Expansion model,\n", Smax, "species"))
text(pc$x[,1], pc$x[,2], labels = seq(Smax), col = c(rep("red", Sseed), rep("black", 5),
  rep("slategray", (Smax - Sseed - 5))), pch = c(rep(19, Sseed), rep(21, (Smax - Sseed))),
  cex = .8)

# Change strength parameter so rules followed 95% of time:
x <- expansion(Sseed = Sseed, Smax = Smax, ecospace = ecospace, strength = 0.95)
if(any(types == "ord.fac" | types == "factor")) pc <- prcomp(FD::gowdis(x)) else
  pc <- prcomp(x)
plot(pc$x, type = "n", main = paste("Expansion model,\n", Smax, "species"))
text(pc$x[,1], pc$x[,2], labels = seq(Smax), col = c(rep("red", Sseed), rep("black", 5),
  rep("slategray", (Smax - Sseed - 5))), pch = c(rep(19, Sseed), rep(21, (Smax - Sseed))),
  cex = .8)

# Create 4 samples using multiple nreps and lapply (can be slow)
nreps <- 1:4
samples <- lapply(X = nreps, FUN = expansion, Sseed = 5, Smax = 40, ecospace)
str(samples)

# }