Create a weight_model that will be used to generate weights for determining
which individuals/units experience an event.
Usage
weight_model(formula = NULL, coefficients = numeric(), fun = NULL)Details
A weight model decides which member of a rate cell experiences an event,
without changing the cell's input intensity and thus the input rates. The
cell produces events at its input rate times its members; each event goes to
member i with probability w_i / sum(w), where w_i = exp(eta_i).
With a formula, eta_i is the linear predictor x_i %*% beta, so
exp(beta) is the hazard ratio between two members of the same cell that
differ by one unit in a term. Users can therefore create proportional hazards
models, without affecting overall input rates. Population level effects can
be smaller where cells are small or homogeneous.
Attach a weight model with the weights argument of set_mortality(),
set_fertility(), set_union_dissolution(), set_group_transition() and
set_union_formation(), or weights_conversion of set_union_formation().
Variables
Group variables are named by the declared group
dimensions (see set_groups()); for a dimension race with categories A
and B.
Mortality, fertility and group transitions are person processes and may use
sex ("f", "m"), race, union_type ("unpartnered", "cohab",
"marriage"), partnered (0/1), parity (births; 0 for men),
previous_union ("none", "separated", "widowed"), partner_race (NA
when unpartnered) and, when the dimension tracks ancestry, shares
ancestry_race_A and ancestry_race_unknown. Group transitions may also
use destination, the destination of the risk in the transition's
dimension.
Dissolution and conversion are union processes and may use race_w,
race_h, parity_w, previous_union_w, previous_union_h,
ancestry_race_A_w, ancestry_race_A_h, same_race (0/1),
age_difference (husband's age minus wife's age) and union_type
("cohab", "marriage").
The first listed level of each categorical variable is its reference; for a group dimension it is its first category (declared, or first in the population).
Formulas
Terms are main effects of these variables and interactions
(: or *); transformations such as I() are not supported (use fun).
Categorical variables use treatment coding, and coefficients must be
named exactly as the corresponding model-matrix columns, for example
raceB or union_typecohab.
Custom functions
Instead of using a formula, users can create a
custom function with fun. fun(members, bin) receives a tibble with one
row per eligible member of the chosen cell, holding the variables above for
every declared dimension (with labels for categorical variables) and
identifiers (person_id, or union_id, wife_id and husband_id), and a
list bin describing the cell: its process, strata (each dimension's
category, or <dim>_w/<dim>_h for union processes, NA when the rates do
not stratify by it; origin and destination for transitions), band
(age_start/age_end or dur_start/dur_end) and the active rate period
time_start/time_end (NA for static rates). Exact ages and times are not
passed. In fertility with weighted matching calibration, the function is
evaluated at every refresh of every woman, which can be slow.
Time-varying weights
A process's weights may instead be a tibble
with numeric time_start, time_end and a list column model of weight
models, as for matching and inheritance model schedules.
Examples
# allow mortality to be 10% lower for individuals with partners
partnered_mortality <- weight_model(~partnered, c(partnered = log(0.9)))
# allow dissolution rates to change by 5% per year increase in partner
# age differences - not in absolute terms which would require the custom
# function
gap_dissolution <- weight_model(
~age_difference,
c(age_difference = log(1.05))
)
# like previous example but use custom function to get absolute age
# difference
gap_dissolution <- weight_model(
fun = function(members, bin) {
log(1.05) * abs(members$age_difference)
}
)
