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_Mn, and om_sensitivity_modelLT.

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

---

Derive Context-Specific Luy Calibration Coefficients

Description

Derives population-specific weighting factors $W(n)$, reference-date parameters $a(n)$, $b(n)$ and the surviving-parent to all-parent mean-age conversion for the Luy orphanhood method, reproducing the calculation workbooks behind Luy (2009, 2010 supplement) and Luy (2012).

Usage

om_calibrate_luy(
  sex_parent,
  asfr,
  cohort_qx,
  pop_age = NULL,
  survey_date,
  age_respondent = seq(20, 60, by = 5),
  mean_age_grid = NULL,
  period_lx = NULL,
  weighting = c("Nf", "f"),
  mixing = c("luy", "exact"),
  smoothing = c("graphical", "lsq"),
  cohort_lag = 4,
  male_shift = 4,
  age_range = NULL,
  s_factors = seq(0.5, 1.5, by = 0.05)
)

Arguments

sex_parent	Character. "Female" or "Male".
asfr	Data frame of period age-specific fertility rates of women. Required columns: age (completed age, integer), year (calendar year, integer), rate (births per woman per year, numeric, not per 1000). Needed for ages 15–49 in the respondents' birth years (see om_luy_data_needs). Period rates are required because the weights describe the mothers giving birth in a given calendar year. For fathers the female rates are shifted by male_shift (pass male rates with male_shift = 0).
cohort_qx	Data frame of cohort probabilities of dying of the parent's sex. Required columns: age (completed age, integer), cohort (birth year, integer), qx (probability 0-1, numeric). Must cover the parental cohorts up to calendar year $\lfloor T \rfloor - 2$, including cohorts still alive (see om_luy_data_needs); published cohort life tables usually exist only for extinct cohorts, so younger cohorts are typically built from cohort death rates. Ages not supplied are treated as unobserved (see Details). Used for q[x,k]; also for period tables when period_lx is not given.
pop_age	Data frame of population size (not exposure) of the parent's sex. Optional; if provided, requires columns age (completed age, integer), year (calendar year, integer), n (population count, numeric). Averaged over the respondents' birth years; enters the mean age at childbearing and, with weighting = "Nf", the weights. If NULL, $N_x = 1$ (with a message).
survey_date	Numeric. Interview date as a decimal year ($T$), e.g. 1998.5.
age_respondent	Numeric vector of respondent age group lower bounds.
mean_age_grid	Numeric vector of (integer) mean ages at childbearing. Defaults to 22:35 (mothers) and 24:37 (fathers), as in Luy.
period_lx	Optional data frame of period life tables of the parent's sex, columns year, age, and lx (or qx). Recommended (e.g. HMD fltper_1x1). If NULL, period tables are assembled from the diagonals of cohort_qx.
weighting	"Nf" (2010 supplement, default) or "f" (Luy 2009).
mixing	"luy" (default, reproduces Luy) or "exact".
smoothing	"graphical" (default; Schmertmann parameters read off the empirical schedule, as Luy did) or "lsq" (least-squares fit of the QS point densities, more robust for noisy rates).
cohort_lag	Integer, default 4 (Luy 2009). Years subtracted, in addition to $n$ and $x$, from the survey year to obtain the birth cohort of a parent aged $x$ at the respondent's birth: cohort = floor(survey_date) - n - cohort_lag - x. The value 4 combines the 3 years between $\lfloor T \rfloor - n$ and the middle of the respondents' five birth years ($\lfloor T \rfloor - n - 3$, Luy 2009, pp. 10, 16) and 1 year for the parent's completed age $x$, as in Luy's calculation workbooks. It also fixes the first calendar year of exposure, $\lfloor T \rfloor - n - 4$. See Details.
male_shift	Numeric. Years by which female ASFR are shifted to obtain paternal schedules (Luy: 4).
age_range	Numeric length-2 vector, youngest and oldest parental age. Defaults to c(15, 49) (mothers) and c(15, 49) + male_shift (fathers).
s_factors	Numeric vector of multipliers applied to the model $S(n)$ to build the mortality scenarios used for $a(n)$, $b(n)$.

Details

For each respondent age group $n$ (exposure $K = n + 3$ years) and each target mean age at childbearing $M$:

