# Getting Started with HOME

## Overview

The HOME package implements three established orphanhood-based methods for indirect adult mortality estimation from survey data:

- Brass and Hill (1973) — the original weighting-factor approach
- Timaeus (1992) — a regression-based refinement
- Luy (2012) — recalibrated for low- and moderate-mortality populations

All three methods share a common estimation pipeline: orphanhood proportions \(S(n)\) are converted to conditional survivorship ratios and then mapped, via a one-parameter relational logit model, onto three comparable mortality indices: \(_{30}q_{30}\), \(_{45}q_{15}\), and \(e_{30}\).

Beyond point estimation, HOME provides diagnostic tools for assessing internal consistency and quantifying sensitivity to key structural assumptions.

## Installation

    install.packages("HOME")

For the interactive Shiny dashboard, install the suggested dependencies:

    install.packages("HOME", dependencies = TRUE)

## Input data

The core function `om_estimate_index()` requires four inputs per respondent age group:

Argument | Description
--- | ---
`age_respondent` | Lower bound of each five-year age group (e.g. 20, 25, …)
`p_surv` | Proportion of respondents reporting the parent alive
`mean_age_parent` | Mean age of parents at respondent’s birth (\(\bar{M}\))
`surv_date` | Survey reference date as a decimal year

The example below uses synthetic data for illustration:

    library(HOME)

    age  <- seq(20, 60, by = 5)
    sn   <- c(0.987, 0.967, 0.934, 0.908, 0.882, 0.835, 0.769, 0.669, 0.565)
    mn   <- rep(27, 9)
    date <- 1998.5

## Core estimation

Pass these inputs to `om_estimate_index()`, selecting a method and the sex of the parent:

    result <- om_estimate_index(
      method          = "luy",
      sex_parent      = "Female",
      age_respondent  = age,
      p_surv          = sn,
      mean_age_parent = mn,
      surv_date       = date,
      model_family    = "General"
    )
    #> Warning: Monotonicity check: 2 estimate(s) removed due to reference date
    #> inconsistency > 0.50 years.

`print()` displays the full results table:

    print(result)
    #>
    #> === Orphanhood Mortality Estimates ===
    #> Method:    Luy (2012)
    #> Target:    Female parent (UN — General)
    #> Age ref:   Lower bound (n)
    #>
    #>  RefYear Age  b n_b   l(b) l(n_b) lx_ratio  Alpha  30q30  45q15   e30
    #>  1989.83  20 30  53 0.9801 0.9611   0.9806 -1.116 0.0349 0.0398 52.60
    #>  1988.60  25 30  58 0.9713 0.9306   0.9581 -0.929 0.0496 0.0565 50.58
    #>  1987.45  30 30  63 0.9653 0.8914   0.9234 -0.830 0.0594 0.0677 49.47
    #>  1986.59  35 30  68 0.9676 0.8593   0.8881 -0.866 0.0556 0.0634 49.88
    #>  1986.23  40 30  73 0.9738 0.8277   0.8500 -0.976 0.0454 0.0518 51.10
    #>  1986.33  45 30  78 0.9794 0.7753   0.7916 -1.097 0.0362 0.0412 52.40
    #>  1986.70  50 30  83 0.9835 0.6761   0.6874 -1.211 0.0292 0.0332 53.56
    #>       NA  55 30  88 0.9876 0.5183   0.5248 -1.358 0.0220 0.0251 54.98
    #>       NA  60 30  93 0.9935 0.3647   0.3670 -1.686 0.0116 0.0132 57.85

`summary()` reports the range and central tendency of the primary index:

    summary(result)
    #> Summary for Female parent mortality (index: 30q30):
    #>   Range:   0.0116 – 0.0594
    #>   Mean:    0.0382
    #>   Median:  0.0362

The returned object is of class `OrphanhoodEstimate` and contains three elements:

- `$estimates` — a data frame with one row per respondent age group, including the survivorship ratio (`lx_ratio`), the reference date (`RefYear`), the Brass logit level (`Alpha`), and the three indices `30q30`, `45q15`, `e30`
- `$meta` — method, sex, and model family metadata
- `$inputs` — the original arguments, retained for use by diagnostic functions

## Comparing methods

Apply all three methods to the same data to make methodological differences visible:

    luy     <- om_estimate_index("luy",     "Female", age, sn, mn, date)
    #> Warning: Monotonicity check: 2 estimate(s) removed due to reference date
    #> inconsistency > 0.50 years.
    brass   <- om_estimate_index("brass",   "Female", age, sn, mn, date)
    #> Warning: Monotonicity check: 2 estimate(s) removed due to reference date
    #> inconsistency > 0.50 years.
    timaeus <- om_estimate_index("timaeus", "Female", age, sn, mn, date)
    #> Warning: Monotonicity check: 2 estimate(s) removed due to reference date
    #> inconsistency > 0.50 years.

    library(ggplot2)
    #> Warning: package 'ggplot2' was built under R version 4.4.3

    methods <- list(
      "Luy (2012)"           = luy,
      "Brass and Hill (1973)"= brass,
      "Timaeus (1992)"       = timaeus
    )
    cols <- c(
      "Luy (2012)"            = "#003082",
      "Brass and Hill (1973)" = "#E09B00",
      "Timaeus (1992)"        = "#5A8FC2"
    )

    df <- do.call(rbind, lapply(names(methods), function(nm) {
      d <- methods[[nm]]$estimates
      d$Method <- nm
      d
    }))
    df <- df[!is.na(df$RefYear) & !is.na(df[["30q30"]]), ]

    ggplot(df, aes(x = RefYear, y = `30q30`, colour = Method, group = Method)) +
      geom_line(linewidth = 0.7) +
      geom_point(size = 1.5, alpha = 0.6) +
      scale_colour_manual(values = cols, name = NULL) +
      labs(x = "Reference year", y = expression({}[30]*q[30])) +
      theme_bw() +
      theme(legend.position = "bottom")

