In flee-group/flume: A Model For Fluvial Meta-Ecosystems

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

library(flume)

The metacommunity is one of the two main components for creating a flume model. It describes the collection of species that can occur in the model, including all of their traits related to the niche, species interactions, and dispersal.

The easiest way to generate these components is by using scenarios, which you pass to the function metacommunity(). There are scenarios around resources and niches, and scenarios for dispersal. For example, the default behaviour when you call the metacommunity() function with no arguments is to create a metacommunity with 2 species and one resource using the niches_uniform() scenario for resources/niches and the dispersal_custom() dispersal scenario (using default parameters in this case that do not vary by species). The equivalent call specifying all parameters would be: metacommunity(nsp = 2, nr = 1, niches = niches_uniform, dispersal = dispersal_custom). The niche scenario here will create niches that are uniformly spaced across the possible resource values, with a standard deviation chosen automatically to cover a moderate breadth.

The focus of this vignette will be explaining the options that can be invoked, primarily using the custom scenarios. In these scenarios, or all pieces of information that can be provided required, there are also defaultsr. In this way, a metacommunity can be generated with real species in mind, or completely randomly, or something in between. It is useful to check out the help file to understand the defaults for the various options.

Niche shape

The niche contains two components, a colonisation and an extinction function. Currently, the only implemented shape is a gaussian colonisation function and a constant extinction function. Each of them has parameters:

Gaussian

scale: the maximum value of the curve
location: where on the resource axis the peak of the curve is
breadth: How broad (i.e., the standard deviation of the gaussian function)

Constant

scale: the height of the function

These parameters can be specified to vary by species, vary by resource axis, or both, and to have orthogonal or covarying resource axes. To change them individually, use the niches_custom scenario. Here, we change the location and breadth of the gaussian colonisation function to make three species, including two low-resource specialists that compete strongly and one generalist with a slight preference for high resource conditions, but a lower peak performance.

library(ggplot2)
nopts = list(location = c(0.1, 0.12, 0.7), breadth = c(0.1, 0.1, 2), scale_c = c(0.5, 0.5, 0.25))
mcom = metacommunity(nsp = 3, nr = 1, niches = niches_custom, niche_args = nopts)
plot(mcom, lwd = 0.8, res = 500, xlim = c(0,1))

Dispersal parameters

Species can disperse in the river network in two ways. Active dispersal, controlled by a parameter alpha, indicates the ability of a species to move under its own power; active dispersal occurs along the stream, in both up- and down-stream directions. Passive dispersal that occurs when one species is transported by another species should also be included in alpha. Passive dispersal is dispersal with the flow of water, and only occurs downstream. It is specified with a parameter beta. Both alpha and beta can be a scalar (all species have the same disperal ability) or a vector with one entry per species. We can change these parameters using the dispersal_custom scenario, in a similar manner as to the niches. Here we edit the previous community to make the specialists primarily passive dispersers, while the generalist is a strong disperser both up- and downstream.

dopts = list(alpha = c(0.05, 0.05, 0.5), beta = 0.5)
mcom = metacommunity(nsp = 3, nr = 1, niches = niches_custom, dispersal = dispersal_custom,
  niche_args = nopts, dispersal_args = dopts)

Complex resources

It isn't always the case that resources map directly to niche axes. Here we load the algae dataset included with flume. The niches object gives average and standard deviation of N:P ratios for 5 aquatic algal taxa. We can create a metacommunity that tracks two resources, but computes the niche based on the ratio of these two resources.

data(algae)
nopts = list(location = algae$niches$location, breadth = algae$niches$breadth, ratio = c(1, 2))
mcom = metacommunity(nsp = nrow(algae$niches), nr = 2, niches = niches_custom, niche_args = nopts,
  sp_names = algae$niches$species, r_names = c("N", "P"))
plot(mcom, res = 500, lwd = 0.8)

Static resources

Many species' niches depend not only on depletable resources (e.g., nitrogen, organic matter), but also on (relatively) fixed features of the environment, such as light availability, riverbed composition, or the presence of pools. These features are not like resource concentrations: they cannot be transported downstream and they are not depeleted by organisms using them. flume represents these features as 'resources', but they are labelled as 'static' in order to tell the model to use them for computing species' niches, but to hold their amounts constant durint the transport-reaction phase.

Here we use the algae dataset again, but this time we add a feature called 'gravel', indicating the proportion of the riverbed covered by gravel. As this is only an example, we generate these values randomly and assign species locations and breadths along a gradient.

nsp = nrow(algae$niches)
location = cbind(algae$niches$location, seq(0, 1, length.out = nsp))
breadth = cbind(algae$niches$location, 0.3)
nopts = list(location = location[,2], breadth = breadth[,2], static = 1)
mcom = metacommunity(nsp = nsp, nr = 1, niches = niches_custom, niche_args = nopts,
  sp_names = algae$niches$species, r_names = c("gravel"))
plot(mcom, res = 500, lwd = 0.8, xlim=c(0,1))

Finally, We could combine these two approaches to generate a multidimensional niche. However, we won't run this code here; multidimensional niches are slow to generate, because they must be integrated numerically in multiple dimensions to generate the competition matrix.

nopts = list(location = location, breadth = breadth, ratio = c(1,2), static = 3)
mcom = metacommunity(nsp = nsp, nr = 3, niches = niches_custom, niche_args = nopts,
  sp_names = algae$niches$species, r_names = c("N", "P", "gravel"))