SimRVPedigree (version 0.4.4)

sim_ped: Simulate a pedigree

Description

Please note the distinction between sim_ped and sim_RVped. Pedigrees simulated using sim_ped do not account for study design. To simulate a pedigree ascertained to contain multiple family members affected by a disease please use sim_RVped.

Usage

sim_ped(hazard_rates, GRR, FamID, founder_byears, stop_year = NULL,
  carrier_prob = 0.002, RVfounder = FALSE, 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.

FamID

Numeric. The family ID to assign to the simulated pedigree.

founder_byears

Numeric vector of length 2. The span of years from which to simulate, uniformly, the birth year for the founder who introduced the rare variant to the pedigree.

stop_year

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

carrier_prob

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

RVfounder

Logical. Indicates if all pedigrees segregate the rare, causal variant. By default, RVfounder = FALSE See details.

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

The simulated pedigree.

See Also

sim_RVped, sim_life

Details

To introduce the rare variant to the pedigree, We allow users to choose from one of the following two assumptions:

1. Assume that the variant is rare enough that a single copy has been introduced by one founder, and begin the simulation of the pedigree with this founder, as in Bureau (2014).

2. Simulate the starting founder's rare-variant status with probability equal to the carrier probability of the rare variant in the population. We note that under this setting pedigrees may not segregate the rare variant.

The sim_ped function starts simulating the pedigree by generating the birth year for the starting founder, uniformly between the years specified by founder_byears. Next, all life events are simulated for the founder via sim_life. Possible life events include: reproduction, disease onset, and death. We only allow disease onset to occur once, i.e. no remission. Computationally, this implies that after disease onset, the waiting time to death is always simulated using the age-specific mortality rates for the affected population. Life events for individuals who have inherited the rare variant are simulated such that their relative-risk of disease is GRR, according to a proportional hazards model. The relative-risk of disease onset for individuals who have not inherited the causal variant is assumed to be 1. Any life events that occur after stop_year are censored.

When segregating in the pedigree, the rare variant is transmitted from parent to offspring according to Mendel's laws. The process of simulating life events is repeated for any offspring that are produced before stop_year.

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.

Alexandre Bureau, Samuel G. Younkin, Margaret M. Parker, Joan E. Bailey-Wilson, Mary L. Marazita, Jeffrey C. Murray, Elisabeth Mangold, Hasan Albacha-Hejazi, Terri H. Beaty, and Ingo Ruczinski (2014). Inferring rare disease risk variants based on exact probabilities of sharing by multiple affected relatives. Bioinformatics; Vol. 30, No. 15, pp. 2189-2196.

Examples

# NOT RUN {
data(AgeSpecific_Hazards)

# Simulate a random pedigree
set.seed(5)
ex_ped <- sim_ped(hazard_rates = hazard(hazardDF = AgeSpecific_Hazards),
                  GRR = 10,
                  FamID = 1,
                  founder_byears = c(1900, 1910),
                  stop_year = 2015)

# View the simulated pedigree
ex_ped

# Plot the pedigree
plot(ex_ped, location = "topleft")

# Plot the pedigree, this time with age labels for
# all descendents of the starting founder (ID 1)
plot(ex_ped, ref_year = 2015,
     cex= 0.75, symbolsize = 1.25,
     location = "topleft")


# Simulate a random pedigree. This time set RVfounder to TRUE so that
# the eldest introduces a causal rare variant with probability 1.
set.seed(5)
ex_ped <- sim_ped(hazard_rates = hazard(hazardDF = AgeSpecific_Hazards),
                  RVfounder = TRUE,
                  GRR = 10,
                  FamID = 1,
                  founder_byears = c(1900, 1910),
                  stop_year = 2015)


# Plot the pedigree with age labels
plot(ex_ped, ref_year = 2015,
     cex= 0.75, symbolsize = 1.25,
     location = "topleft")

# }