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

Title

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

Syntax

cmogram yvar xvar [if] [, options ]

options Description ------------------------------------------------------------------------- Main title(...) title of graph controls(varlist) control variables for graphing residuals cutpoint(#) point along x axis to split the graph cutright include border observations on the right side ci(#) plot means with confidence intervals of level # median plot medians rather than means count plot counts (frequencies) rather than means fraction plot fractions (proportions) rather than means lineat(#) draw one or more vertical lines at points along x axis scatter format as scatterplot rather than bar graph legend allow legend to display lfit include line of best fit lfitci include line of best fit, with confidence interval qfit include quadratic of best fit qfitci include quadratic of best fit, with confidence interval lowess include local linear smooth plot by(varname) graph subgroups according to varname bytitle(...) overall title for by() graphs byvalues(...) optional ordered list of categories for by() graphs noten note # observations at bottom of graph notepfx(...) prefix for note at bottom of graph notesfx(...) suffix for note at bottom of graph nonotes suppress all notes at bottom of graph histopts(options) control bin definition with histogram options graphopts(options) control graph output with graph options lfitopts(options) control line or quadratic of best fit options lowopts(options) control lowess plot options ciopts(options) control ci confidence intervals with ci options rcapopts(options) control ci output with rcap options saving(filename) save graph to file generate(prefix) save graph values in variables with given prefix; programmer's option -------------------------------------------------------------------------

Description

cmogram graphs the means, medians, frequencies, or proportions of yvar, conditional on xvar. By default, bins are defined along the x axis as they are by histogram. Alternatively, histogram options can be used to override the default bin definitions, as in histopts(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 scatter option allows for scatterplot-style output. For regression discontinuity and similar applications, cutpoint(#) can be used to split graphs at a particular x value. To plot conditional means or medians of residuals, controls(...) can be used; the plotted residuals will be after a regression of the form regress yvar controls.

by allows subgroups to be plotted separately.

Options

+------+ ----+ Main +-------------------------------------------------------------

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

controls(varlist) considers residuals of yvar rather than the values of yvar directly. A regression of the form regress yvar controls is executed, then means or medians of the residuals are plotted accordingly.

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

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

ci(#) plots means of yvar with confidence intervals of level #.

median plots medians of yvar rather than means.

count plots counts (frequencies) of yvar rather than means.

fraction plots fractions (proportions) of yvar rather than means.

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

scatter formats 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.

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

lfit plots a line of best fit on the graph. When the graph is split using cutpoint, separate lines of best fit are plotted on the left and right.

lfitci is the same as lfit, but with confidence intervals.

qfit is the same as lfit, but with a quadratic.

qfitci is the same as qfit, but with confidence intervals.

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

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

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

byvalues(...) specifies an ordered list of category values, when by is used. So, e.g., byvalues(1 0) will place the 1 graph before the 0 graph. By default, graphs appear in sorted order.

noten notes 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.

nonotes suppresses all notes at the bottom of the graph, even when using by.

histopts(options) controls the definition of bins with histogram options. When graphs are split by cutpoint, 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 # in graphopts#(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 using lfit. When using lfitci, specifies additional lfitci options. When using qfit, specifies additional qfit options. When using qfitci, specifies additional qfitci options. Specify the graph number as the # in lfitopts#(options) to specify options for only one of several graphs output.

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

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

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

saving(filename) exports the graph to filename and 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 form prefixx#, where # is the graph number starting from 0, are saved with the center x value for each bin. Variables of the form prefixy# are saved with the corresponding heights.

Saved results

cmogram saves the following in r():

Scalars:

r(bw#) bin width for graph #

By default, there is only one graph output by cmogram, so # is 0; when cutpoint is specified, there are two graphs, 0 and 1, corresponding to the left and right sides of the graph; when by is specified, there are additional graphs. To save more details for each graph, use the generate option.

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("median mpg.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(3000 3250 3500) controls(price)

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

Author

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

Also see

Online: help for histogram