Package 'DemoKin'

Title: Estimate Population Kin Distribution
Description: Estimate population kin counts and its distribution by type, age and sex. The package implements one-sex and two-sex framework for studying living-death availability, with time varying rates or not, and multi-stage model.
Authors: Iván Williams [cre], Diego Alburez-Gutierrez [aut], Xi Song [ctb], Caswell Hal [ctb]
Maintainer: Iván Williams <[email protected]>
License: MIT + file LICENSE
Version: 1.0.3
Built: 2024-11-13 12:27:46 UTC
Source: https://github.com/ivanwilli/demokin

Help Index

Title time invariant two-sex multi-state kin projections

Description

Title time invariant two-sex multi-state kin projections

Usage

all_kin_dy(
  Uf,
  Um,
  Ff,
  Fm,
  alpha,
  na,
  ns,
  Parity,
  sex_Focal,
  Initial_stage_Focal
)

Arguments

Uf

matrix (block structured). transfers female individuals across stages and advances their age (conditional on survial)
Um

matrix (block structured). transfers male individuals across stages and advances their age (conditional on survial)
Ff

matrix (block structured). accounts for female reproduction, and assigns newborns into given age*stage
Fm

matrix (block structured). accounts for male reproduction; assigns newborns into age-class, and stage
alpha

scalar. birth ratio (male:female)
na

scalar. number of ages.
ns

scalar. number of stages.
Parity

logical. If true then we omit mothers of parity 0, and re-scale the mother's age*stage of parenting
sex_Focal

logical. Female or Male
Initial_stage_Focal

numeric. Any natural number 1,2,3,4,...

Value

