Chapter 7 PSPMind: life history simulation

7.1 Simulating individual life histories in specific environments

To analyze the factors and mechanisms that lead to specific changes in model equilibria with a change in parameters it is often necessary to compute the life history trajectory of an individual organism at a specific set of environmental conditions. Although to some extent this information can be extracted from the population state file (the .csb file) that is generated as output, the package also contains a separate function PSPMind that computes the individual life history, given a particular set of values for the environmental variables. In principle, the PSPMind function only requires the values of environmental variables as input. However, this input vector of environmental variables can be extended with the values of the birth rates of all structured populations in the model. Providing values of the population birth rates will scale the output of the function PSPMind with these birth rates, which is useful if the PSPMind function is used for generating an initial state for simulating the ecological dynamics of the model, as discussed in chapter 4.

The output of PSPMind function is a structure with similar contents as the structures that are normally stored in the .csb file (see section 2.4.2, 3.4.5, 4.3 or 6.4 for a discussion of the .csb file). In fact, the program generates such a file with a name <Modelname>-IND-<NNNN>.csb which contains exactly one population state. As before, <Modelname> is the same as the name of the file specifying the model excluding its '.R' or '.h' extension and <NNNN> is a 4-digit number that is unique for the current computation.

7.1.1 Arguments and output of the PSPMind function

The general call to the PSPMind function is shown in the command box below.

> output <- PSPMind(modelname = NULL, environment = NULL, parameters = NULL, options = NULL,
                    clean = FALSE, force = FALSE, debug = FALSE, silent = FALSE)

The obligatory and optional arguments to the PSPMind function are the following:

  1. The first, obligatory argument to the function PSPMind is the name of the file specifying the PSPM, passed as a string argument. It is unnecessary to include the extension '.R' or '.h' as part of the file name, the PSPMevodyn function will automatically try to locate the appropriate file, checking first for a file implemented in C (with an extension '.h') and subsequently for a file implemented in R (with an extension '.R'). If both a file with an extension '.h' and a file with an extension '.R' are found, the program will use the first one. The program can be forced to use the file with an extension '.R' by including the extension explicitly as part of the filename. The R-command to simulate the life history with the model specified in PNAS2002.h, which will be used for the illustration below, therefore takes "PNAS2002" as its first argument. If the file specifying the PSPM can not be found in the current directory, the PSPMind function will ask the user to search in the package directory for a model file with the specified name.

  2. The second, obligatory argument is a (row) vector containing the values of the environmental variables, for which to compute the individual life history:

    c(\(<\)environment variable 1\(>\),\(<\)environment variable 2\(>\),....)

    The number of values specified in this vector should equal the number of environmental variables in the model, that is, the length of the variable EnvironmentState for models implemented in R (see code block 3.3.1.3) and the value of the constant ENVIRON_DIM for models implemented in C (see code block 3.3.2.1). Notice, that this vector therefore does not contain any parameter values.

    Alternatively, the vector in this second argument can be extended with the birth rates of the structured population model. In this case, the argument has the form:

    c(\(<\)environment variable 1\(>\),\(<\)environment variable 2\(>\),....,\(<\)birth rate 1\(>\),\(<\)birth rate 2\(>\),....)

    Notice that as many birth rates have to be specified as there are structured populations in the model (the value of the element PopulationNr in the vector PSPMdimensions for models implemented in R, see code block 3.3.1.1, or the value of POPULATION_NR models implemented in C, see code block 3.3.2.1). The effect of specifying these birth rates is that the value of the individual survival produced as output by the model (see command box 7.1.2 below) will be multiplied by the birth rates of the particular structured population model. This allows for arbitrary scaling of the number of individuals in the output, which is useful if the function PSPMind is used for producing an initial state for the function PSPMecodyn (see chapter 4). If the birth rates are not specified the program assumes a default value of these rates equal to 1.

  3. The third, optional argument of the PSPMind function is a (row) vector of model parameter values. When used, this array should have the same length as the number of parameters in the model (the length of the vector DefaultParameters in R, or the value of PARAMETER_NR in C). When of this length the values will replace the default values of the parameters that are listed in the model specification file. If the array used for this third argument is not of the correct length or when it is not specified at all, it will simply be ignored.

  4. The fourth, optional argument of the PSPMind function is a (row) vector of string elements, containing possible options that modify the behavior of the computational module. The PSPMind function only recognizes a single option isort. Hence, this fourth argument is either left unspecified (or, equivalently, specified as options = NULL, which is the default) or takes the form:

    c("isort", "i")

    This option modifies the output of the equilibrium state of the populations that are stored in the output file with a name of the form <Modelname>-IND-<NNNN>.csb (see below). By default the computational module reports the information about the stable population state distributions by subdividing the axis of the first state variable (the one with index "0") in 100 subintervals of equal length and reporting the statistics for the cohort of individuals within each subinterval. By using the option "isort" the default choice to use the first individual state variable for this subdivision can be changed to the second, third, and so on. Therefore, passing c("isort", "0") as option vector to the PSPMind function is the same as the default behavior: the first individual state variable is used for the subdivision and ordering of the population state distribution, while passing c("isort", "1") would use the second individual state variable for this purpose. Also notice that the number of subdivisions of the individual state variable can be redefined by assigning the dimension COHORT_NR a value different from 100 (see chapter 8).

