Constructs a union formation process specification for a simulation model.
The convenience function set_union_formation is equivalent to
set_process(model, union_formation(...)) and allows for direct piping from
a model.
Usage
union_formation(
initiation,
rates = NULL,
matching = age_gap_matching_model(0, 5),
father_matching = NULL,
cohab_matching = NULL,
cohab_prob = NULL,
union_convert_rate = NULL,
weights = NULL,
weights_conversion = NULL,
min_male_age = 15,
kinship_generations = 2,
cancel_birth_if_no_match = TRUE,
cohab_as_previous_union = FALSE,
diagnostics = FALSE
)
set_union_formation(
model,
initiation,
rates = NULL,
matching = age_gap_matching_model(0, 5),
father_matching = NULL,
cohab_matching = NULL,
cohab_prob = NULL,
union_convert_rate = NULL,
weights = NULL,
weights_conversion = NULL,
min_male_age = 15,
kinship_generations = 2,
cancel_birth_if_no_match = TRUE,
cohab_as_previous_union = FALSE,
diagnostics = FALSE
)Arguments
- initiation
Either
"on_demand"for birth-triggered searches or"rate"for scheduled searches. No default is selected.- rates
For rate mode, a nonempty data frame defining the marriage rate schedules. Must contain at least numeric
age_start,age_end, andrate. See details for description of stratification variables that can be applied.- matching
A specification created by
matching_model(), or a tibble with numerictime_start,time_end, and list-columnmodelholding complete matching objects. Defaults toage_gap_matching_model(0, 5): preferred age gap zero years, with selection weight halving five years on either side.- father_matching
Optional matching specification for fathers of unpartnered births in rate mode, created by
matching_model(), or atime_start/time_end/modelschedule as formatching. Defaults toNULL, using the generalmatchingmodel active at that birth.- cohab_matching
Optional matching model or whole-model schedule for cohabitation; NULL shares the general
matchingmodel.- cohab_prob
Optional age-specific probability table defining the probability that a union is a cohabitation. See details for specification.
- union_convert_rate
Optional age- or duration-specific conversion table, defining conversion rates of cohabitations into marriages. See details for specification.
- weights
NULL (default) for unweighted selection of searching women, or a
weight_model()using person variables, which chooses which unpartnered woman in a cell searches without changing the cell's input search rate. Rate mode only.- weights_conversion
NULL (default) for unweighted selection, or a
weight_model()using union variables, which chooses which cohabitation in a cell converts to marriage without changing the cell's input rate.- min_male_age
Minimum male age in continuous years for partner eligibility, default
15. Finite nonnegative scalar; zero disables this age exclusion.- kinship_generations
Generation bound on both sides of a known common ancestor defining partner ineligiblity, default
2. Excludes parents, grandparents, siblings, aunts/uncles, nieces/nephews and first cousins, including half relationships, when known. Zero imposes no cross-person kin exclusion. Seeextract_kin()for the shared distance definitions.- cancel_birth_if_no_match
Logical, default
TRUE. Cancel a birth when its on-demand partner search or rate-mode nonmarital father selection fails. SetFALSEto allow births with unknown fathers. Historical missing father IDs are retained. Partner scarcity can reduce realized fertility below inputs.- cohab_as_previous_union
Logical, default FALSE. FALSE only marriage defines the
previous_unionvalue; TRUE cohabitation or marriage define theprevious_unionvalue.- diagnostics
Logical, default
FALSE. WhenTRUE, adds additional technical variables from matching model to each union record.- model
A
hammel_modelobject.
Value
union_formation() returns a hammel_union_formation process;
set_union_formation() returns an updated model.
Details
The union formation process is female-centric. Women initiate searches and
select male partners. Two different approaches to union search initiation are
provided for the required initiation argument:
The "on_demand" approach will initiate a union search when an unpartnered woman gives birth. This approach should not be used with fertility rates that are stratified by
union_typebecause unpartnered fertility is what creates the search. This approach is useful if the user has no particular interest in union formation processes but wants to assign parentage correctly for kinship determination.The "rate" approach uses female marriage rates defined by the
ratesargument. The input should be a marriage rate schedule that may be stratified by group dimensions and/orprevious_union. When stratified byprevious_union, remarriages may be duration-specific rather than age-specific. This approach should generally be used with fertility rates that are stratified byunion_type, although it is not required. Failure to stratify byunion_typewill lead to independence between fertility and union formation.
Once a search is initiated, a woman will select a male partner from among all
eligible male partners. Men related to the women are considered ineligible
out to a kinship depth defined by kinship_generations and men below
min_male_age are also ineligible. the decision itself is determined by the
provided matching_model which uses a conditional logit formulation to score
potential suitors by age differences and group exogamy. See
matching_model() for more details.
It is possible for this search to fail if no eligible men are available. When
using the "on_demand" method, the cancel_birth_if_no_match argument
controls whether the birth continues if no match is found. If set to FALSE,
the birth continues but with NA values for the father. If set to TRUE,
observed fertility rates may deviate from input rates.
When unpartnered fertility is allowed, the matching_model will also be used
to identify the father of a birth to an unpartnered woman. Users can
optionally specify a separate father_matching model for this case.
Cohabitation can be added to the union formation process by specifying
cohab_prob and union_convert_rate. The cohab_prob argument expects a
data frame that is similar to a rate process object. It contains age-specific
bands defined by age_start and age_end, but also contains a prob column
rather than a rate column. This prob column defines the probability that
a union formed by a woman of the given age is a cohabitation instead of a
marriage. Like rate processes, cohab_prob can be stratified by time period
using time_start and time_end, group dimensions, or by previous_union.
The union_convert_rate is not required, but is necessary for cohabitations
to be able to convert into marriages. It follows the standard rate process
format and can be either duration or age dependent. It can also be stratified
by time period and group dimension.
By default, partner selection for cohabitation will use the matching_model
argument. Users can specify a matching model specific to cohabitations with
the cohab_matching argument.
Examples
union_process <- union_formation(
initiation = "rate",
rates = usa_2000_marriage,
matching = age_gap_matching_model(3, 5)
)
model <- hammel_model() |>
set_fertility(usa_2000_fertility_union) |>
set_mortality(usa_2000_mortality) |>
set_process(union_process)
