home *** CD-ROM | disk | FTP | other *** search
/ Big Green CD 8 / BGCD_8_Dev.iso / NEXTSTEP / UNIX / Educational / R-0.49-MI / R-0.49-I / help / survival4 / pyears < prev    next >
Encoding:
Text File  |  1997-09-13  |  6.1 KB  |  152 lines
  1.     
  2.     _P_e_r_s_o_n _Y_e_a_r_s _T_h_i_s _f_u_n_c_t_i_o_n _c_o_m_p_u_t_e_s _t_h_e _p_e_r_s_o_n-_y_e_a_r_s _o_f
  3.     _f_o_l_l_o_w-_u_p _t_i_m_e _c_o_n_t_r_i_b_u_t_e_d _b_y _a _c_o_h_o_r_t _o_f _s_u_b_j_e_c_t_s, _s_t_r_a_-
  4.     _t_i_f_e_d _i_n_t_o _s_u_b_g_r_o_u_p_s.  _I_t _a_l_s_o _c_o_m_p_u_t_e_s _t_h_e _n_u_m_b_e_r _o_f _s_u_b_-
  5.     _j_e_c_t_s _w_h_o _c_o_n_t_r_i_b_u_t_e _t_o _e_a_c_h _c_e_l_l _o_f _t_h_e _o_u_t_p_u_t _t_a_b_l_e, _a_n_d
  6.     _o_p_t_i_o_n_a_l_l_y _t_h_e _n_u_m_b_e_r _o_f _e_v_e_n_t_s _a_n_d/_o_r _e_x_p_e_c_t_e_d _n_u_m_b_e_r _o_f
  7.     _e_v_e_n_t_s _i_n _e_a_c_h _c_e_l_l.
  8.     
  9.          pyears(formula, data, weights, subset, na.action, ratetable=survexp.us,
  10.          scale=365.25, expect=c('event', 'pyears'), model=F, x=F, y=F)
  11.     
  12.     _A_r_g_u_m_e_n_t_s:
  13.     
  14.           formula:
  15.          a formula object.  The response variable will be a vec-
  16.          tor of follow-up times for each subject, or a Surv
  17.          object containing the follow-up time and an event indi-
  18.          cator.  The predictors consist of optional grouping
  19.          variables separated by + operators (exactly as in
  20.          survfit), time-dependent grouping variables such as age
  21.          (specified with tcut), and optionally a ratetable()
  22.          term.  This latter matches each subject to his/her
  23.          expected cohort.
  24.     
  25.              data:
  26.          a data frame in which to interpret the variables named
  27.          in the formula.
  28.     
  29.           weights:
  30.          case weights.
  31.     
  32.            subset:
  33.          expression stating that only a subset of the rows
  34.          should be used.
  35.     
  36.         na.action:
  37.          missing data filter function.
  38.     
  39.         ratetable:
  40.          a table of event rates, such as survexp.uswhite.
  41.     
  42.             scale:
  43.          a scaling for the results.  As most rate tables are in
  44.          units/day, the default value of 365.25 causes the out-
  45.          put to be reported in years.
  46.     
  47.          expected:
  48.          should the output table include the expected number of
  49.          events, or the expected number of person-years of
  50.          observation.  This is only valid with a rate table.
  51.     
  52.       model, x, y:
  53.          If any of these is true, then the model frame, the
  54.          model matrix, and/or the vector of response times will
  55.          be returned as components of the final result.
  56.     
  57.          Value:
  58.     
  59.          a list with components
  60.     
  61.       pyears:
  62.     an array containing the person-years of exposure. (Or other
  63.     units, depending on the rate table and the scale).
  64.     
  65.            n:
  66.     an array containing the number of subjects who contribute
  67.     time to each cell of the pyears array.
  68.     
  69.        event:
  70.     an array containing the observed number of events.  This
  71.     will be present only if the resonse variable is a Surv
  72.     object.
  73.     
  74.     expected:
  75.     an array containing the expected number of events (or person
  76.     years).  This will be present only if there was a ratetable
  77.     term.
  78.     
  79.     offtable:
  80.     the number of person-years of exposure in the cohort that
  81.     was not part of any cell in the pyears array.  This is often
  82.     useful as an error check; if there is a mismatch of units
  83.     between two variables, nearly all the person years may be
  84.     off table.
  85.     
  86.      summary:
  87.     a summary of the rate-table matching.  This is also useful
  88.     as an error check.
  89.     
  90.         call:
  91.     an image of the call to the function.
  92.     
  93.     na.action:
  94.     the na.action attribute contributed by an na.action routine,
  95.     if any.  Because pyears may have several time variables, it
  96.     is necessary that all of them be in the same units.  For
  97.     instance in the call
  98.     
  99.          py <- pyears(futime ~ rx + ratetable(age=age, sex=sex, year=entry.dt))
  100.     with a ratetable whose natural unit is days, it is important
  101.     that futime, age and entry.dt all be in days.  Given the
  102.     wide range of possible inputs, it is difficult for the rou-
  103.     tine to do sanity checks of this aspect.  A special function
  104.     tcut is needed to specify time-dependent cutpoints.  For
  105.     instance, assume that age is in years, and that the desired
  106.     final arrays have as one of their margins the age groups 0-
  107.     2, 2-10, 10-25, and 25+.  A subject who enters the study at
  108.     age 4 and remains under observation for 10 years will con-
  109.     tribute follow-up time to both the 2-10 and 10-25 subsets.
  110.     If cut(age, c(0,2,10,25,100)) were used in the formula, the
  111.     subject would be classifed according to his starting age
  112.     only.  The tcut function has the same arguments as cut, but
  113.     produces a different output object which allows the pyears
  114.     function to correctly track the subject.  The results of
  115.     pyears() are normally used as input to further calculations.
  116.     The example below is from a study of hip fracture rates from
  117.     1930 - 1990 in Rochester, Minnesota.  Survival post hip
  118.     fracture has increased over that time, but so has the sur-
  119.     vival of elderly subjects in the population at large.  A
  120.     model of relative survival helps to clarify what has hap-
  121.     pened: Poisson regression is used, but replacing exposure
  122.     time with expected exposure (for an age and sex matched con-
  123.     trol).  Death rates change with age, of course, so the
  124.     result is carved into 1 year increments of time.  Males and
  125.     females were done separately.
  126.     
  127.     _E_x_a_m_p_l_e_s:
  128.     
  129.          attach(malehips)
  130.          temp1 <- tcut(dt.fracture, seq(from=mdy.date(1,1,30), by=365.25, length=61))
  131.          temp2 <- tcut(age*365.5,   365.25*(0:105))   #max age was > 100!
  132.          pfit  <- pyears(Surv(futime, status) ~ temp1 + temp2 +
  133.                       ratetable(age=age*365.25, year=dt.fracture, sex=1),
  134.                     subset=(sex==1),
  135.                     ratetable=survexp.minnwhite)
  136.          cat(pfitummary)
  137.            age ranges from 50.1 to 110.5 years
  138.            male: 374  female: 1578
  139.            date of entry from 29Jun29 to 18Dec92
  140.          # now, convert the arrays into a data frame
  141.          tdata <- data.frame( age  = (0:105)[col(pfityears)],
  142.                       yr   = (1930:1990)[row(pfityears)],
  143.                         y  = c(pfitvent),
  144.                       time = c(pfitxpect))
  145.          # fit the gam model
  146.          gfit.m <- gam(y ~ s(age) + s(yr) + offset(log(time)), family=poisson,
  147.                      data= tdata)
  148.          plot(gfit.m, se=T)
  149.     
  150.          ratetable, survexp, Surv
  151.     
  152.