1. The empirical ASFR of the respondents' five birth years is averaged and summarised by Schmertmann's graphical parameters ($P$, $f(P)$, $H$, $\alpha = 14$; fathers: rates shifted by male_shift years, $\alpha = 18$). The quadratic-spline schedule is moved to $M$ – measured as $\sum (x+0.5) N_x f_x / \sum N_x f_x$ – by stepping $P$, $H$ and fine-tuning with the Brass relational Gompertz model.

2. The parental cohorts' probabilities of dying are averaged with fixed weights $w_x$ and chained into a survival curve $L_k$; $S = L_K$.

3. $t(n)$ is the mean time before the survey of the reconstructed deaths; the reference period is $T - t(n)$.

4. $W(n) = [l(33+n)/l(30)]_{T - t(n)} / S$.

5. $a(n)$, $b(n)$ come from regressing $t(n)$ on $\ln S$ across logit-relevelled mortality scenarios.

Weights. weighting = "Nf" (default) uses $w_x \propto N_x f_x$ as in the 2010 supplement and in the package's built-in coefficients; "f" uses $w_x \propto f_x$ as in Luy (2009).

Mixing. mixing = "luy" (default) averages the probabilities of dying with weights fixed at the respondents' birth, as Luy's workbooks do. "exact" mixes the cohort survival curves, $\sum_x w_x l_x(k)$, which is the demographically exact proportion of parents alive; the two diverge strongly at older respondent ages, so only "luy" reproduces the published tables.

Parental cohorts (cohort_lag). Respondents aged $n$ to $n+4$ at the survey were born in the five calendar years $\lfloor T \rfloor - n - 5$ to $\lfloor T \rfloor - n - 1$. Luy (2009, pp. 10 and 16) approximates their parents by the parents who gave birth in the middle of these five years, $\lfloor T \rfloor - n - 3$; in his calculation workbooks a parent aged $x$ (completed years) at that birth belongs to the cohort born in $\lfloor T \rfloor - n - 3 - x - 1$. Hence the parental cohort is

$c(x, n) = \lfloor T \rfloor - n - \mathrm{cohort\_lag} - x, \qquad \mathrm{cohort\_lag} = 4,$

and $q[x, k]$ is the probability of dying of cohort $c(x, n)$ at age $x + k - 1$, i.e. in calendar year $\lfloor T \rfloor - n - 4 + k - 1$, for $k = 1, \dots, K$ with $K = n + 3$ (Luy 2009, p. 10: exposure of $n + 2.5$ years plus the time of the interview within the survey year).

