rateplot                 package:Epi                 R Documentation

_F_u_n_c_t_i_o_n_s _t_o _p_l_o_t _r_a_t_e_s _f_r_o_m _a _t_a_b_l_e _c_l_a_s_s_i_f_i_e_d _b_y _a_g_e _a_n_d
_c_a_l_e_n_d_a_r _t_i_m_e (_p_e_r_i_o_d)

_D_e_s_c_r_i_p_t_i_o_n:

     Produces plots of rates versus age, connected within period or
     cohort ('Aplot'), rates versus period connected within age-groups
     ('Pplot') and rates and rates versus date of birth cohort
     ('Cplot'). 'rateplot' is a wrapper for these, allowing to produce
     the four classical displays with a single call.

_U_s_a_g_e:

     rateplot( rates,
               which = c("ap","ac","pa","ca"),
                 age = as.numeric( dimnames( rates )[[1]] ),
                 per = as.numeric( dimnames( rates )[[2]] ),
                grid = FALSE,
              a.grid = grid,
              p.grid = grid,
              c.grid = grid,
               ygrid = grid,
            col.grid = gray( 0.9 ),
               a.lim = range( age, na.rm=TRUE ) + c(0,diff( range( age ) )/30),
               p.lim = range( per, na.rm=TRUE ) + c(0,diff( range( age ) )/30),
               c.lim = NULL, 
                ylim = range( rates[rates>0], na.rm=TRUE ),
                  at = NULL,
              labels = paste( at ),
               a.lab = "Age at diagnosis",
               p.lab = "Date of diagnosis",
               c.lab = "Date of birth",
                ylab = "Rates",
                type = "l",
                 lwd = 2,
                 lty = 1,
              log.ax = "y",
                 las = 1,
                 ann = FALSE,
               a.ann = ann,
               p.ann = ann,
               c.ann = ann,
               xannx = 1/20,
             cex.ann = 0.8,
              a.thin = seq( 1, length( age ), 2 ),
              p.thin = seq( 1, length( per ), 2 ),
              c.thin = seq( 2, length( age ) + length( per ) - 1, 2 ),
                 col = par( "fg" ),
               a.col = col,
               p.col = col,
               c.col = col,
                 ... )

     Aplot( rates, age = as.numeric( dimnames( rates )[[1]] ),
            per = as.numeric( dimnames( rates )[[2]] ), grid = FALSE,
            a.grid = grid, ygrid = grid, col.grid = gray( 0.9 ),
            a.lim = range( age, na.rm=TRUE ), ylim = range( rates[rates>0], na.rm=TRUE ),
            at = NULL, labels = paste( at ), a.lab = names( dimnames( rates ) )[1],
            ylab = deparse( substitute( rates ) ), type = "l", lwd = 2, lty = 1,
            col = par( "fg" ), log.ax = "y", las = 1, c.col = col, p.col = col,
            c.ann = FALSE, p.ann = FALSE, xannx = 1/20, cex.ann = 0.8,
            c.thin = seq( 2, length( age ) + length( per ) - 1, 2 ),
            p.thin = seq( 1, length( per ), 2 ), p.lines = TRUE,
            c.lines = !p.lines, ... )

     Pplot( rates, age = as.numeric( dimnames( rates )[[1]] ),
            per = as.numeric( dimnames( rates )[[2]] ), grid = FALSE,
            p.grid = grid, ygrid = grid, col.grid = gray( 0.9 ),
            p.lim = range( per, na.rm=TRUE ) + c(0,diff(range(per))/30),
            ylim = range( rates[rates>0], na.rm=TRUE ), p.lab = names( dimnames( rates ) )[2],
            ylab = deparse( substitute( rates ) ), at = NULL, labels = paste( at ),
            type = "l", lwd = 2, lty = 1, col = par( "fg" ), log.ax = "y",
            las = 1, ann = FALSE, cex.ann = 0.8, xannx = 1/20,
            a.thin = seq( 1, length( age ), 2 ), ... )

     Cplot( rates, age = as.numeric( rownames( rates ) ),
            per = as.numeric( colnames( rates ) ), grid = FALSE,
            c.grid = grid, ygrid = grid, col.grid = gray( 0.9 ),
            c.lim = NULL, ylim = range( rates[rates>0], na.rm=TRUE ),
            at = NULL, labels = paste( at ), c.lab = names( dimnames( rates ) )[2],
            ylab = deparse( substitute( rates ) ), type = "l", lwd = 2, lty = 1,
            col = par( "fg" ), log.ax = "y", las = 1, xannx = 1/20, ann = FALSE,
            cex.ann = 0.8, a.thin = seq( 1, length( age ), 2 ), ...  )

