{smcl} {* *! version 3.0.0 Apr2013}{...} {hline} help for {hi:lgraph} -- Tool for drawing line graphs (and more) (Requires Version 9) {right:(Version 3.0.0)} {hline} {marker syntax}{...} {title:Syntax} {p 8 14 2} {cmd:lgraph} {it:varlist} {ifin} {weight} [{cmd:,} {opt s:tatistic(stat)} {opt err:ortype(errortype)}{break} {cmd:fit}({cmd:lfit}|{cmd:qfit}|{cmd:fpfit} [, {opt now:eight}]) {cmdab:colorg:radient}({cmd:on}|{cmd:by}|{help colorstyle} [{it:start_num end_num}]) {opt sep:arate(#)} {opt by(groupvar2)}{break} {opt lop:tions(line_options)} {opt eop:tions(errorbar_options)} {opt fop:tions(fit_options)} {opt leop:tions(omnibus_options)}{break} {opt bw} {opt nom:arker} {opt nol:egend} {opt wide} {opt swap} {opt plot:orderoptions} {help twoway_options}{break} {opt nopreserve} {opt also:collapse(clist)} {opt addplot(plot)} ] {phang2} where {it:varlist} can be either {phang3} Syntax 1: {it:yvar} {it:xvar} [{it:groupvar1}] {phang3} or {phang3} Syntax 2: {it:yvar1} {it:yvar2} [...] {it:xvar} {phang2} For Syntax 2, the option {cmd:wide} must be specified. {phang2} Weights supported are the same as those supported by {helpb collapse}. {marker description}{...} {title:Description} {p 4 4 2} {cmd:lgraph} is a tool for drawing line graphs with optional error bars optionally stratified by one or two variables. {cmd:lgraph} {helpb collapse}s {it:yvar} by {it:xvar} and optionally {it:groupvar1} and {it:groupvar2}. It then plots a {helpb twoway_connected} graph of {it:yvar} against {it:xvar}, stratified by {it:groupvar1} and {it:groupvar2} with optional error bars. The advantage of using {cmd:lgraph} is that the data is automatically {helpb preserve}d. Moreover, {cmd:lgraph} automatically takes care of the coloring of the lines and the error bars, and produces meaningful legends. It is most useful for graphical exploration of longitudinal and/or multilevel data. {p 4 4 2} Although the syntax of {cmd:lgraph} has changed since 2.0.0, the old syntax will continue to work. {marker options}{...} {title:Options} {p 4 8 2}{opt statistic(stat)} specifies the summary statistic which we plot. It can be any of the {it:stat} in {helpb collapse}. The default summary statistic is {it:mean}. {p 4 8 2}{opt errortype(errortype)} specifies the type of error bar to be plotted. {p_end} {synoptset 23 tabbed} {synopthdr:errortype} {synoptline} {synopt:{opt ci(#)}}{it:#}% Confidence Interval{p_end} {synopt:{opt q:uantile(# #)}}Quantiles. e.g. {cmd:quantile(25 75)}{p_end} {synopt:{opt minmax}}Minimum and maximum{p_end} {synopt:{opt sd}}Standard Deviation{p_end} {synopt:{opt iqr}}Inter-quartile Range{p_end} {synopt:{opt se:mean} [{opt ci(#)}]}Standard error of the mean. If {opt ci(#)} is specified, then it is the {it:#}% confidence interval{p_end} {synopt:{opt seb:inomial} [{opt ci(#)}]}Standard error of the mean, binomial. If {opt ci(#)} is specified, then it is the {it:#}% confidence interval based on the Binomial standard error {p_end} {synopt:{opt sep:oisson} [{opt ci(#)}]}Standard error of the mean, Poisson. If {opt ci(#)} is specified, then it is the {it:#}% confidence interval based on the Poisson standard error {p_end} {synopt:{opt c:ollapse}({it:var1} {it:var2})}User-defined error bars. Generally, {it:var1} and {it:var2} should not differ between levels of {it:groupvar1} and {it:groupvar2}, because it is {helpb collapse}d over using ({it:mean}) as the option. {it:var1} gives the lower bound and {it:var2} the upper bound of the error bars.{p_end} {synoptline} {p2colreset}{...} {p 4 8 2}{cmd:fit}({cmd:lfit}|{cmd:qfit}|{cmd:fpfit} [, {opt now:eight}]) specifies that a linear/quadratic/fractional polynomial fit should be plotted instead of a line graph. See {helpb twoway_lfit}, {helpb twoway_qfit}, {helpb twoway_fpfit} for details. By default, if {cmd:mean} (the default) is specified as the summary statistic, the fit of the lines is weighted by the number of observations that go into each plotted mean, corresponding to using the {it: aweight} option in {helpb regress}. Use the {opt now:eight} option to override this. {p 4 8 2}{cmdab:colorg:radient}({cmd:on}|{cmd:by}|{help colorstyle} [{it:start_num end_num}]) By default each level in {it:groupvar1} will have a different color line. The color given to each line follows the loop implied by the particular {help scheme}, e.g.: navy, maroon, forest_green, dkorange, etc. Specifying {cmdab:colorg:radient}({cmd:on}|{cmd:by}|{help colorstyle} [{it:start_num end_num}]) causes the color scheme to follow a gradient, e.g. navy*0.1, navy*0.2, ..., navy*1. This is particularly useful if {it:groupvar1} has an ordinal scale. Specifying {cmdab:colorg:radient}({cmd:on}) plots the gradient in the default color. Otherwise, the color can be specified by typing {cmdab:colorg:radient}({help colorstyle}). {cmdab:colorg:radient}({cmd:by}) is useful when combined with {opt by(groupvar2)}. It causes a different color gradient to be used for each different level of {it:groupvar2}. This is useful if the lines are, e.g., stratified by {it:groupvar1}=age and {it:groupvar2}=sex. Specifying {it:startnum} and {it:endnum} gives the starting and ending multiplying factor for the color gradient. For example, specifying {cmd:colorgradient(blue 0.3 1.2)} when {it:groupvar1} has 4 levels will cause the colors for the four levels to be blue*0.3, blue*0.6, blue*0.9, blue*1.2, respectively. The default {it:startnum} and {it:endnum} are 0.1 and 1. {p 4 8 2}{opt sep:arate(#)} causes the points that are plotted to be slightly shifted so that the error bars do not overlap. {it:#} will usually be in the range of 0.001 to 0.05. By default, points are not shifted. {p 4 8 2}{opt by(groupvar2)} specifies a second-level group variable. When {opt by(groupvar2)} is specified, the color scheme of {cmd:lgraph} now loops over {it:groupvar2} instead of {it:groupvar1}, although lines are still drawn for each {it:groupvar1}, albeit using the same color. {p 4 8 2}{opt lop:tions(line_options)} passes extra options to {helpb twoway_connected}. {cmd:lgraph} works by generating a {helpb twoway} command with multiple {helpb twoway_connected} plots. The syntax for {it:line_options} is: {phang3} [{help numlist}] {it:twoway_connected_options} [; [{help numlist}] {it:twoway_connected_options} ... ] {pin} {help numlist}, if specified, indicates which lines the {it:twoway_connected_options} apply to. {help numlist} would be the levels of {it:groupvar1}, or if {opt by(groupvar2)} is specified, {it:groupvar2}. (However, see {opt plot:orderoptions} below.) If {help numlist} is not specified, then the options apply to all levels. Options given to different lines should be separated by a {cmd:;}. For example, {cmd: loptions(lpat(dot) ; 1/3 color(green))} causes all lines to be dotted and the line whose {it:groupvar1} == 1 or 2 or 3 to be plotted in green. {p 4 8 2}{opt eop:tions(errorbar_options)} is the same as {opt lop:tions(line_options)} except that options are passed to {helpb twoway_rcap} for the drawing of the error bars. {p 4 8 2}{opt fop:tions(fit_options)} is the same as {opt lop:tions(line_options)} except that options are passed to {helpb twoway_lfit} | {helpb twoway_qfit} | {helpb twoway_fpfit} for the drawing of the fitted lines. Use this option to control, e.g., the fitting of the fractional polynomial curve. {p 4 8 2}{opt leop:tions(omnibus_options)} applies the {it:omnibus_options} to all of {opt lop:tions(line_options)}, {opt eop:tions(errorbar_options)}, and {opt fop:tions(fit_options)}. {p 4 8 2}{opt bw} draws the graph in black and white instead of color. (It applies {cmd:scheme(s2mono)}.) {p 4 8 2}{opt nom:arker} suppresses the drawing of markers. {p 4 8 2}{opt nol:egend} suppresses the legend. {p 4 8 2}{opt wide} specifies that {help lgraph##syntax:Syntax} 2 be used when parsing {varlist}. {cmd:lgraph} was written to work with data in the {cmd:long} format. This means that different lines on the graph, rather than representing different dependent variables, represent the plotting of {it:yvar} against {it:xvar} for different levels of {it:groupvar1}. However, it may sometimes be useful to plot {it:xvar} against different dependent variables. The {opt wide} option enables this. {p 4 8 2}{opt swap} specifies that {it:groupvar1} and {it:groupvar2} be swapped. It is useful mainly when using {opt wide}. {p 4 8 2}{opt plot:orderoptions} By default the {help numlist}s to be used with {opt lop:tions}, {opt eop:tions}, {opt fop:tions}, and {opt leop:tions} refer to the levels of {it:groupvar1} or {it:groupvar2}. Specifying {opt plot:orderoptions} causes the {help numlist}s to refer instead to the order by which the lines are plotted. This is especially useful when the {opt by(groupvar2)} option is used, since it is not otherwise possible to specifying options for levels of {it:groupvar1} and {it:groupvar2} jointly. {p 4 8 2}{help twoway_options} Most options available to {helpb twoway} can be used. {hline} {p 8 8 2}{it:(Advanced options)} {p 4 8 2}{opt nopreserve} requests that {cmd:lgraph} does not {helpb preserve} the data first before {helpb collapse}-ing and drawing the graph. This is useful if one desires to draw a graph that is more complicated than is possible with {cmd:lgraph}. {cmd:lgraph} saves the command that is used to generate the graph in {cmd:r(command)} and {cmd:r(options)}. Therefore, one can use {cmd:lgraph, nopreserve} to generate {cmd:r(command)} and {cmd:r(options)}, edits the data or {cmd:`r(command)'} or {cmd:`r(options)'}, before drawing the graph by calling {cmd:twoway `r(command)', `r(options)'}. {p 4 8 2}{opt also:collapse(clist)} requests {cmd:lgraph} to perform additional {helpb collapse} tasks. It is only useful when combined with the {opt nopreserve} or the {opt addplot(plot)} option, to facilitate manipulation of the {helpb collapse}d data in plotting the graph. The syntax for {it:clist} is given in {helpb collapse}. Care should be taken so that names such as {cmd:statistic}, {cmd:scaleparam}, {cmd:count}, {cmd:lbound} and {cmd:ubound} are not given, as these may conflict with names generated by {cmd:lgraph}. {p 4 8 2}{opt addplot(plot)} This allows additional {helpb twoway} plots to be plotted. See {help addplot_option}. Note that because {cmd:lgraph} {helpb collapse}s the data before plotting in {helpb twoway}, plots given in {opt addplot(plot)} should also refer to the {helpb collapse}d data. Specify in {opt also:collapse(clist)} any additional data that need to be {helpb collapse}d. {hline} {marker examples}{...} {title:Examples} {p 4 8 2}Simple line graph with error bars plotting the mean price against 1978 repair record, stratified by origin {p 8 8 2}{stata sysuse auto, clear}{break} {stata lgraph price rep78 foreign, errortype(sd) separate(0.01) } {p 4 8 2}Plotting unemployment rates by states (using the {opt wide} option) {p 8 8 2}{stata "use http://www.stata-press.com/data/r9/urates.dta, clear"}{break} {stata lgraph tenn missouri kentucky indiana illinois arkansas t, wide nom} {p 4 8 2}Comparing college and non-college graduates on work experience gained (using the {opt by(groupvar2)} option) {p 8 8 2}{stata "use http://www.stata-press.com/data/r9/nlswork.dta, clear"}{break} {stata lgraph ttl_exp age idcode if idcode < 100, by(collgrad)} {p 4 8 2}Examining relationship between weight and height {p 8 8 2}{stata "use http://www.stata-press.com/data/r9/nhanes2f.dta, clear"}{break} {stata lgraph weight height agegrp, fit(lfit) lopt(msize(tiny))} // Fitting a straight line {break} {stata lgraph weight height agegrp, fit(lfit) lopt(msize(tiny)) colorg(on)} // Using a color gradient {p 4 8 2}Examining mortality rate (with user-given error bars) {p 8 8 2}{stata "use http://www.stata-press.com/data/r9/mortality.dta, clear"}{break} {stata gen mortality = deaths / population}{break} {stata gen se = sqrt(deaths) / population}{break} {stata gen lb = mortality - invnormal(0.975) * se}{break} {stata gen ub = mortality + invnormal(0.975) * se}{break} {stata encode nation, gen(nation2)}{break} {stata lgraph mortality age_category nation2, err(collapse(lb ub)) nom ytitle(Mortality rate) xlabel(1 2 3,valuel)} {marker saved_results}{...} {title:Saved results} {p 4 8 2}{cmd:twoway `r(command)', `r(options)'} gives the entire command used to generate the graph. {p 4 8 2}{cmd:r(command)} gives the {it:plot} part of the command. {p 4 8 2}{cmd:r(options)} gives the {help twoway_options} part of the command. {title:Also see} {p 4 8 2}{helpb xtline}, {net "describe xtgraph, from(http://fmwww.bc.edu/RePEc/bocode/x)":xtgraph} {title:Author} {p 4 4 2}Timothy Mak{break} School of Public Health, University of Hong Kong{break} tshmak@hku.hk{break} April 2013