Merge pull request #1 from rickecon/first

Merging

.gitignore

@@ -0,0 +1,45 @@
+*.pyc
+MANIFEST
+build/*
+dist/*
+*.cache/
+.coverage
+.coveragerc
+htmlcov/*
+*.aux
+*.bbl
+*.blg
+*.fdb_latexmk
+*.idx
+*.ilg
+*.ind
+*.lof
+*.log
+*.lot
+*.out
+*.pdfsync
+*.synctex.gz
+*.toc
+*.swp
+*.asv
+*.nav
+*.snm
+*.gz
+*.bib.bak
+*.fls
+*.m~
+*.sublime*
+*.DS_Store*
+*puf.csv
+*tax_func_loop_inputs_large.pkl
+*/OUTPUT/*
+envs/
+*.egg-info/
+*dask-worker-space*
+.ipynb_checkpoints*
+*/__pycache__/*
+docs/book/_build/*
+docs/build*
+examples/OG-ZAF_example_plots/*
+examples/ogzaf_example_output.csv
+examples/OG-ZAF-Example/*

LICENSE.md

@@ -0,0 +1,31 @@
+This project is in the
+public domain within the United States.
+
+Additionally, we waive copyright and related rights in the work
+worldwide through the CC0 1.0 Universal public domain dedication.
+
+## CC0 1.0 Universal Summary
+
+This is a human-readable summary of the [Legal Code (read the full text)](https://creativecommons.org/publicdomain/zero/1.0/legalcode).
+
+### No Copyright
+
+The person who associated a work with this deed has dedicated the work to
+the public domain by waiving all of his or her rights to the work worldwide
+under copyright law, including all related and neighboring rights, to the
+extent allowed by law.
+
+You can copy, modify, distribute and perform the work, even for commercial
+purposes, all without asking permission.
+
+### Other Information
+
+In no way are the patent or trademark rights of any person affected by CC0,
+nor are the rights that other persons may have in the work or in how the
+work is used, such as publicity or privacy rights.
+
+Unless expressly stated otherwise, the person who associated a work with
+this deed makes no warranties about the work, and disclaims liability for
+all uses of the work, to the fullest extent permitted by applicable law.
+When using or citing the work, you should not imply endorsement by the
+author or the affirmer.

README.md

@@ -1,2 +1,62 @@
+[![Python 3.7+](https://img.shields.io/badge/python-3.7%2B-blue.svg)](https://www.python.org/downloads/release/python-377/)
+
 # OG-ZAF
-Overlapping-generations macroeconomic model for evaluating fiscal policy in South Africa
+OG-ZAF is an overlapping-generations (OG) model that allows for dynamic general equilibrium analysis of fiscal policy for South Africa. OG-ZAF is built on the OG-Core framework. The model output includes changes in macroeconomic aggregates (GDP, investment, consumption), wages, interest rates, and the stream of tax revenues over time. Regularly updated documentation of the model theory--its output, and solution method--and the Python API is available at https://pslmodels.github.io/OG-Core and documentation of the specific South African calibration of the model will be available soon.
+
+
+## Using and contributing to OG-ZAF
+
+* Install the [Anaconda distribution](https://www.anaconda.com/distribution/) of Python
+  * Make sure the `conda` package manager is up-to-date: `conda update conda`.
+  * Make sure the Anaconda distribution of Python is up-to-date: `conda update anaconda`.
+* Fork this repository and clone your fork of this repository to a directory on your computer.
+* From the terminal (or Anaconda command prompt), navigate to the directory to which you cloned this repository and run `conda env create -f environment.yml`. The process of creating the `ogzaf-dev` conda environment should not take more than five minutes.
+* Then, `conda activate ogzaf-dev`
+* Then install by `pip install -e .`
+* Navigate to `./examples`
+* Run the model with an example reform from terminal/command prompt by typing `python run_og_zaf.py`
+* You can adjust the `./examples/run_og_zaf.py` by modifying model parameters specified in the dictionary passed to the `p.update_specifications()` calls.
+* Model outputs will be saved in the following files:
+  * `./examples/OG-ZAF_example_plots`
+    * This folder will contain a number of plots generated from OG-Core to help you visualize the output from your run
+  * `./examples/ogzaf_example_output.csv`
+    * This is a summary of the percentage changes in macro variables over the first ten years and in the steady-state.
+  * `./examples/OG-ZAF-Example/OUTPUT_BASELINE/model_params.pkl`
+    * Model parameters used in the baseline run
+    * See [`ogcore.execute.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/execute.py) for items in the dictionary object in this pickle file
+  * `./examples/OG-ZAF-Example/OUTPUT_BASELINE/SS/SS_vars.pkl`
+    * Outputs from the model steady state solution under the baseline policy
+    * See [`ogcore.SS.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/SS.py) for what is in the dictionary object in this pickle file
+  * `./examples/OG-ZAF-Example/OUTPUT_BASELINE/TPI/TPI_vars.pkl`
+    * Outputs from the model timepath solution under the baseline policy
+    * See [`ogcore.TPI.py`](https://github.com/PSLmodels/OG-Core/blob/master/ogcore/TPI.py) for what is in the dictionary object in this pickle file
+  * An analogous set of files in the `./examples/OUTPUT_REFORM` directory, which represent objects from the simulation of the reform policy
+
+Note that, depending on your machine, a full model run (solving for the full time path equilibrium for the baseline and reform policies) can take more than two hours of compute time.
+
+If you run into errors running the example script, please open a new issue in the OG-ZAF repo with a description of the issue and any relevant tracebacks you receive.
+
+Once the package is installed, one can adjust parameters in the OG-Core `Specifications` object using the `Calibration` class as follows:
+
+```
+from ogcore.parameters import Specifications
+from ogind.calibrate import Calibration
+p = Specifications()
+c = Calibration(p)
+updated_params = c.get_dict()
+p.update_specifications({'initial_debt_ratio': updated_params['initial_debt_ratio']})
+```
+
+## Disclaimer
+The organization of this repository will be changing rapidly, but the `OG-ZAF/examples/run_og_zaf.py` script will be kept up to date to run with the master branch of this repo.
+
+## Core Maintainers
+
+The core maintainers of the OG-ZAF repository are:
+
+* Marcelo LaFleur (GitHub handle: [@SeaCelo](https://github.com/SeaCelo)), Senior Economist, Department of Economic and Social Affairs (DESA), United Nations
+* [Richard W. Evans](https://sites.google.com/site/rickecon/) (GitHub handle: [@rickecon](https://github.com/rickecon)), Senior Research Fellow and Director of Open Policy, Center for Growth and Opportunity at Utah State University; President, Open Research Group, Inc.
+
+## Citing OG-ZAF
+
+OG-ZAF (Version #.#.#)[Source code], https://github.com/EAPD-DRB/OG-ZAF

environment.yml

@@ -0,0 +1,34 @@
+name: ogzaf-dev
+channels:
+- conda-forge
+dependencies:
+- python>=3.7.7, <=3.9.12  # This restriction can be removed as soon as these packages support Python 3.10
+- mkl>=2020.2
+- numpy<=1.21.2  # This restriction can be removed as soon as Numba supports NumPy 1.22
+- psutil
+- scipy>=1.5.0
+- pandas>=1.2.5
+- matplotlib
+- dask>=2.30.0
+- dask-core>=2.30.0
+- distributed>=2.30.1
+- paramtools>=0.15.0
+- sphinx>=3.5.4
+- sphinx-book-theme>=0.1.3
+- pip
+- pytest>=6.0
+- pytest-pep8
+- pytest-xdist
+- pycodestyle
+- pylint
+- coverage
+- requests
+- xlwt
+- openpyxl
+- statsmodels
+- linearmodels
+- black
+- pip:
+  - jupyter-book>=0.9.1
+  - pandas-datareader
+  - ogcore

examples/run_og_zaf.py

@@ -0,0 +1,126 @@
+# Need to fix references to Calculator, reform json, and substitute new tax
+# function call
+import multiprocessing
+from distributed import Client
+import os
+import json
+import time
+# from taxcalc import Calculator
+from ogzaf.calibrate import Calibration
+from ogcore.parameters import Specifications
+from ogcore import output_tables as ot
+from ogcore import output_plots as op
+from ogcore.execute import runner
+from ogcore.utils import safe_read_pickle
+
+
+def main():
+    # Define parameters to use for multiprocessing
+    client = Client()
+    num_workers = min(multiprocessing.cpu_count(), 7)
+    print("Number of workers = ", num_workers)
+
+    # Directories to save data
+    CUR_DIR = os.path.dirname(os.path.realpath(__file__))
+    base_dir = os.path.join(CUR_DIR, "OG-ZAF-Example", "OUTPUT_BASELINE")
+    reform_dir = os.path.join(CUR_DIR, "OG-ZAF-Example", "OUTPUT_REFORM")
+
+    """
+    ---------------------------------------------------------------------------
+    Run baseline policy
+    ---------------------------------------------------------------------------
+    """
+    # Set up baseline parameterization
+    p = Specifications(
+        baseline=True,
+        num_workers=num_workers,
+        baseline_dir=base_dir,
+        output_base=base_dir,
+    )
+    # Update parameters for baseline from default json file
+    p.update_specifications(
+        json.load(
+            open(
+                os.path.join(
+                    CUR_DIR, "..", "ogzaf", "ogzaf_default_parameters.json"
+                )
+            )
+        )
+    )
+
+    # Run model
+    start_time = time.time()
+    runner(p, time_path=True, client=client)
+    print("run time = ", time.time() - start_time)
+
+    """
+    ---------------------------------------------------------------------------
+    Run reform policy
+    ---------------------------------------------------------------------------
+    """
+
+    # create new Specifications object for reform simulation
+    p2 = Specifications(
+        baseline=False,
+        num_workers=num_workers,
+        baseline_dir=base_dir,
+        output_base=reform_dir,
+    )
+    # Update parameters for baseline from default json file
+    p2.update_specifications(
+        json.load(
+            open(
+                os.path.join(
+                    CUR_DIR, "..", "ogzaf", "ogzaf_default_parameters.json"
+                )
+            )
+        )
+    )
+    # additional parameters to change
+    updated_params = {
+        "cit_rate": [[0.35]],
+    }
+    p2.update_specifications(updated_params)
+    # Run model
+    start_time = time.time()
+    runner(p2, time_path=True, client=client)
+    print("run time = ", time.time() - start_time)
+    client.close()
+
+    """
+    ---------------------------------------------------------------------------
+    Save some results of simulations
+    ---------------------------------------------------------------------------
+    """
+    base_tpi = safe_read_pickle(os.path.join(base_dir, "TPI", "TPI_vars.pkl"))
+    base_params = safe_read_pickle(os.path.join(base_dir, "model_params.pkl"))
+    reform_tpi = safe_read_pickle(
+        os.path.join(reform_dir, "TPI", "TPI_vars.pkl")
+    )
+    reform_params = safe_read_pickle(
+        os.path.join(reform_dir, "model_params.pkl")
+    )
+    ans = ot.macro_table(
+        base_tpi,
+        base_params,
+        reform_tpi=reform_tpi,
+        reform_params=reform_params,
+        var_list=["Y", "C", "K", "L", "r", "w"],
+        output_type="pct_diff",
+        num_years=10,
+        start_year=base_params.start_year,
+    )
+
+    # create plots of output
+    op.plot_all(
+        base_dir, reform_dir, os.path.join(CUR_DIR, "OG-ZAF_example_plots")
+    )
+
+    print("Percentage changes in aggregates:", ans)
+    # save percentage change output to csv file
+    ans.to_csv("ogind_example_output.csv")
+
+
+if __name__ == "__main__":
+    # execute only if run as a script
+    main()