{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
