Constructs a fertility process specification for a simulation model. The
convenience function set_fertility is equivalent to set_process(model, fertility(...)) and allows for direct piping from a model.
Usage
fertility(rates, birth_interval = 0.75, ffab = 0.4886, weights = NULL)
set_fertility(
model,
rates,
birth_interval = 0.75,
ffab = 0.4886,
weights = NULL
)Arguments
- rates
A nonempty data frame defining the fertility rate schedules. Must contain at least numeric
age_start,age_end, andrate. See details for description of stratification variables that can be applied.- birth_interval
Minimum maternal birth-to-birth interval in years, defaulting to
0.75. Must be finite and nonnegative.- ffab
Probability that a newborn is female, default
0.4886. Must be a finite numeric scalar between 0 and 1.- weights
NULL (default) for unweighted selection within rate cells, or a
weight_model()specification. Weights choose which member of a cell experiences an event without changing the cell's input rate.- model
A
hammel_modelobject, used byset_fertility().
Value
fertility() returns an inspectable process inheriting from
hammel_fertility and hammel_process, with name, rates,
birth_interval, ffab, and weights. set_fertility()
returns an updated hammel_model.
Details
The primary and only required input to the function is a fertility rate
schedule for the rates argument. This data frame must contain age_start
and age_end columns to define the half-open age intervals (inclusive at the
start and exclusive at the end) and a rate column for the age-specific
fertility rates. The example below shows the basic format:
#> # A tibble: 6 x 3
#> age_start age_end rate
#> <int> <int> <dbl>
#> 1 15 20 0.0477
#> 2 20 25 0.110
#> 3 25 30 0.114
#> 4 30 35 0.0912
#> 5 35 40 0.0397
#> 6 40 45 0.008Rates are always specified as births over person-years lived for women. An
open-ended age group specified with age_end of Inf can be included but is
not required. Any age groups without a specified rate will be assumed to have
a zero rate.
Columns named by declared group dimensions (see set_groups()), such as
race or region, supply separate schedules for each combination of their
categories; dimensions without a column share the schedule. Every combination
of categories of the dimensions must be included in the rates if the
dimension is used.
Optional time_start/time_end columns select half-open calendar intervals
in absolute years, including fractional years. Both columns are required
together; starts are finite and ends exceed starts (possibly Inf). Active
slices must satisfy the strata and coverage rules and cover the requested
simulation run.
Fertility optionally accepts union_type containing both "partnered" and
"unpartnered", or all three of "unpartnered", "cohab", "marriage".
Shared partnered rates cover either partnership type. Rates use woman-years
in the indicated type; the old fertility input union_status is rejected.
Without that column, one overall schedule applies to all women. On-demand
union formation requires overall rates; rate-based formation accepts either
form, but using overall fertility rates with specified union formation rates
will lead to independence between marriage and fertility, which is likely
undesirable in most applications. A warning is printed if this is the case.
Optional parity_start/parity_end use half-open current maternal parity
bands, covering zero through Inf without gaps or overlap in every group/type
stratum.
The stratify_rates() function provides a quick means to add stratification
to an existing rate schedule.
Examples
fert_process <- fertility(usa_2000_fertility)
model <- hammel_model() |> set_process(fert_process)
# Equivalent convenience setter:
model <- hammel_model() |> set_fertility(usa_2000_fertility)
