SimRVPedigree (version 0.4.4)

sim_life: Simulate all life events

Description

Primarily intended as an internal function, sim_life simulates all life events for an individual starting at birth, age 0, and ending with death or the end of the study.

Usage

sim_life(hazard_rates, GRR, carrier_prob, RV_status, YOB, stop_year,
  NB_params = c(2, 4/7), fert = 1)

Arguments

hazard_rates

An object of class hazard, created by hazard.

GRR

Numeric. The genetic relative-risk of disease, i.e. the relative-risk of disease for individuals who carry at least one copy of the causal variant. Note: When simulating diseases with multiple subtypes GRR must contain one entry for each simulated subtype. See details.

carrier_prob

Numeric. The carrier probability for all causal variants with relative-risk of disease GRR. By default, carrier_prob = 0.002

RV_status

Numeric. RV_status = TRUE if the individual is a carrier of a rare variant that increases disease suseptibility, and FALSE otherwise.

YOB

A positive number. The indivdiual's year of birth.

stop_year

Numeric. The last year of study. If not supplied, defaults to the current year.

NB_params

Numeric vector of length 2. The size and probability parameters of the negative binomial distribution used to model the number of children per household. By default, NB_params = c(2, 4/7), due to the investigation of Kojima and Kelleher (1962).

fert

Numeric. A constant used to rescale the fertility rate after disease-onset. By default, fert = 1.

Value

an object of class event. An object of class event is a list that contains the following items.

life_events

A named numeric vector of life events, see details.

repro_events

A vector of reproduction years, that is the year(s) that the individual produces offspring. When the individual does not reproduce repro_events = NULL.

onset_event

Numeric. When applicable the year of disease-onset. When onset does not occur onset_event = NA

death_event

Numeric. When applicable the year of death. When death is censored death_event = NA

subtype

Character. When applicable, the disease subtype.

censor_year

Numeric. When applicable the last year that data was observed. Note: after death censor_year = NA

Details

Starting at birth, age 0, sim_life generates waiting times to reproduction, onset, and death. The event with the shortest waiting time is chosen as the next life event, and the individual's age is updated by the waiting time of the winning event. Conditioned on the individual's new age, this process is applied recursively, until death or until the end of the study is reached.

We make the following assumptions regarding the simulation of waiting times:

1. We assume that, given an individual's current age, their time to disease onset is the waiting time in a non-homogeneous Poisson process with an age-specific hazard rate that follows a proportional hazards model. In this model, individuals who have NOT inherited the rare variant experience disease onset according to the baseline (or population) hazard rate of disease. On the other hand, individuals who have inherited the rare variant are assumed to have an increased risk of disease onset relative to those who have inherited it. The user is expected to supply the baseline hazard rate of disease, as well as the relative-risk of disease for genetic cases. Additionally, we impose the restriction that individuals may only experience disease onset once, and remain affected from that point on.

2. We assume that, given an individual's current age, their time to death is the waiting time in a non-homogeneous Poisson process with age-specific hazard rate determined by their affection status. We assume that disease-affected individuals experience death according to the age-specific hazard rate for death in the affected population. On the other hand, we assume that unaffected individuals experience death according to the age-specific hazard rate for death in the unaffected population. If the disease of interest is sufficiently rare, the user may choose to substitute the population age-specific hazard rate for death for the aforementioned age-specific hazard rate for death in the unaffected population. The user is expected to supply age-specific hazard rates of death for both the affected and unaffected populations.

3. We assume that, given an individual's current age, their time to reproduction is the waiting time in a homogeneous Poisson process. That is, we assume that individuals reproduce at uniform rate during their reproductive years. For example, one's reproductive years may span from age 20 to age 35 years. To mimic observed age-specific fertility data, the birth range for an individual is simulated as follows: first we sample the lower bound uniformly from ages 16 to 27, next we sample the range of the birth span uniformly from 10 to 18 years and add this value to the lower bound to determine the upper bound of the birth range. We do not allow for offspring to be produced outside of an individual's simulated reproductive birth span.

The events simulated by sim_life are labelled as follows:

• "Start" the individual's year of birth.

• "Child" a reproductive event, i.e. creation of offspring

• "Onset" disease onset event,

• "Death" death event

References

Nieuwoudt, Christina and Jones, Samantha J and Brooks-Wilson, Angela and Graham, Jinko (2018). Simulating Pedigrees Ascertained for Multiple Disease-Affected Relatives. Source Code for Biology and Medicine, 13:2.

Ken-Ichi Kojima, Therese M. Kelleher. (1962), Survival of Mutant Genes. The American Naturalist 96, 329-346.

Examples

# NOT RUN {
data(AgeSpecific_Hazards)
my_HR <- hazard(hazardDF = AgeSpecific_Hazards)

# The following commands simulate all life events for an individual who
# has NOT inherited a causal variant, born in 1900.  From the output, this
# individual has two children, one in 1921 and another in 1923, and then
# dies in 1987.
set.seed(135)
sim_life(hazard_rates = my_HR, GRR = 10,
         carrier_prob = 0.002,
         RV_status = FALSE,
         YOB = 1900, stop_year = 2000)

# Using the same random seed, notice how life events can vary for
# someone who has inherited the causal variant, which carries a
# relative-risk of 10. From the output, this individual also has
# two children, but then experiences disease onset in 1974,
# and dies in 1976.
set.seed(135)
sim_life(hazard_rates = my_HR, GRR = 10,
               carrier_prob = 0.002,
               RV_status = TRUE,
               YOB = 1900, stop_year = 2000)

# The following commands simulate life events for an individual who
# has inherited a causal rare variant, with relative risk 100 for
# the subtype "HL" and no increased relative risk for the subtype"NHL".
set.seed(1)
sim_life(hazard_rates = hazard(SubtypeHazards,
                               subtype_ID = c("HL", "NHL")),
         GRR = c(100, 1),
         carrier_prob = 0.002,
         RV_status = TRUE,
         YOB = 1900, stop_year = 2000)


# }