In brouwern/FACavian: An R implementation and extension of full-annual cycle (FAC) model of Runge & Marra *2005)

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

Introduction

A major motivation for studying full-annual cycle population dynamics is to determine when during the annual cycle population limitation occurs. For example, a perennial question is whether habitat loss on the breeding grounds or wintering grounds is more important for population dynamics (TODO: CITE).

For standard density-independent (di) population models , such as matrix models (TODO: CITE) or integral projection models (TODO: CITE), there are analytical solutions that allow you to compare the importance of vital rates for population growth. These methods include sensitivity and elasticity analyses (TODO: CITE), as well as Life Table Response Experiments (LTRE; (TODO: CITE)). To carry out these analyses all that is required is the parameterized model and a program (such as R) that can do mathematical functions such as determinie what are known as the the eigenvalues of matrices. For an introduction to matrix models and eigenanlysis in R see ... (TODO: CITE). For a general introduction to matrix models with worked examples see Morris and Doak 200x and the R package based on it popbio (TODO: CITE).

Density-dependent (dd) models are analyzed very differently than density-independent models (TODO: CITE). The add complexities of building and anlysing dd has made them relatively rare. Moreover, most dd models use functions similar to the classic logistic growth curve ((TODO: add figure of curve) to model have vital rates change as a function of density. For birds the primary form of density dependence is suspected to be due to the constrains imposed by a limited number of territories. This has been called site-dependence in the bird literature (TODo: cite Rodenhouse etc) and corresponds with what is called celing model of density depencence elsewhere (cite Morris and Doak, etc).

Complex dd models such as the one developed by Runge and Marra (2004) can not be assayed directly using analytical methods. Models such as this must be run repeatedly with different parameter values and the output of the model compared as conditions change. This requires running many indepdent models to equilibrium, each with slightly diffrent paramter values, storing the relevant output, and comparing the output. Runge and Marra (2004) graphically explored how

1. varying breeding season and winter carrying capacity impacted breeding ground population size (Figures 28.3in the original paper),
2. how breeding ground carrying capacity impacted breeding and winter population structure (28.4), and male dominance impacted the sex ratio (Figure 28.5), and
3. the strength of carry-over effects impacted population size (Figure 28.6).

The redstart package implements and extends the analyses carried out by Runge and Marra (2004) using the function runFAC_multi(). This function allows you to run multiple FAC models each with different parameter values. The following vignette demonstrates the basic functionality of runFAC_multi(). Each of the analyses in Runge and Marra (2004) are then coverged in a seperate vignette.

Preliminaries

library(redstart)

The runFAC_multi() function

runFAC_multi(param.grid = param_grid(), Ninit = c(10, 0, 10, 0), remakeFigure = NA, use.IBM = F, verbose = F, eq.tol = 6, ...)

Recreate figures in the original paper

Figure 28.3: 3D surface

F28_3 <- runFAC_multi(eq.tol = 2, 
                      verbose = F)

runFAC_multi produces a list with two elements.

is(F28_3)
length(F28_3)

One holds the output for the original model of Runge and Marra (rmFAC; multiFAC.out.df.RM), while the other holds the output for from a model with individual-based submodels (ibFAC; multiFAC.out.df.IB:'data.frame). We'll focus on rmFAC.

str(F28_3, 1)

The rmFAC element is a dataframe.

is(F28_3$multiFAC.out.df.RM)

This dataframe contains information on the output of dozens of individual runs of the FAC model to equilibrium, so it very large

dim(F28_3$multiFAC.out.df.RM)

There are 23 rows for various output such as the population sizes and sex ratios. There are 100 rows.

str(F28_3$multiFAC.out.df.RM,1)

Each rows is a single run of the model. runFAC_multi() is designed to run the model over multiple combinations of parametrs. A principle output is a 3D surface plot where the x and y axes are two parameters varied between runs of the model and the z (vertical axis) is a state of interest when the model is at equilibrium, such as the equilibirum summer population size.

Plot the 3D surface.

par(mfrow = c(1,1))
plot_Fig28_3(F28_3$multiFAC.out.df.RM)

Figure 28.4

Create parameters

Create the intial range of the parameters

The param_ranges() function can be used to create ranges (minimum and maxiumum) of parameters that can then be subsequently explored using runFAC_multi(). This is the first step, followed by generating sequences of numbers between the min and the max. param_ranges() is set up to take as arguements different scenarios (scenario = ... ) or figures (figure = ...) defined by Runge and Marra and to produce the combinations of parameters used in that paper. In general one or two parameters are varied and all the others are kept constant.

We can set up the parameters for Figures 28.3 and 28.4 like this

F28.3.range <- param_ranges(figure = 28.3)
F28.4.range <- param_ranges(figure = 28.4)

In this figure K.bc was varied from 100 to 600 and all other parameters kept constant.

head(F28.4.range)

Turn any varying parameters into sequence

Once the minimum and maxium are set the actual sequence of numbers can be made. This

For Figure 28.4 breding ground carrying capacity is varied from 100 to 600, so we want a vector of numbers, say 100, 200, 300, 400, 500, 600.

For Figure 28.3 breding ground carrying capacity is varied from 1 to 1000, and also winter carrying capacity is varied from 1 to 100.

We make a list the has all the parameters we need

F28.3.seq <- param_seqs(F28.3.range)
F28.4.seq <- param_seqs(F28.4.range)

This is a list

is(F28.4.seq)

There is one element for each input parameter

length(F28.4.seq)

If a parameter does not need to be varied a single value appears in its slot. Otherwise a vector. For figure 28.4 there is just one parameter that varies

head(F28.4.seq)

For figure 28.3 there are two

head(F28.3.seq)

Expand parameters into a grid

Once the parameters have been defined a set of all possible parameter combinations needs to be created. This is essentially a grid of all possible value. (The shape isn't a square grid, but takes its name from the use of R's expand.grid function)

For figure 28.4 only one parameter is varied.

F28.4.grid <- param_grid(param.seqs = F28.4.seq)

Figure 28.3 is much larger because two parameters are varied.

F28.3.grid <- param_grid(param.seqs = F28.3.seq)

The output is a dataframe

is(F28.4.grid)

Each row of the dataframe contains all the parameters needed for a single run of the model.

head(F28.4.grid)[,1:10]

Each row of data will be fed in the runFAC() function and the model run until an equilibirum is reached.

Run multiple FACs accross the parameters

We can run the grid to equilibrium with runFAC_multi().

F28.4.FAC <- runFAC_multi(param.grid = F28.4.grid,
                             verbose = F, 
                             eq.tol =6,
                             Ninit = c(100, 0, 100, 0))

Plot Figure 28.4

Different kinds of figures require different set up and so there are specific functions for each figure. Figure 28.3 is made with function plot_Fig28_3(). Figure 28.4 has its own function.

plot_Fig28_4(F28.4.FAC$multiFAC.out.df.RM)

brouwern/FACavian documentation built on March 23, 2022, 10:07 a.m.