help cmogram-------------------------------------------------------------------------------

Title

cmogram-- Draw histogram-style conditional mean or median graph

Syntax

cmogramyvarxvar[if] [,options]

optionsDescription ------------------------------------------------------------------------- Maintitle(...)title of graphcontrols(varlist)control variables for graphing residualscutpoint(#)point alongxaxis to split the graphcutrightinclude border observations on the right sideci(#)plot means with confidence intervals of level#medianplot medians rather than meanscountplot counts (frequencies) rather than meansfractionplot fractions (proportions) rather than meanslineat(#)draw one or more vertical lines at points alongxaxisscatterformat as scatterplot rather than bar graphlegendallow legend to displaylfitinclude line of best fitlfitciinclude line of best fit, with confidence intervalqfitinclude quadratic of best fitqfitciinclude quadratic of best fit, with confidence intervallowessinclude local linear smooth plotby(varname)graph subgroups according tovarnamebytitle(...)overall title forby()graphsbyvalues(...)optional ordered list of categories forby()graphsnotennote # observations at bottom of graphnotepfx(...)prefix for note at bottom of graphnotesfx(...)suffix for note at bottom of graphnonotessuppress all notes at bottom of graphhistopts(options)control bin definition with histogram optionsgraphopts(options)control graph output with graph optionslfitopts(options)control line or quadratic of best fit optionslowopts(options)control lowess plot optionsciopts(options)controlciconfidence intervals with ci optionsrcapopts(options)controlcioutput with rcap optionssaving(filename)save graph to filegenerate(prefix)save graph values in variables with given prefix; programmer's option -------------------------------------------------------------------------

Description

cmogramgraphs the means, medians, frequencies, or proportions ofyvar, conditional onxvar. By default, bins are defined along thexaxis as they are by histogram. Alternatively, histogram options can be used to override the default bin definitions, as inhistopts(bin(10)). The exact bin definitions are always output along with the graph(s).While the default output style is similar to a histogram, the

scatteroption allows for scatterplot-style output. For regression discontinuity and similar applications,cutpoint(#)can be used to split graphs at a particularxvalue. To plot conditional means or medians of residuals,controls(...)can be used; the plotted residuals will be after a regression of the formregress yvar controls.

byallows subgroups to be plotted separately.

Options+------+ ----+ Main +-------------------------------------------------------------

title(...)adds a title to the top of the graph. Specify the graph number as the#intitle#(...)to specify a title for only one of several graphs output (e.g., usingby).

controls(varlist)considers residuals ofyvarrather than the values ofyvardirectly. A regression of the formregress yvar controlsis executed, then means or medians of the residuals are plotted accordingly.

cutpoint(#)splits the graph at the specified point along thexaxis. Bins are defined along thexaxis to the right and left of this cutoff, with no bin spanning the cutoff.

cutrightincludes border observations on the right side of a split graph. By default, border observations are included on the left.

ci(#)plots means ofyvarwith confidence intervals of level#.

medianplots medians ofyvarrather than means.

countplots counts (frequencies) ofyvarrather than means.

fractionplots fractions (proportions) ofyvarrather than means.

lineat(#)draws a vertical line at the specified point along thexaxis. To draw multiple lines, include multiple numbers separated by spaces.

scatterformats output as a scatterplot rather than a bar graph. In this case, each conditional median or mean is plotted as a dot rather than a bar.

legendallows display of the legend; by default it is suppressed. To more fully control display of the legend, include this option as well asgraphopts(legend(...)).

lfitplots a line of best fit on the graph. When the graph is split usingcutpoint, separate lines of best fit are plotted on the left and right.

lfitciis the same aslfit, but with confidence intervals.

qfitis the same aslfit, but with a quadratic.

qfitciis the same asqfit, but with confidence intervals.

lowessplots local linear smooth (lowess) plot on the graph. When the graph is split usingcutpoint, separate lowess plots are plotted on the left and right.

by(varname)graphs subgroups separately, according tovarname. Subgroups are identified in the note field below each graph.

bytitle(...)adds an overall title to a series of subgroup graphs, whenbyis used.

byvalues(...)specifies an ordered list of category values, whenbyis used. So, e.g.,byvalues(1 0)will place the1graph before the0graph. By default, graphs appear in sorted order.

notennotes the number of observations at the bottom of the graph.

notepfx(...)adds a prefix to the note at the bottom of the graph. This will precede the number of observations and/or the subgroup, depending on other options.

notesfx(...)adds a suffix to the note at the bottom of the graph. This will follow the number of observations and/or the subgroup, depending on other options.

nonotessuppresses all notes at the bottom of the graph, even when usingby.

histopts(options)controls the definition of bins with histogram options. When graphs are split bycutpoint, these options govern bin definitions for each side of the graph. So, e.g.,histopts(bin(10))will define 10 bins to the left and 10 to the right.

graphopts(options)specifies additional graph options to govern graph output. These options can control any aspect of the look of the graph, including titles, labels, and styles. Specify the graph number as the#ingraphopts#(options)to specify options for only one of several graphs output.

lfitopts(options)specifies additional lfit options to govern output of the line-of-best-fit when usinglfit. When usinglfitci, specifies additional lfitci options. When usingqfit, specifies additional qfit options. When usingqfitci, specifies additional qfitci options. Specify the graph number as the#inlfitopts#(options)to specify options for only one of several graphs output.

lowopts(options)specifies additional lowess options to govern output of lowess plots when usinglowess. Specify the graph number as the#inlowopts#(options)to specify options for only one of several graphs output.

ciopts(options)specifies additional ci options to govern calculation of confidence intervals when usingci.

rcapopts(options)specifies additional rcap options to govern output of confidence intervals when usingci. Specify the graph number as the#inrcapopts#(options)to specify options for only one of several graphs output.

saving(filename)exports the graph tofilenameand closes the graph window. This option is ideal for automating the output of graphs with .do files.

generate(prefix)is a programmer's option to save graphing values, as in twoway__histogram_gen. Variables of the formprefixx#, where#is the graph number starting from 0, are saved with the centerxvalue for each bin. Variables of the formprefixy# are saved with the corresponding heights.

Saved results

cmogramsaves the following inr():Scalars:

r(bw#)bin width for graph#By default, there is only one graph output by

cmogram, so#is 0; whencutpointis specified, there are two graphs, 0 and 1, corresponding to the left and right sides of the graph; whenbyis specified, there are additional graphs. To save more details for each graph, use thegenerateoption.

Examples

. sysuse auto

. cmogram mpg weight

. cmogram mpg weight, median title("Median MPG by Weight")

. cmogram mpg weight, median title("Median MPG by Weight") saving("medianmpg.png")

. cmogram mpg weight, histopts(bin(10)) lfit scatter

. cmogram mpg weight, histopts(bin(10)) lfit graphopts(note("Source:..."))

. cmogram mpg weight, histopts(bin(5)) lfit cutpoint(3250) lineat(3250)

. cmogram mpg weight, histopts(bin(5)) lfit cutpoint(3250) lineat(30003250 3500) controls(price)

. cmogram mpg weight, histopts(bin(5)) by(foreign) bytitle("Mean MPG byType and Weight")

AuthorChristopher Robert, Harvard University, chris_robert@hksphd.harvard.edu

Also seeOnline: help for

histogram