Skip to content

Commit f6d7b82

Browse files
jdebackerjdebacker
committed
complete doc strings
1 parent 955b97e commit f6d7b82

File tree

1 file changed

+243
-1
lines changed

1 file changed

+243
-1
lines changed

‎ogcore/pensions.py

Lines changed: 243 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -531,7 +531,16 @@ def deriv_PS(w, e, per_rmn, factor, p):
531531
labor supply
532532
533533
Args:
534-
w
534+
w (array_like): real wage rate
535+
e (Numpy array): effective labor units
536+
per_rmn (int): number of periods remaining in the model
537+
factor (scalar): scaling factor converting model units to
538+
p (OG-Core Specifications object): model parameters
539+
540+
Returns:
541+
d_theta (Numpy array): change in points system pension benefits
542+
for another unit of labor supply
543+
535544
"""
536545

537546
if per_rmn < (p.S - p.retire + 1):
@@ -552,6 +561,17 @@ def deriv_PS(w, e, per_rmn, factor, p):
552561
def delta_point(r, Y, g_n, g_y, p):
553562
"""
554563
Compute growth rate used for contributions to points system pension
564+
565+
Args:
566+
r (array_like): interest rate
567+
Y (array_like): GDP
568+
g_n (array_like): population growth rate
569+
g_y (array_like): GDP growth rate
570+
p (OG-Core Specifications object): model parameters
571+
572+
Returns:
573+
delta_point (Numpy array): growth rate used for contributions to
574+
points
555575
"""
556576
# TODO: Add option to allow use to enter growth rate amount
557577
# Also to allow rate to vary by year
@@ -572,6 +592,15 @@ def delta_point(r, Y, g_n, g_y, p):
572592
def g_ndc(r, Y, p):
573593
"""
574594
Compute growth rate used for contributions to NDC pension
595+
596+
Args:
597+
r (array_like): interest rate
598+
Y (array_like): GDP
599+
p (OG-Core Specifications object): model parameters
600+
601+
Returns:
602+
g_ndc (Numpy array): growth rate used for contributions to NDC
603+
575604
"""
576605
if p.ndc_growth_rate == "r":
577606
g_ndc = r[-1]
@@ -588,6 +617,17 @@ def g_ndc(r, Y, p):
588617
def g_dir(r, Y, g_y, g_n, dir_growth_rate):
589618
"""
590619
Compute growth rate used for contributions to NDC pension
620+
621+
Args:
622+
r (array_like): interest rate
623+
Y (array_like): GDP
624+
g_y (array_like): GDP growth rate
625+
g_n (array_like): population growth rate
626+
dir_growth_rate (str): growth rate used for contributions to NDC
627+
628+
Returns:
629+
g_dir (Numpy array): growth rate used for contributions to NDC
630+
591631
"""
592632
if dir_growth_rate == "r":
593633
g_dir = r[-1]
@@ -604,6 +644,16 @@ def g_dir(r, Y, g_y, g_n, dir_growth_rate):
604644
def delta_ret(r, Y, p):
605645
"""
606646
Compute conversion coefficient for the NDC pension amount
647+
648+
Args:
649+
r (array_like): interest rate
650+
Y (array_like): GDP
651+
p (OG-Core Specifications object): model parameters
652+
653+
Returns:
654+
delta_ret (Numpy array): conversion coefficient for the NDC
655+
pension amount
656+
607657
"""
608658
surv_rates = 1 - p.mort_rates_SS
609659
dir_delta_s_empty = np.zeros(p.S - p.retire + 1)
@@ -620,6 +670,23 @@ def delta_ret(r, Y, p):
620670
def deriv_DB_loop(
621671
w, e, S, S_ret, per_rmn, avg_earn_num_years, alpha_db, yr_contr
622672
):
673+
"""
674+
Change in DB pension benefits for another unit of labor supply
675+
676+
Args:
677+
w (array_like): real wage rate
678+
e (Numpy array): effective labor units
679+
S (int): number of periods in the model
680+
S_ret (int): retirement age
681+
per_rmn (int): number of periods remaining in the model
682+
avg_earn_num_years (int): number of years AIME is computed from
683+
alpha_db (scalar): replacement rate
684+
yr_contr (scalar): years of contribution
685+
686+
Returns:
687+
d_theta (Numpy array): change in DB pension benefits for
688+
another unit of labor supply
689+
"""
623690
d_theta = np.zeros(per_rmn)
624691
num_per_retire = S - S_ret
625692
for s in range(per_rmn):
@@ -631,6 +698,27 @@ def deriv_DB_loop(
631698

632699
@numba.jit
633700
def deriv_PS_loop(w, e, S, S_ret, per_rmn, d_theta, vpoint, factor):
701+
"""
702+
Change in points system pension benefits for another unit of
703+
labor supply
704+
705+
Args:
706+
w (array_like): real wage rate
707+
e (Numpy array): effective labor units
708+
S (int): number of periods in the model
709+
S_ret (int): retirement age
710+
per_rmn (int): number of periods remaining in the model
711+
d_theta (Numpy array): change in points system pension benefits
712+
for another unit of labor supply
713+
vpoint (scalar): value of points
714+
factor (scalar): scaling factor converting model units to
715+
local currency
716+
717+
Returns:
718+
d_theta (Numpy array): change in points system pension benefits
719+
for another unit of labor supply
720+
721+
"""
634722
# TODO: do we need these constants or can we scale vpoint to annual??
635723
for s in range((S - per_rmn), S_ret):
636724
d_theta[s] = (w[s] * e[s] * vpoint * MONTHS_IN_A_YEAR) / (
@@ -644,6 +732,27 @@ def deriv_PS_loop(w, e, S, S_ret, per_rmn, d_theta, vpoint, factor):
644732
def deriv_NDC_loop(
645733
w, e, per_rmn, S, S_ret, tau_p, g_ndc_value, delta_ret_value, d_theta
646734
):
735+
"""
736+
Change in NDC pension benefits for another unit of labor supply
737+
738+
Args:
739+
w (array_like): real wage rate
740+
e (Numpy array): effective labor units
741+
per_rmn (int): number of periods remaining in the model
742+
S (int): number of periods in the model
743+
S_ret (int): retirement age
744+
tau_p (scalar): tax rate
745+
g_ndc_value (scalar): growth rate of NDC pension
746+
delta_ret_value (scalar): conversion coefficient for the NDC
747+
pension amount
748+
d_theta (Numpy array): change in NDC pension benefits for
749+
another unit of labor supply
750+
751+
Returns:
752+
d_theta (Numpy array): change in NDC pension benefits for
753+
another unit of labor supply
754+
755+
"""
647756
for s in range((S - per_rmn), S_ret):
648757
d_theta[s - (S - per_rmn)] = (
649758
tau_p
@@ -658,7 +767,21 @@ def deriv_NDC_loop(
658767

659768
@numba.jit
660769
def delta_ret_loop(S, S_ret, surv_rates, g_dir_value, dir_delta_s):
770+
"""
771+
Compute conversion coefficient for the NDC pension amount
661772
773+
Args:
774+
S (int): number of periods in the model
775+
S_ret (int): retirement age
776+
surv_rates (Numpy array): survival rates
777+
g_dir_value (scalar): growth rate of NDC pension
778+
dir_delta_s (Numpy array): conversion coefficient for the NDC
779+
pension amount
780+
781+
Returns:
782+
dir_delta (scalar): conversion coefficient for the NDC pension
783+
amount
784+
"""
662785
cumul_surv_rates = np.ones(S - S_ret + 1)
663786
for s in range(S - S_ret + 1):
664787
surv_rates_vec = surv_rates[S_ret : S_ret + s + 1]
@@ -673,6 +796,26 @@ def delta_ret_loop(S, S_ret, surv_rates, g_dir_value, dir_delta_s):
673796

674797
@numba.jit
675798
def PS_1dim_loop(w, e, n, S_ret, S, g_y, vpoint, factor, L_inc_avg_s, PS):
799+
"""
800+
Calculate public pension from a points system.
801+
802+
Args:
803+
w (array_like): real wage rate
804+
e (Numpy array): effective labor units
805+
n (Numpy array): labor supply
806+
S_ret (int): retirement age
807+
S (int): number of periods in the model
808+
g_y (array_like): GDP growth rate
809+
vpoint (scalar): value of points
810+
factor (scalar): scaling factor converting model units to
811+
local currency
812+
L_inc_avg_s (Numpy array): average labor income
813+
PS (Numpy array): pension amount for each household
814+
815+
Returns:
816+
PS (Numpy array): pension amount for each household
817+
818+
"""
676819
# TODO: do we need these constants or can we scale vpoint to annual??
677820
for u in range(S_ret, S):
678821
# TODO: allow for g_y to be time varying
@@ -687,6 +830,27 @@ def PS_1dim_loop(w, e, n, S_ret, S, g_y, vpoint, factor, L_inc_avg_s, PS):
687830

688831
@numba.jit
689832
def PS_2dim_loop(w, e, n, S_ret, S, J, g_y, vpoint, factor, L_inc_avg_sj, PS):
833+
"""
834+
Calculate public pension from a points system.
835+
836+
Args:
837+
w (array_like): real wage rate
838+
e (Numpy array): effective labor units
839+
n (Numpy array): labor supply
840+
S_ret (int): retirement age
841+
S (int): number of periods in the model
842+
J (int): number of lifetime income groups
843+
g_y (array_like): GDP growth rate
844+
vpoint (scalar): value of points
845+
factor (scalar): scaling factor converting model units to
846+
local currency
847+
L_inc_avg_sj (Numpy array): average labor income
848+
PS (Numpy array): pension amount for each household
849+
850+
Returns:
851+
PS (Numpy array): pension amount for each household
852+
853+
"""
690854
# TODO: do we need these constants or can we scale vpoint to annual??
691855
for u in range(S_ret, S):
692856
for s in range(S_ret):
@@ -715,7 +879,26 @@ def DB_1dim_loop(
715879
alpha_db,
716880
yr_contr,
717881
):
882+
"""
883+
Calculate public pension from a defined benefits system.
884+
885+
Args:
886+
w (array_like): real wage rate
887+
e (Numpy array): effective labor units
888+
n (Numpy array): labor supply
889+
S_ret (int): retirement age
890+
S (int): number of periods in the model
891+
g_y (array_like): GDP growth rate
892+
L_inc_avg_s (Numpy array): average labor income
893+
L_inc_avg (scalar): average labor income
894+
DB (Numpy array): pension amount for each household
895+
avg_earn_num_years (int): number of years AIME is computed from
896+
alpha_db (scalar): replacement rate
897+
yr_contr (scalar): years of contribution
718898
899+
Returns:
900+
DB (Numpy array): pension amount for each household
901+
"""
719902
for u in range(S_ret, S):
720903
for s in range(S_ret - avg_earn_num_years, S_ret):
721904
# TODO: pass t so that can pull correct g_y value
@@ -746,7 +929,27 @@ def DB_2dim_loop(
746929
alpha_db,
747930
yr_contr,
748931
):
932+
"""
933+
Calculate public pension from a defined benefits system.
934+
935+
Args:
936+
w (array_like): real wage rate
937+
e (Numpy array): effective labor units
938+
n (Numpy array): labor supply
939+
S_ret (int): retirement age
940+
S (int): number of periods in the model
941+
g_y (array_like): GDP growth rate
942+
L_inc_avg_sj (Numpy array): average labor income
943+
L_inc_avg (scalar): average labor income
944+
DB (Numpy array): pension amount for each household
945+
avg_earn_num_years (int): number of years AIME is computed from
946+
alpha_db (scalar): replacement rate
947+
yr_contr (scalar): years of contribution
749948
949+
Returns:
950+
DB (Numpy array): pension amount for each household
951+
952+
"""
750953
for u in range(S_ret, S):
751954
for s in range(S_ret - avg_earn_num_years, S_ret):
752955
L_inc_avg_sj[s - (S_ret - avg_earn_num_years), :] = (
@@ -761,7 +964,26 @@ def DB_2dim_loop(
761964

762965
@numba.jit
763966
def NDC_1dim_loop(w, e, n, S_ret, S, g_y, tau_p, g_ndc, delta_ret, NDC_s, NDC):
967+
"""
968+
Calculate public pension from a notional defined contribution
764969
970+
Args:
971+
w (array_like): real wage rate
972+
e (Numpy array): effective labor units
973+
n (Numpy array): labor supply
974+
S_ret (int): retirement age
975+
S (int): number of periods in the model
976+
g_y (array_like): GDP growth rate
977+
tau_p (scalar): tax rate
978+
g_ndc (scalar): growth rate of NDC pension
979+
delta_ret (scalar): conversion coefficient for the NDC pension amount
980+
NDC_s (Numpy array): average labor income
981+
NDC (Numpy array): pension amount for each household
982+
983+
Returns:
984+
NDC (Numpy array): pension amount for each household
985+
986+
"""
765987
for u in range(S_ret, S):
766988
for s in range(0, S_ret):
767989
# TODO: update so can take g_y from period t
@@ -780,6 +1002,26 @@ def NDC_1dim_loop(w, e, n, S_ret, S, g_y, tau_p, g_ndc, delta_ret, NDC_s, NDC):
7801002
def NDC_2dim_loop(
7811003
w, e, n, S_ret, S, g_y, tau_p, g_ndc, delta_ret, NDC_sj, NDC
7821004
):
1005+
"""
1006+
Calculate public pension from a notional defined contribution
1007+
1008+
Args:
1009+
w (array_like): real wage rate
1010+
e (Numpy array): effective labor units
1011+
n (Numpy array): labor supply
1012+
S_ret (int): retirement age
1013+
S (int): number of periods in the model
1014+
g_y (array_like): GDP growth rate
1015+
tau_p (scalar): tax rate
1016+
g_ndc (scalar): growth rate of NDC pension
1017+
delta_ret (scalar): conversion coefficient for the NDC pension amount
1018+
NDC_sj (Numpy array): average labor income
1019+
NDC (Numpy array): pension amount for each household
1020+
1021+
Returns:
1022+
NDC (Numpy array): pension amount for each household
1023+
1024+
"""
7831025
for u in range(S_ret, S):
7841026
for s in range(0, S_ret):
7851027
NDC_sj[s, :] = (

0 commit comments

Comments
 (0)