## Internal consistency diagnostic

The Brass logit level parameter \(\alpha_n\) should vary smoothly across respondent age groups if the model is well-specified. `om_plot_linearity()` visualises this sequence:

    om_plot_linearity(luy)

A roughly flat or smoothly trending line indicates consistency. Sharp jumps may signal age-reporting errors, adoption effects, or genuine period shocks to mortality.

## Sensitivity to mean age at childbearing

The mean age at childbearing \(\bar{M}\) governs how survivorship ratios are located in calendar time. When this parameter is uncertain, `om_sensitivity()` re-estimates all indices across a grid of additive offsets \(\delta\):

    sens_m <- om_sensitivity(luy, range_m = seq(-2, 2, by = 0.5))
    print(sens_m)
    #>
    #> === Sensitivity Analysis: Mean Age of Childbearing ===
    #> Method:    luy
    #> Offsets:   -2, -1.5, -1, -0.5, 0, 0.5, 1, 1.5, 2 (years)
    #> N offsets: 9
    #> N rows:    81
    #>
    #> Use plot(x, index = "30q30") to visualise results.
    summary(sens_m, index = "30q30")
    #> Sensitivity of '30q30' to Mean Age of Childbearing (M):
    #>   Method:  luy
    #>   Offsets: -2 to 2 years
    #>   30q30 range:  0.0047 to 0.0695
    #>   Spread:        0.0648 (max - min)

    plot(sens_m, index = "30q30")

Lines run from light grey (most negative offset) to black (most positive). Narrow bands indicate low sensitivity; wide bands indicate that the estimates depend substantially on the assumed fertility timing.

## Sensitivity to model life table family

The choice of model life table family fixes the assumed age pattern of mortality. `om_sensitivity_family()` repeats the estimation across all families in a given system:

    sens_fam <- om_sensitivity_family(luy, type = "UN")
    print(sens_fam)
    #>
    #> === Sensitivity Analysis: Model Life Table Family ===
    #> Method:    luy
    #> System:    UN
    #> Families:  General, Latin, Chilean, South_Asian, Far_East_Asian
    #> N families:5
    #> N rows:    45
    #>
    #> Use plot(x, index = "30q30") to visualise results.
    summary(sens_fam, index = "30q30")
    #> Sensitivity of '30q30' to Model Life Table Family:
    #>   Method:  luy
    #>   System:  UN
    #>   Families tested: General, Latin, Chilean, South_Asian, Far_East_Asian
    #>   30q30 range:  0.0095 to 0.0602
    #>   Spread:        0.0508 (max - min)
    #>   Mean by family:
    #>     Chilean              0.0400
    #>     Far_East_Asian       0.0385
    #>     General              0.0382
    #>     Latin                0.0402
    #>     South_Asian          0.0349

    plot(sens_fam, index = "30q30")

## Combined diagnostic dashboard

`om_dashboard()` arranges the internal consistency plot and both sensitivity analyses into a single three-panel display:

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

## Interactive application

An interactive Shiny dashboard is available for users who prefer a graphical interface. It exposes the same estimation and diagnostic pipeline, accepts user-uploaded data (`.csv` or `.xlsx`), and allows real-time exploration of sensitivity assumptions:

    app_HOME()

The application requires the suggested packages `shiny`, `bslib`, `plotly`, `DT`, `readxl`, and `writexl`.

## Model life table families

The `model_family` argument accepts nine values across two systems:

UN regional families (Coale and Demeny extended): `"General"`, `"Latin"`, `"Chilean"`, `"South_Asian"`, `"Far_East_Asian"`

Coale-Demeny families: `"West"`, `"North"`, `"East"`, `"South"`

The default is `"General"`. When the true age pattern of mortality for the target population is unknown, comparing estimates across families via `om_sensitivity_family()` is recommended.

## References

Brass, W. and Hill, K. H. (1973). Estimating adult mortality from orphanhood. In Proceedings of the International Population Conference, Liège 1973, Vol. 3, pp. 111–123. IUSSP.

Luy, M. (2012). Estimating mortality differences in developed countries from survey information on maternal and paternal orphanhood. Demography, 49(2), 607–627. https://doi.org/10.1007/s13524-012-0101-4

Timaeus, I. M. (1992). Estimation of adult mortality from paternal orphanhood: a reassessment and a new approach. Population Bulletin of the United Nations, 33, 47–63.

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