Merge pull request PSLmodels#369 from jdebacker/getstarted

Update instructions

README.md

@@ -15,20 +15,36 @@ will have released versions, which will be checked against existing code prior
 to release. Stay tuned for an upcoming release!
 
 
-## Using OG-USA
-
-To be completed.
+## Using/contributing to OG-USA
+
+* Install the [Anaconda distribution](https://www.anaconda.com/distribution/) of Python
+* Clone this repository to a directory on your computer
+* 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`
+* Then, `source activate ospcdyn`
+* Then install by `python setup.py install` (use `python setup.py develop` if you would like to modifty the code base and run the updated model)
+* Navigate to `./run_examples`
+* Run the model with an example reform from terminal/command prompt by typing `python run_ogusa_example.py`
+* You can adjust the `./run_examples/run_ogusa_example.py` by adjusting the individual income tax reform (using a dictionary or JSON file in a format that is consistent with [Tax Calculator](https://github.com/open-source-economics/Tax-Calculator)) or other model parameters specified in the `user_params` or `kwargs` dictionaries.
+* Model outputs will be saved in the following files:
+  * `./run_examples/OUTPUT_BASELINE/model_params.pkl`
+    * Model parameters used in the baseline run
+    * See `execute.py` for items in the dictionary object in this pickle file
+  * `./run_examples/OUTPUT_BASELINE/TxFuncEst_baseline_'guid'.pkl`
+    * Tax function parameters used for the baseline model run
+    * See `txfunc.py` for what is in the dictionary object in this pickle file
+  * `./run_examples/OUTPUT_BASELINE/SS/SS_vars.pkl`
+    * Outputs from the model steady state solution under the baseline policy
+    * See `SS.py` for what is in the dictionary object in this pickle file
+  * `./run_examples/OUTPUT_BASELINE/TPI/TPI_vars.pkl`
+    * Outputs from the model timepath solution under the baseline policy
+    * See `SS.py` for what is in the dictionary object in this pickle file
+  * An analogous set of files in the `./run_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 from a few to several hours of compute time.
+
+If you run into errors running the example script, please open a new issue in the OG-USA repo with a description of the issue and any relevant tracebacks you receive.
 
 
 ## Citing OG-USA
 
 OG-USA (Version 0.5.7)[Source code], https://github.com/open-source-economics/OG-USA
-
-
-## Contributing
-
-To get up and running with the project, run the following commands:
-
-* `conda env create -f environment.yml`
-* `source activate ospcdyn`
-* `python setup.py install`

run_examples/2017_law.json

@@ -0,0 +1,62 @@
+// Title: 2017-law policy extrapolated into the future as if under pre-TCJA law
+// Reform_File_Author: Martin Holmer and Cody Kallen
+// Reform_Reference: 
+// Reform_Baseline: current_law_policy.json
+// Reform_Description:
+// - Switch to unchained CPI-U calculation of 2018+ policy parameter values (0)
+// - Set pre-TCJA tax rates (1)
+// - Set pre-TCJA handling of pass-through income (2)
+// - Set pre-TCJA child tax credit (CTC) and additional CTC policy (3)
+// - Set pre-TCJA dependent credit policy parameters (4)
+// - Set pre-TCJA above the line deduction policy (5)
+// - Set pre-TCJA itemized deduction policy (6)
+// Reform_Parameter_Map:
+// - 0: _cpi_offset
+// - 1: _II_rt? and _PT_rt?
+// - 2: four _PT_excl_* parameters
+// - 3: _CTC_c and _CTC_ps and _ACTC_Income_thd
+// - 4: four different _DependentCredit_* parameters
+// - 5: three _ALD_* parameters
+// - 6: seven different _ID_* parameters
+// NOTE: this reform projects pre-TCJA 2017 parameter values forward using the
+//       unchained CPI-U price index.
+{
+    "policy": {
+        "_cpi_offset": {"2017": [0.0025]},
+        "_II_rt1": {"2018": [0.10]},
+        "_II_rt2": {"2018": [0.15]},
+        "_II_rt3": {"2018": [0.25]},
+        "_II_rt4": {"2018": [0.28]},
+        "_II_rt5": {"2018": [0.33]},
+        "_II_rt6": {"2018": [0.35]},
+        "_II_rt7": {"2018": [0.396]},
+        "_PT_rt1": {"2018": [0.10]},
+        "_PT_rt2": {"2018": [0.15]},
+        "_PT_rt3": {"2018": [0.25]},
+        "_PT_rt4": {"2018": [0.28]},
+        "_PT_rt5": {"2018": [0.33]},
+        "_PT_rt6": {"2018": [0.35]},
+        "_PT_rt7": {"2018": [0.396]},
+        "_PT_excl_rt": {"2018": [0.0]},
+        "_PT_excl_wagelim_rt": {"2018": [9e99]},
+        "_PT_excl_wagelim_thd": {"2018": [[0.0, 0.0, 0.0, 0.0, 0.0]]},
+        "_PT_excl_wagelim_prt": {"2018": [[0.0, 0.0, 0.0, 0.0, 0.0]]},
+        "_CTC_c": {"2018": [1000.0]},
+        "_CTC_ps": {"2018": [[75000.0, 110000.0, 55000.0, 75000.0, 75000.0]]},
+        "_ACTC_Income_thd": {"2018": [3000.0]},
+        "_DependentCredit_Child_c": {"2018": [0.0]},
+        "_DependentCredit_Nonchild_c": {"2018": [0.0]},
+        "_DependentCredit_Nonchild_c": {"2018": [0.0]},
+        "_DependentCredit_before_CTC": {"2018": [0.0]},
+        "_ALD_AlimonyPaid_hc": {"2019": [0.0]},
+        "_ALD_AlimonyReceived_hc": {"2019": [1.0]},
+        "_ALD_DomesticProduction_hc": {"2018": [0.0]},
+        "_ID_prt": {"2018": [0.03]},
+        "_ID_crt": {"2018": [0.8]},
+        "_ID_Charity_crt_all": {"2018": [0.5]},
+        "_ID_Casualty_hc": {"2018": [0.0]},
+        "_ID_AllTaxes_c": {"2018": [[9e99, 9e99, 9e99, 9e99, 9e99]]},
+        "_ID_Miscellaneous_hc": {"2018": [0.0]},
+        "_ID_Medical_frt": {"2017": [0.1]}
+    }
+}

run_examples/run_ogusa_example.py

@@ -0,0 +1,103 @@
+from __future__ import print_function
+# import modules
+import multiprocessing
+from multiprocessing import Process
+from dask.distributed import Client
+import time
+import numpy as np
+
+from taxcalc import *
+import ogusa
+from ogusa.scripts import postprocess
+from ogusa.scripts.execute import runner
+from ogusa.utils import REFORM_DIR, BASELINE_DIR
+
+
+def run_micro_macro(user_params):
+    # Grab a reform JSON file already in Tax-Calculator
+    # In this example the 'reform' is a change to 2017 law (the
+    # baseline policy is tax law in 2018)
+    rec = Records()
+    pol = Policy()
+    calc = Calculator(policy=pol, records=rec)
+    ref = calc.read_json_param_objects('2017_law.json', None)
+    reform = ref['policy']
+
+    # Define parameters to use for multiprocessing
+    client = Client(processes=False)
+    num_workers = multiprocessing.cpu_count()
+    print('Number of workers = ', num_workers)
+    start_time = time.time()
+
+    # Set some model parameters
+    # See parameters.py for description of these parameters
+    T_shifts = np.zeros(50)
+    T_shifts[2:10] = 0.01
+    T_shifts[10:40] = -0.01
+    G_shifts = np.zeros(6)
+    G_shifts[0:3] = -0.01
+    G_shifts[3:6] = -0.005
+    small_open = False
+    # small_open = dict(world_int_rate=0.04)
+    # Alternatively small_open can be False/None
+    # if False/None then 0.04 is used
+    user_params = {'frisch': 0.41, 'start_year': 2018,
+                   'tau_b': (0.21 * 0.55) * (0.017 / 0.055),
+                   'debt_ratio_ss': 1.0, 'T_shifts': T_shifts,
+                   'G_shifts': G_shifts, 'small_open': small_open}
+
+    '''
+    ------------------------------------------------------------------------
+    Run baseline policy first
+    ------------------------------------------------------------------------
+    '''
+    output_base = BASELINE_DIR
+    input_dir = BASELINE_DIR
+    kwargs = {'output_base': output_base, 'baseline_dir': BASELINE_DIR,
+              'test': False, 'time_path': True, 'baseline': True,
+              'constant_rates': False,
+              'analytical_mtrs': False, 'age_specific': True,
+              'user_params': user_params, 'guid': '_example',
+              'run_micro': True, 'small_open': small_open,
+              'budget_balance': False, 'baseline_spending': False,
+              'data': 'cps', 'client': client,
+              'num_workers': num_workers}
+
+    start_time = time.time()
+    runner(**kwargs)
+    print('run time = ', time.time()-start_time)
+
+
+    '''
+    ------------------------------------------------------------------------
+    Run reform policy
+    ------------------------------------------------------------------------
+    '''
+    user_params = {'frisch': 0.41, 'start_year': 2018,
+                   'tau_b': (0.35 * 0.55) * (0.017 / 0.055),
+                   'debt_ratio_ss': 1.0, 'T_shifts': T_shifts,
+                   'G_shifts': G_shifts, 'small_open': small_open}
+    output_base = REFORM_DIR
+    input_dir = REFORM_DIR
+    guid_iter = 'reform_' + str(0)
+    kwargs = {'output_base': output_base, 'baseline_dir': BASELINE_DIR,
+              'test': False, 'time_path': True, 'baseline': False,
+              'constant_rates': False, 'analytical_mtrs': False,
+              'age_specific': True, 'user_params': user_params,
+              'guid': '_example', 'reform': reform, 'run_micro': True,
+              'small_open': small_open, 'budget_balance': False,
+              'baseline_spending': False, 'data': 'cps',
+              'client': client, 'num_workers': num_workers}
+
+    # return ans - the percentage changes in macro aggregates and prices
+    # due to policy changes from the baseline to the reform
+    ans = postprocess.create_diff(baseline_dir=BASELINE_DIR,
+                                  policy_dir=REFORM_DIR)
+
+    print("total time was ", (time.time() - start_time))
+    print('Percentage changes in aggregates:', ans)
+
+
+
+if __name__ == "__main__":
+    run_micro_macro(user_params={})