IBMPopSim v0.3.0

0

Monthly downloads

0th

Percentile

Individual Based Model Population Simulation

Simulation of the random evolution of structured population dynamics, called stochastic Individual Based Models (IBMs) (see e.g. Ferri<c3><a8>re and Tran (2009) <doi:10.1051/proc/2009033>, Bansaye and M<c3><a9>l<c3><a9>ard (2015) <doi:10.1007/978-3-319-21711-6>, Boumezoued (2016)). The package allows users to simulate the random evolution of a population in which individuals are characterised by their date of birth, a set of attributes, and their potential date of death.

Readme

IBMPopSim

The IBMPopSim package aims at simulating the random evolution of heterogeneous populations, called stochastic Individual Based Models (IBMs). Such models have a wide range of applications in various fields including actuarial sciences, biology, demography, or ecology. For instance, IBMs can be used for simulating the evolution of an heterogeneous insurance portfolio, of an spatial ecological population with interacting individuals, or for validation mortality forecasts.

The package allows users to simulate population evolution in which individuals are characterized by their age and some characteristics, and where the population is modified by different types of events including births/arrivals, death/exit events, or changes of characteristics. The frequency at which an event can occur to an individual can depend on his age and characteristics, but also on time and on the rest of the population (interactions).

IBMPopSim overcomes the limitations of time consuming IBMs simulations. This is done by implementing new efficient algorithms based on thinning methods, which are compiled using the Rcpp library. The package allows a wide range of IMBs to be simulated, while being user-friendly thanks to its structure based on simple build blocks. In addition, we provide tools for analyzing outputs, such a age-pyramids or life tables obtained from the simulated data, consistent with the data format of packages for mortality modeling such as StMoMo. See vignette(IBMPopSim) for more details.

Installation

The latest stable version can be installed from CRAN:

install.packages('IBMPopSim')

The latest development version can be installed from github:

# install.packages("devtools")
devtools::install_github('DaphneGiorgi/IBMPopSim')

First example to check installation

To illustrate the use of the package and to check the installation, a simple model with Poisson arrivals and exits is implemented.

library(IBMPopSim)

init_size <- 100000
pop <- data.frame(birth = rep(0, init_size), death = NA)

birth = mk_event_poisson(type = 'birth', intensity = 'lambda')
death = mk_event_poisson(type = 'death', intensity = 'mu')
params = list('lambda' = 100, 'mu' = 100)

# mk_model compiles C++ code using sourceCpp from Rcpp
birth_death <- mk_model(events = list(birth, death),
                        parameters = params)

If there are no errors then the C++ built environment is compatible with the package. The model is created and a C++ code has been compiled. The simulation is done using the popsim function.

sim_out <- popsim(model = birth_death, 
                  population = pop, 
                  events_bounds = c('birth' = params$lambda, 'death' = params$mu),
                  parameters = params, 
                  time = 10)
## Simulation on  [0, 10]

num_births <- length(sim_out$population$birth) - init_size
num_deaths <- sum(!is.na(sim_out$population$death))
print(c("births" = num_births, "deaths" = num_deaths))
## births deaths 
##    952    981

Quick model creation

  • We take here an initial population, stored in a data frame, composed of 100 000 individuals marked by their gender (encoded by a Boolean characteristic):
pop <- EW_pop_14$sample
  • The second step is to define the model parameters’ list:
params <- list("alpha" = 0.008, "beta" = 0.02, "p_male" = 0.51,
               "birth_rate" = stepfun(c(15,40), c(0,0.05,0)))
  • The last step is to defined the events that can occur in the population, here birth and death events:
death_event <- mk_event_individual(type = "death",
                  intensity_code = "result = alpha * exp(beta * age(I, t));")

birth_event <- mk_event_individual(type = "birth", 
                  intensity_code = "result = birth_rate(age(I,t));",
                  kernel_code = "newI.male = CUnif(0, 1) < p_male;")

Note that these events contain some C++ statements that depend (implicitly) on the previously declared parameters in variable params.

  • Finally, the model is created by calling the function mk_model. A C++ source code is obtained from the events and parameters, then compiled using the sourceCpp function of the Rcpp package.
model <- mk_model(characteristics = get_characteristics(pop),
                  events = list(death_event, birth_event),
                  parameters = params)
  • In order to simulate a random trajectory of the population until a given time T bounds on the events intensities have to be specified:
a_max <- 115
events_bounds = c("death" = params$alpha * exp(params$beta * a_max),
                  "birth" = max(params$birth_rate))

Then, the function popsim can be called:

sim_out <- popsim(model, pop, events_bounds, params,
                  age_max = a_max, time = 30)
## Simulation on  [0, 30]
  • The data frame sim_out$population contains the information (date of birth, date of death, gender) on individuals who lived in the population over the period [0, 30]. Functions of the package allows to provide aggregated information on the population.