Unobserved ages. No closure rule is applied to the cohort series. A probability of dying that is not in cohort_qx (e.g. ages beyond the last age of a cohort's table, such as the open interval 110+) is kept as NA and gets no weight: in each year $k$ the weighted average of the probabilities of dying is taken over the cohorts observed in that year,

$\bar q_k = \sum_{x \in O_k} v_{x,k} q[x,k] / \sum_{x \in O_k} v_{x,k},$

with $v_{x,k} = w_x$ (mixing = "luy") or $v_{x,k} = w_x l_x(k-1)$ (mixing = "exact"). This distinguishes the absence of observations from a probability of dying of 0 and prevents unobserved ages from contributing to the calculation. Luy's workbooks filled these cells with $q = 0$ (1998 survey) or $q = 1$ (2003 survey). If no parental cohort is observed in some year $k$ (data that end before the calendar year $\lfloor T \rfloor - 2$), $S$, $W(n)$, $a(n)$ and $b(n)$ are NA. The share of the weights observed in each year is returned in the intermediates (om_luy_intermediates(cal, "w_observed")). In a complete cohort life table the last, open age interval (e.g. 110+) has $q = 1$: the cohort is extinct and no older age is needed.

How closely Luy is reproduced. Fed with Luy's own schedules and cohort probabilities, the calculation reproduces his published $W(n)$ (Luy 2009) to within about 1% and his reference periods exactly. Run on independent data (e.g. HMD/HFD for Italy), the differences from the built-in tables are below about 1% up to $n = 40$, a few per cent at $n = 45$–55 and larger at $n = 60$, where Luy's values depend on how he filled the ages after the end of the cohort series (see above) and on his source tables ending around age 100. Treat the $n \ge 55$ coefficients with caution.

Mean age of all vs. surviving parents. The tables are indexed by the mean age at childbearing of all parents. If your survey only records the parent's age for living parents, convert it first with the returned mac table (survivors' mean in the column header, all parents' mean in the cells), as Luy does with his Tables A.5-A.8.

Value

A named list with elements "Female" and "Male"; the one matching sex_parent holds a list of four data frames (the other is NULL). Each data frame has one row per respondent age group (column Age_Group = $n$) and one column per mean age at childbearing in mean_age_grid (named "22", "23", ...), the layout of the built-in coefficients, so that the result can be passed to custom_coef_luy in om_estimate_index:

wn

weighting factors $W(n)$, with $l(33+n)/l(30) = S(n) W(n)$ (Luy 2009, eq. 1; Tables A.9–A.12).

an, bn

reference-period parameters, with $t(n) = a(n) \ln S(n) + b(n)$ years before the survey (Luy 2009, Tables A.13–A.20).

mac

mean age at childbirth of all parents (cells) given the mean age of surviving parents (column names) (Luy 2009, Tables A.5–A.8).

NA marks cells that could not be computed (see the warnings). Attributes:

diagnostics

data frame, one row per age group and mean age: Age_Group, mean_age, model survival S_model, reference year ref_year, t_n, W, Brass-Gompertz gompertz_alpha, Schmertmann P and H, and weight_dropped (share of the weights of parental cohorts absent from cohort_qx).

intermediates

list by age group with every intermediate quantity of the calculation, laid out like Luy's workbooks; extract with om_luy_intermediates.

settings

list of the arguments used.

References

Luy, M. (2009). Estimating mortality differentials in developed populations from survey information on maternal and paternal orphanhood. European Demographic Research Papers 2009-3; supplement, August 2010.

Luy, M. (2012). Estimating mortality differences in developed countries from survey information on maternal and paternal orphanhood. Demography, 49(2), 607-627.

Schmertmann, C. P. (2003). A system of model fertility schedules with graphically intuitive parameters. Demographic Research, 9(5), 81-110.

See Also

om_estimate_index, om_luy_intermediates, om_luy_data_needs

Examples

# synthetic inputs in the standard long format
asfr <- expand.grid(age = 15:49, year = 1950:2000)
asfr$rate <- 0.1 * exp(-0.5 * ((asfr$age - 28) / 5.5)^2)
cohort_qx <- expand.grid(age = 0:110, cohort = 1900:1990)
cohort_qx$qx <- pmin(1, 0.00005 * exp(0.095 * cohort_qx$age))
cohort_qx <- cohort_qx[cohort_qx$cohort + cohort_qx$age <= 2003, ]
pop_age <- expand.grid(age = 0:110, year = 1950:2000)
pop_age$n <- 1e5 * exp(-0.01 * pop_age$age)
period_lx <- expand.grid(age = 0:110, year = 1980:2003)
period_lx$lx <- 1e5 * exp(-0.00005 / 0.095 * (exp(0.095 * period_lx$age) - 1))

cal <- om_calibrate_luy("Female", asfr = asfr, cohort_qx = cohort_qx,
                        pop_age = pop_age, period_lx = period_lx,
                        survey_date = 2003.9, age_respondent = c(20, 40))
cal$Female$wn    # W(n)
cal$Female$mac   # mean age of all parents given that of surviving parents

# use the coefficients in the estimation
est <- om_estimate_index(method = "luy", sex_parent = "Female",
                         age_respondent = c(20, 40), p_surv = c(0.95, 0.75),
                         mean_age_parent = 27, surv_date = 2003.9,
                         custom_coef_luy = cal)
est$estimates

---

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

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

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

See Also

om_plot_linearity, om_sensitivity_Mn, om_sensitivity_modelLT

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",
  e0 = 60,
  custom_coef_luy = NULL
)

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".
e0	Numeric. Life expectancy at birth ($e_0$) level identifying which mortality level of the chosen model_family to use as the relational logit standard. Must match one of the levels bundled in the package's internal model life table database (currently 60, 70, 80, 90, or 100). Default is 60, matching the package's previous fixed behaviour. Lower levels represent higher-mortality standards; choose a level close to the expected mortality of the population under analysis.
custom_coef_luy	Optional. A named list containing at least the element matching sex_parent ("Female" or "Male"), itself a list with data frames wn, an, and bn in the same format as the package's built-in Luy (2012) coefficients (see sysdata). When supplied and method = "luy", these coefficients replace the package's default Italy-calibrated tables for the sex being estimated. Use om_calibrate_luy to derive such a set from historical fertility and cohort mortality data for a population other than Italy.

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_Mn and om_sensitivity_modelLT.

