rateplot: Functions to plot rates from a table classified by age and calendar time (period)

Description

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.

Usage

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

Arguments

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 group

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

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.

Value

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

Details

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

Examples

Run this code

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 )