{smcl} {* 26jul2006}{...} {hline} help for {hi:nbercycles} SSC distribution 30 January 2024 {hline} {title:Generate graph command (and optionally graph) timeseries vs. NBER recession dating} {p 8 17}{cmd:nbercycles} [{it:varname}] [{cmd:if} {it:exp}] {cmd:,} {cmdab:file(}{it:string}{cmd:)} [ {cmdab:replace} {cmdab:from(}{it:string}{cmd:)} {cmdab:to(}{it:string}{cmd:)} {cmdab:min:val(}{it:#}{cmd:)} {cmdab:max:val(}{it:#}{cmd:)} {cmdab:gropt(}{it:string}{cmd:)} ] {p 4 4}You must {cmd:tsset} your data before using {cmd:nbercycles}; see help {cmd:tsset}. This command requires that you are using a monthly or quarterly time-series calendar, and that the variable defining the calendar have a time-series format.{p_end} {* {p 4 4}{cmd:varlist} may contain time-series operators; see help {cmd:varlist}. {p_end} *} {p 4 4}{cmd:nbercycles} accesses a copy of the National Bureau of Economic Research (NBER) record of economic cycles (see {browse "http://www.nber.org/cycles/cyclesmain.html":http://www.nber.org/cycles/cyclesmain.html}), the official dating of U.S. business cycle phases: contractions (recessions) and expansions, defined by their peaks and troughs, from 1854-2024. The ancillary Stata database distributed in the {cmd:nbercycles} package reproduces the data on the NBER web page, and adds quarterly dating information. {p_end} {p 4 4}{cmd:nbercycles} can operate in two modes. The simpler "automatic" mode involves providing a variable name and, optionally, an [{cmd:if} {it:exp}] (usually employing the {cmd:tin()} function). You need use no other options beyond the mandatory {cmd:file} option (and perhaps the {cmd:replace} option for convenience). The program writes an entire graph command to the specified file, but it also produces the graph. You may save the graph as displayed. If you wish to further customize the graph, you may edit the file (e.g. using the Do-File Editor). {p_end} {p 4 4} In the "manual" mode, if the {cmd:nbercycles} command is given without a variable name but with the (then-required) {cmdab:from(}{it:string}{cmd:)} and {cmdab:to(}{it:string}{cmd:)} options, the program generates the {cmd:graph twoway} commands required to overlay a time-series plot with shaded recession bands. Those commands are written to the filename specified. They do not include the specification of the variable that you want to graph, nor any graph options. You should also use the {cmdab:min:val(}{it:#}{cmd:)} and {cmdab:max:val(}{it:#}{cmd:)} options to specify the lower and upper bounds of the variable that you would like to graph, rounded outward: e.g. if the variable has a range of 2.5-9.3, use minimum and maximum values of 2 and 10. This mode of the program might be particularly useful if you want to graph more than one time-series, or want to use different scaled y-axes for multiple series. {p_end} {title:Options} {p 4 8}[{it:varname}] may be given to specify the name of a variable to be graphed, superimposed on the recession dating. You may use [{cmd:if} {it:exp}] to restrict the range of dates plotted. {p_end} {p 4 8}{cmdab:file(}{it:string}{cmd:)} is a required option: the name of a file to be created in the current working directory. If the file already exists, the {cmdab:replace} option must also be given. {p_end} {p 4 8}{cmdab:from(}{it:string}{cmd:)} and {cmdab:to(}{it:string}{cmd:)} are specified in terms of calendar dates: e.g. {cmd:from(1977m1) to(1999m8)}. They are only used in the second (manual) form of the command, in which they are required options. {p_end} {p 4 8}{cmdab:min:val(}{it:#}{cmd:)} and {cmdab:max:val(}{it:#}{cmd:)} are used to specify the range of the Y-axis on the graph. They are only used in the second (manual) form of the command. {p_end} {p 4 8}{cmdab:gropt(}{it:string}{cmd:)} can be used to pass graph options, such as scheme(), to the graphics commands. {p_end} {title:Examples} Note: the examples below with {cmd:freduse} require that the command be installed: {p 4 8}{stata "ssc install freduse, replace" :. ssc install freduse, replace}{p_end} {p 4 8}{stata "freduse MPRIME, clear" :. freduse MPRIME, clear}{p_end} {p 4 8}{stata "gen ym = mofd(daten)" :. gen ym = mofd(daten)}{p_end} {p 4 8}{stata "tsset ym, monthly" :. tsset ym, monthly}{p_end} {p 4 8}{stata "nbercycles MPRIME if tin(1970m1,1990m1), file(nber2.do) replace" :. nbercycles MPRIME if tin(1970m1,1990m1), file(nber2.do) replace}{p_end} {p 4 8}{stata "type nber2.do" :. type nber2.do}{p_end} {p 4 8}{stata "freduse GDPC1, clear" :. freduse GDPC1, clear}{p_end} {p 4 8}{stata "gen yq = qofd(daten)" :. gen yq = qofd(daten)}{p_end} {p 4 8}{stata "tsset yq, quarterly" :. tsset yq,quarterly}{p_end} {p 4 8}{stata "nbercycles GDPC1 if tin(1980q1,), file(nber3.do) gropt(scheme(plotplainblind)) replace" :. nbercycles GDPC1 if tin(1980q1,), file(nber3.do) gropt(scheme(plotplainblind)) replace}{p_end} {p 4 8}{stata "type nber3.do" :. type nber3.do}{p_end} {p 4 8}{stata "nbercycles, file(nber1.do) replace from(1979m9) to(1999m12) min(2) max(21) " :. nbercycles, file(nber1.do) replace from(1979m9) to(1999m12) min(2) max(21) }{p_end} {p 4 8}{stata "type nber1.do" :. type nber1.do}{p_end} {p 4 8}{stata "use http://fmwww.bc.edu/ec-p/data/FFRperUSD, clear" :. use http://fmwww.bc.edu/ec-p/data/FFRperUSD, clear}{p_end} {p 4 8}{stata "nbercycles FFRperUSD, file(nber4.do) replace" :. nbercycles FFRperUSD, file(nber4.do) replace}{p_end} {p 4 8}{stata "type nber4.do" :. type nber4.do}{p_end} {title:Author} {p 4 4}Christopher F. Baum, Boston College, USA{break} baum@bc.edu {title:Acknowledgements} {p 4 4}This program was inspired by David Drukker's presentation at the NASUG'2006 meetings in Boston, July 2006. I thank David for his suggestions about the routine. {p_end} {title:Also see} {p 4 13}On-line: {help freduse} (if installed), {help tsset} {p_end}