--- title: "Getting Started with HOME" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Getting Started with HOME} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include=FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4 ) ``` ## 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 ```r install.packages("HOME") ``` For the interactive Shiny dashboard, install the suggested dependencies: ```r 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: ```{r data} 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: ```{r estimate} 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" ) ``` `print()` displays the full results table: ```{r print} print(result) ``` `summary()` reports the range and central tendency of the primary index: ```{r summary} summary(result) ``` 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: ```{r compare} luy <- om_estimate_index("luy", "Female", age, sn, mn, date) brass <- om_estimate_index("brass", "Female", age, sn, mn, date) timaeus <- om_estimate_index("timaeus", "Female", age, sn, mn, date) ``` ```{r compare-plot, fig.height=3.5} library(ggplot2) 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: ```{r linearity, fig.height=3} 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$: ```{r sens-m} sens_m <- om_sensitivity(luy, range_m = seq(-2, 2, by = 0.5)) print(sens_m) summary(sens_m, index = "30q30") ``` ```{r sens-m-plot, fig.height=3.5} 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: ```{r sens-fam} sens_fam <- om_sensitivity_family(luy, type = "UN") print(sens_fam) summary(sens_fam, index = "30q30") ``` ```{r sens-fam-plot, fig.height=3.5} 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: ```{r dashboard, fig.height=6, fig.width=7} 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: ```r 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. 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.