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^(#) > ^boxcox^(#) ^savedat^(filename) v7 ^nograph^ ^list^ ^missing^ ^listwise^ ^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^), an > d median (^median^).
Both "new" (version 8 and higher) and "old" (version 7 ands lower) graph types are available. Graphs are produced in Version 8 format, unless option ^V7^ is chosen. General appearance of version 7 graphs is currently given by ^oldgprefs^. However, verison 7 graphics may not be available in future versions of Stata.
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.
Box-cox, 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.
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 transforma > tion. 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. ^s > e^ 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 an > y 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)^ i > s specified. It is equivalent to ^bar(rr)^ ^level(50)^.
^level(^#^)^ specifies the confidence level, in percent, used in calculating th > e 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 om > itted 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 o > f 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 g > roup. Otherwise such observations are dropped.
^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 ^powe > r^, ^boxcox^ or ^log^ can be specified. Where data are not Normal, the command @lnskew0@ will suggest suitable values for k.
^power(^#^)^ specifies a power transformation to be carried out before averages > and error bars are calculated. These values are back-transformed to the origin > al 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 speci > fied. Where data are not Normal, the @ladder@ command or Box-Cox procedure (@bcskew0@ > , @boxcox@) will suggest suitable power transformations.
^boxcox(^#^)^ is in most circumstances a synonym for ^power^. The Box-Cox transformation is a variant on a simple power transformation: ^y - > (y^^p - 1) / p^ , instead of ^y - > y^^p^ The difference is only apparent in ^xtgraph^ when using the ^model^ option, or (possibly) when the power is very close to zero, and there are rounding problems.
^model^ instructs ^xtgraph^ to use the most recent regression model to estimate > the average, (using @predict@), the standard deviation (^predict, stdf^) or the standard error (^predict, stdp^). Confidence intervals and reference ranges ar > e worked out in the usual way. This option works with most of Stata's many regression commands for continuous data. It can be used, for instance, to produce graphs with pooled or robust standard errors, or adjustment for censored data. If the outcome has been transformed before fitting the model, the appropriate transfomation option (^log^, ^power^, or ^boxcox^) must be used > . This is the only ocasion where the distinction between ^power^ and ^boxcox^ is > important. All values are taken from the last fitted model, except for the frequency count used in working out confidence intervals. Models involving logit or probit transformations (@logistic@, @xtprobit@ etc.) are not supported > .
^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 @grot > her@.
^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.
Control of version 8+ graphics is available through the options ^lineopts^ , ^ > bartype^, and ^baropts^. Any graphics options contained in ^lineopts()^ is used as an op > tion or set of options for the ^line^ portion of the graph drawing. See @graph twowa > y line@). Similarly, graphics options for the bars are given by ^baropts^. See @ > graph twoway bar@.
^bartype()^ sets the type of bar used. The default is ^rcap^. Other possibilit > ies include: ^rarea^, ^rbar^, ^rcapsym^, ^rconnected^. See @twoway rcap@, @twoway rarea@, @twoway rba > r@, @twoway rcapsym@, @twoway ronnected@.
Control of plotting symbol & line type are available for version 7 graphs only. Use options ^symbol()^ to control the plotting symbols, and ^connect()^ for the > line type.
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) ^
Using xtgraph with Stata version 8 graphics -------------------------------------------
. ^preserve^ . ^tempfile myfile^ . ^xtgraph c, group(group) bar(se) nograph savedat("`myfile'")^ . ^use "`myfile'", clear^ . ^reshape wide n mean lb ub , j(group) i(week)^
. ^* Carry out any desired version 8 graphics commands. ^ . ^* Note that -offset- is not available in Version 8.^
. ^restore^
Also see --------
Manual: [R] xt On-line: help for @xt@, @graph@, @ladder@, @bcskew0@, @boxcox@, @label@, @predi > ct@.