pop_out <- sim_out$population
head(pop_out)
##       birth death  male
## 1 -84.96043    NA FALSE
## 2 -84.86327    NA FALSE
## 3 -84.84161    NA FALSE
## 4 -84.79779    NA FALSE
## 5 -84.76461    NA FALSE
## 6 -84.76363    NA FALSE
female_pop <- pop_out[pop_out$male==FALSE, ]
age_pyramid(female_pop, ages = 85:90, time = 30)
##       age  male value
## 1 85 - 86 FALSE   224
## 2 86 - 87 FALSE   250
## 3 87 - 88 FALSE   213
## 4 88 - 89 FALSE   170
## 5 89 - 90 FALSE   180
Dxt <- death_table(female_pop, ages = 85:90, period = 20:30)
Ext <- exposure_table(female_pop, ages = 85:90, period = 20:30)
  • Note that parameters of the model can be changed without recompiling the model.
params$beta <- 0.01

# Update death event bound:
events_bounds["death"] <- params$alpha * exp(params$beta * a_max)

sim_out <- popsim(model, pop, events_bounds, params,
                  age_max = a_max, time = 30)

Functions in IBMPopSim

Name Description
mk_parameters_types Extract types (R and C++) of the parameters
mk_event_individual Creates an event with intensity of class individual.
merge_pop_withid A function returning a merged dataframe from a list of population dataframes with id.
mk_event_poisson Creates Poisson class event.
piecewise_xy Piecewise real function of two variables.
plot_population Plot the age pyramid of a population data frame (at a given time).
mk_model Creates a model for IBMPopSim.
weibull Weibull function.
mk_event_inhomogeneous_poisson Creates inhomogeneous Poisson class event.
plot_pyramid Plot an age pyramid from age pyramid data frame.
mk_event_interaction Creates an event with intensity of type interaction.
linfun Linear interpolation function.
piecewise_x Piecewise real function.
popsample Sample a population from an age pyramid (at a given time).
stepfun Step Function.
max.stepfun Returns the maximum of a function of class stepfun.
summary.event Summary of an event.
popsim Simulation of a model.
population_alive Returns a population of individuals alive.
exposure_table Creates an exposure table.
toy_params Toy parameters for IBMPopSim-human_popIMD vignette example.
summary.model Summary of a model.
get_characteristics Returns names and C types of the characteristics.
EW_pop_14 England and Wales (EW) 2014 population, death and birth rates.
age_pyramids Age pyramid from a population data frame at some given times.
death_table Creates a death table.
gompertz Gompertz<U+2013>Makeham intensity function.
age_pyramid Age pyramid from a population data frame at a given time.
EW_pop_out Example of "human population" after 100 years of simulation.
EW_popIMD_14 England and Wales (EW) 2014 population and death rates by Index of Multiple Deprivation (IMD).
EWdata_hmd England and Wale mortality data (source: Human Mortality Database)
No Results!

Vignettes of IBMPopSim

Name
IBMPopSim.Rmd
IBMPopSim.Rmd.orig
IBMPopSim.bib
IBMPopSim_cpp.Rmd
IBMPopSim_cpp.Rmd.orig
IBMPopSim_human_pop.Rmd
IBMPopSim_human_pop.Rmd.orig
IBMPopSim_human_pop_IMD.Rmd
IBMPopSim_human_pop_IMD.Rmd.orig
IBMPopSim_insurance_portfolio.Rmd
IBMPopSim_insurance_portfolio.Rmd.orig
IBMPopSim_interaction.Rmd
IBMPopSim_interaction.Rmd.orig
hpIMD_birth_intensities-1.pdf
hpIMD_compo_fem-1.pdf
hpIMD_compo_fem2-1.pdf
hpIMD_compo_fem2-2.pdf
hpIMD_death_rate-1.pdf
hpIMD_df-1.pdf
hpIMD_pyramids-1.pdf
hpIMD_pyramids-2.pdf
hp_birth_distrib-1.pdf
hp_death_rate_1-1.pdf
hp_intensities-1.pdf
hp_log_death-1.pdf
hp_pop_init-1.pdf
hp_pop_init_1e6-1.pdf
hp_pyramid_50-1.pdf
hp_pyramids-1.pdf
hp_pyramids2-1.pdf
insur_LeeCarter_risk1-1.pdf
insur_cohort-1.pdf
insur_evol_mortality-1.pdf
insur_forecast-1.pdf
insur_mortality_rates-1.pdf
insur_pyr_group-1.pdf
insur_pyramid-1.pdf
inter_output-1.png
inter_output2-1.png
inter_output3-1.png
inter_pyramid-1.png
main_plot_30-1.pdf
main_prob_subgroup1-1.pdf
plot_piecewise-1.pdf
plot_stepfun-1.pdf
precompile.R
No Results!

Last month downloads

Details

Type Package
Date 2020-10-09
URL https://github.com/DaphneGiorgi/IBMPopSim, https://DaphneGiorgi.github.io/IBMPopSim/
BugReports https://github.com/DaphneGiorgi/IBMPopSim/issues
License MIT + file LICENSE
LazyData true
SystemRequirements C++11
NeedsCompilation no
VignetteBuilder knitr
RoxygenNote 7.1.1
Encoding UTF-8
Packaged 2020-10-09 10:56:02 UTC; giorgi
Repository CRAN
Date/Publication 2020-10-17 12:00:02 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/IBMPopSim)](http://www.rdocumentation.org/packages/IBMPopSim)