Four other optional arguments can be passed to the PSPMind function: clean, force, debug and silent. These are all boolean arguments that hence have to be passed to the PSPMind function as \(<\)option name\(>\)=TRUE or \(<\)option name\(>\)=FALSE, the latter being the default value of all options (Specifying these options as argument is hence only useful when setting them equal to TRUE). Unlike the previous arguments, which all modify the computations to be performed, these options modify the behavior of the PSPMind function itself, in particular the compilation of the model specific file into a dynamic library module that can be executed from R. Also unlike all the previous arguments that can be passed, these arguments can be passed in any order and at any position, the PSPMind function will filter these 3 optional arguments from the argument list before passing the filtered argument list to the computational routine.

  • Option clean: When clean=TRUE is passed as argument, this argument instructs the PSPMind function to delete all result files that have been generated during previous calculations with the model. These result files have names of the form <Modelname>-<Type>-<NNNN>.csb, in which <Modelname> refers to the name of the model, <Type> refers to the type of computation that has been performed, which in the case of PSPMind equals IND, and <NNNN> is a unique number that distinguishes consecutive computations of the same type of curve with the same model. Deleting all the output files from previous computations and/or the compiled program executables that the package has generated can also be done separately. The package implements a function PSPMclean(), taking no arguments, to delete all .bif, .err, .csb and .out files and/or all executable files that are present in the current working directory.

  • Option force: When force=TRUE is passed as argument, it instructs the PSPMind function to force re-compilation of the model specific file into a dynamic library module that can be executed by R. This option will usually not be needed by normal users, as the PSPMind function automatically recompiles the computational module when the model specific file with an '.R' or '.h' extension is more recently changed than the compiled dynamic library file. However, if for some unclear reason this automatic recompilation fails, the force option can be used to initiate re-compilation.

  • Option debug: When debug=TRUE is passed as argument, it instructs the PSPMind function to turn on debugging flags while compiling the model specific file into a dynamic library module. This option can be useful to detect programming mistakes in the model-specific file that are otherwise hard to track down. The downside is that depending on the version of R that is used, turning on debugging flags during compilation may generate a lot of output, including warnings about standard files of the operating system that are perfectly correct. It is hence not so easy to spot among all these messages the warnings that relate to the model-specific code that has been implemented.

  • Option silent: When silent=TRUE is passed as argument, it instructs the PSPMind function to suppress all messages from the compilation of the model specific file into a dynamic library module. This option is useful to prevent cluttering the console with superfluous messages once a model specific file has been tested sufficiently and functions without problems.

The output of function is discussed in the example below.

7.1.2 An example using the PSPMind function

To illustrate the use of the PSPMind function, I will consider the example as discussed in section 3.4.5 and shown in command box 3.4.5.B. There, an equilibrium population state called State_4_042258E_04 pertaining to the parameter value \(R_{max}=4.042258\cdot10^{-4}\), was read from the population state (.csb) file using the function csbread. The vector of environmental variables for the computed model equilibrium equals c(2.533511e-04, 1.335974e-04, 4.008016e-06). Computing the individual life history for this particular environmental state with PSPMind gives the following result:

Command box 7.1.2
> output <- PSPMind("PNAS2002",c(2.533511e-04, 1.335974e-04, 4.008016e-06), options = c("isort", "1"),
                    clean=TRUE, force=TRUE)

Building executable PNAS2002ind.so using sources from /Users/andre/programs/PSPM analysis ...

<...compilation output lines suppressed in this box...>

                              Istate[0]  Istate[1]  Survival  R0  Impact[0]  Impact[1]  Impact[ 2]  Impact[3]
Pop. #0 - Bstate 0 - (Final):   1237.26    283.066     1E-09   1  0.0512525  0.0136153   0.0370566   0.625002

> output
$Parameters
 [1] 1.0e-01 3.0e-04 7.0e+00 2.7e+01 1.1e+02 3.0e+02 9.0e-06 1.0e-04 ... 3.0e-03 1.0e-02 5.0e+03 1.0e-01 5.0e-01 1.0e-02

$Environment
[1] 2.533511e-04 1.335974e-04 4.008016e-06

$Pop00
           Survival    Istate00  Istate01    Impact00    Impact01     Impact02    Impact03         R0
  [1,] 1.000000e+00    0.000000   7.00000 0.000000000 0.000000000 0.0000000000 0.000000000 0.00000000
  [2,] 3.221467e-01    1.674051   9.76066 0.006303773 0.004973069 0.0000000000 0.000000000 0.00000000
  [3,] 1.025926e-01    3.365087  12.52132 0.009951990 0.008797279 0.0000000000 0.000000000 0.00000000
<...output lines suppressed in this box...>
 [99,] 3.652493e-07  647.198013 277.54468 0.050983548 0.013615309 0.0370566144 0.617830389 0.99193394
[100,] 1.206611e-07  757.957444 280.30534 0.051163073 0.013615309 0.0370566144 0.622602248 0.99731968
[101,] 1.000000e-09 1237.256038 283.06600 0.051252524 0.013615309 0.0370566144 0.625001749 1.00000322

Passing the option vector c("isort", "1") as argument implies that the interval between the minimum and maximum value of the individual state variable with index 1 (here ranging between 7 and 283.1) is subdivided into 100 subintervals and that life history values are provided at these 100 intermediate values of that state variable. At these points in the life history the output contained in $Pop00 shows the individual survival, the values of the individual state variables, the values of the different impacts of the individual as well as the value of its lifetime reproductive success \(R_0\). If the model contains multiple structured populations, the individual life histories of individuals in the other populations will follow as $Pop01, $Pop02, etc.

Do note, however, that the function PSPMind will simulate the individual life history for the default values of the parameters, unless the parameters argument is passed to the function. Therefore, technically the life history shown above pertains to a parameter value of \(R_{max}=3.0\cdot10^{-4}\) (default value) as opposed to \(R_{max}=4.042258\cdot10^{-4}\), for which the equilibrium environmental variables were calculated. In this particular case this does not matter because the parameter \(R_{max}\) represents the resource productivity which does not affect the individual life history at all. But in case the bifurcation parameter does influence the individual life history make sure to pass the proper parameter vector as an argument to the function PSPMind.