.-
help for ^xtgraph^
.-

Graphs of cross-sectional time series (xt) data
-----------------------------------------------

     ^xtgraph^ yvar [^if^ exp ][^in^ exp ] , 
     [^av^erage(avname) ^bar^(barname) ^model^ ^level^(significance
     level) ^h^alf ^gr^oup(var) ^off^set(#) ^min^obs(#) ^pow^er(#)
     ^log^(#) ^list^ ^savedat^(filename) ^nograph^ ^listwise^ ^missing^
     ^i^(varname) ^t^(varname) graph_options]

Description
-----------

^xtgraph^ produces graphs showing averages of a single outcome
measured at several points over time.  Data must be in xt format (see
@xt@).  Points are connected by straight lines. Separate lines can be
produced for groups defined by any categorical variable (string or
numeric).  Averages that can be plotted include arithmetic mean
(^mean^), geometric (^gm^) or harmonic means (^hm^), and median
(^median^).

Error bars can be drawn, showing confidence intervals (^ci^), standard
errors (^se^), standard deviations (^sd^) or reference ranges (^rr^).
For medians, the inter-quartile range (^iqr^) and reference ranges
(^rr^) are available.  If there are two groups, the ^half^ option
allows for half-error bars, from the average to the upper limit or
from the average to the lower limit. Otherwise, multiple error bars
can be separated horizontally using the ^offset^ option.

Power and three-parameter log transformations are also available.
Transformations are carried out before averages and limits of error
bars are calculated.  These values are back-transformed to the
original scale before plotting.

Reference ranges are based on the Normal distribution, confidence intervals 
use the t-distribution.  Medians and quantiles are calculated using the @centile@ command.
Calculations are carried out separately for each group and time point.

                     (PT Seed - paul.seed@@kcl.ac.uk)

Options
-------

^average(^avname^)^ specifies the average to be calculated.

	^average(mean)^ is the default.  Simple arithmetic means are calculated.

	^average(gm)^ gives for geometric means, based on a log transformation.  
	It is a synonym for ^power(0)^

	^average(hm)^ gives for harmonic means, based on the inverse transformation.  
	It is a synonym for ^power(-1)^

	^average(median)^ gives medians.  


^group(^groupvar^)^ specifies the groups to be compared.  Separate averages and 
limits of error bars are calculated for each group at each time.  For clarity, ^groupvar^ 
should usually have no more than four or five values.  If ^groupvar^ is not 
specified, all observations at any one time are combined.

Groups are distinguished by different plotting symbols and colours. 
No points are plotted if ^groupvar^ is missing.  Lines are labelled 
according to the values if ^groupvar^ is a string.  Value labels are used if 
^groupvar^ is numberic. See @label@ for details of how to set up value labels.
details of how to set up value labels for .

^bar(^barname^)^ determines how the limits of the error bars are calculated. ^se^ 
and ^sd^ are only available with ^average(mean)^; ^iqr^ is available only with 
^average(median)^.

	^bar(ci)^ is the default.  Standard errors and confidence intervals are 
	calculated separately for every time point, using the t-distribution. 
	The confidence level is set by the ^level^ option.  Otherwise, Stata's 
	global macro $S_level, is used. It assumed that the transformed data is 
	Normal, unless ^average(median)^ is specified.  Confidence intervals 
	for medians are calculated using the @centile@ command.  

	^bar(se)^ gives bars stretching to 1 standard errors of the mean after transformation
	(means only).  They correspond roughly to 68% confidence intervals for large samples,
	narrower for small numbers.

	^bar(rr)^ gives reference ranges  within which a certain proportion 
	(set by the ^level^ option) of the values can be expected to fall.
	It is assumed that the transformed data is Normal, unless ^average(median)^ 
	is specified. ^bar(rr)^ ^level(68.3)^ is equivalent to ^bar(sd)^. 

	^bar(sd)^ gives bars stretching to 1 standard deviation above and below 
	the mean (means only).  For data that are normally distributed after any 
	transformation, 68.3% (roughly two thirds) of observed values will lie 
	within these intervals.  

	^bar(iqr)^ gives the upper and lower quartiles when ^average(median)^ is specified.
	It is equivalent to ^bar(rr)^ ^level(50)^.

^level(^#^)^ specifies the confidence level, in percent, used in calculating the 
confidence interval or the reference range.   A slight modification to the 
command @centile@  allows non-integer values (for example 99.9%) for medians.
It defaults to 95% or the value set by ^set level^; see help for @level@.

^half^ allows for half-error bars, where there are exactly two groups.
At each time point, the bars run either from the larger average to the upper 
limit or from the smaller average to the lower limit.  With option ^mean^
and no transformation, the bars are symmetric, so one half of the bar can be omitted
without loss of information.  With more than 2 groups, ^offset^ may be used.

^offset(^#^)^ changes the plotted time values by a fixed amount for each group.
Overlapping points are separated, and the error bars are disentangled.
Provided a suitable small value of ^offset^ is chosen, there is no distortion of the 
impression given by the graph. A value less than 1/10 of the difference between time
points is recommended.  With 2 groups, ^half^ may also be used.

^minobs^, ^listwise^ and ^missing^ are options for handling missing data.
If none are specified, all available data are used.

^minobs(^#^)^ specifies the minimum number of observations needed for a 
value to be included in the calculation of plotted values.  If (for any 
group), there are not enough observations at a given time, that time point 
is dropped.  Other groups are not affected.  If ^minobs^ is not specified, 
the graph can be dominated by the very wide confidence intervals or 
standard errors that occur where data are sparse.

^listwise^ specifies that all panels with missing data are to be dropped.  

^missing^ requires observations with the ^group^ variable missing as an extra group.  
Otherwise such observations are dropped.

^power(^#^)^ specifies a power transformation to be carried out before averages 
and error bars are calculated.  These values are back-transformed to the original 
scale before plotting.  ^power(1)^ (no transformation) is the default value. 
^power(0)^ is equivalent to a log transformation, leading to geometric means. 
^power(-1)^ leads to harmonic means.  Only one of ^power^ or ^log^ can be specified.
Where data are not Normal, the @ladder@ command or Box-Cox procedure (@bcskew0@, @boxcox@) 
will suggest suitable power transformations.

^log(^#^)^ specifies a 3 parameter log transformation with the general form
y = log(x-k) to be carried out before averages and error bars are calculated.  
These values are back-transformed to the original scale before plotting.  
If ^log^ is not specified, no transformation is carried out.  Only one of ^power^ 
or ^log^ can be specified.  Where data are not Normal, the command @lnskew0@ 
will suggest suitable values for k.

^list^ displays a list of the plotted means and limits by group and time in the output.

^savedat(^filename[^, replace^]^)^ saves the data shown in the graph as a Stata data set.  
Intelligent decisions are made about naming the new variables.  
Note: to save the graph, the graphics option ^saving^ should be used. See @grother@.

^nograph^ suppresses the production of the graph, which may be unnecessary if ^list^ or ^savedat^ 
are used. If ^saving^ is set, ^nograph^ is ignored.

xt options: The variables representing ^i^ and ^t^ can be set using options ^i(^ivar^)^ 
and  ^t(^tvar^)^ or with the commands ^iis^, ^tis^.  See @xt@, @iis@, @tis@ for more information.

Standard graph options are available. See @graph@.  


Examples
--------

	. ^iis pno ^
	. ^tis week^
	. ^xtgraph c ^

	. ^xtgraph c , minobs(10) group(group) offset(.2) ^
	. ^xtgraph c if week>=20

	. label define group 0 Placebo 1 vitamin
	. label values group group 
	. ^drop if week == 16^
	. ^xtgraph c , xlab(20,24,28,32,36,40) ylab group(group) bar(se) offset(.2) ^

	. ^replace group = 2 if control == 1^
	. ^label define group 2 Control, modify^
	. ^xtgraph c , xlab(20,24,28,32,36,40) ylab group(group) bar(se) offset(.2) ^


	. ^xtgraph c , group(group) offset(.2) list ^


	. ^xtgraph c , av(median) ^

	. ^xtgraph c , av(median) bar(rr) ^


Also see
--------

 Manual: [R] xt
On-line: help for @xt@, @iis@, @tis@, @graph@, @ladder@, @bcskew0@, @boxcox@, @label@.