life_histories: R6 class to simulate the life histories of mothers

In courtiol/twinR: A Supporting R Package for the Paper "Mothers with higher twinning propensity had lower fertility in pre-industrial Europe" (Rickard et al., Nature Communications 2002)

R6 class to simulate the life histories of mothers

Description

R6 class to simulate the life histories of mothers

R6 class to simulate the life histories of mothers

Details

life_histories is an R6 class which we used to simulate the reproductive life of mothers, according to specific hypotheses defined by the simulation scenarios. The class contains the simulated data, as well as methods (i.e. functions) that can be applied on the R6 object after it has been created.

We recommend you to look at the raw R code of this class definition on GitHub (file '/R/simulations.R') to understand how simulations work. We commented the code to make this clear. While you could directly look at the code of this class definition while using the package, mind that the comments will have been stripped away during the installation process.

What is R6? R6 is an R package that provides a system to define objects in R. Perhaps you have already heard of some of the native systems for creating objects in R. Those are S3 (which is by far the dominant way of handling objects in R), S4 (which is heavily used by some specific packages like Matrix and all packages from Bioconductor) and ReferenceClasses (which is little used).

R6 is a system tailored to define classes and methods following a traditional Object Oriented Programming (OOP; as found in C++ & Java), while keeping with a very simple R syntax.

We initially chose to use R6 because we thought of coding individual-based simulations as a collection of R6 objects, wherein each object would represent a mother (and would thus be of the same class). In the end, we chose not to do that, since the simulations are simple enough to manipulate data frames, which is more efficient. Yet, the structure offered by R6 is still suitable since it allows to code within a single well structured chunk of code, the entire simulation and data representation. We believe that this should help those who want to understand exactly how we performed our simulations.

Public fields

birth_level_data

a tibble containing the birth-level data used to initialize the simulation (provided as input)

fit_PP

a fitted model for predicting the probability of parity progression (see fit_models) (provided as input)

fit_IBI

a fitted model for predicting the duration of the interbirth interval (minus 6 months) (see fit_models) (provided as input)

fit_twinning.binary

a fitted model for predicting the probability of twinning for a given birth event (see fit_models) (provided as input)

verbose

a list of booleans indicating whether or not to display information at various steps (provided as input)

iteration

the number of the current iteration of the simulation

data_iteration

a tibble storing the information corresponding to one simulation iteration (generated automatically)

data_simulated

a tibble containing the complete simulated dataset (generated automatically)

birth_level_data.simulated

a tibble containing the simulated data expressed as birth-level data (generated automatically)

fit_twinning.binomial

the fitted model producing the main slope of interest (see fit_models) (generated automatically)

slope

the main slope of interest quantifying effect of total_birth on the log odd of twinning (generated automatically)

Methods

Public methods

• life_histories$new()

• life_histories$build_initial_state()

• life_histories$simulate_one_iteration()

• life_histories$update_data_simulated()

• life_histories$filter_data_simulated()

• life_histories$run()

• life_histories$format_data_outputs()

• life_histories$clone()

---

Method new()

Create a new object from the class life_histories (constructor)

This functions is used to import the users' inputs and prepare the object that will store the outcome of simulations.

Usage

life_histories$new(
  fit_PP,
  fit_IBI,
  fit_twinning.binary,
  birth_level_data,
  verbose = list(fit = FALSE, simu = FALSE)
)

Arguments

fit_PP

fit_PP a fitted model for predicting the probability of parity progression (see fit_models)

fit_IBI

a fitted model for predicting the duration of the interbirth interval (minus 6 months) (see fit_models)

fit_twinning.binary

a fitted model for predicting the probability of twinning for a given birth event (see fit_models)

birth_level_data

a tibble containing the birth-level data used to initialize the simulation

verbose

a list of booleans indicating whether or not to display information at various steps

Returns

an object of class life_histories

---

Method build_initial_state()

Build the initial state for the simulations

To initialize the population, we use the observed dataset and retain the information of mothers at their first parity. That way, the age at first birth, their identity and the number of mothers from each population remains the same as the one from the real dataset. We do not keep the twinning status of the first birth. This is because we only keep the characteristics of the mothers that are not influenced by our simulation scenarios. Since our simulation scenarios influence the probability of twinning at all births, including the first one, we will thus simulate the twinning status at first birth. This will be done in steps beyond such building of the initial state of the population.

Usage

life_histories$build_initial_state()

---

Method simulate_one_iteration()

Simulate an iteration of the life history of the mothers

This function simulates one iteration of the life history of the mothers. In the simulation, an iteration corresponds to three specific happenings:

• the simulation of the twinning status of the current birth based on the probability of twinning for a given birth event (pre-birth twinning probability)

• the simulation of whether the mother will go on producing a next birth based on the probability for parity progression

• and, if the mother does go on reproducing, the simulation of the duration of the interbirth interval between the current birth and the next one

Usage

life_histories$simulate_one_iteration()

---

Method update_data_simulated()

Update the simulated dataset

This function adds data from a given iteration to the complete dataset (i.e. data_simulated).

Usage

life_histories$update_data_simulated()

---

Method filter_data_simulated()

Filter the simulated dataset

This function removes the mothers no longer reproducing, so they won't contribute to future iterations. Such mothers are those for which fit_PP predicts they won't go on reproducing. Additionally, we put a hard threshold at 60 years so that even under badly fitted models, the simulation will stop at some point. Some simulated mothers can still reach ages greater than 60, but no mother will reproduce passed 60.

Usage

life_histories$filter_data_simulated()

---

Method run()

Run the simulation

This is the main function used to run the simulation. It calls, in turns, simulate_one_iteration(), update_data_simulated() and filter_data_simulated(), until no mother keeps reproducing.

Usage

life_histories$run()

---

Method format_data_outputs()

Format the simulated data as original data

This function turns the simulated data into birth level data and mother level data that are structured as the original data.

Usage

life_histories$format_data_outputs()

---

Method clone()

The objects of this class are cloneable with this method.

Usage

life_histories$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# See ?twinR

courtiol/twinR documentation built on July 11, 2024, 12:04 a.m.