# README for "A Tractable Income Process for Business Cycle Analysis" (Fatih Guvenen, Alisdair McKay, and Conor Ryan)

## Overview

There are two components of this replication package.

**Income Process Estimation**

The replication package estimates several versions of the income process. The main programming langauge is Python. 

**Consumption-Savings Simulation**

The replication package simulates a consumption-savings problem. This part of the package is written in Julia.  

## Data Availability and Provenance Statements

All data used in this paper are publicly available and copies are included in the replication package.

### Statement about Rights

- [x] I certify that the author(s) of the manuscript have legitimate access to and permission to use the data used in this manuscript.
- [x] I certify that the author(s) of the manuscript have documented permission to redistribute/publish the data contained within this replication package. Appropriate permissions are documented in the LICENSE.txt file.

### License for Data

Data files distributed with this replication package are licensed under a Creative Commons Attribution 4.0 International (CC BY 4.0) license. See LICENSE.txt for details. Individual original sources are in the public domain or made freely available by their authors as described below.

### Summary of Availability

- [x] All data **are** publicly available.

#### Summary of Data Availability

| Data Name | Data Files | Location | Provided | Citation |
|-----------|-----------|----------|----------|---------|
| Income process calibration targets | `Guvenen.xlsx` | `input_data/` | Yes | Guvenen et al. (2014, 2021) |
| Macroeconomic time series | `FRED.xlsx` | `input_data/` | Yes | BEA, FRED |

### Details on each Data Source


Datafile: `calibration/IncomeProcess_FigB1/InputData/Guvenen.xlsx`

**Macroeconomic time series**

Annual macroeconomic time series were assembled from the Bureau of Economic Analysis (BEA) via the Federal Reserve Economic Data (FRED) database. See the notes within `input_data/FRED.xlsx` and `input_data/Sec6Datat.xlsx` for individual series sources and mnemonics. 

Datafiles: `input_data/FRED.xlsx` and `input_data/Sec6Datat.xlsx`


## Computational requirements

### Software Requirements

For the estimation (most of the paper), we used.
- Python 3.9.25
  - numpy 2.0.2
  - numba 0.60.0
  - scipy 1.13.1
  - nlopt 2.7.1
  - jinja2 3.1.6
  - argparse 1.1
  - pandas 2.3.3
  - matplotlib 3.9.2

In addition, the very last step of the replication compiles a summary report with pdflatex.

You can install all of the needed python packages via `cd EstimationCode` followed by `pip install -r requirements.txt` If you want to create a virtual environment for this using the uv Python package manager proceed as follows
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
[run python scripts as normal]
rm -rf .venv
```



For the consumption-savings problem in Section 6 we use the following enviroment.
- Julia v1.12.6
  - CSV v0.10.15
  - DataFrames v1.8.1
  - Distributions v0.25.123
  - FastGaussQuadrature v1.1.0
  - Interpolations v0.16.2
  - JLD v0.13.5
  - Parameters v0.12.3
  - Plots v1.41.1
  - Roots v2.2.10
  - StatsBase v0.34.9

The replication script will install the needed packages using the information in Project.toml.
  


### Memory, Runtime, Storage Requirements

#### Summary time to reproduce

In the configuration we used for the paper, estimating a single specification takes several hours on a cluster with 64 cores.  This configuration is invoked with `large_script.sh`  A configuration that explores the parameter space less intensively takes about 15 minutes on a laptop although it does not necessarily achieve the same objective function value as we report in the paper. This configuration can be invoked with `small_script.sh`.

#### Required memory and storage

The estimation is not particularly intensive in memory or storage use.


#### Random numbers

In our estimation we set the random seed of the default numpy RNG in line 451 of `Objective.py`. 



## Instructions to Replicators



**Component 1: prepare the inputs from raw data**

You may skip this step as we have included the prepared inputs in the replication package.

1. `cd input_data`
2. Run `run_prepare.sh`

**Component 2: perform estimation**

The following steps estimate a specification indicated by `spec_ID`

1. `cd EstimationCode`
2. `large_script.sh [spec_ID]` for the intensive parameter search. For a faster, but less exhaustive search use `small_script.sh [spec_ID]` 

The meaning of `spec_ID` is as follows

| Name in the paper | spec_ID       |
|-------------------|---------------|
| 1                 | 1             |
| 2                 | 2             |
| 3                 | 3             |
| 4                 | 4             |
| 5                 | 5             |
| 6                 | 6             |
| 2'                | 2_prime       |
| 3'                | 3_prime       |
| 3''               | 3_doubleprime |
| 4'                | 4_prime       |



**Component 3: Make the tables and figures**

1. `cd EstimationCode`
2. `post.sh [spec_ID]`  Results are saved to `[top-level-dir]/Output/Report_[spec_ID].pdf`

**Component 4: Andrews et al. sensitivity plot**

1. `cd EstimationCode`
2. `run_andrews.sh` Results are saved to  `[top-level-dir]/Output/Andrews_4_G[0:2].pdf`


**Component 5: Consumption simulation**

1. `cd ConsumptionSavings`
2. `runall.sh`  Results are saved to `[top-level-dir]/ConsumptionSavings/Plots`



## References

Guvenen, Fatih, Serdar Ozkan, and Jae Song. "The Nature of Countercyclical Income Risk." *Journal of Political Economy* 122, no. 3 (2014): 621–660.

Guvenen, Fatih, Fatih Karahan, Serdar Ozkan, and Jae Song. "What Do Data on Millions of US Workers Reveal about Lifecycle Earnings Dynamics?" *Econometrica* 89, no. 5 (2021): 2303–2339.