xtgraph() function

added July 22, 2010

Code File

The code for the xtgraph() function is contained in the file xtgraph.R. You can source the file directly into R by calling

      source("http://www.biostat.jhsph.edu/~pmurakam/xtgraph.R")
The code is licensed under the GNU General Public License version 3, or (at your option) any later version.

Manual page


Description:
STATA has an xtgraph function (via an xtgraph.ado file) that plots graphs showing averages 
of a single outcome measured at several points over time. Unfortunately these plots are not 
so easy to manipulate to a publication-ready format. This function implements an R version 
of STATA's xtgraph command, giving the user much more control over the final appearance of 
the plot. Currently this function does not have all the options of STATA's xtgraph implemented, 
but it is easily modifiable if you want to add any yourself. For example, this function presently 
allows only for plotting of means and confidence intervals (using the t-distribution), whereas in 
xtgraph in STATA one may opt to plot medians and IQRs, etc., instead.

Usage:
xtgraph(y,id,time,group,off=(max(time)-min(time))/100,leg=TRUE,
        where="topright",bar.lty=1,xlab,ylab,...)

Arguments:
y       - the variable to be plotted (like yvar in STATA's xtgraph)
id      - the cluster variable
time    - the time variable
group   - the grouping variable (like group in STATA's xtgraph)
off     - how much you want the bars to be offset from one another, to prevent overlapping
          (like offset in STATA's xtgraph)
leg     - TRUE or FALSE for whether or not you want the legend displayed
where   - argument to R's legend function telling it where you want the legend placed
          (i.e., "bottomright","bottom","bottomleft","left","topleft","top","topright",
          "right", or "center")
bar.lty - line type for the bars
xlab    - x-axis label
ylab    - y-axis label
...     - additional graphical parameters (see the help file for 'par')

Note:
Whereas in STATA longitudinal data is specified via the xtset command, rendering unnecessary 
the specification of the cluster and time variables thereafter, R does not use any similar 
convention, thus unlike with xtgraph in which the id and time variables need not be specified, 
in this R version of xtgraph, they do (via the id and time arguments).

Also, currently this function is set to use only grayscale for colors, a different shade for 
each level of the grouping variable. Unfortunately therefore, however, if there are many levels 
of the grouping variable, the different shades of gray become hard to distinguish. If you want 
real colors, you can modify the function code.

See also:
plotCI in the gplots package.

Example:
#no data is attached for now, so this will not produce a graph, but here is an example of what 
a call to this function could look like, if dat is a data frame in your work session with columns 
for the outcome 'y', id 'ID', time 'minutes', and grouping variable 'group':

xtgraph(y=dat$ACTH,id=dat$ID,time=dat$minutes,group=dat$group,las=1,
        ylab="outcome",xlab="minutes from start")