Implementation of combined formal demographic models: Caswell II,III,IV.

kin_multi_stage_time_variant_2sex(
  U_list_females = NULL,
  U_list_males = NULL,
  F_list_females = NULL,
  F_list_males = NULL,
  T_list_females = NULL,
  T_list_males = NULL,
  birth_female = 0.49,
  parity = FALSE,
  output_kin = NULL,
  summary_kin = TRUE,
  sex_Focal = "Female",
  initial_stage_Focal = NULL,
  output_years,
  fast = FALSE
)

Arguments

U_list_females

list with matrix entries: period-specific female survival probabilities. Age in rows and states in columns.

U_list_males

list with matrix entries: period-specific male survival probabilities. Age in rows and states in columns.

F_list_females

list with matrix with elements: period-specific female fertility (age in rows and states in columns).

F_list_males

list with matrix entries: period-specific male fertility (age in rows and states in columns).

T_list_females

list of lists with matrix entries: each outer list entry is period-specific, and composed of a list of stochastic matrices which describe age-specific female probabilities of transferring stage

T_list_males

list of lists with matrix entries: each outer list entry is period-specific, and composed of a list of stochastic matrices which describe age-specific male probabilities of transferring stage

birth_female

numeric. Female portion at birth. This can be a vector of length equal to the number of years in the input data, or a single value that will be repeated for all years.

parity

logical. parity states imply age distribution of mothers re-scaled to not have parity 0 when Focal born. Default TRUE.

output_kin

vector. A vector of particular kin one wishes to obtain results for, e.g., c("m","d","oa"). Default is all kin types.

summary_kin

logical. Results as a data frame of accumulated kin by age of Focal if TRUE, and kin by their age*stage distribution by age of Focal if FALSE.

sex_Focal

character. Female or Male as the user requests.

initial_stage_Focal

Numeric in Natural number set 1,2,...,. The stage which Focal is born into (e.g., 1 for parity 0)

output_years

vector. The times at which we wish to count kin: start year = output_years1, and end year = output_yearslength.

fast

logical. If FALSE (the default) the model runs with the original R implementation (dense matrix products in R, output tables assembled with dplyr, tidyr and data.table). If TRUE, the same projections run in compiled C++ code and the output tables are built directly, which is typically 5 to 200 times faster on large inputs (long time series, two-sex, cause-of-death or multistate models). The returned object is identical in both cases: same values, same columns, same row order, same classes. Use fast = TRUE for production runs and fast = FALSE to read or step through the model equations in R.

Value

A data frame with focal age, kin age, kin stage, kin sex, year, cohort, and expected number of kin given these restrictions.