demoniche – an R-package for simulating spatially-explicit population dynamics


  • Hedvig K. Nenzén,

    1. Rui Nabeiro Biodiversity Chair, CIBIO, Univ. of Évora, Casa Cordovil, 2° Andar, Rua Dr. Joaquim Henrique da Fonseca, PT-7000-890 Évora, Portugal
    Search for more papers by this author
  • Rebecca M. Swab,

    1. Rui Nabeiro Biodiversity Chair, CIBIO, Univ. of Évora, Casa Cordovil, 2° Andar, Rua Dr. Joaquim Henrique da Fonseca, PT-7000-890 Évora, Portugal
    Search for more papers by this author
  • David A. Keith,

    1. Rui Nabeiro Biodiversity Chair, CIBIO, Univ. of Évora, Casa Cordovil, 2° Andar, Rua Dr. Joaquim Henrique da Fonseca, PT-7000-890 Évora, Portugal
    Search for more papers by this author
  • Miguel B. Araújo

    1. Rui Nabeiro Biodiversity Chair, CIBIO, Univ. of Évora, Casa Cordovil, 2° Andar, Rua Dr. Joaquim Henrique da Fonseca, PT-7000-890 Évora, Portugal
    Search for more papers by this author

H. K. Nenzén, Rui Nabeiro Biodiversity Chair, CIBIO, Univ. of Évora, Casa Cordovil, 2° Andar, Rua Dr. Joaquim Henrique da Fonseca, PT-7000-890 Évora, Portugal. E-mail:


demoniche is a freely available R-package which simulates stochastic population dynamics in multiple populations of a species. A demographic model projects population sizes utilizing several transition matrices that can represent impacts on species growth. The demoniche model offers options for setting demographic stochasticity, carrying capacity, and dispersal. The demographic projection in each population is linked to spatially-explicit niche values, which affect the species growth. With the demoniche package it is possible to compare the influence of scenarios of environmental changes on future population sizes, extinction probabilities, and range shifts of species.

Studying processes and systems on multiple scales, and how these systems interact, is essential to understanding the ecology of environmental change. Simultaneously, it is difficult to carry out multi-scale, interlinked experiments, so the simulation of ecological systems is an increasingly necessary complement to the experimental approach. We also used models to guide responses to present and future threats to biodiversity in a world of increasing human and environmental changes (Brook et al. 2008, Pereira et al. 2010). In part, these objectives can be accomplished by coupling models that characterize different processes at different scales. These are called coupled or hybrid models (Jongejans et al. 2008, Thuiller et al. 2008, Franklin 2010, Gallien et al. 2010) and are promising approaches to improve understanding of the interlinked and hierarchical processes governing distributions and abundances in space and time.

Here, we introduce the R-package demoniche software (R Development Core Team) that enables the creation of coupled models of species distributions. In short, it creates demographic models with multiple populations connected by dispersal and with different habitat suitability. The package couples detailed models of a species’population growth to large-scale predictions about future environmental conditions, modelling both intrinsic and extrinsic effects on species persistence. By changing parameter values between simulations and comparing results, we can also estimate model and species sensitivity, and guide future data collection. demoniche can also be used to develop hypotheses concerning habitat configuration, species persistence, and range shifts.

Model algorithm

Demographic model in each population

The inner model in demoniche is a demographic model, employing transition matrices to project population growth (Leslie 1945, Lefkovitch 1965, Caswell 2001, Morris and Doak 2002). The matrix rows and columns represent distinct life stages or sizes of an organism. The matrix dia gonal represents the probability of surviving within the same stage, and off-diagonal elements represent probabilities of growing or receding to another stage. Multiplying a matrix by a population vector representing current population structure gives the number of individuals one time step later. Structured matrix models differ from unstructured population models in that species-specific growth strategies, seed stages and time lags can be modelled.

