Plots of US employment and unemployment

Org
Package
Testing

The code in this repository makes up a package usempl-plots that can create multiple customizable and dynamic plots of US employment and unemployment by downloading multiple vintages of current data or using data in memory. The content for this README.md file is out of date as the following content only deals with the usempl_npp.py module. This will be updated in the near future.

1. Normalized peak plot of US nonfarm employment over past recessions

The code in this part of the repository allows the user to create a normalized peak plot of U.S. nonfarm payroll employment (PAYEMS, seasonally adjusted) over the last 15 recessions, from the Great Depression (Aug. 1929 to Mar. 1933) to the most recent COVID-19 recession (Feb. 2020 to Apr. 2020). The dynamic version of this plot, which is updated regularly, is available to manipulate and explore at https://www.oselab.org/gallery/usempl_npp. The core maintainer of this repository is Richard Evans (@RickEcon).

A normalized peak plot takes the maximum level of U.S. payroll employment at the beginning of a recession (within two months of the NBER declared beginning month) and normalizes the entire series so that the value at that peak equals 1.0. As such, the normalized time series shows the percent change from that peak. This is an intuitive way to compare the progression of nonfarm employment across recessions. The following figure is a screen shot of the normalized peak plot of the PAYEMS series from data downloaded on January 15, 2025 (most recent employment data is December 2024).

The monthly PAYEMS data series begins in January 1939. The U.S. Bureau of Labor Statistics published an annual survey of U.S. nonfarm employment which provided an annual average nonfarm payroll employment (not seasonally adjusted) for the years 1919-1938. I set the date values for annual average data to July 1 of that year. These data are taken from Table 1 on page 1 of the Bureau of Labor Statistics' "Employment, Hours, and Earnings, United States, 1909-90, Volume I," Bulletin of the United States Bureau of Labor Statistics, No. 2370 (Mar. 1991). In order to have monthly data, I imputed the missing months as a cubic spline that connected the annual data from July 1919 to July 1938 to the first two months of 1939 (January and February 1939). These annual data are stored as a .csv file in this repository (usempl_npp/data/usempl_anual_1919-1938.csv). The imputation takes place in the usempl_npp_bokeh.py file, and the final PAYEMS monthly data series from 1919-07 to 2024-12 with the imputed months is usempl_npp/data/usempl_2024-12-01.csv.

This README.md is organized into the following three sections.

1. Running the code and generating the dynamic visualization
2. Functionality of the dynamic visualization
3. Contributing to this visualization code

1.1. Running the code and generating the dynamic visualization

The code for creating this visualization is written in the Python programming language. It requires the following file in the usempl_plots directory (package):

• usempl_npp_bokeh.py: a Python module that defines two functions in order to create the HTML and JavaScript for the dynamic visualization of the U.S. employment normalized peak plot of the last 15 recessions.
  • get_usempl_data() takes inputs for the date ranges to plot and whether to download the data directly from fred.stlouisfed.org or retrieve the data from a file saved previously on your local hard drive in the data directory of this repository. Then the function collects, cleans, and returns the PAYEMS data.
  • usempl_npp() creates the dynamic visualization of the normalized peak plot of the PAYEMS series over the last 15 recessions. This script calls the get_usempl_data() function. It then uses the Bokeh library to create a dynamic visualization using HTML and JavaScript to render the visualization in a web browser.

The most standard way to successfully run this code if you are using the Anaconda distribution of Python is to install and activate the usempl-plots-dev conda environment defined in the environment.yml file, then run the usempl_npp_bokeh.py module as a script with the defaults or import the usempl_npp_bokeh.py module and run the usempl_npp() function using the appropriate options. Use the following steps.