a list of matrices. Each list entry represents a particular kin. Each kin is chacacterised by a matrix of dimension: nrow = 2* na * ns (2-sex age-stage structured) and ncol = na (Focal's age) yielding the age*stage distribution of kin for each age of Focal

Title time-variant two-sex multi-state kin projections

Description

Title time-variant two-sex multi-state kin projections

Usage

all_kin_dy_TV(
  Uf,
  Um,
  Ff,
  Fm,
  alpha,
  na,
  ns,
  Parity,
  sex_Focal,
  Initial_stage_Focal,
  previous_kin_Focal,
  prev_kin_children,
  prev_kin_grandchildren,
  prev_kin_greatgrandchildren,
  prev_kin_parents,
  prev_kin_grand_parents,
  prev_kin_great_grand_parents,
  prev_kin_older_sibs,
  prev_kin_younger_sibs,
  prev_kin_older_niece_nephew,
  prev_kin_younger_niece_nephew,
  prev_kin_older_aunts_uncles,
  prev_kin_younger_aunts_uncles,
  prev_kin_older_cousins,
  prev_kin_younger_cousins,
  previous_population_age_stage_structure
)

Arguments

Uf

matrix (block structured). transfers female individuals across stages and advances their age (conditional on survial)
Um

matrix (block structured). transfers male individuals across stages and advances their age (conditional on survial)
Ff

matrix (block structured). accounts for female reproduction, and assigns newborns into given age*stage
Fm

matrix (block structured). accounts for male reproduction; assigns newborns into age-class, and stage
alpha

scalar. birth ratio (male:female)
na

scalar. number of ages.
ns

scalar. number of stages.
Parity

logical. If true then we omit mothers of parity 0, and re-scale the mother's age*stage of parenting
sex_Focal

logical. Female or Male
Initial_stage_Focal

numeric. Any natural number 1,2,3,4,...
previous_kin_Focal

matrix. last years kinship output.
prev_kin_children

matrix. last years kinship output.
prev_kin_grandchildren

matrix. last years kinship output.
prev_kin_greatgrandchildren

matrix. last years kinship output.
prev_kin_parents

matrix. last years kinship output.
prev_kin_grand_parents

matrix. last years kinship output.
prev_kin_older_sibs

matrix. last years kinship output.
prev_kin_younger_sibs

matrix. last years kinship output.
prev_kin_older_niece_nephew

matrix. last years kinship output.
prev_kin_younger_niece_nephew

matrix. last years kinship output.
prev_kin_older_aunts_uncles

matrix. last years kinship output.
prev_kin_younger_aunts_uncles

matrix. last years kinship output.
prev_kin_older_cousins

matrix. last years kinship output.
prev_kin_younger_cousins

matrix. last years kinship output.
previous_population_age_stage_structure

vector. The transient "population structure" (age*stage distributed)

Value

a list of matrices. Each list entry represents a particular kin. Each kin is chacacterised by a matrix of dimension: nrow = 2* na * ns (2-sex age-stage structured) and ncol = na (Focal's age) yielding the age*stage distribution of kin for each age of Focal

Title Accumulated kin by each age of Focal, for each time period, and cohort of birth

Description

Title Accumulated kin by each age of Focal, for each time period, and cohort of birth

Usage

create_cumsum_df(
  kin_matrix_lists,
  kin_names,
  years,
  start_year,
  na,
  ns,
  specific_kin
)

Arguments

kin_matrix_lists

list of lists of kin matrices: list( list(X_focal), list(X_parents), ... ). Outer list is length 14 = number of kin. Inner lists have lenght = timescale so list(X_focal) = list(X_focalyear1,X_focalyear2,...,X_focalyearlast)
kin_names

list of characters. Corresponding to above lists: list("F","m",....)
years

vector. The timescale on which we implement the kinship model.
start_year

. First year of varying vital rates (e.g., if years = 1990:2000 then start_year = 1990)
na

numeric. Number of ages.
ns

numeric. Number of stages.
specific_kin

character. names of kin we wish to analyse, e.g., list("os","ys"). If null returns all 14.

Value

A data frame which gives for each age of Focal at each year in the timescale, Focal's experienced number kin demarcated by stages (summed over all ages)

Title joint age*stage distributions of kin by each age of Focal, for each time period, and cohort of birth

Description

Title joint age*stage distributions of kin by each age of Focal, for each time period, and cohort of birth

Usage

create_full_dists_df(
  kin_matrix_lists,
  kin_names,
  years,
  start_year,
  na,
  ns,
  specific_kin
)

Arguments

kin_matrix_lists

list of lists of kin matrices: list( list(X_focal), list(X_parents), ... ). Outer list is length 14 = number of kin. Inner lists have lenght = timescale so list(X_focal) = list(X_focalyear1,X_focalyear2,...,X_focalyearlast)
kin_names

list of characters. Corresponding to above lists: list("F","m",....)
years

vector. The timescale on which we implement the kinship model.
start_year

. First year of varying vital rates (e.g., if years = 1990:2000 then start_year = 1990)
na

numeric. Number of ages.
ns

numeric. Number of stages.
specific_kin

character. names of kin we wish to analyse, e.g., list("os","ys"). If null returns all 14.

Value

A data frame which gives for each age of Focal at each year in the timescale, the full age*stage dist of kin

DemoKin codes, Caswell (2020) codes, and useful labels.

Description

DemoKin codes, Caswell (2020) codes, and useful labels.

Usage

demokin_codes

Format

A data.frame with codes and labels for distinction between kin types.

Historic and projected fertility ratios from Sweden used in Caswell (2021)

Description

Historic and projected fertility ratios from Sweden used in Caswell (2021)

Usage

f_caswell_2021

Format

A matrix f with years as cols and ages as rows.

Source

Caswell (2019)

Fertility for France (2012) by sex in Caswell (2022).

Description

Fertility for France (2012) by sex in Caswell (2022).

Usage

fra_asfr_sex

Format

A data.frame with age specific fertility rates by age and sex.

Source

Caswell (2022)

Survival probability for France (2012) by sex in Caswell (2022).

Description

Survival probability for France (2012) by sex in Caswell (2022).

Usage

fra_surv_sex

Format

A data.frame with survival probabilities by age and sex.

Source

Caswell (2022)

Estimate kin counts in a one-sex framework.

Description

Implementation of Goodman-Keyfitz-Pullum equations in a matrix framework. This produce a matrilineal (or patrilineal) kin count distribution by kin and age.

Usage

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,
  birth_female = 1/2.04,
  summary_kin = TRUE
)

Arguments

p

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).
f

numeric. Same as p but for fertility rates.
time_invariant

logical. Constant assumption for a given year rates. Default TRUE.
pi

numeric. Same as U but for childbearing distribution (sum to 1). Optional.
n

numeric. Only for time_invariant = FALSE. Same as p but for population distribution (counts or ⁠%⁠). Optional.
output_cohort

integer. Vector of year cohorts for returning results. Should be within input data years range.
output_period

integer. Vector of period years for returning results. Should be within input data years range.
output_kin

character. kin types to return: "m" for mother, "d" for daughter,...
output_age_focal

integer. Vector of ages to select (and make faster the run).
birth_female

numeric. Female portion at birth. This multiplies f argument. If f is already for female offspring,
summary_kin

