create.baseline.complete       package:poplab       R Documentation

_C_r_e_a_t_e _a _b_a_s_e_l_i_n_e _p_o_p_u_l_a_t_i_o_n _o_f _r_e_l_a_t_e_d _i_n_d_i_v_i_d_u_a_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

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).

_D_e_t_a_i_l_s:

     '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).

_V_a_l_u_e:

     the matrix containing the baseline population

_N_o_t_e:

     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.

_S_e_e _A_l_s_o:

     'simped', 'plot.poplab', 'print.poplab'

_E_x_a_m_p_l_e_s:

     ## 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)

