fit_models: Fit the models
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)

fit_models

R Documentation

Fit the models

Description

These functions fit the models used in the paper. They are all wrappers more or less simple ultimately calling the function fitme to fit the (G)LM(M)s we need. They have been programmed to be used with our specific data structure. The functions fit_PP, fit_IBI and fit_twinning.binary are those used to fit the three main life history traits. There are called repeatedly when simulating slopes of interests so to perform the goodness of fit (the most computationally demanding task of this project, see simulate_slopes_for_GOF). We programmed them specially so that the polynomial order of the term poly(cbind(age, parity), order) can be automatically estimated if poly_order is set to NA. In such a case, models differing in their polynomial orders will be fitted, starting from an order of 0 till reaching the order defined by max_order, unless the timeout value is reached. When the later occurs, only the polynomial orders below the critical value are being compared to identify the best order. Otherwise, they are all compared and the model fits leading to the minimal marginal AIC values are retained. To speed up the estimation of parameters, the fitting of more complex models reuse the model fitted with the polynomial order just bellow. For example, when fitting a polynomial order of 3, the fit obtained for a polynomial order of 2 is used to initialized the parameter values to be estimated.

Usage

fit_totalbirths(
  mother_level_data,
  when_twinner = "allbirths",
  with_age = FALSE,
  timeout = Inf,
  verbose = TRUE
)

fit_twinner.allbirths(
  mother_level_data,
  with_age = FALSE,
  timeout = Inf,
  verbose = TRUE
)

fit_twinner.firstbirth(mother_level_data, timeout = Inf, verbose = TRUE)

fit_twinning.binomial(mother_level_data, timeout = Inf, verbose = TRUE)

fit_twinning.binomial_with_pop_as_fixed(
  mother_level_data,
  timeout = Inf,
  verbose = TRUE
)

fit_twinning.binomial_with_pop_interaction(
  mother_level_data,
  timeout = Inf,
  verbose = TRUE
)

fit_AFB(mother_level_data, timeout = Inf, verbose = TRUE)

fit_PP(
  birth_level_data,
  poly_order = NA,
  twin_as.predictor = TRUE,
  max_order = 6L,
  timeout = Inf,
  verbose = TRUE,
  .simpler_fit = NULL
)

fit_IBI(
  birth_level_data,
  poly_order = NA,
  twin_as.predictor = TRUE,
  max_order = 6L,
  timeout = Inf,
  verbose = TRUE,
  .simpler_fit = NULL
)

fit_twinning.binary(
  birth_level_data,
  poly_order = NA,
  maternal_ID_as.predictor = TRUE,
  max_order = 6L,
  timeout = Inf,
  verbose = TRUE,
  .simpler_fit = NULL
)

fit_life_histories(
  scenario,
  birth_level_data,
  max_order = 6L,
  timeout = Inf,
  verbose = TRUE
)

compute_slope_from_birth.level.data(
  birth_level_data,
  timeout = Inf,
  verbose = TRUE
)

fit_model_safely(timeout, .args)

Arguments

`mother_level_data`	a `tibble` or `data.frame` with mother level data
`when_twinner`	a string of characters indicating if the twinning status is based on all births ('allbirths') or just on the first one ('firstbirth')
`with_age`	a logical indicating if the fit must be controlled for by mothers' age
`timeout`	the maximal duration (in seconds) allowed for the fitting procedure (default = Inf)
`verbose`	whether to display the formula of the fit during the fitting procedure
`birth_level_data`	a `tibble` or `data.frame` with birth level data (expanded or not)
`poly_order`	an integer value defining the polynomial order when considering the effect of age and parity (default = `NA`, find best value between 0 and `max_order`)
`twin_as.predictor`	whether to include the variable `twin` as a predictor or not in some models (default = `TRUE`)
`max_order`	if `poly_order = NA`, the argument defines the maximum polynomial order to try (default = 6L)
`.simpler_fit`	a simpler fit from which to extract fitted parameter values to use as initial parameter values in more complex fit (optional)
`maternal_ID_as.predictor`	whether to include the variable `maternal_ID` as a random effect predictor or not in some models (default = `TRUE`)
`scenario`	the scenario defining which models to be fitted: e.g. "ABCD", "AC"... (see paper for explanations)
`.args`	an internal list used to pass the argument to the function `fitme`

Details

See Functions, below, for details on which model each function does fit.

Value

the fitted model

Functions

fit_totalbirths(): fit the model predicting the total number of births per mother from her twinning status
fit_twinner.allbirths(): fit the model predicting the twinning status of the mother at any birth during her life from her total number of births
fit_twinner.firstbirth(): fit the model predicting the twinning status of the mother at first birth from her total number of births
fit_twinning.binomial(): fit the model predicting the probability of a birth to result in twins from the total number of births
fit_twinning.binomial_with_pop_as_fixed(): fit the model predicting the probability of a birth to result in twins from the total number of births with population considered as a fixed effect
fit_twinning.binomial_with_pop_interaction(): fit the model predicting the probability of a birth to result in twins from the total number of births in interaction with the population
fit_AFB(): fit the model predicting the age at first birth from the twinning status and the total number of births
fit_PP(): fit the model predicting the probability of parity progression
fit_IBI(): fit the model predicting the duration of the interbirth interval (minus 6 months)
fit_twinning.binary(): fit the model predicting the probability of twinning for a given birth event
fit_life_histories(): fit all three life history models according to the simulation scenario

This function fits all three life history models according to the simulation scenario provided. The polynomial orders are estimated, which is why each of the three models has to be fitted seven times under its default settings (order 0->6). It also returns the total time elapsed by the function.
compute_slope_from_birth.level.data(): compute the slope between the total number of births and the per-birth twinning probability from birth level data

This function fits the model investigating the relationship between parity and twinning probability using fit_twinning.binomial and retrieve the slope of interest. For this, it aggregates the birth level data.
fit_model_safely(): internal function calling the fitting function from spaMM

This internal function allows for the handling of messages and timeout threshold. It is called by all the other fitting functions.