# IBMPopSim v0.3.0

0

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.

# 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
##       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 GompertzMakeham 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!