Constructing realistic matrices requires long-term data from inventories or mark recapture studies. These are available for relatively few species (Crone et al. 2011). There are many assumptions and methodological issues in demographic models, and we encourage readers to become familiar with them (Cabral and Schurr 2010, Salguero-Gómez and De Kroon 2010, Stott et al. 2010).

demoniche has two optional sources of demographic stochasticity: varying the matrix elements, or randomly selecting a different matrix each time step. For the first option, the values in the transition matrix are randomly varied according to a normal probability distribution and variance matrix. For the second option, during each time step a mean/reference transition matrix or a scenario matrix is randomly selected following a user-defined probability.

Placing populations in a landscape

The user supplies the coordinate locations and areas of the species current distribution, which can be either patches (metapopulations, islands, lakes, patches, protected areas) or grids (equal-sized cells within a continuous lattice). Dispersal between populations can be either over short or long- distance, and in both cases the user sets the ratio of dispersing to non-dispersing propagules. Short-distance dispersal is a flow of propagules to contiguous populations. Long-distance dispersal is modelled deterministically according to the formula P = a*exp(Dc/b), with D = distance between populations. The user-defined constants describe the shape of the dispersal probability curve and define a maximum distance beyond which dispersal is impossible. Short- and long-distance dispersal can be applied separately or combined; alternatively, simulations can be run with stationary populations.

Linking niche conditions to population growth

Up to here, we have described spatially explicit populations linked by dispersal, with population sizes updated in each time step. However, extrinsic spatially heterogeneous environmental factors also affect population growth. The demoniche software has three options to model the link between the environment and the species. For example, the niche suitability can be derived from ecological niche models or bioclimatic envelope models (Keith et al. 2008), future climate scenarios (Hunter et al. 2010), land use (Lawson et al. 2010), landscape topology, presence of another species, or a composite of values.

One way to link population growth to the environment is by defining a carrying capacity – the maximum number of individuals that can be sustained in a patch. The carrying capacity removes individuals above the defined limit, which can be different for each patch and at each time period. Habitat suitability could be defined as a proportion of the maximum carrying capacity, or set to zero where the area is unsuitable for the species. The effects of the environment are modelled without changing the demographic parameters, as an envelope beyond which the species cannot persist.

Environmental changes could affect a species rate of growth, as well as its absolute population size (Jeltsch et al. 2011). Therefore, a second way the demoniche model links current and future environmental conditions to growth is through ‘Niche values’. In each time step, the niche value where the population is located is multiplied by the matrix elements defined by the user. Using niche values to modify the matrix directly affects transition probabilities, and thus represents a more ‘mechanistic’ effect of the environment. However, this requires more information about the species, but many experimental and observational studies in the literature can be used to estimate parameters (Thuiller et al. 2008). For example, one might know from previous studies that a certain land use decreases the probability of juvenile survival but has no effect on adults, so niche values can be set to only affect juveniles (Monasterio et al. 2011). Users can either keep the niche conditions stable or model temporal changes in the niche suitability of the species, according to the availability of information and purpose of the investigation.

A third way to model the link between the environment and the species growth is through including different matrices that can represent different scenarios (the scenario matrices described above). For example, a matrix can represent a periodic fire that triggers seedling establishment but kills all other life stages (Keith et al. 2008). The matrices are selected randomly each time step according to a user-defined probability.

Model parameterization

Input data is either written directly into the R workspace, or imported from csv or txt files according to standard R pro cedures. The first step is to run the function ‘demoniche_ setup’ (Fig. 1), which checks the consistency of the user-supplied information and generates an R object containing the necessary modelling information.

Figure 1.

Schema of the two functions in ‘demoniche’ in their simplest realization. Each argument in the function has to be defined by the user. Other possible arguments are detailed in the manual. First the user enters demographic and geographic information into the ‘demoniche_setup’ function. A species object, ‘Hmontana’ with all the necessary information is created. In the ‘demoniche_model’ function the user specifies if she/he wishes to include effects of Niche values and dispersal, and runs the demographic modelling with the information from the species object. A summary file (mean population sizes per time step) from the demographic modelling is created in the R workspace. Plots (Fig. 2, 3) are generated, and complete yearly projections from each repetition and each sub-population are saved in the working directory.