References

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

Luy, M. (2009). Estimating mortality differentials in developed populations from survey information on maternal and paternal orphanhood. European Demographic Research Papers 2009-3. Vienna Institute of Demography.

Luy, M. (2012). Estimating mortality differences in developed countries from survey information on maternal and paternal orphanhood. Demography, 49(2), 607–627. doi: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. New York: United Nations.

See Also

om_sensitivity_Mn, om_sensitivity_modelLT, om_plot_linearity, om_calibrate_luy

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)

---

Data Requirements for om_calibrate_luy()

Description

Lists, for a given survey date, the calendar years, ages and cohorts that each input of om_calibrate_luy must cover, following the timing conventions of Luy (2009) and his calculation workbooks.

Usage

om_luy_data_needs(
  survey_date,
  sex_parent = c("Female", "Male"),
  age_respondent = seq(20, 60, by = 5),
  cohort_lag = 4,
  male_shift = 4,
  age_range = NULL,
  max_age = 110
)

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

Arguments

survey_date	Numeric. Interview date as a decimal year ($T$), e.g. 1998.5.
sex_parent	Character. "Female" or "Male".
age_respondent	Numeric vector of respondent age group lower bounds.
cohort_lag	Integer, default 4 (Luy 2009). Years subtracted, in addition to $n$ and $x$, from the survey year to obtain the birth cohort of a parent aged $x$ at the respondent's birth: cohort = floor(survey_date) - n - cohort_lag - x. The value 4 combines the 3 years between $\lfloor T \rfloor - n$ and the middle of the respondents' five birth years ($\lfloor T \rfloor - n - 3$, Luy 2009, pp. 10, 16) and 1 year for the parent's completed age $x$, as in Luy's calculation workbooks. It also fixes the first calendar year of exposure, $\lfloor T \rfloor - n - 4$. See Details.
male_shift	Numeric. Years by which female ASFR are shifted to obtain paternal schedules (Luy: 4).
age_range	Numeric length-2 vector, youngest and oldest parental age. Defaults to c(15, 49) (mothers) and c(15, 49) + male_shift (fathers).
max_age	Last age of the cohort life tables, an open interval (default 110, as in the Human Mortality Database).
x	An object of class "LuyDataNeeds".
...	Ignored.

Details

For respondent age group $n$ (respondents aged $n$ to $n+4$), survey date $T$, exposure $K = n + 3$ years and parental age $x$ at the respondent's birth (Luy 2009, pp. 10–18):

• asfr and pop_age: the respondents' five birth years $\lfloor T \rfloor - n - 5$ to $\lfloor T \rfloor - n - 1$; ASFR at ages 15–49 (female rates, also for fathers), population at the parental ages (15–49 mothers, 19–53 fathers).

• cohort_qx: parental cohort $\lfloor T \rfloor - n - cohort\_lag - x$ (see cohort_lag in om_calibrate_luy), from age $x$ to $x + K - 1 = x + n + 2$, i.e. from calendar year $\lfloor T \rfloor - n - 4$ to $\lfloor T \rfloor - 2$.

• period_lx: ages 30 and $33 + n$ (the ratio $l(33+n)/l(30)$, Luy 2009, eq. 1) in the years around the reference period. The reference period depends on mortality; it always lies between $T - K$ and $T$, and in practice within the "typical" range shown ($T - K + 0.55K$ to $T - K + 0.9K$, plus one year for the linear interpolation between calendar years).

Oldest age. The age reached by the oldest parents at the end of the exposure, $x + n + 2$, can exceed the last age of a life table (for $n = 60$: 111 for mothers, 115 for fathers). It is capped at max_age: the last age of a life table is an open interval (e.g. 110+, ages 0 to 110+ are 111 age classes) in which $q = 1$, so no older age exists in the data or is needed. Ages without data are not filled in by om_calibrate_luy(); they get no weight (see Details there).

Value

A data frame of class "LuyDataNeeds" with one row per respondent age group and the columns

n

respondent age group (lower bound).

birth_years

respondents' birth years: years needed in asfr and pop_age.

asfr_ages

ages needed in asfr (female ages).

pop_ages

