Implementation of Goodman-Keyfitz-Pullum equations in a matrix framework. This produce a matrilineal (or patrilineal) kin count distribution by kin and age.
kin(
p = NULL,
f = NULL,
time_invariant = TRUE,
pi = NULL,
n = NULL,
output_cohort = NULL,
output_period = NULL,
output_kin = NULL,
output_age_focal = NULL,
output_year_last = FALSE,
birth_female = 1/2.04,
summary_kin = TRUE,
fast = FALSE
)numeric. A vector (atomic) or matrix with probabilities (or survival ratios, or transition between age class in a more general perspective) with rows as ages (and columns as years in case of matrix, being the name of each col the year).
numeric. Same as p but for fertility rates.
logical. Constant assumption for a given year rates. Default TRUE.
numeric. Same as U but for childbearing distribution (sum to 1). Optional.
numeric. Only for time_invariant = FALSE. Same as p but for population distribution (counts or %). Optional.
integer. Vector of year cohorts for returning results. Should be within input data years range.
integer. Vector of period years for returning results. Should be within input data years range.
character. kin types to return: "m" for mother, "d" for daughter,... See demokin_codes.
integer. Vector of ages to select (and make faster the run).
numeric. Female portion at birth. This multiplies f argument. If f is already for female offspring, this needs to be set as 1. 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.
logical. Whether or not include kin_summary table (see output details). Default TRUE.
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.
Include or not last year of living kin. If rates are from years 0 to n, not including is no output in n+1. Deafult FALSE.
A list with:
kin_full a data frame with year, cohort, Focal´s age, related ages and type of kin (for example d is daughter,
oa is older aunts, etc.), including living and dead kin at that age.
kin_summary a data frame with Focal´s age, related ages and type of kin, with indicators obtained processing kin_full,
grouping by cohort or period (depending on the given arguments):
count_living: count of living kin at actual age of Focal
mean_age: mean age of each type of living kin.
sd_age: standard deviation of age of each type of living kin.
count_death: count of dead kin at specific age of Focal.
count_cum_death: cumulated count of dead kin until specific age of Focal.
mean_age_lost: mean age where Focal lost her relative.
See Caswell (2019) and Caswell (2021) for details on formulas. One sex only (female by default).
Fast implementation. Setting fast = TRUE switches to a C++ implementation of the
same model: the projection recursions are replayed on the non-zero entries of the
projection matrices, accumulating in the same order as R's dense matrix product, so the
results round identically. The R code run with fast = FALSE is unchanged and remains
the reference description of the method; the C++ path is checked against it in the test
suite (tests/testthat/test-fast_equals_default.R) and on a 46-scenario harness
(dev/equivalence/). Messages, warnings and errors are the same in both modes; the only
user-visible difference is run time.
# Kin expected matrilineal count for a Swedish female based on 2015 rates.
swe_surv_2015 <- swe_px[,"2015"]
swe_asfr_2015 <- swe_asfr[,"2015"]
# Run kinship models
swe_2015 <- kin(p = swe_surv_2015, f = swe_asfr_2015)
head(swe_2015$kin_summary)
#> # A tibble: 6 × 10
#> age_focal kin year cohort count_living mean_age sd_age count_dead
#> <int> <chr> <lgl> <lgl> <dbl> <dbl> <dbl> <dbl>
#> 1 0 coa NA NA 0.275 8.32 6.14 0.0000633
#> 2 0 cya NA NA 0.0898 4.05 3.68 0.0000370
#> 3 0 d NA NA 0 NaN NaN 0
#> 4 0 gd NA NA 0 NaN NaN 0
#> 5 0 ggd NA NA 0 NaN NaN 0
#> 6 0 ggm NA NA 0.320 84.4 6.43 0.0287
#> # ℹ 2 more variables: count_cum_dead <dbl>, mean_age_lost <dbl>