Package {HOME}

Brass and Hill (1973) orphanhood estimation

Description

Brass and Hill (1973) orphanhood estimation

Usage

.om_brass(sex, age, sn, mn, date, sn_10 = NULL, n_resp = NULL)

Arguments

Details

Implements UN Manual X equations B.4–B.8. Conditional survivorship is estimated via weighting factors W(n) (Hill 1977):

\frac{l(25+n)}{l(25)} = W(n)\,S(n-5) + (1 - W(n))\,S(n)

The reference time t(n) is located using:

u(n) = \frac{1}{3} \ln S(n) + Z(M+n) + 0.0037\,(27 - M)

t(n) = \frac{n\,(1 - u(n))}{2}

For fathers, base ages 32.5 and 37.5 replace 25 (equations B.5–B.6), and a correction of 0.75 is applied to t(n) and Z.

Value

A data frame with columns age_input, base_age, target_age, prob, and ref_date.

References

United Nations (1983). Manual X: Indirect Techniques for Demographic Estimation. ST/ESA/SER.A/81. New York: United Nations.

Luy (2012) orphanhood estimation

Description

Luy (2012) orphanhood estimation

Usage

.om_luy(sex, age, sn, mn, date)

Arguments

Value

A data frame with columns age_input, base_age, target_age, prob, and ref_date.

Timaeus (1992) orphanhood estimation

Description

Timaeus (1992) orphanhood estimation

Usage

.om_timaeus(sex, age, sn, mn, date)

Arguments

Value

A data frame with columns age_input, base_age, target_age, prob, and ref_date.

Resolve inputs for diagnostic functions

Description

Extracts estimation arguments from an existing OrphanhoodEstimate object, optionally overriding individual arguments supplied via ....

Usage

.resolve_inputs(object, provided_args)

Arguments

Value

A named list of arguments suitable for passing to om_estimate_index.

Launch the HOME Shiny Application

Description

Opens the interactive dashboard for indirect adult mortality estimation using the orphanhood-based methods implemented in the HOME package. The application provides a graphical interface to om_estimate_index, om_plot_linearity, om_sensitivity, and om_sensitivity_family.

Usage

app_HOME()

Details

The Shiny application is located in inst/shiny/home_app/ and is launched via shiny::runApp(). An active R session with the shiny, bslib, ggplot2, plotly, DT, readxl, and writexl packages is required; these are listed under Suggests in the package DESCRIPTION file.

Value

This function is called for its side effect of launching a Shiny application. It does not return a meaningful value; the return value of shiny::runApp() is returned invisibly.

See Also

om_estimate_index for the underlying estimation function.

Examples

if (interactive()) {
  app_HOME()
}

Combined Diagnostic Dashboard

Description

Produces a three-panel diagnostic display combining the internal consistency check with sensitivity analyses for mean age of childbearing and model life table family.

Usage

om_dashboard(
  object,
  index = "30q30",
  family_type = "UN",
  range_m = seq(-1.5, 1.5, 0.5)
)

Arguments

Value

Invisibly returns the gtable object produced by gridExtra::grid.arrange().

See Also

om_plot_linearity, om_sensitivity, om_sensitivity_family

Examples

result <- om_estimate_index(
  method          = "luy",
  sex_parent      = "Female",
  age_respondent  = seq(20, 60, by = 5),
  p_surv          = c(0.987, 0.967, 0.934, 0.908, 0.882,
                      0.835, 0.769, 0.669, 0.565),
  mean_age_parent = rep(27, 9),
  surv_date       = 1998.5
)

om_dashboard(result, index = "30q30", family_type = "UN")

Estimate Adult Mortality Indices from Orphanhood Data

Description

Estimates conditional survivorship probabilities using orphanhood methods and harmonizes them into common adult mortality indices using a one-parameter relational logit model.

Usage

om_estimate_index(
  method = c("luy", "timaeus", "brass"),
  sex_parent = c("Female", "Male"),
  age_respondent,
  p_surv,
  mean_age_parent,
  surv_date,
  num_respondents = NULL,
  model_family = "General"
)

Arguments

Details

Three orphanhood-based estimation methods are supported. Regardless of the method selected, estimates are harmonized into three comparable mortality indices:

• 30q30: Probability of dying between ages 30 and 60.

• 45q15: Probability of dying between ages 15 and 60.

• e30: Life expectancy at age 30.

For the Brass method, adjacent orphanhood proportions are paired across successive age groups. The first observation yields NA by construction because no preceding adjacent proportion exists.

Value

An object of class OrphanhoodEstimate, a named list with:

estimates

Data frame of estimated adult mortality indices by respondent age group. Columns:

Method

Citation label of the estimation method used.

RefYear

Estimated reference year of the mortality estimate, expressed as a decimal year.

Age

Lower bound of the respondent age group (n) used to derive the orphanhood estimate.

b

Initial exact age of the conditional survivorship interval. Equals 30 for Luy (2012); 25 for Timaeus (1992) females, 35 for males; 25 for Brass and Hill (1973) females, 32.5 or 37.5 for males depending on \bar{M}.

n_b

Terminal exact age of the survivorship interval (b + \text{duration}). For Luy (2012) this equals 33 + n.

l(b)

Estimated survivorship at exact age b, derived from the relational logit model.

l(n_b)

Estimated survivorship at exact age n\_b, derived from the relational logit model.

lx_ratio

Conditional survivorship probability l(n\_b) / l(b), i.e.\ the probability of surviving from exact age b to exact age n\_b. This is the key observable quantity derived from the orphanhood method and used to estimate Alpha.

Alpha

