Create a hammel_population object to serve as the starting population for a
simulation.
Usage
hammel_population(
persons,
unions = NULL,
end_time,
ancestry = NULL,
transitions = NULL,
groups = NULL
)Arguments
- persons
A data frame with one row per person, including deceased persons. Must include a unique
person_id, nonmissingsex, nonmissingbirth_time,death_time,mother_id, andfather_id.- unions
A data frame with one row per union episode, or
NULLfor no unions.wife_idreferences the female partner andhusband_idthe male partner. Optionalunion_typeis cohab or marriage.- end_time
Required finite numeric reference time in years. Its calendar origin is supplied by the user. This supplies the next simulation's starting time. Recorded events must not occur after this time.
- ancestry
Optional ancestry shares for dimensions declared with
group(ancestry = TRUE): a named list with one data frame per such group dimension (a bare data frame when only one dimension tracks ancestry), each with exactly one row per person, keyed byperson_id, one column of shares per category (named by the category) and anunknownshare. Shares must be finite, between zero and one, and sum to one per row (tolerance1e-8).- transitions
Optional data frame of individual category changes with
person_id,time,group(the dimension; may be omitted when one is declared),origin, anddestination. Each person's history in each dimension must chain to their current category and lie within life dates and the known endpoint. Grouped populations always include this tibble, even when empty, with charactergroup,originanddestination.- groups
Optional group declaration: a character vector of dimension names (each with
group()defaults) or a named list ofgroup()objects. Persons columns that are not declared are ordinary custom columns. Models usually declare groups withset_groups().
Value
A named list of class hammel_population with components persons,
unions, and end_time, plus an ancestry tibble when supplied or when
persons has groups, and a transitions tibble when groups are present.
Details
In most cases, it will be more common to create a hammel_population object
by using generate_uniform_population() or to receive a hammel_population
object as the output of run_simulation().
The hammel_population object must always contain a persons data frame and
an end_time value. The end_time value defines the starting point for the
simulation and no dates in the hammel_population may exceed the end_time
value.
Examples
population <- hammel_population(
persons = data.frame(
person_id = 1:2, sex = c("m", "f"), birth_time = c(-25, -23),
death_time = NA_real_, mother_id = NA_integer_, father_id = NA_integer_
),
end_time = 0
)
