help for nbercycles SSC distribution 30 January 2024

Generate graph command (and optionally graph) timeseries vs. NBER recession dating

nbercycles
[varname]
[if exp]
,
file(string)
[
replace
from(string)
to(string)
minval(#)
maxval(#)
gropt(string)
]

You must tsset your data before using nbercycles; see help 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.

nbercycles accesses a copy of the National Bureau of Economic Research (NBER)
record of economic cycles (see 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 nbercycles
package reproduces the data on the NBER web page, and adds quarterly dating
information.

nbercycles can operate in two modes. The simpler "automatic" mode involves providing a variable name and, optionally,
an [if exp] (usually employing the tin() function). You need
use no other options beyond the mandatory file option (and perhaps the
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).

In the "manual" mode, if the nbercycles command is given without
a variable name but with the (then-required) from(string) and to(string)
options, the program generates the 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
minval(#) and maxval(#) 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.

Options

[varname] may be given to specify the name of a variable to be graphed,
superimposed on the recession dating. You may use [if exp] to restrict
the range of dates plotted.

file(string) is a required option: the name
of a file to be created in the current working directory. If the file
already exists, the replace option must also be given.

from(string) and to(string) are
specified in terms of calendar dates: e.g. from(1977m1) to(1999m8). They
are only used in the second (manual) form of the command, in which they are required
options.

minval(#) and maxval(#) 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.

gropt(string) can be used to pass graph options, such
as scheme(), to the graphics commands.

Examples

Note: the examples below with freduse require that the command be installed:

. ssc install freduse, replace

. freduse MPRIME, clear

. gen ym = mofd(daten)

. tsset ym, monthly

. nbercycles MPRIME if tin(1970m1,1990m1), file(nber2.do) replace

. type nber2.do

. freduse GDPC1, clear

. gen yq = qofd(daten)

. tsset yq,quarterly

. nbercycles GDPC1 if tin(1980q1,), file(nber3.do) gropt(scheme(plotplainblind)) replace

. type nber3.do

. nbercycles, file(nber1.do) replace from(1979m9) to(1999m12) min(2) max(21)

. type nber1.do

. use http://fmwww.bc.edu/ec-p/data/FFRperUSD, clear

. nbercycles FFRperUSD, file(nber4.do) replace

. type nber4.do

Author

Christopher F. Baum, Boston College, USA

baum@bc.edu

Acknowledgements

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.

Also see

On-line: freduse (if installed), tsset