create.baseline.complete {poplab}R Documentation

Create a baseline population of related individuals

Description

Create a baseline population for a given calendar year. Require fertility and mortality rates, and age-profile for the specified year in order to create a population of related individuals of the correct age profile (the "trimmed" population), to which there are added the parents of these individuals who were excluded by the trimming process. Disease incidence is simulated when desired.

The function looks in the folder specified in its call for 6 input data files: age-specific population counts for males and females separately, female fertility, mortality rates for males and females separately, and disease (e.g. breast cancer) incidence rates.

Usage

create.baseline.complete (baseyear, healthy, risk,
sex.a, mortratio, base.scale, runintime,
d.mod, fam.rel, print.option, population.fem, 
population.male, mortality.fem, mortality.male, 
fertility, incidence, seed, folder)

Arguments

baseyear year for which to create a baseline population.
healthy 0/1 values - disease incidence simulated/not simulated during the creation of the baseline population. The default is 1.
risk parameter for familial aggregation of disease; used only if healthy is set to 0. The default is 1 (i.e. no familial aggregation). See Details below.
sex.a 1/2 values - gender specification (1 = males, 2 = females) for familial aggregation of disease; used only if healthy is set to 0. The default is 2 (mother/daughter or sister/sister disease aggregation).
mortratio mortality ratio for cases compared to disease free individuals. The default is 1 (i.e. cases have the same risk of death as disease free individuals).
base.scale this factor multiplied by 100 is the sex-specific number of individuals in the starting population. The default is 500 i.e. 50000 females and approximately 50000 males in the starting population (see Details below).
runintime number of years the baseyear real population age profile is set back in time (see Details below). The default is 100.
d.mod familial model of disease aggregation to choose from (see Details below); used only if healthy is set to 0.
fam.rel familial relationship of disease aggregation to choose from (see Details below); used only if healthy is set to 0.
print.option TRUE/FALSE values - option for saving to file the baseline population. The default is FALSE.
population.fem name (quoted) of the tab-separated file storing age-specific counts from the real female population (e.g. "populationfem.txt").
population.male name (quoted) of the tab-separated file storing age-specific counts from the real male population (e.g. "populationmale.txt").
mortality.fem name (quoted) of the tab-separated file storing age-specific female mortality rates (e.g. "mortalityfem.txt").
mortality.male name (quoted) of the tab-separated file storing age-specific male mortality rates (e.g. "mortalitymale.txt").
fertility name (quoted) of the tab-separated file storing female fertility rates (e.g. "fertility.txt").
incidence name (quoted) of the tab-separated file storing disease incidence rates (e.g. "incidence.txt").
seed seed used in the creation of the population. The default is NULL. Useful when the user wants to reproduce the exact same simulation results (population).
folder folder (quoted) where the function looks for input files such as population counts, mortality, fertility and incidence rates. For example, it might be your R_HOME/library/poplab/data/ directory, where R_HOME is the location where R is installed on your computer (see Examples below).

Details

base.scale The exact number of male individuals is calculated in such a way as to maintain the real ratio between the number of male individuals and the number of female individuals.

runintime To create a baseline population of related individuals for the baseyear, a population of unrelated individuals (the starting population) is constructed for the calendar year calculated as (baseyear - runintime); this starting population has the age profile of the baseyear real population. For the number of years specified by runintime, the baseyear fertility and mortality rates are applied to this starting population and their descendants, "arriving" in the baseyear with a complete population of related individuals.

d.mod The options to choose from are: familial relative risk ("rr"), familial odds-ratio ("or"), familial relative risk depending on the age at incidence of the affected relative ("agesprr") and familial odds-ratio depending on age at incidence of the affected relative ("agespor").

fam.rel The options to choose from are: familial aggregation occurs through a parent ("p") and familial aggregation occurs thorugh a sibling ("s").

risk If this is a single value, it is expected that the value for d.mod is either "rr" or "or". For the familial models of disease where the risk and the odds, respectively, depend on the age at incidence of the affected relative, a numerical array is specified. The first part of the array represents the upper limit of the age categories and the last part are the actual coefficients of increase. The age-intervals are open to the left (see also Examples).

Value

the matrix containing the baseline population

Note

If a call to this function is made without assigning its value to a variable, the result will be printed on the screen (most probably, a very large matrix!). Thus it is advisable to always assign the object returned by this function to a variable.

See Also

simped, plot.poplab, print.poplab

Examples


## Not run: 
The syntax below constructs the baseline population for the
calendar year 1955 (baseyear). It applies the 1955 fertility
and mortality rates for 70 years (runintime) to the virtual
population of 1855 constructed from the 1955 age profile; the
1855 population consists of 3000 females and approximately
3000 males (base.scale), all unrelated individuals. Incident
cancer is assigned during the creation (healthy), but there is
no familial risk of cancer (risk). The mortality ratio for cases
is 2 (mortratio). The resulting population is not saved to file
(print.option). The input files are "populationfem.txt",
"populationmale.txt", "mortalityfem.txt", "mortalitymale.txt",
"fertility.txt" and "incidence.txt" from the "data" folder of the
poplab package.
## End(Not run)

base <- 
create.baseline.complete(baseyear = 1955, healthy = 0, risk =
1, mortratio = 2, d.mod = "rr", fam.rel = "p", base.scale = 
30, runintime = 70, print.option = FALSE, population.fem = 
"populationfem.txt", population.male = "populationmale.txt", 
mortality.fem = "mortalityfem.txt", mortality.male = 
"mortalitymale.txt", fertility = "fertility.txt", incidence = 
"incidence.txt", seed = 52482337, folder =
system.file("data", package = "poplab"))

## Not run: 
In the syntax below the familial relative risk (d.mod) depends
on maternal (fam.rel) age at incidence: the risk of disease (risk)
is increased by factor of 4 for women whose mothers where strictly 
younger than 50 years of age at diagnosis compared to daughters 
of unaffected mothers, and by a factor of 2 for daughters of 
women diagnosed between the age of 50 to 100 years.

base <- 
create.baseline.complete(baseyear = 1955, healthy = 0, risk =
c(50, 101, 4, 2), mortratio = 2, d.mod = "agesprr", fam.rel =
"p", base.scale = 30, runintime = 70, print.option = FALSE, 
population.fem = "populationfem.txt", population.male = 
"populationmale.txt", mortality.fem = "mortalityfem.txt", 
mortality.male = "mortalitymale.txt", fertility = 
"fertility.txt", incidence = "incidence.txt",
seed = 52482337, folder =
system.file("data", package = "poplab"))
## End(Not run)


[Package poplab version 1.0.2 Index]