logical. Whether or not include kin_summary table (see output details). Default TRUE. this needs to be set as 1.

Details

See Caswell (2019) and Caswell (2021) for details on formulas. One sex only (female by default).

Value

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.

Examples

# 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)

Estimate kin counts by age and stage in a time invariant framework

Description

Implementation of age-stage kin estimates (multi-state) by Caswell (2020). Stages are implied in length of input lists.

Usage

kin_multi_stage(
  U = NULL,
  f = NULL,
  D = NULL,
  H = NULL,
  birth_female = 1/2.04,
  output_kin = NULL,
  parity = FALSE,
  list_output = FALSE
)

Arguments

U

list. age elements with column-stochastic transition matrix with dimension for the state space, conditional on survival.
f

matrix. state-specific fertility (age in rows and states in columns). Is accepted also a list with for each age-class.
D

matrix. survival probabilities by state (age in rows and states in columns). Is accepted also a list for each state with survival matrices.
H

matrix. assigns the offspring of individuals in some stage to the appropriate age class (age in rows and states in columns). Is accepted also a list with a matrix for each state.
birth_female

numeric. Female portion at birth.
output_kin

character. kin to return. For example "m" for mother, "d" for daughter. See the vignette for all kin types.
parity

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

logical. Results as a list. Default FALSE.

Value

A data frame with focal´s age, related ages and type of kin (for example d is daughter, oa is older aunts, etc.), living and death kin counts, and specific stage. If list_output = TRUE then this is a list with elements as kin types.

Estimate kin counts by age, stage, and sex, in a time variant framework

Description

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

Usage

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,
  H_list = NULL,
  birth_female = 0.49,
  parity = FALSE,
  output_kin = FALSE,
  summary_kin = TRUE,
  sex_Focal = "Female",
  initial_stage_Focal = NULL,
  output_years
)

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
H_list

list with matrix entries: redistribution of newborns across each stage to a specific age-class
birth_female

numeric. birth ratio of females to males in population
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.

Value

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

Output for Slovakia 1990 in Caswell (2020).

Description

Output for Slovakia 1990 in Caswell (2020).

Usage

kin_svk1990_caswell2020

Format

A list with specific kin types age-stage matrix

Source

Caswell (2021)

Estimate kin counts in a time invariant framework for one-sex model (matrilineal/patrilineal)

Description

Mtrix implementation of Goodman-Keyfitz-Pullum equations adapted by Caswell (2019).

Usage

kin_time_invariant(
  p = NULL,
  f = NULL,
  birth_female = 1/2.04,
  pi = NULL,
  output_kin = NULL,
  list_output = FALSE
)

Arguments

p

numeric. A vector of survival probabilities with same length as ages.
f

numeric. A vector of age-specific fertility rates with same length as ages.
birth_female

numeric. Female portion at birth.
pi

numeric. For using some specific non-stable age distribution of childbearing (same length as ages). Default NULL.
output_kin

character. kin to return. For example "m" for mother, "d" for daughter. See vignette for all kin types.
list_output

logical. Results as a list with output_kin elements, with focal´s age in columns and kin ages in rows (2 * ages, last chunk of ages for death experience). Default FALSE

Value

A data frame with focal´s age, related ages and type of kin (for example d is daughter, oa is older aunts, etc.), alive and death. If list_output = TRUE then this is a list.

Estimate kin counts in a time invariant framework for two-sex model.

Description

Two-sex matrix framework for kin count estimates.This produces kin counts grouped by kin, age and sex of each relatives at each Focal´s age. For example, male cousins from aunts and uncles from different sibling's parents are grouped in one male count of cousins.

Usage

kin_time_invariant_2sex(
  pf = NULL,
  pm = NULL,
  ff = NULL,
  fm = NULL,
  sex_focal = "f",
  birth_female = 1/2.04,
  pif = NULL,
  pim = NULL,
  output_kin = NULL,
  list_output = FALSE
)

Arguments

pf

numeric. A vector of survival probabilities for females with same length as ages.
pm

numeric. A vector of survival probabilities for males with same length as ages.
ff

numeric. A vector of age-specific fertility rates for females with same length as ages.
fm

numeric. A vector of age-specific fertility rates for males with same length as ages.
sex_focal

character. "f" for female or "m" for male.
birth_female

numeric. Female portion at birth.
pif

numeric. For using some specific non-stable age distribution of childbearing for mothers (same length as ages). Default NULL.
pim

numeric. For using some specific non-stable age distribution of childbearing for fathers (same length as ages). Default NULL.
output_kin

