Package 'HOME'

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, 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

## Not run: 
  app_HOME()

## End(Not run)

---

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. Requires the gridExtra package.

Usage

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

Arguments

object	An object of class OrphanhoodEstimate.
index	Character. Mortality index to display in sensitivity panels. One of "30q30", "45q15", or "e30". Default: "30q30".
family_type	Character. Life table family system for the family sensitivity panel. One of "UN", "CD", or "All". Default: "UN".
range_m	Numeric vector. Offsets applied to the mean age of childbearing. Default: seq(-1.5, 1.5, 0.5).

Value

If gridExtra is available, arranges and displays the three plots and returns the gtable object invisibly. Otherwise returns a named list with elements Linearity, Sensitivity_M, and Sensitivity_Family.

See Also

om_plot_linearity, om_sensitivity, om_sensitivity_family

Examples

## Not run: 
  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")

## End(Not run)

---

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

method	Character. Estimation method. One of "luy", "timaeus", or "brass".
sex_parent	Character. Sex of the parent. One of "Female" or "Male".
age_respondent	Numeric vector. Lower bound of respondent age groups (e.g., c(15, 20, 25, 30)).
p_surv	Numeric vector. Proportion of respondents reporting the parent alive, one value per age group.
mean_age_parent	Numeric scalar or vector. Mean age of parents at respondent's birth ($M$). A scalar is recycled across all age groups.
surv_date	Numeric. Survey reference date as a decimal year (e.g., 2015.5).
num_respondents	Numeric vector. Optional. Number of respondents per age group. Reserved for future use; currently has no effect on estimates.
model_family	Character. Model life table family used as the relational logit standard. UN families: "General", "Latin", "Chilean", "South_Asian", "Far_East_Asian". Coale-Demeny families: "West", "North", "East", "South". Default is "General".

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 (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

## Not run: 
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)

## End(Not run)

---

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

object

An object of class OrphanhoodEstimate.

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

## Not run: 
  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)

## End(Not run)

---

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

object	Optional. An object of class OrphanhoodEstimate. When supplied, all estimation arguments are taken from object$inputs and may be overridden via ....
range_m	Numeric vector of offsets (in years) applied to the baseline mean age of childbearing. Default: seq(-1.5, 1.5, 0.5).
...	Additional arguments passed to om_estimate_index, overriding values stored in object.

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

## Not run: 
  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")

## End(Not run)

---

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

object	Optional. An object of class OrphanhoodEstimate.
type	Character. Family system to evaluate. One of "UN", "CD", or "All" (default). Ignored when families is supplied.
families	Optional character vector of specific family names to test, overriding type.
...	Additional arguments passed to om_estimate_index.

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

## Not run: 
  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")

## End(Not run)

---

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

x	An object of class OrphanhoodSensitivity.
index	Character. Mortality index to plot. One of "30q30", "45q15", or "e30". Default: "30q30".
...	Further arguments (currently unused).

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

x	An object of class OrphanhoodSensitivityFamily.
index	Character. Mortality index to plot. One of "30q30", "45q15", or "e30". Default: "30q30".
...	Further arguments (currently unused).

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

x	An object of class OrphanhoodEstimate.
...	Further arguments passed to print.data.frame.

Value

Invisibly returns x.

---

Summary method for OrphanhoodEstimate objects

Description

Summary method for OrphanhoodEstimate objects

Usage

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

Arguments

object	An object of class OrphanhoodEstimate.
...	Further arguments (currently unused).

Value

Invisibly returns object.

---