opensourceecon / cps_hrs_age Goto Github PK

We should make sure that we follow the Python PEP 8 conventions in our code for this repository.

@hayleefay . I can't seem to figure out what this line of loop is doing (line 410 in hrs_by_age.py). What lines do we need to loop through here? Do you remember this?

Lets have the main function hrs_by_age() return the hours by age vector as a one-dimensional NumPy array that is (S,) length.

As soon as we merge the current PR #7, I would like to transfer this repository to the OpenSourceMacro organization. That will certainly mean that I have to create a new fork and a new clone. I am not sure if @hayleefay will have to. However, it might just be a good idea to re-fork and re-clone when we make this transfer. All the previous commit history will go with the new repository location.

Lets use the following convention in commenting functions in their docstrings.

def func_name(args1, args2):
    '''
    --------------------------------------------------------------------
    Describe what the function does
    --------------------------------------------------------------------
    INPUTS:
    args1 = describe size of input, describe content of input
    args2 = describe size of input, describe content of input

    OTHER FUNCTIONS AND FILES CALLED BY THIS FUNCTION: None
        other_func()  # Function from this same module
        othr.another_func()  # Function from another module

    OBJECTS CREATED WITHIN FUNCTION:
    obj1 = describe size of input, describe content of input
    obj2 = describe size of input, describe content of input

    FILES CREATED BY THIS FUNCTION: None
        obj_image.png

    RETURNS: obj1, obj2
    --------------------------------------------------------------------
    '''
    # Do stuff that the function does
    var1, var2, var3 = args1
    var4, var5, var6 = args2
    obj1 = var1 * var4 + other_func(var3, var4)
    obj2 = (var2 + var3) / (var5 + var6) - othr.another_func(var1, var4)

    # Make a plot of obj1 and obj2 and save as obj_image.png

    return obj1, obj2

An example of such a function with this approach of function docstring commenting is the following:

def get_b_errors(cvec, r, params, diff=True):
    '''
    --------------------------------------------------------------------
    Generates vector of dynamic Euler errors that characterize the
    optimal lifetime savings decision. Because this function is used for
    solving for lifetime decisions in both the steady-state and in the
    transition path, lifetimes will be of varying length. Lifetimes in
    the steady-state will be S periods. Lifetimes in the transition path
    will be p in [2, S] periods
    --------------------------------------------------------------------
    INPUTS:
    cvec   = (p,) vector, distribution of consumption by age c_p
    r      = scalar > 0 or (p,) vector, steady-state interest rate or
              time path of interest rates
    params = length 2 tuple, (beta, sigma)
    diff   = boolean, =True if use simple difference Euler
              errors. Use percent difference errors otherwise.

    OTHER FUNCTIONS AND FILES CALLED BY THIS FUNCTION:
        MU_c_stitch()

    OBJECTS CREATED WITHIN FUNCTION:
    beta     = scalar in (0,1), discount factor
    sigma    = scalar > 0, coefficient of relative risk aversion
    mu_c     = (p-1,) vector, marginal utility of current consumption
    mu_cp1   = (p-1,) vector, marginal utility of next period consumpt'n
    b_errors = (p-1,) vector, Euler errors characterizing optimal
               savings bvec

    FILES CREATED BY THIS FUNCTION: None

    RETURNS: b_errors
    --------------------------------------------------------------------
    '''
    beta, sigma = params
    mu_c = MU_c_stitch(cvec[:-1], sigma)
    mu_cp1 = MU_c_stitch(cvec[1:], sigma)
    if diff:
        b_errors = (beta * (1 + r) * mu_cp1) - mu_c
    else:
        b_errors = ((beta * (1 + r) * mu_cp1) / mu_c) - 1

    return b_errors

Another convention I try to follow is to order the inputs such that the most important or central inputs to the function come first. Next comes a tuple of parameters or secondary objects. And finally come the objects that need not be called to run the function that have defaults set if they are not called (I forgot what these are called).

We should put functionality in this module to save the output and arguments of the function as a pickle. This is done by importing the pickle library. I also usually import the os library.

import pickle
import os

Then I give the function some instructions about where to save things in the current directory.

# Create OUTPUT/folder directory if does not already exist
cur_path = os.path.split(os.path.abspath(__file__))[0]
output_fldr = 'OUTPUT/folder'
output_dir = os.path.join(cur_path, output_fldr)
if not os.access(output_dir, os.F_OK):
    os.makedirs(output_dir)
outputfile = os.path.join(ss_output_dir, 'filename.pkl')

The if not... lines check whether a directory of that name exists in the current directory and creates that directory if it does not exist. To save output as a pickle file, use the pickle.dump() command.

# Save output as pickle
pickle.dump(output_object, open(outputfile, 'wb'))

The 'wb' option means "write binary". This is helpful for ensuring that all python objects are saved and retrieved in the same format across platforms (i.e., OSX, Windows, Linux). Pickle files are retrieved from memory using the pickle.load() command.

output_object = pickle.load(open(outputfile, 'rb'))

The 'rb' argument in the pickle.load() command means "read binary". @hayleefay

This module hrs_by_age.py should be imported for use in other programs by a line like,

import hrs_by_age as hrage

the main functionality of which should be importing the use of the hrs_by_age() function, which has the following form.

hrs_age = hrs_by_age(age_bins, l_tilde, beg_mmyy, end_mmyy, web=True,
                     dir=None, graph=False)

The inputs and outputs have the following definitions:

• hrs_age = (S,) vector, per-period hours by age as a percent of l_tilde
• age_bins = (S,) vector, beginning cutoff ages for each age bin
• l_tilde = scalar > 1, model time endowment for each life period
• beg_mmyy = length 4 string, numeric two-digit month and numeric last-two-digits of four-digit year for beginning month-year of data period
• end_mmyy = length 4 string, numeric two-digit month and numeric last-two-digits of four-digit year for ending month-year of data period
• web = boolean, =True if get data from NBER data website
• dir = string, directory of local folder where data reside
• graph = boolean, =True if save plot of hrs_age

The following is a list of the functionalities that this function hrs_by_age() should have.

1. Should take an arbitrary number of bins and bin sizes through the age_bins input.

• This functionality will have to extrapolate values of hours by age for any age above 79 or below 15. However, the lower bound will probably not bind.

2. Should take an arbitrary maximum labor endowment per period l_tilde.
3. User can specify what month-year date range to use from the CPS monthly data.
4. User can specify whether the function should go get the data directly off the web or whether it should get the data from a directory on the local computer using the web boolean input.
5. If the user specifies that the data should be taken from a local directory web=False, then the user specifies the path of the local directory of the data using the dir input.
6. The user can specify with the graph boolean whether or not to save a plot of the hrs_age object.

• This is where we could have some nice augmented visualization tools (e.g., Bokeh, JavaScript).

Add a progress bar to be printed on the terminal when the web option is used.