character. kin to return, considering matrilineal names. For example "m" for parents, "d" for children, etc. See the vignette for all kin types.
list_output

logical. Results as a list with output_kin elements, with focal´s age in columns and kin ages in rows (2 * ages, last chunk of ages for death experience). Default FALSE

Details

See Caswell (2022) for details on formulas.

Value

A data frame with focal´s age, related ages and type of kin (for example d is children, oa is older aunts/uncles, etc.), sex, alive and death. If list_output = TRUE then this is a list.

Estimate kin counts in a time invariant framework for two-sex model.

Description

Two-sex matrix framework for kin count and death estimates.This produces kin counts grouped by kin, age and sex of each relatives at each Focal´s age. For example, male cousins from aunts and uncles from different sibling's parents are grouped in one male count of cousins. This also produces kin deaths grouped by kin, age, sex of each relatives at each Focal´s age, and cause of death.

Usage

kin_time_invariant_2sex_cod(
  pf = NULL,
  pm = NULL,
  ff = NULL,
  fm = NULL,
  Hf = NULL,
  Hm = NULL,
  sex_focal = "f",
  birth_female = 1/2.04,
  pif = NULL,
  pim = NULL,
  output_kin = NULL,
  list_output = FALSE
)

Arguments

pf

numeric. A vector of survival probabilities for females with same length as ages.
pm

numeric. A vector of survival probabilities for males with same length as ages.
ff

numeric. A vector of age-specific fertility rates for females with same length as ages.
fm

numeric. A vector of age-specific fertility rates for males with same length as ages.
Hf

numeric. A matrix with cause-specific hazards for females with rows as causes and columns as ages, being the name of each col the age.
Hm

numeric. A matrix with cause-specific hazards for males with rows as causes and columns as ages, being the name of each col the age.
sex_focal

character. "f" for female or "m" for male.
birth_female

numeric. Female portion at birth.
pif

numeric. For using some specific non-stable age distribution of childbearing for mothers (same length as ages). Default NULL.
pim

numeric. For using some specific non-stable age distribution of childbearing for fathers (same length as ages). Default NULL.
output_kin

character. kin to return, considering matrilineal names. For example "m" for parents, "d" for children, etc. See the vignette for all kin types.
list_output

logical. Results as a list with output_kin elements, with focal´s age in columns and kin ages in rows (2 * ages, last chunk of ages for death experience). Default FALSE

Details

See Caswell (2022) for details on formulas.

Value

A data frame with focal´s age, related ages and type of kin (for example d is children, oa is older aunts/uncles, etc.), sex, alive and death. If list_output = TRUE then this is a list.

Estimate kin counts in a time variant framework (dynamic rates) for one-sex model (matrilineal/patrilineal)

Description

Matrix implementation of time variant Goodman-Keyfitz-Pullum equations in a matrix framework.

Usage

kin_time_variant(
  p = NULL,
  f = NULL,
  pi = NULL,
  n = NULL,
  output_cohort = NULL,
  output_period = NULL,
  output_kin = NULL,
  birth_female = 1/2.04,
  list_output = FALSE
)

Arguments

p

numeric. A matrix of survival ratios with rows as ages and columns as years. Column names must be equal interval.
f

numeric. A matrix of age-specific fertility rates with rows as ages and columns as years. Coincident with U.
pi

numeric. A matrix with distribution of childbearing with rows as ages and columns as years. Coincident with U.
n

numeric. A matrix of population with rows as ages and columns as years. Coincident with U.
output_cohort

integer. Year of birth of focal to return as output. Could be a vector. Should be within input data years range.
output_period

integer. Year for which to return kinship structure. Could be a vector. Should be within input data years range.
output_kin

character. kin to return as output: "m" for mother, "d" for daughter,... See vignette for exahustive kin.
birth_female

numeric. Female portion at birth.
list_output

logical. Results as a list with years elements (as a result of output_cohort and output_period combination), with a second list of output_kin elements, with focal´s age in columns and kin ages in rows (2 * ages, last chunk of ages for death experience). Default FALSE

Details

See Caswell (2021) for details on formulas.

Value

A data frame of population kinship structure, with Focal's cohort, focal´s age, period year, type of relatives (for example d is daughter, oa is older aunts, etc.), living and death kin counts, and age of (living or time deceased) relatives. If list_output = TRUE then this is a list.

Estimate kin counts in a time variant framework (dynamic rates) in a two-sex framework (Caswell, 2022)

Description