1. Either fork this repository then clone it to your local hard drive or clone it directly to your local hard drive from this repository.
2. Install the Anaconda distribution of Python to your local machine.
3. Update conda and anaconda by opening your terminal and typing conda update conda and following the instructions, then typing conda update anaconda and following the instructions.
4. From the terminal (or Conda command prompt), navigate to the directory to which you cloned this repository and run conda env create -f environment.yml. This will create the conda environment with all the necessary dependencies to run the script to create the dynamic visualization.
5. Activate the conda environment by typing in your terminal conda activate usempl-plots-dev.
6. Install the usempl-plots package in the usempl-plots-dev conda environment by typing pip install -e ..
7. Create the visualization in one of two ways.
   • Run the usempl_npp_bokeh.py module as a script with the default settings of the usempl_npp() function. This will produce the dynamic visualization in which the data are downloaded from the internet, the end date is either the month of the current day or the most recent month with PAYEMS data, and then the default months from peak.
   • Import the usempl_npp_bokeh.py module and execute the usempl_npp() function by typing something like the following:

   from usempl_plots import usempl_npp_bokeh as usempl_npp
   
   usempl_npp.usempl_npp(14, 2, 18, 4, '2020-06-22')
   

8. Executing the function usempl_npp() will result in three output objects: the dynamic visualization HTML file, the original time series of the PAYEMS series, and the organized dataset of each recession's variables time series for the periods specified in the function inputs.
   • usempl_plots/images/usempl_npp_[YYYY-mm-dd].html. This is the dynamic visualization. The code in the file is a combination of HTML and JavaScript. You can view this visualization by opening the file in a web browser window. A version of this visualization is updated regularly on the web at https://www.oselab.org/gallery/usempl_npp.
   • usempl_plots/data/usempl_[YYYY-mm-dd].csv. A comma separated values data file of the original time series of the PAYEMS series from 1919-01-01 to whatever end date is specified in the usempl_npp() function arguments, which end date is also the final 10 characters of the file name YYYY-mm-dd.
   • usempl_plots/data/usempl_pk_[YYYY-mm-dd].csv. Adjusted dataset of 15 different time series for their maximum months beginning to end, each containing the beginning of the recession (peak employment).

1.2. Functionality of the dynamic visualization

This dynamic visualization allows the user to customize some different views and manipulations of the data using the following functionalities. The default view of the visualization is shown above.

• Highlight or mute specific recession time series by clicking on the series label in the legend on the right side of the plot. The screen shot below shows a version of the plot in which all the recession time series have been muted except for the current COVID-19 recession and the Great Depression. Note that even when muted, the time series are still faintly visible.
• Hovertool display. If you select the hovertool button on the left side of the plot, which is the default for the plot, information about each point in each time series will be displayed when you hover your cursor over a given point in the plot area. The screen shot below shows a version of the plot in which the hovertool is selected and the information about the minimum point in the current recession is displayed.
• Pan different areas of the data. If you click on the pan button on the left side of the plot, you can use your cursor to click and drag on the data window and change your view of the data.
• Zoom in or out on the data. You can zoom in or zoom out on the data series in three different ways. You can use the box zoom functionality by clicking on its button on the left side of the plot and clicking and dragging a box on the area of the plot that you want to zoom in on. You can also zoom in by clicking on the zoom in button on the left side of the plot, then clicking on the area of the plot you want to center your zoom in around. Or you can zoom out by clicking on the zoom out button on the left side of the plot, then clicking on the area of the plot you want to center your zoom out around. The screen shot below shows a zoomed out version of the plot.
• Save current view of data as .png file. You can save your current view of the data as a .png file to your local hard drive by clicking on the save button on the left side of the plot.
• Undo and redo actions. You can undo or redo any of the plot changes that you make using the undo button or the redo button on the left side of the plot.
• Reset the plot. After any changes you make to the plot, you can reset it to its original position by using the reset button on the left side of the plot.

2. Contributing to this visualization code

If you wish to improve or enhance this code or if you find errors or bugs, please consider the following ways to contribute to this project.

• Browse the repository Issues for known areas that need attention.
• Submit questions or suggestions by submitting a new issue in the repository Issues.
• Submit a pull request with your proposed changes.