ages needed in pop_age (parent's sex).

cohorts

parental birth cohorts needed in cohort_qx.

cohort_ages

ages of those cohorts needed in cohort_qx (capped at max_age).

cohort_last_year

last calendar year the cohort series must reach, $\lfloor T \rfloor - 2$.

period_ages

ages read from period_lx: 30 and $33 + n$.

period_years_bounds

years within which the reference period always lies.

period_years_typical

years within which it usually lies.

The attribute "overall" holds the ranges over all age groups, which the print method shows first.

References

Luy, M. (2009). Estimating mortality differentials in developed populations from survey information on maternal and paternal orphanhood. European Demographic Research Papers 2009-3. Vienna Institute of Demography.

See Also

om_calibrate_luy, om_luy_validate_inputs

Examples

om_luy_data_needs(2003.9, "Female")
om_luy_data_needs(1998.5, "Male")

---

Extract the Intermediate Quantities of a Luy Calibration

Description

Returns the intermediate quantities computed by om_calibrate_luy for each respondent age group, arranged like the sheets of Luy's workbooks (Multipliers_*_NEW_REF_YEARS.xls), so that they can be compared cell by cell with his values.

Usage

om_luy_intermediates(
  cal,
  what = c("summary", "f_prime", "weights", "N", "f_empirical", "q", "q_bar", "L",
    "w_observed"),
  n = NULL,
  format = c("wide", "long")
)

Arguments

cal	Output of om_calibrate_luy().
what	Which quantity: "summary" per mean age: model S(n), reference year, t(n), period l(33+n)/l(30), W(n), mean age of all parents, Schmertmann P, H and Gompertz alpha (sheet rows 4-9, 769-774). "f_prime" modelled schedules f(x)/sum f, parental age x by mean age (Luy's "MODELED f(x)/TFR", sheet rows 14-48). "weights" weights actually used, f' or N f' normalised (equal to f_prime when weighting = "f"). "N" population age structure N(x) (average over the birth years). "f_empirical" averaged empirical ASFR. "q" cohort probabilities of dying q[x, k], parental age x by year k after the respondent's birth (sheet rows 55-89). "q_bar" weighted average q, year k by mean age (sheet row 129 of each mean-age block). "L" reconstructed survival L_k, k = 0..K, by mean age (sheet row 130 / 10000). "w_observed" share of the weights whose q[x, k] is observed, year k by mean age (1 = all parental cohorts observed; unobserved ages get no weight, see om_calibrate_luy).
n	Respondent age group(s). Default: all.
format	"wide" (a matrix per age group; a list when several groups are requested) or "long" (one data frame with columns n, row and column identifiers, and value).

Value

With format = "wide": for one age group, the matrix (or named vector for "N" and "f_empirical", data frame for "summary"); for several, a list of them named by age group. With format = "long": a data frame with column n, the row and column identifiers (age, k, mean_age; for "q" also the parental cohort) and value. The "summary" columns are mean_age, S_model, ref_year, t_n, lx_ratio, W, mac, P, H and gompertz_alpha.

References

Luy, M. (2009). Estimating mortality differentials in developed populations from survey information on maternal and paternal orphanhood. European Demographic Research Papers 2009-3. Vienna Institute of Demography.

See Also

om_calibrate_luy

Examples

# synthetic inputs in the standard long format
asfr <- expand.grid(age = 15:49, year = 1950:2000)
asfr$rate <- 0.1 * exp(-0.5 * ((asfr$age - 28) / 5.5)^2)
cohort_qx <- expand.grid(age = 0:110, cohort = 1900:1990)
cohort_qx$qx <- pmin(1, 0.00005 * exp(0.095 * cohort_qx$age))
cohort_qx <- cohort_qx[cohort_qx$cohort + cohort_qx$age <= 2003, ]
pop_age <- expand.grid(age = 0:110, year = 1950:2000)
pop_age$n <- 1e5 * exp(-0.01 * pop_age$age)
period_lx <- expand.grid(age = 0:110, year = 1980:2003)
period_lx$lx <- 1e5 * exp(-0.00005 / 0.095 * (exp(0.095 * period_lx$age) - 1))
cal <- om_calibrate_luy("Female", asfr = asfr, cohort_qx = cohort_qx,
                        pop_age = pop_age, period_lx = period_lx,
                        survey_date = 2003.9, age_respondent = c(20, 40))
om_luy_intermediates(cal, "f_prime", n = 40)   # Luy's "MODELED f(x)/TFR"
om_luy_intermediates(cal, "summary", n = 40)
head(om_luy_intermediates(cal, "q", format = "long"))

---

Validate the Inputs of om_calibrate_luy()

Description

Checks that the data frames you prepared are in the standard long format expected by om_calibrate_luy and, if survey_date is given, that they cover the years, ages and cohorts the calibration needs (see om_luy_data_needs). Run it after reading your data and before calibrating.

Usage

om_luy_validate_inputs(
  asfr = NULL,
  cohort_qx = NULL,
  pop_age = NULL,
  period_lx = NULL,
  survey_date = NULL,
  sex_parent = c("Female", "Male"),
  age_respondent = seq(20, 60, by = 5),
  cohort_lag = 4,
  male_shift = 4,
  verbose = TRUE
)

Arguments

asfr, cohort_qx, pop_age, period_lx	Data frames to check (each optional; NULL is skipped).
survey_date	Optional survey date (decimal year). If given, the coverage of the inputs is compared with om_luy_data_needs().
sex_parent	"Female" or "Male"; used with survey_date.
age_respondent, cohort_lag, male_shift	As in om_calibrate_luy; used with survey_date.
verbose	Print a summary (default TRUE).

Value

Invisibly, a data frame with one row per input: number of complete rows and the age and year (or cohort) ranges. Stops with an informative error if an input is malformed.

Standard format

argument	columns	content
asfr	age, year, rate	period ASFR of women, births per woman (not per 1000)
cohort_qx	age, cohort, qx	cohort probability of dying, 0--1
pop_age	age, year, n	population size (not exposure)
period_lx	year, age, lx (or qx)	period life table

age, year and cohort are whole numbers (completed age, calendar year, birth year). Each key combination appears once.

Checks

Errors: not a data frame; missing columns; non-numeric columns; non-integer ages/years/cohorts; duplicated keys; rate > 1 (per 1000) or negative; qx outside 0–1; negative n or lx. Warnings: rows with NA (they are ignored by the calibration); with survey_date, years, ages or cohorts the calibration needs but that are missing.

See Also

om_calibrate_luy, om_luy_data_needs

Examples

# synthetic inputs in the standard long format
asfr <- expand.grid(age = 15:49, year = 1950:2000)
asfr$rate <- 0.1 * exp(-0.5 * ((asfr$age - 28) / 5.5)^2)
cohort_qx <- expand.grid(age = 0:110, cohort = 1900:1990)
cohort_qx$qx <- pmin(1, 0.00005 * exp(0.095 * cohort_qx$age))
cohort_qx <- cohort_qx[cohort_qx$cohort + cohort_qx$age <= 2003, ]
pop_age <- expand.grid(age = 0:110, year = 1950:2000)
pop_age$n <- 1e5 * exp(-0.01 * pop_age$age)
period_lx <- expand.grid(age = 0:110, year = 1980:2003)
period_lx$lx <- 1e5 * exp(-0.00005 / 0.095 * (exp(0.095 * period_lx$age) - 1))
om_luy_validate_inputs(asfr, cohort_qx, pop_age, period_lx,
                       survey_date = 2003.9, sex_parent = "Female",
                       age_respondent = c(20, 40))

# a typical preparation error: rates per 1000 women
try(om_luy_validate_inputs(asfr = transform(asfr, rate = rate * 1000)))

---

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

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_Mn(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_modelLT, 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_Mn(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_modelLT(
  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_Mn, 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_modelLT(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

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_Mn

---

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_modelLT

---

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.

---

Print Method for OrphanhoodSensitivity Objects

Description

Prints a concise summary of a mean-age-of-childbearing sensitivity analysis.

Usage

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

Arguments

x	An object of class OrphanhoodSensitivity.
...	Further arguments (currently unused).

Value

Invisibly returns x.

---

Print Method for OrphanhoodSensitivityFamily Objects

Description

Prints a concise summary of a model life table family sensitivity analysis.

Usage

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

Arguments

x	An object of class OrphanhoodSensitivityFamily.
...	Further arguments (currently unused).

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.

---

Summary Method for OrphanhoodSensitivity Objects

Description

Summarises the range of estimated mortality indices across all mean-age-of-childbearing offsets.

Usage

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

Arguments

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

Value

Invisibly returns object.

---

Summary Method for OrphanhoodSensitivityFamily Objects

Description

Summarises the range of estimated mortality indices across all model life table families tested.

Usage

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

Arguments

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

Value

Invisibly returns object.

---