Two-sex matrix framework for kin count estimates with varying rates. This produces kin counts grouped by kin, age and sex of each relatives at each Focal´s age. For example, male cousins from aunts and uncles from different sibling's parents are grouped in one male count of cousins.

Usage

kin_time_variant_2sex(
  pf = NULL,
  pm = NULL,
  ff = NULL,
  fm = NULL,
  sex_focal = "f",
  birth_female = 1/2.04,
  pif = NULL,
  pim = NULL,
  nf = NULL,
  nm = NULL,
  output_cohort = NULL,
  output_period = NULL,
  output_kin = NULL,
  list_output = FALSE
)

Arguments

pf

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).
pm

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).
ff

numeric. Same as pf but for fertility rates.
fm

numeric. Same as pm but for fertility rates.
sex_focal

character. "f" for female or "m" for male.
birth_female

numeric. Female portion at birth. This multiplies f argument. If f is already for female offspring, this needs to be set as 1.
pif

numeric. For using some specific age distribution of childbearing for mothers (same length as ages). Default NULL.
pim

numeric. For using some specific age distribution of childbearing for fathers (same length as ages). Default NULL.
nf

numeric. Same as pf but for population distribution (counts or ⁠%⁠). Optional.
nm

numeric. Same as pm but for population distribution (counts or ⁠%⁠). Optional.
output_cohort

integer. Vector of year cohorts for returning results. Should be within input data years range.
output_period

integer. Vector of period years for returning results. Should be within input data years range.
output_kin

character. kin types to return: "m" for mother, "d" for daughter,...
list_output

logical. Results as a list with years elements (as a result of output_cohort and output_period combination), with a second list of output_kin elements, with focal´s age in columns and kin ages in rows (2 * ages, last chunk of ages for death experience). Default FALSE

Details

See Caswell (2022) for details on formulas.

Value

A data.frame with year, cohort, Focal´s age, related ages, sex and type of kin (for example d is daughter, oa is older aunts, etc.), including living and dead kin at that age and sex.

Estimate kin counts in a time variant framework (dynamic rates) in a two-sex framework (Caswell, 2022)

Description

Two-sex matrix framework for kin count estimates with varying rates. This produces kin counts grouped by kin, age and sex of each relatives at each Focal´s age. For example, male cousins from aunts and uncles from different sibling's parents are grouped in one male count of cousins. This also produces kin deaths grouped by kin, age, sex of each relatives at each Focal´s age, and cause of death.

Usage

kin_time_variant_2sex_cod(
  pf = NULL,
  pm = NULL,
  ff = NULL,
  fm = NULL,
  Hf = NULL,
  Hm = NULL,
  sex_focal = "f",
  birth_female = 1/2.04,
  pif = NULL,
  pim = NULL,
  nf = NULL,
  nm = NULL,
  output_cohort = NULL,
  output_period = NULL,
  output_kin = NULL,
  list_output = FALSE
)

Arguments

pf

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).
pm

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).
ff

numeric. Same as pf but for fertility rates.
fm

numeric. Same as pm but for fertility rates.
Hf

numeric. A list where each list element (being the name of each list element the year) contains a matrix with cause-specific hazards for females with rows as causes and columns as ages, being the name of each col the age.
Hm

numeric. A list where each list element (being the name of each list element the year) contains a matrix with cause-specific hazards for males with rows as causes and columns as ages, being the name of each col the age.
sex_focal

character. "f" for female or "m" for male.
birth_female

numeric. Female portion at birth. This multiplies f argument. If f is already for female offspring, this needs to be set as 1.
pif

numeric. For using some specific age distribution of childbearing for mothers (same length as ages). Default NULL.
pim

numeric. For using some specific age distribution of childbearing for fathers (same length as ages). Default NULL.
nf

numeric. Same as pf but for population distribution (counts or ⁠%⁠). Optional.
nm

numeric. Same as pm but for population distribution (counts or ⁠%⁠). Optional.
output_cohort

integer. Vector of year cohorts for returning results. Should be within input data years range.
output_period

integer. Vector of period years for returning results. Should be within input data years range.
output_kin

character. kin types to return: "m" for mother, "d" for daughter,...
list_output

logical. Results as a list with years elements (as a result of output_cohort and output_period combination), with a second list of output_kin elements, with focal´s age in columns and kin ages in rows (2 * ages, last chunk of ages for death experience). Default FALSE

Details

See Caswell (2022) for details on formulas.

Value