_A_r_g_u_m_e_n_t_s:

   rates: A two-dimensional table (or array) with rates to be plotted.
          It is assumed that the first dimension is age and the second
          is period.

   which: A character vector with elements from
          'c("ap","ac","apc","pa","ca")', indication which plots should
          be produced. One plot per element is produced. The first
          letter indicates the x-axis of the plot, the remaining which
          groups should be connected, i.e. '"pa"' will plot rates
          versus period and connect age-classes, and '"apc"' will plot
          rates versus age, and connect both periods and cohorts.

     age: Numerical vector giving the means of the age-classes.
          Defaults to the rownames of 'rates' as numeric.

     per: Numerical vector giving the means of the periods. Defaults to
          the columnnames of 'rates' as numeric.

    grid: Logical indicating whether a background grid should be drawn.

  a.grid: Logical indicating whether a background grid on the age-axis
          should be drawn. If numerical it indicates the
          age-coordinates of the grid.

  p.grid: do. for the period.

  c.grid: do. for the cohort.

   ygrid: do. for the rate-dimension.

col.grid: The colour of the grid.

   a.lim: Range for the age-axis.

   p.lim: Range for the period-axis.

   c.lim: Range for the cohort-axis.

    ylim: Range for the y-axis (rates).

      at: Position of labels on the y-axis (rates).

  labels: Labels to put on the y-axis (rates).

   a.lab: Text on the age-axis. Defaults to "Age".

   p.lab: Text on the period-axis. Defaults to "Date of diagnosis".

   c.lab: Text on the cohort-axis. Defaults to "Date of birth".

    ylab: Text on the rate-axis. Defaults to the name of the
          rate-table.

    type: How should the curves be plotted. Defaults to '"l"'.

     lwd: Width of the lines. Defaults to 2.

     lty: Which type of lines should be used. Defaults to 1, a solid
          line.

  log.ax: Character with letters from '"apcyr"', indicating which axes
          should be logarithmic. '"y"' and '"r"' both refer to the rate
          scale. Defaults to '"y"'.

     las: see 'par'.

     ann: Should the curves be annotated?

   a.ann: Logical indicating whether age-curves should be annotated.

   p.ann: do. for period-curves.

   c.ann: do. for cohort-curves.

   xannx: The fraction that the x-axis is expanded when curves are
          annotated.

 cex.ann: Expansion factor for characters annotating curves.

  a.thin: Vector of integers indicating which of the age-classes should
          be labelled.

  p.thin: do. for the periods.

  c.thin: do. for the cohorts.

     col: Colours for the curves.

   a.col: Colours for the age-curves.

   p.col: do. for the period-curves.

   c.col: do. for the cohort-curves.

 p.lines: Should rates from the same period be connected?

 c.lines: Should rates from the same cohort be connected?

     ...: Additional arguments pssed on to 'matlines' when plotting the
          curves.

_D_e_t_a_i_l_s:

     Zero values of the rates are ignored. They are neiter in the plot
     nor in the calculation of the axis ranges.

_V_a_l_u_e:

     'NULL'. The function is used for its side-effect, the plot.

_A_u_t_h_o_r(_s):

     Bendix Carstensen, Steno Diabetes Center, <URL:
     http://www.pubhealth.ku.dk/~bxc/>

_S_e_e _A_l_s_o:

     'apc.frame'

_E_x_a_m_p_l_e_s:

     data( blcaIT )
     attach(blcaIT)

     # Table of rates:
     bl.rate <- tapply( D, list(age,period), sum ) /
                tapply( Y, list(age,period), sum )
     bl.rate

     # The four classical plots:
     par( mfrow=c(2,2) )
     rateplot( bl.rate*10^6 )

     # The labels on the vertical axis could be nicer:
     rateplot( bl.rate*10^6, at=10^(-1:3), labels=c(0.1,1,10,100,1000) ) 

     # More bells an whistles
     par( mfrow=c(1,3), mar=c(3,3,1,1), oma=c(0,3,0,0), mgp=c(3,1,0)/1.6 )
     rateplot( bl.rate*10^6, ylab="", ann=TRUE, which=c("AC","PA","CA"),
                           at=10^(-1:3), labels=c(0.1,1,10,100,1000),
                           col=topo.colors(11), cex.ann=1.2 ) 