Secondly, the ‘demoniche_model’ function (Fig. 1) performs the modelling simulations on the species object created by ‘demoniche_setup’. It creates a population vector for each population, time step and time period, which is fed to the ‘demoniche_ population’ function that carries out matrix multiplication. The user also specifies how many repetitions are to be carried out and supplies a name for the folder where simulation results will be saved.

A manual and an example script explaining the possible values of each argument in the model are included in the package. The script shows step-by-step modelling for one example species and uses demographic data for Hudsonia montana (mountain goldenheather, Gross et al. 1998, Morris and Doak 2002) from the popbio package, and a hypothetical geographical distribution.

Model output

demoniche offers different ways to compare results across multiple repetitions and scenarios. Outputs are created from the modelling process to assess species sensitivity to the environmental and human impacts that have been defined in the model (Fig. 1). First, the output from the ‘demoniche_model’ function is a summary file containing the mean and standard deviation of population sizes at each time step calculated from all repetitions. The function also saves the total initial range size, initial population size, percentage of populations that went extinct during the simulations, the growth rate (λ, function ‘eigen.analysis’from the popbio R-package, Stubben and Milligan 2007) of the scenario matrix and the long-term stochastic growth rate calculated from the mean/reference and scenario matrices. The function automatically creates graphs of the EMA of each transition matrix scenario (expected minimum abundance, McCarthy and Thompson 2001, Fig. 2) and maps of the spatial abundance at each time step (Fig. 3). Complete population projections from each time step, population and repetition are saved.

Figure 2.

Expected minimum abundance in each modelled time period. Hudsonia montana is a low-growing shrub. Each EMA trajectory results from matrix multiplication with different matrices may represent different scenarios of environmental change, management or catastrophes.

Figure 3.

Map of population sizes in each patch, with dispersal. Each panel is a snapshot of the species distribution (along x and y axis), during each time period of the simulation (2000–2030). The colour indicates the population size in each population. These maps are automatically generated by the ‘demoniche_model’ function and are intended for a quick visualization of results. The original data can be accessed and graphed as the user wants.

In conclusion, the demoniche package offers a modifiable framework for spatially-explicit demographic modelling, with random fluctuations and gradual changes in the environment. With demoniche users can explore the effects of various future scenarios, for example, future environmental conditions, different probabilities of scenario matrix selection, demographic variability, and dispersal rates. Modellers can directly take advantage of the graphing and data-management capacities of R. A further advantage to R is the transparency and adaptability of any part of the code to the specific modelling needs of the species and the modellers.

Available at: < >. From within R type: install.packages (“demoniche”, repos = <>).

To cite demoniche or acknowledge its use, cite this Software note as follows, substituting the version of the application that you used for ‘version 0’:

Nenzén, H. K., Swab, R. M., Keith, D. A. and Araújo, M. B. 2012. demoniche – an R-package for simulating spatially-explicit population dynamics. – Ecography 35: xxx–xxx (ver. 0).


Thanks to Regan Early for thoughtful advice about demographic modelling. Thanks to François Guilhaumon for generously sharing knowledge about package-building in R. Thanks to popbio and BIOMOD packages for inspiration. Early versions of this model were made at the Center for Spatial Analysis, Univ. Mayor de San Andres, Bolivia. HN is funded by the Portuguese Foundation Science and Technology (FCT) through the ‘Rui Nabeiro’ Biodiversity Chair and the CIBIO. MBA is funded through the FCT Range Shift (PTDC/AAC-AMB/ 98163/2008) project and acknowledges the Spanish Research Council (CSIC), the ‘Rui Nabeiro/Delta’ Biodiversity Chair, and the Danish NSF for support of his research.