A data.frame with year, cohort, Focal´s age, related ages, sex and type of kin (for example d is daughter, oa is older aunts, etc.), including living and dead kin at that age and sex.

Estimate kin counts in a two-sex framework

Description

Implementation of two-sex matrix kinship model. This produces kin counts grouped by kin, age and sex of each relatives at each Focal´s age. For example, male cousins from aunts and uncles from different sibling's parents are grouped in one male count of cousins. Note that the output labels relative following female notation: the label m refers to either mothers or fathers, and column sex_kin determine the sex of the relative.

Usage

kin2sex(
  pf = NULL,
  pm = NULL,
  ff = NULL,
  fm = NULL,
  time_invariant = TRUE,
  sex_focal = "f",
  birth_female = 1/2.04,
  pif = NULL,
  pim = NULL,
  nf = NULL,
  nm = NULL,
  Hf = NULL,
  Hm = NULL,
  output_cohort = NULL,
  output_period = NULL,
  output_kin = NULL,
  output_age_focal = NULL,
  summary_kin = TRUE
)

Arguments

pf

numeric. A vector (atomic) or matrix with female 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).
pm

numeric. A vector (atomic) or matrix with male 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).
ff

numeric. Same as pf but for fertility rates.
fm

numeric. Same as pm but for fertility rates.
time_invariant

logical. Constant assumption for a given year rates. Default TRUE.
sex_focal

character. "f" for female or "m" for male.
birth_female

numeric. Female portion at birth. This multiplies f argument. If f is already for female offspring, this needs to be set as 1.
pif

numeric. For using some specific age distribution of childbearing for mothers (same length as ages). Default NULL.
pim

numeric. For using some specific age distribution of childbearing for fathers (same length as ages). Default NULL.
nf

numeric. Only for time_invariant = FALSE. Same as pf but for population distribution (counts or ⁠%⁠). Optional.
nm

numeric. Only for time_invariant = FALSE. Same as pm but for population distribution (counts or ⁠%⁠). Optional.
Hf

numeric. A list where each list element (being the name of each list element the year) contains a matrix with cause-specific hazards for females with rows as causes and columns as ages, being the name of each col the age.
Hm

numeric. A list where each list element (being the name of each list element the year) contains a matrix with cause-specific hazards for males with rows as causes and columns as ages, being the name of each col the age.
output_cohort

integer. Vector of year cohorts for returning results. Should be within input data years range.
output_period

integer. Vector of period years for returning results. Should be within input data years range.
output_kin

character. kin types to return: "m" for mother, "d" for daughter,...
output_age_focal

integer. Vector of ages to select (and make faster the run).
summary_kin

logical. Whether or not include kin_summary table (see output details). Default TRUE.

Details

See Caswell (2022) for details on formulas.

Value

A list with:

  • kin_full a data frame with year, cohort, Focal´s age, related ages and type of kin (for example d could be daughter or son depending sex_kin, oa is older aunts or uncles also depending sex_kin value, etc.), including living and dead kin at that age.

  • kin_summary a data frame with Focal´s age, related ages, sex 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.

Examples

# Kin expected count by relative sex for a French female based on 2012 rates.
fra_fert_f <- fra_asfr_sex[,"ff"]
fra_fert_m <- fra_asfr_sex[,"fm"]
fra_surv_f <- fra_surv_sex[,"pf"]
fra_surv_m <- fra_surv_sex[,"pm"]
fra_2012 <- kin2sex(fra_surv_f, fra_surv_m, fra_fert_f, fra_fert_m)
head(fra_2012$kin_summary)

APC combination to return

Description

define APC combination to return in kin and kin2sex.

Usage

output_period_cohort_combination(
  output_cohort = NULL,
  output_period = NULL,
  age = NULL,
  years_data = NULL
)

Arguments

output_cohort

integer. A vector with selected calendar years.
output_period

integer. A vector with selected cohort years.
age

integer. A vector with ages from the kinship network to be filtered.
years_data

integer. A vector with years from the time-varying kinship network to be filtered.

Details

Because returning all period and cohort data from a huge time-series would be hard memory consuming, this function is an auxiliary one to deal with selection from inputs output_cohort and output_period.

Value

data.frame with years and ages to filter in kin and kin_2sex functions.

Historic and projected mother´s age distribution of childbearing from Sweden used in Caswell (2021)

Description

Historic and projected mother´s age distribution of childbearing from Sweden used in Caswell (2021)

Usage

pi_caswell_2021

Format

A matrix pi with years as cols and ages as rows.

Source

Caswell (2019)