Relational logit level parameter \alpha estimated by solving l(n\_b) / l(b) = \text{lx\_ratio} against the standard life table. Higher values indicate lower mortality.

30q30

Probability of dying between exact ages 30 and 60.

45q15

Probability of dying between exact ages 15 and 60.

e30

Life expectancy at exact age 30.

meta

Named list of metadata: sex of the parent, model life table family, family system type ("UN" or "CD"), method identifier, and primary index name.

inputs

Named list of the original input arguments, retained for reproducibility and use by om_sensitivity and om_sensitivity_family.

See Also

om_sensitivity, om_sensitivity_family, om_plot_linearity

Examples

result <- om_estimate_index(
  method          = "brass",
  sex_parent      = "Female",
  age_respondent  = c(20, 25, 30, 35, 40, 45),
  p_surv          = c(0.906, 0.840, 0.747, 0.631, 0.518, 0.400),
  mean_age_parent = 28.8,
  surv_date       = 1975.64,
  model_family    = "General"
)
print(result)

Diagnostic Plot: Internal Consistency Check

Description

Displays the estimated Brass logit \alpha parameter across respondent age groups. A roughly constant \alpha indicates internal consistency of the orphanhood-based estimates; a systematic trend suggests age-reporting errors, adoption effects, or structural changes in mortality.

Usage

om_plot_linearity(object)

Arguments

Value

A ggplot object with respondent age group (Age) on the x-axis and the relational logit level parameter \alpha (Alpha) on the y-axis. A dashed horizontal line marks the median \alpha across age groups.

See Also

om_estimate_index, om_dashboard

Examples

  result <- om_estimate_index(
    method          = "luy",
    sex_parent      = "Female",
    age_respondent  = seq(20, 60, by = 5),
    p_surv          = c(0.987, 0.967, 0.934, 0.908, 0.882,
                        0.835, 0.769, 0.669, 0.565),
    mean_age_parent = rep(27, 9),
    surv_date       = 1998.5
  )
  om_plot_linearity(result)

Sensitivity Analysis: Mean Age of Childbearing

Description

Evaluates the sensitivity of orphanhood-based mortality estimates to assumptions about the mean age of childbearing (M_n) by re-estimating indices across a grid of additive offsets.

Usage

om_sensitivity(object = NULL, range_m = seq(-1.5, 1.5, 0.5), ...)

Arguments

Value

An object of class OrphanhoodSensitivity, a named list with:

data

A data frame of estimates for each offset value, with columns matching om_estimate_index()$estimates plus an additional column Offset_M identifying the applied offset in years.

meta

A named list of metadata: variable name, offset range, standard level, and estimation method.

See Also

plot.OrphanhoodSensitivity, om_sensitivity_family, om_estimate_index

Examples

  result <- om_estimate_index(
    method          = "luy",
    sex_parent      = "Female",
    age_respondent  = seq(20, 60, by = 5),
    p_surv          = c(0.987, 0.967, 0.934, 0.908, 0.882,
                        0.835, 0.769, 0.669, 0.565),
    mean_age_parent = rep(27, 9),
    surv_date       = 1998.5
  )
  sens <- om_sensitivity(result, range_m = seq(-2, 2, by = 0.5))
  plot(sens, index = "30q30")

Sensitivity Analysis: Model Life Table Family

Description

Evaluates the sensitivity of orphanhood-based mortality estimates to the assumed age pattern of mortality by re-estimating indices across multiple model life table families.

Usage

om_sensitivity_family(
  object = NULL,
  type = c("UN", "CD", "All"),
  families = NULL,
  ...
)

Arguments

Value

An object of class OrphanhoodSensitivityFamily, a named list with:

data

A data frame of estimates for each family, with columns matching om_estimate_index()$estimates plus an additional column Family identifying the model life table family.

meta

A named list of metadata: variable name, families tested, standard level, family system name, and estimation method.

See Also

plot.OrphanhoodSensitivityFamily, om_sensitivity, om_estimate_index

Examples

  result <- om_estimate_index(
    method          = "luy",
    sex_parent      = "Female",
    age_respondent  = seq(20, 60, by = 5),
    p_surv          = c(0.987, 0.967, 0.934, 0.908, 0.882,
                        0.835, 0.769, 0.669, 0.565),
    mean_age_parent = rep(27, 9),
    surv_date       = 1998.5
  )
  sens_fam <- om_sensitivity_family(result, type = "UN")
  plot(sens_fam, index = "30q30")

Plot Method for OrphanhoodSensitivity Objects

Description

Displays estimated mortality indices across reference years for each mean-age-of-childbearing offset, coloured from light (low offset) to dark (high offset).

Usage

## S3 method for class 'OrphanhoodSensitivity'
plot(x, index = "30q30", ...)

Arguments

Value

A ggplot object.

See Also

om_sensitivity

Plot Method for OrphanhoodSensitivityFamily Objects

Description

Displays estimated mortality indices across reference years for each model life table family, distinguished by line type.

Usage

## S3 method for class 'OrphanhoodSensitivityFamily'
plot(x, index = "30q30", ...)

Arguments

Value

A ggplot object.

See Also

om_sensitivity_family

Print method for OrphanhoodEstimate objects

Description

Print method for OrphanhoodEstimate objects

Usage

## S3 method for class 'OrphanhoodEstimate'
print(x, ...)

Arguments

Value

Invisibly returns x.

Summary method for OrphanhoodEstimate objects

Description

Summary method for OrphanhoodEstimate objects

Usage

## S3 method for class 'OrphanhoodEstimate'
summary(object, ...)

Arguments

Value

Invisibly returns object.