Mixing distributions for the time-invariant multi-state 2-sex model: Non-parity case

Description

Mixing distributions for the time-invariant multi-state 2-sex model: Non-parity case

Usage

pi_mix(Uf, Um, Ff, Fm, alpha, na, ns)

Arguments

Uf

matrix. Block-structured matrix which transfers females over stage and advances their age
Um

matrix. Block-structured matrix which transfers males over stage and advances their age
Ff

matrix. Block-structured matrix which counts reproduction by females and assigns newborns an age and stage
Fm

matrix. Block-structured matrix which counts reproduction by males and assigns newborns an age and stage
alpha

scalar. Birth ratio male:female
na

scalar. Number of age-classes
ns

scalar. Number of stages

Value

list (of vectors). list[1] = full agestagesex distribution list[2] = female agestage distribution normalised list[3] = male agestage distribution normalised list[4] = female marginal age distribution normalised list[5] = male marginal age distribution normalised

Mixing distributions for the time-invariant multi-state 2-sex model: Parity-specific case

Description

Mixing distributions for the time-invariant multi-state 2-sex model: Parity-specific case

Usage

pi_mix_parity(Uf, Um, Ff, Fm, alpha, na, ns)

Arguments

Uf

matrix. Block-structured matrix which transfers females over stage and advances their age
Um

matrix. Block-structured matrix which transfers males over stage and advances their age
Ff

matrix. Block-structured matrix which counts reproduction by females and assigns newborns an age and stage
Fm

matrix. Block-structured matrix which counts reproduction by males and assigns newborns an age and stage
alpha

scalar. Birth ratio male:female
na

scalar. Number of age-classes
ns

scalar. Number of stages

Value

list (of vectors). list[1] = full agestagesex distribution list[2] = female agestage distribution normalised list[3] = male agestage distribution normalised list[4] = female marginal age distribution normalised list[5] = male marginal age distribution normalised

Mixing distributions for the time-variant multi-state 2-sex model: Non-parity case

Description

Mixing distributions for the time-variant multi-state 2-sex model: Non-parity case

Usage

pi_mix_TV(Ff, Fm, alpha, na, ns, previous_age_stage_dist)

Arguments

Ff

matrix. Block-structured matrix which counts reproduction by females and assigns newborns an age and stage
Fm

matrix. Block-structured matrix which counts reproduction by males and assigns newborns an age and stage
alpha

scalar. Birth ratio male:female
na

scalar. Number of age-classes
ns

scalar. Number of stages
previous_age_stage_dist

vector. Last years population structure (agestagesex full distribution)

Value

list (of vectors). list[1] = full agestagesex distribution list[2] = female agestage distribution normalised list[3] = male agestage distribution normalised list[4] = female marginal age distribution normalised list[5] = male marginal age distribution normalised

Mixing distributions for the time-variant multi-state 2-sex model: Parity-specific case

Description

Mixing distributions for the time-variant multi-state 2-sex model: Parity-specific case

Usage

pi_mix_TV_parity(Ff, Fm, alpha, na, ns, previous_age_stage_dist)

Arguments

Ff

matrix. Block-structured matrix which counts reproduction by females and assigns newborns an age and stage
Fm

matrix. Block-structured matrix which counts reproduction by males and assigns newborns an age and stage
alpha

scalar. Birth ratio male:female
na

scalar. Number of age-classes
ns

scalar. Number of stages
previous_age_stage_dist

vector. Last years population structure (agestagesex full distribution)
Uf

matrix. Block-structured matrix which transfers females over stage and advances their age
Um

matrix. Block-structured matrix which transfers males over stage and advances their age

Value

list (of vectors). list[1] = full agestagesex distribution list[2] = female agestage distribution normalised list[3] = male agestage distribution normalised list[4] = female marginal age distribution normalised list[5] = male marginal age distribution normalised

plot a Kin diagram (network)

Description

Draws a Keyfitz-style kinship diagram given a kinship object created by the kin function. Displays expected kin counts for a Focal aged 'a'.

Usage

plot_diagram(kin_total, rounding = 3)

Arguments

kin_total

data.frame. values in column kin define the relative type - see demokin_codes(). Values in column count are the expected number of relatives.
rounding

numeric. Number of decimals to show in diagram.

Value

A Keyfitz-style kinship plot.

rename kin

Description

Add kin labels depending the sex

Usage

rename_kin(df, sex = "f")

Arguments

df

data.frame. A data frame with variable kin with DemoKin codes to be labelled.
sex

character. "f" for female, "m" for male or "2sex" for both sex naming.

Details

See table demokin_codes to know label options.

Value

Add a column with kin labels in the input data frame.

Female Slovakian fertility rates by parity stage in 1990 (Caswell, 2021)

Description

Female Slovakian fertility rates by parity stage in 1990 (Caswell, 2021)

Usage

svk_fxs

Format

A matrix of fx with stages as cols and ages as rows.

Source

Caswell (2021)

Age where assign offspring of individuals in each partity stage (Caswell, 2021). All to zero age in this case.

Description

Age where assign offspring of individuals in each partity stage (Caswell, 2021). All to zero age in this case.

Usage

svk_Hxs

Format

A matrix of ones in ages where assign offspring individuals, with stages as cols and ages as rows.

Source

Caswell (2021)

Female Slovakian survival probabilities by parity stage in 1990 (Caswell, 2021)

Description

Female Slovakian survival probabilities by parity stage in 1990 (Caswell, 2021)

Usage

svk_pxs

Format

A matrix of px with stages as cols and ages as rows.

Source

Caswell (2021)

Probability of transition among parity stage for Slovakia in 1990, for each age, conditional on survival (Caswell, 2021).

Description

Probability of transition among parity stage for Slovakia in 1990, for each age, conditional on survival (Caswell, 2021).

Usage

svk_Uxs

Format

A list of column-stochastic matrix with probabilities of transition among parity stage, for each age, conditional on survival.

Source

Caswell (2021)

Swedish age-specific fertility rates from 1900 to 2015

Description

Swedish age-specific fertility rates from 1900 to 2015

Usage

swe_asfr

Format

A matrix with years as cols and ages (0 to 100 as OAG) as rows.

Source

HMD/HFD

Female swedish population from 1900 to 2015

Description

Female swedish population from 1900 to 2015

Usage

swe_pop

Format

A matrix with years as cols and ages (0 to 100 as OAG) as rows.

Source

HMD/HFD

Female swedish survival probabilities from 1900 to 2015

Description

Female swedish survival probabilities from 1900 to 2015

Usage

swe_px

Format

A matrix with years as cols and ages (0 to 100 as OAG) as rows.

Source

HMD/HFD

Female swedish survival ratios from 1900 to 2015

Description

Female swedish survival ratios from 1900 to 2015

Usage

swe_Sx

Format

A matrix with years as cols and ages (0 to 100 as OAG) as rows.

Source

HMD/HFD

one time projection kin

Description

one time projection kin. internal function.

Usage

timevarying_kin(Ut, ft, pit, ages, pkin)

Arguments

Ut

numeric. A matrix of survival probabilities (or ratios).
ft

numeric. A matrix of age-specific fertility rates.
pit

numeric. A matrix with distribution of childbearing.
ages

numeric.
pkin

numeric. A list with kin count distribution in previous year.

Value

A list of 14 types of kin matrices (kin age by Focal age) projected one time interval.

one time projection kin

Description

one time projection kin. internal function.

Usage

timevarying_kin_2sex(Ut, Ft, Ft_star, pit, sex_focal, ages, pkin)

Arguments

Ut

numeric. A matrix of survival probabilities (or ratios).
Ft

numeric. A matrix of age-specific fertility rates.
Ft_star

numeric. Ft but for female fertility.
pit

numeric. A matrix with distribution of childbearing.
sex_focal

character. "f" for female or "m" for male.
ages

numeric.
pkin

numeric. A list with kin count distribution in previous year.

Value

A list of 14 types of kin matrices (kin age by Focal age, blocked for two sex) projected one time interval.

one time projection kin

Description

one time projection kin. internal function.

Usage

timevarying_kin_2sex_cod(Ut, Ft, Ft_star, pit, sex_focal, ages, pkin)

Arguments

Ut

numeric. A matrix of survival probabilities (or ratios).
Ft

numeric. A matrix of age-specific fertility rates.
Ft_star

numeric. Ft but for female fertility.
pit

numeric. A matrix with distribution of childbearing.
sex_focal

character. "f" for female or "m" for male.
ages

numeric.
pkin

numeric. A list with kin count distribution in previous year.

Value

A list of 14 types of kin matrices (kin age by Focal age, blocked for two sex) projected one time interval.

Historic and projected survival ratios from Sweden used in Caswell (2021)

Description

Historic and projected survival ratios from Sweden used in Caswell (2021)

Usage

U_caswell_2021

Format

A matrix U with years as cols and ages as rows.

Source

Caswell (2019)