owlplanner 2025.1.24__py3-none-any.whl → 2025.1.27__py3-none-any.whl

owlplanner/data/rates.csv

@@ -0,0 +1,98 @@
+year,S&P 500,Bonds Baa,Bonds Aaa,TBills,TNotes,Inflation
+1928,43.81,3.22,3.22,3.08,0.84,-1.16
+1929,-8.3,3.02,3.02,3.16,4.2,0.58
+1930,-25.12,0.54,0.54,4.55,4.54,-6.4
+1931,-43.84,-15.68,-15.68,2.31,-2.56,-9.32
+1932,-8.64,23.59,23.59,1.07,8.79,-10.27
+1933,49.98,12.97,12.97,0.96,1.86,0.76
+1934,-1.19,18.82,18.82,0.28,7.96,1.52
+1935,46.74,13.31,13.31,0.17,4.47,2.99
+1936,31.94,11.38,11.38,0.17,5.02,1.45
+1937,-35.34,-4.42,-4.42,0.28,1.38,2.86
+1938,29.28,9.24,9.24,0.07,4.21,-2.78
+1939,-1.1,7.98,7.98,0.05,4.41,0.0
+1940,-10.67,8.65,8.65,0.04,5.4,0.71
+1941,-12.77,5.01,5.01,0.13,-2.02,9.93
+1942,19.17,5.18,5.18,0.34,2.29,9.03
+1943,25.06,8.04,8.04,0.38,2.49,2.96
+1944,19.03,6.57,6.57,0.38,2.58,2.3
+1945,35.82,6.8,6.8,0.38,3.8,2.25
+1946,-8.43,2.51,2.51,0.38,3.13,18.13
+1947,5.2,0.26,0.26,0.6,0.92,8.84
+1948,5.7,3.44,3.44,1.05,1.95,2.99
+1949,18.3,5.38,5.38,1.12,4.66,-2.07
+1950,30.81,4.24,4.24,1.2,0.43,5.93
+1951,23.68,-0.19,-0.19,1.52,-0.3,6.0
+1952,18.15,4.44,4.44,1.72,2.27,0.75
+1953,-1.21,1.62,1.62,1.89,4.14,0.75
+1954,52.56,6.16,6.16,0.94,3.29,-0.74
+1955,32.6,2.04,2.04,1.72,-1.34,0.37
+1956,7.44,-2.35,-2.35,2.62,-2.26,2.99
+1957,-10.46,-0.72,-0.72,3.22,6.8,2.9
+1958,43.72,6.43,6.43,1.77,-2.1,1.76
+1959,12.06,1.57,1.57,3.39,-2.65,1.73
+1960,0.34,6.66,6.66,2.87,11.64,1.36
+1961,26.64,5.1,5.1,2.35,2.06,0.67
+1962,-8.81,6.5,6.5,2.77,5.69,1.33
+1963,22.61,5.46,5.46,3.16,1.68,1.64
+1964,16.42,5.16,5.16,3.55,3.73,0.97
+1965,12.4,3.19,3.19,3.95,0.72,1.92
+1966,-9.97,-3.45,-3.45,4.86,2.91,3.46
+1967,23.8,0.9,0.9,4.29,-1.58,3.04
+1968,10.81,4.85,4.85,5.34,3.27,4.72
+1969,-8.24,-2.03,-2.03,6.67,-5.01,6.2
+1970,3.56,5.65,5.65,6.39,16.75,5.57
+1971,14.22,14.0,14.0,4.33,9.79,3.27
+1972,18.76,11.41,11.41,4.06,2.82,3.41
+1973,-14.31,4.32,4.32,7.04,3.66,8.71
+1974,-25.9,-4.38,-4.38,7.85,1.99,12.34
+1975,37.0,11.05,11.05,5.79,3.61,6.94
+1976,23.83,19.75,19.75,4.98,15.98,4.86
+1977,-6.98,9.95,9.95,5.26,1.29,6.7
+1978,6.51,3.14,3.14,7.18,-0.78,9.02
+1979,18.52,-2.01,-2.01,10.05,0.67,13.29
+1980,31.74,-3.32,-3.32,11.39,-2.99,12.52
+1981,-4.7,8.46,8.46,14.04,8.2,8.92
+1982,20.42,29.05,29.05,10.6,32.81,3.83
+1983,22.34,16.19,16.19,8.62,3.2,3.79
+1984,6.15,15.62,15.62,9.54,13.73,3.95
+1985,31.24,23.86,23.86,7.47,25.71,3.8
+1986,18.49,21.35,21.35,5.97,24.28,1.1
+1987,5.81,2.81,2.81,5.78,-4.96,4.43
+1988,16.54,14.38,14.38,6.67,8.22,4.42
+1989,31.48,15.95,15.95,8.11,17.69,4.65
+1990,-3.06,6.28,6.28,7.5,6.24,6.11
+1991,30.23,18.93,18.93,5.38,15.0,3.06
+1992,7.49,11.31,11.31,3.43,9.36,2.9
+1993,9.97,15.47,15.47,3.0,14.21,2.75
+1994,1.33,-0.97,-0.97,4.25,-8.04,2.67
+1995,37.2,21.29,21.29,5.49,23.48,2.54
+1996,22.68,3.42,3.42,5.01,1.43,3.32
+1997,33.1,12.75,12.75,5.06,9.94,1.7
+1998,28.34,7.63,7.63,4.78,14.92,1.61
+1999,20.89,0.91,0.91,4.64,-8.25,2.68
+2000,-9.03,9.39,9.39,5.82,16.66,3.39
+2001,-11.85,8.54,8.54,3.4,5.57,1.55
+2002,-21.97,12.14,12.14,1.61,15.12,2.38
+2003,28.36,12.32,12.32,1.01,0.38,1.88
+2004,10.74,10.35,10.35,1.37,4.49,3.26
+2005,4.83,5.3,5.3,3.15,2.87,3.42
+2006,15.61,5.2,5.2,4.73,1.96,2.54
+2007,5.48,4.84,4.84,4.36,10.21,4.08
+2008,-36.55,-3.54,-3.54,1.37,20.1,0.09
+2009,25.94,20.21,20.21,0.15,-11.12,2.72
+2010,14.82,9.41,9.41,0.14,8.46,1.5
+2011,2.1,12.26,12.26,0.05,16.04,2.96
+2012,15.89,9.33,9.33,0.09,2.97,1.74
+2013,32.15,-0.98,-0.98,0.06,-9.1,1.5
+2014,13.52,10.78,10.78,0.03,10.75,0.76
+2015,1.38,-1.5,-1.5,0.05,1.28,0.73
+2016,11.77,11.52,11.52,0.32,0.69,2.07
+2017,21.61,9.23,9.23,0.93,2.8,2.11
+2018,-4.23,-3.27,-3.27,1.94,-0.02,1.91
+2019,31.21,15.25,15.25,2.06,9.64,2.29
+2020,18.02,10.6,10.6,0.35,11.33,1.36
+2021,28.47,0.93,0.93,0.05,-4.42,7.04
+2022,-18.04,-15.14,-15.14,2.02,-17.83,6.45
+2023,26.06,8.74,8.74,5.07,3.88,3.35
+2024,24.88,1.74,1.74,4.97,-1.64,2.75

owlplanner/plan.py

@@ -315,7 +315,7 @@ class Plan(object):
         self._adjustedParameters = False
         self.timeListsFileName = "None"
         self.timeLists = {}
-        self.resetContributions()
+        self.zeroContributions()
         self.caseStatus = 'unsolved'
         self.rateMethod = None
 
@@ -900,10 +900,18 @@ class Plan(object):
         try:
             filename, self.timeLists = timelists.read(filename, self.inames, self.horizons, self.mylog)
         except Exception as e:
-            raise Exception('Unsuccessful read: %s' % e)
+            raise Exception('Unsuccessful read of contributions: %s' % e)
+            return False
 
-        timelists.check(self.inames, self.timeLists, self.horizons)
         self.timeListsFileName = filename
+        self.setContributions()
+
+        return True
+
+    def setContributions(self, timeLists=None):
+        if timeLists is not None:
+            timelists.check(timeLists, self.inames, self.horizons)
+            self.timeLists = timeLists
 
         # Now fill in parameters which are in $.
         for i, iname in enumerate(self.inames):
@@ -926,7 +934,7 @@ class Plan(object):
 
         self.caseStatus = 'modified'
 
-        return True
+        return self.timeLists
 
     def saveContributions(self):
         """
@@ -954,7 +962,7 @@ class Plan(object):
 
         return wb
 
-    def resetContributions(self):
+    def zeroContributions(self):
         """
         Reset all contributions variables to zero.
         """

owlplanner/rates.py

@@ -31,6 +31,8 @@ Disclaimer: This program comes with no guarantee. Use at your own risk.
 ###################################################################
 import numpy as np
 import pandas as pd
+import pkgutil
+import io
 from datetime import date
 
 from owlplanner import logging
@@ -41,673 +43,31 @@ from owlplanner import utils as u
 FROM = 1928
 TO = 2024
 
+try:
+    csvBytes = pkgutil.get_data('owlplanner', 'data/rates.csv')
+    csvFile = io.BytesIO(csvBytes)
+    df = pd.read_csv(csvFile)
+except Exception as e:
+    raise RuntimeError(f'Could not find rates data file: {e}')
+
+
 # Annual rate of return (%) of S&P 500 since 1928, including dividends.
-SP500 = [
-    43.81,
-    -8.30,
-    # 1930
-    -25.12,
-    -43.84,
-    -8.64,
-    49.98,
-    -1.19,
-    46.74,
-    31.94,
-    -35.34,
-    29.28,
-    -1.10,
-    # 1940
-    -10.67,
-    -12.77,
-    19.17,
-    25.06,
-    19.03,
-    35.82,
-    -8.43,
-    5.20,
-    5.70,
-    18.30,
-    # 1950
-    30.81,
-    23.68,
-    18.15,
-    -1.21,
-    52.56,
-    32.60,
-    7.44,
-    -10.46,
-    43.72,
-    12.06,
-    # 1960
-    0.34,
-    26.64,
-    -8.81,
-    22.61,
-    16.42,
-    12.40,
-    -9.97,
-    23.80,
-    10.81,
-    -8.24,
-    # 1970
-    3.56,
-    14.22,
-    18.76,
-    -14.31,
-    -25.90,
-    37.00,
-    23.83,
-    -6.98,
-    6.51,
-    18.52,
-    # 1980
-    31.74,
-    -4.70,
-    20.42,
-    22.34,
-    6.15,
-    31.24,
-    18.49,
-    5.81,
-    16.54,
-    31.48,
-    # 1990
-    -3.06,
-    30.23,
-    7.49,
-    9.97,
-    1.33,
-    37.20,
-    22.68,
-    33.10,
-    28.34,
-    20.89,
-    # 2000
-    -9.03,
-    -11.85,
-    -21.97,
-    28.36,
-    10.74,
-    4.83,
-    15.61,
-    5.48,
-    -36.55,
-    25.94,
-    # 2010
-    14.82,
-    2.10,
-    15.89,
-    32.15,
-    13.52,
-    1.38,
-    11.77,
-    21.61,
-    -4.23,
-    31.21,
-    # 2020
-    18.02,
-    28.47,
-    -18.04,
-    26.06,
-    24.88,
-]
+SP500 = df['S&P 500']
 
 # Annual rate of return (%) of Baa Corporate Bonds since 1928.
-BondsBaa = [
-    3.22,
-    3.02,
-    # 1930
-    0.54,
-    -15.68,
-    23.59,
-    12.97,
-    18.82,
-    13.31,
-    11.38,
-    -4.42,
-    9.24,
-    7.98,
-    # 1940
-    8.65,
-    5.01,
-    5.18,
-    8.04,
-    6.57,
-    6.80,
-    2.51,
-    0.26,
-    3.44,
-    5.38,
-    # 1950
-    4.24,
-    -0.19,
-    4.44,
-    1.62,
-    6.16,
-    2.04,
-    -2.35,
-    -0.72,
-    6.43,
-    1.57,
-    # 1960
-    6.66,
-    5.10,
-    6.50,
-    5.46,
-    5.16,
-    3.19,
-    -3.45,
-    0.90,
-    4.85,
-    -2.03,
-    # 1970
-    5.65,
-    14.00,
-    11.41,
-    4.32,
-    -4.38,
-    11.05,
-    19.75,
-    9.95,
-    3.14,
-    -2.01,
-    # 1980
-    -3.32,
-    8.46,
-    29.05,
-    16.19,
-    15.62,
-    23.86,
-    21.35,
-    2.81,
-    14.38,
-    15.95,
-    # 1990
-    6.28,
-    18.93,
-    11.31,
-    15.47,
-    -0.97,
-    21.29,
-    3.42,
-    12.75,
-    7.63,
-    0.91,
-    # 2000
-    9.39,
-    8.54,
-    12.14,
-    12.32,
-    10.35,
-    5.30,
-    5.20,
-    4.84,
-    -3.54,
-    20.21,
-    # 2010
-    9.41,
-    12.26,
-    9.33,
-    -0.98,
-    10.78,
-    -1.50,
-    11.52,
-    9.23,
-    -3.27,
-    15.25,
-    # 2020
-    10.60,
-    0.93,
-    -15.14,
-    8.74,
-    1.74,
-]
+BondsBaa = df['Bonds Baa']
 
 # Annual rate of return (%) of Aaa Corporate Bonds since 1928.
-BondsAaa = [
-    3.28,
-    4.14,
-    # 1930
-    5.86,
-    -1.56,
-    11.07,
-    5.30,
-    10.15,
-    6.90,
-    6.33,
-    2.17,
-    4.31,
-    4.28,
-    # 1940
-    4.93,
-    1.93,
-    2.71,
-    3.42,
-    3.09,
-    3.48,
-    2.61,
-    0.46,
-    3.46,
-    4.62,
-    # 1950
-    1.80,
-    -0.23,
-    3.35,
-    1.61,
-    5.10,
-    0.78,
-    -1.78,
-    3.26,
-    1.63,
-    0.14,
-    # 1960
-    6.41,
-    3.79,
-    5.86,
-    3.36,
-    3.64,
-    2.56,
-    -0.70,
-    -0.45,
-    4.32,
-    -2.18,
-    # 1970
-    8.27,
-    10.35,
-    8.44,
-    3.00,
-    -0.12,
-    9.54,
-    14.23,
-    6.58,
-    2.01,
-    -0.25,
-    # 1980
-    -2.55,
-    7.94,
-    27.89,
-    7.85,
-    14.80,
-    25.97,
-    18.95,
-    -0.85,
-    12.87,
-    14.39,
-    # 1990
-    7.72,
-    14.98,
-    9.84,
-    14.30,
-    -2.78,
-    21.16,
-    2.83,
-    11.26,
-    10.20,
-    -3.39,
-    # 2000
-    10.99,
-    11.09,
-    10.42,
-    9.54,
-    7.14,
-    6.73,
-    3.75,
-    5.84,
-    10.97,
-    -0.09,
-    # 2010
-    8.83,
-    13.99,
-    4.59,
-    -3.43,
-    11.56,
-    1.13,
-    4.53,
-    8.40,
-    -0.93,
-    12.08,
-    # 2020
-    10.23,
-    -1.93,
-    -12.88,
-    5.09,
-    -1.03,
-]
+BondsAaa = df['Bonds Aaa']
 
 # Annual rate of return (%) for 10-y Treasury notes since 1928.
-TNotes = [
-    0.84,
-    4.20,
-    # 1930
-    4.54,
-    -2.56,
-    8.79,
-    1.86,
-    7.96,
-    4.47,
-    5.02,
-    1.38,
-    4.21,
-    4.41,
-    # 1940
-    5.40,
-    -2.02,
-    2.29,
-    2.49,
-    2.58,
-    3.80,
-    3.13,
-    0.92,
-    1.95,
-    4.66,
-    # 1950
-    0.43,
-    -0.30,
-    2.27,
-    4.14,
-    3.29,
-    -1.34,
-    -2.26,
-    6.80,
-    -2.10,
-    -2.65,
-    # 1960
-    11.64,
-    2.06,
-    5.69,
-    1.68,
-    3.73,
-    0.72,
-    2.91,
-    -1.58,
-    3.27,
-    -5.01,
-    #  1970
-    16.75,
-    9.79,
-    2.82,
-    3.66,
-    1.99,
-    3.61,
-    15.98,
-    1.29,
-    -0.78,
-    0.67,
-    #  1980
-    -2.99,
-    8.20,
-    32.81,
-    3.20,
-    13.73,
-    25.71,
-    24.28,
-    -4.96,
-    8.22,
-    17.69,
-    # 1990
-    6.24,
-    15.00,
-    9.36,
-    14.21,
-    -8.04,
-    23.48,
-    1.43,
-    9.94,
-    14.92,
-    -8.25,
-    #  2000
-    16.66,
-    5.57,
-    15.12,
-    0.38,
-    4.49,
-    2.87,
-    1.96,
-    10.21,
-    20.10,
-    -11.12,
-    # 2010
-    8.46,
-    16.04,
-    2.97,
-    -9.10,
-    10.75,
-    1.28,
-    0.69,
-    2.80,
-    -0.02,
-    9.64,
-    # 2020
-    11.33,
-    -4.42,
-    -17.83,
-    3.88,
-    -1.64,
-]
+TNotes = df['TNotes']
 
 # Annual rates of return for 3-month Treasury bills since 1928.
-TBills = [
-    3.08,
-    3.16,
-    # 1930
-    4.55,
-    2.31,
-    1.07,
-    0.96,
-    0.28,
-    0.17,
-    0.17,
-    0.28,
-    0.07,
-    0.05,
-    # 1940
-    0.04,
-    0.13,
-    0.34,
-    0.38,
-    0.38,
-    0.38,
-    0.38,
-    0.60,
-    1.05,
-    1.12,
-    # 1950
-    1.20,
-    1.52,
-    1.72,
-    1.89,
-    0.94,
-    1.72,
-    2.62,
-    3.22,
-    1.77,
-    3.39,
-    # 1960
-    2.87,
-    2.35,
-    2.77,
-    3.16,
-    3.55,
-    3.95,
-    4.86,
-    4.29,
-    5.34,
-    6.67,
-    # 1970
-    6.39,
-    4.33,
-    4.06,
-    7.04,
-    7.85,
-    5.79,
-    4.98,
-    5.26,
-    7.18,
-    10.05,
-    # 1980
-    11.39,
-    14.04,
-    10.60,
-    8.62,
-    9.54,
-    7.47,
-    5.97,
-    5.78,
-    6.67,
-    8.11,
-    # 1990
-    7.50,
-    5.38,
-    3.43,
-    3.00,
-    4.25,
-    5.49,
-    5.01,
-    5.06,
-    4.78,
-    4.64,
-    # 2000
-    5.82,
-    3.40,
-    1.61,
-    1.01,
-    1.37,
-    3.15,
-    4.73,
-    4.36,
-    1.37,
-    0.15,
-    # 2010
-    0.14,
-    0.05,
-    0.09,
-    0.06,
-    0.03,
-    0.05,
-    0.32,
-    0.93,
-    1.94,
-    2.06,
-    # 2020
-    0.35,
-    0.05,
-    2.02,
-    5.07,
-    4.97,
-]
-
-# Inflation rate as U.S. CPI index (%) since 1928 (1914).
-Inflation = [
-    # 1.00, 1.98, 12.62, 18.10, 20.44, 14.55, 2.65,  # 1920
-    # -10.82, -2.31, 2.37, 0.00, 3.47, -1.12, -2.26,
-    -1.16,
-    0.58,
-    # 1930
-    -6.40,
-    -9.32,
-    -10.27,
-    0.76,
-    1.52,
-    2.99,
-    1.45,
-    2.86,
-    -2.78,
-    0.00,
-    # 1940
-    0.71,
-    9.93,
-    9.03,
-    2.96,
-    2.30,
-    2.25,
-    18.13,
-    8.84,
-    2.99,
-    -2.07,
-    # 1950
-    5.93,
-    6.00,
-    0.75,
-    0.75,
-    -0.74,
-    0.37,
-    2.99,
-    2.90,
-    1.76,
-    1.73,
-    # 1960
-    1.36,
-    0.67,
-    1.33,
-    1.64,
-    0.97,
-    1.92,
-    3.46,
-    3.04,
-    4.72,
-    6.20,
-    # 1970
-    5.57,
-    3.27,
-    3.41,
-    8.71,
-    12.34,
-    6.94,
-    4.86,
-    6.70,
-    9.02,
-    13.29,
-    # 1980
-    12.52,
-    8.92,
-    3.83,
-    3.79,
-    3.95,
-    3.80,
-    1.10,
-    4.43,
-    4.42,
-    4.65,
-    # 1990
-    6.11,
-    3.06,
-    2.90,
-    2.75,
-    2.67,
-    2.54,
-    3.32,
-    1.70,
-    1.61,
-    2.68,
-    # 2000
-    3.39,
-    1.55,
-    2.38,
-    1.88,
-    3.26,
-    3.42,
-    2.54,
-    4.08,
-    0.09,
-    2.72,
-    # 2010
-    1.50,
-    2.96,
-    1.74,
-    1.50,
-    0.76,
-    0.73,
-    2.07,
-    2.11,
-    1.91,
-    2.29,
-    # 2020
-    1.36,
-    7.04,
-    6.45,
-    3.35,
-    2.75,
-]
+TBills = df['TBills']
+
+# Inflation rate as U.S. CPI index (%) since 1928.
+Inflation = df['Inflation']
 
 
 def getRatesDistributions(frm, to, mylog=None):

owlplanner/timelists.py

@@ -19,60 +19,76 @@ from datetime import date
 import pandas as pd
 
 
+# Expected headers in each excel sheet, one per individual.
+timeHorizonItems = [
+    'year',
+    'anticipated wages',
+    'ctrb taxable',
+    'ctrb 401k',
+    'ctrb Roth 401k',
+    'ctrb IRA',
+    'ctrb Roth IRA',
+    'Roth X',
+    'big-ticket items',
+]
+
+
 def read(finput, inames, horizons, mylog):
     """
     Read listed parameters from an excel spreadsheet or through
     a dictionary of dataframes through Pandas.
-    Use one sheet for each individual with the following columns.
+    Use one sheet for each individual with the following 9 columns:
+    year, anticipated wages, ctrb taxable, ctrb 401k, ctrb Roth 401k,
+    ctrb IRA, ctrb Roth IRA, Roth X, and big-ticket items.
     Supports xls, xlsx, xlsm, xlsb, odf, ods, and odt file extensions.
-    Returs a list of dataframes.
+    Returs a dictionary of dataframes by individual's names.
     """
 
-    # Expected headers in each excel sheet, one per individual.
-    timeHorizonItems = [
-        'year',
-        'anticipated wages',
-        'ctrb taxable',
-        'ctrb 401k',
-        'ctrb Roth 401k',
-        'ctrb IRA',
-        'ctrb Roth IRA',
-        'Roth X',
-        'big-ticket items',
-    ]
+    mylog.vprint('Reading wages, contributions, conversions, and big-ticket items over time...')
 
-    timeLists = {}
-    thisyear = date.today().year
     if isinstance(finput, dict):
-        dfDict = finput
+        timeLists = finput
         finput = 'dictionary of DataFrames'
-        filename = 'dictionary of DataFrames'
+        streamName = 'dictionary of DataFrames'
     else:
         # Read all worksheets in memory but only process those with proper names.
         try:
             dfDict = pd.read_excel(finput, sheet_name=None)
         except Exception as e:
             raise Exception('Could not read file %r: %s.' % (finput, e))
-        filename = "file '%s'" % finput
+        streamName = "file '%s'" % finput
 
-    mylog.vprint('Reading wages, contributions, conversions, and big-ticket items over time...')
+        timeLists = condition(dfDict, inames, horizons, mylog)
+
+    mylog.vprint("Successfully read time horizons from %s." % streamName)
+
+    return finput, timeLists
+
+
+def condition(dfDict, inames, horizons, mylog):
+    """
+    Make sure that time horizons contain all years up to life expectancy,
+    and that values are positive (except big-ticket items).
+    """
+    timeLists = {}
+    thisyear = date.today().year
     for i, iname in enumerate(inames):
-        mylog.vprint('\tfor %s...' % iname)
         endyear = thisyear + horizons[i]
+
         if iname not in dfDict:
-            raise RuntimeError("Could not find a sheet for %s in %s." % (iname, filename))
+            raise ValueError(f"No sheet found for {iname}.")
 
         df = dfDict[iname]
-        # Check all columns.
-        for col in timeHorizonItems:
-            if col not in df.columns:
-                raise ValueError('Missing column %s in dataframe for %s.' % (col, iname))
 
         df = df.loc[:, ~df.columns.str.contains('^Unnamed')]
         for col in df.columns:
             if col == '' or col not in timeHorizonItems:
                 df.drop(col, axis=1)
 
+        for item in timeHorizonItems:
+            if item not in df.columns:
+                raise ValueError(f"Item {item} not found for {iname}.")
+
         # Only consider lines in proper year range.
         df = df[df['year'] >= thisyear]
         df = df[df['year'] < endyear]
@@ -82,9 +98,15 @@ def read(finput, inames, horizons, mylog):
             if not (df[df['year'] == year]).any(axis=None):
                 df.loc[len(df)] = [year, 0, 0, 0, 0, 0, 0, 0, 0]
                 missing.append(year)
+            else:
+                for item in timeHorizonItems:
+                    if item != 'big-ticket items' and df[item].iloc[n] < 0:
+                        raise ValueError('Item %s for %s in year %d is < 0.'
+                                         % (item, iname, df['year'].iloc[n])
+                                         )
 
         if len(missing) > 0:
-            mylog.vprint('\tAdding %d missing years for %s: %r.' % (len(missing), iname, missing))
+            mylog.vprint('Adding %d missing years for %s: %r.' % (len(missing), iname, missing))
 
         df.sort_values('year', inplace=True)
         # Replace empty (NaN) cells with 0 value.
@@ -92,53 +114,10 @@ def read(finput, inames, horizons, mylog):
 
         timeLists[iname] = df
 
-    mylog.vprint("Successfully read time horizons from %s." % filename)
-
-    return finput, timeLists
-
+        if df['year'].iloc[-1] != endyear - 1:
+            raise ValueError('Time horizon for', iname,
+                             'is too short.\n\tIt should end in',
+                             endyear, 'but ends in', df['year'].iloc[-1]
+                             )
 
-def check(inames, timeLists, horizons):
-    """
-    Make sure that time horizons contain all years up to life expectancy.
-    """
-    if len(inames) == 2:
-        # Verify that both sheets start on the same year.
-        if timeLists[inames[0]]['year'].iloc[0] != timeLists[inames[1]]['year'].iloc[0]:
-            raise RuntimeError('Time horizons not starting on same year.')
-
-    # Verify that year range covers life expectancy for each individual
-    thisyear = date.today().year
-    for i, iname in enumerate(inames):
-        yend = thisyear + horizons[i]
-        if timeLists[iname]['year'].iloc[-1] < yend - 1:
-            raise RuntimeError(
-                'Time horizon for',
-                iname,
-                'is too short.\n\tIt should end in',
-                yend,
-                'but ends in',
-                timeLists[iname]['year'].iloc[-1],
-            )
-
-    timeHorizonItems = [
-        'year',
-        'anticipated wages',
-        'ctrb taxable',
-        'ctrb 401k',
-        'ctrb Roth 401k',
-        'ctrb IRA',
-        'ctrb Roth IRA',
-        'Roth X',
-    ]
-
-    # Verify that all numbers except bti are positive.
-    for i, iname in enumerate(inames):
-        for item in timeHorizonItems:
-            for n in range(horizons[i]):
-                assert timeLists[iname][item].iloc[n] >= 0, 'Item %s for %s in year %d is < 0.' % (
-                    item,
-                    iname,
-                    timeLists[iname]['year'].iloc[n],
-                )
-
-    return
+    return timeLists

owlplanner/version.py

@@ -1 +1 @@
-__version__ = "2025.1.24"
+__version__ = "2025.1.27"

{owlplanner-2025.1.24.dist-info → owlplanner-2025.1.27.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.1.24
+Version: 2025.1.27
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -698,6 +698,7 @@ Requires-Dist: pandas
 Requires-Dist: scipy
 Requires-Dist: seaborn
 Requires-Dist: streamlit
+Requires-Dist: toml
 Description-Content-Type: text/markdown
 
 
@@ -707,6 +708,15 @@ Description-Content-Type: text/markdown
 
 <img align=right src="https://raw.github.com/mdlacasse/Owl/main/docs/images/owl.png" width="250">
 
+-----
+
+### TLDR
+Owl is a planning tool that uses a linear programming optimization algorithm to provide guidance on retirement decisions.
+
+Go to [owlplanner.streamlit.app](https://owlplanner.streamlit.app) and explore the app to learn about its capabilities.
+
+-----
+
 This package is a retirement modeling framework for exploring the sensitivity of retirement financial decisions.
 Strictly speaking, it is not a planning tool, but more an environment for exploring *what if* scenarios.
 It provides different realizations of a financial strategy through the rigorous

owlplanner-2025.1.27.dist-info/RECORD

@@ -0,0 +1,17 @@
+owlplanner/__init__.py,sha256=QqrdT0Qks20osBTg7h0vJHAxpP9lL7DA99xb0nYbtw4,254
+owlplanner/abcapi.py,sha256=eemIsdbtzdWCIj5VuuswgphxXMcxJ_GZfUlDi6lttFM,6658
+owlplanner/config.py,sha256=ouADb6YES5Zgv0UwnEK9Axwvs8drp-ahboQjI4WTrr0,12069
+owlplanner/logging.py,sha256=pXg_mMgBll-kklqaDRLDNVUFo-5DAa-yqTKtiVrhNWw,2530
+owlplanner/plan.py,sha256=eRX04KT8DVkWD6sFzqm18OZZazSONQviuIYe7WNW7BM,115405
+owlplanner/progress.py,sha256=YZjL5_m4MMgKPlWlhhKacPLt54tVhVGF1eXxxZapMYs,386
+owlplanner/rates.py,sha256=7o4F4hlRHr8epZGBl7rUDQQDhKR6OMnDSRg7OEgh3sc,15628
+owlplanner/tax2025.py,sha256=W3yXKC3rgcqPjZMguOyejgsox9J42w3ogBNN1mIBHBI,6965
+owlplanner/timelists.py,sha256=ifxbyMlRW3IMwsiu8zsoodA1CKJQthgk3iPq50vQIds,4104
+owlplanner/utils.py,sha256=adIwqGVQFfvekke0JCxYJD3PKHbptVCj3NrQT2TQIB4,2351
+owlplanner/version.py,sha256=DmL4UDn0l9KwBvfubL0ZjwP_lUKHu2amlvxJShNQMO0,27
+owlplanner/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+owlplanner/data/rates.csv,sha256=6fxg56BVVORrj9wJlUGFdGXKvOX5r7CSca8uhUbbuIU,3734
+owlplanner-2025.1.27.dist-info/METADATA,sha256=qAUeEqSZPQiN6N37IkvN4M81R38TS5AaS9BpEirwHkc,64515
+owlplanner-2025.1.27.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+owlplanner-2025.1.27.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+owlplanner-2025.1.27.dist-info/RECORD,,

owlplanner/tax2024.py

@@ -1,234 +0,0 @@
-"""
-
-Owl/tax2024
----
-
-A retirement planner using linear programming optimization.
-
-See companion document for a complete explanation and description
-of all variables and parameters.
-
-Module to handle all tax calculations.
-
-Copyright (C) 2024 -- Martin-D. Lacasse
-
-Disclaimer: This program comes with no guarantee. Use at your own risk.
-"""
-
-import numpy as np
-from datetime import date
-
-
-##############################################################################
-# Prepare the data.
-
-taxBracketNames = ['10%', '12/15%', '22/25%', '24/28%', '32/33%', '35%', '37/40%']
-
-rates_2024 = np.array([0.10, 0.12, 0.22, 0.24, 0.32, 0.35, 0.370])
-rates_2026 = np.array([0.10, 0.15, 0.25, 0.28, 0.33, 0.35, 0.396])
-
-# Single [0] and married filing jointly [1].
-taxBrackets_2024 = np.array(
-    [
-        [11600, 47150, 100525, 191950, 243450, 609350, 9999999],
-        [23200, 94300, 201050, 383900, 487450, 731200, 9999999],
-    ]
-)
-
-irmaaBrackets = np.array([[0, 103000, 129000, 161000, 193000, 500000], [0, 206000, 258000, 322000, 386000, 750000]])
-
-# medicareBasis_2024 = 12 * 174.70
-# [174.70, 244.60, 349.40, 454.20, 559.00, 594.00]
-irmaaFees = 12 * np.array([174.70, 69.90, 104.80, 104.80, 104.80, 35.00])
-
-# taxBrackets_2017 = np.array(
-#     [[9325, 37950, 91900, 191650, 416700, 418400, 9999999],
-#     [18650, 75900, 153100, 233350, 416700, 470000, 9999999]])
-
-# Adjusted from 2017 to 2024 with 27% increase.
-taxBrackets_2026 = np.array(
-    [
-        [11850, 48200, 116700, 243400, 529200, 531400, 9999999],
-        [23700, 96400, 194400, 296350, 529200, 596900, 9999999],
-    ]
-)
-
-stdDeduction_2024 = np.array([14600, 29200])
-stdDeduction_2026 = np.array([8300, 16600])
-extraDeduction_65 = np.array([1950, 1550])
-
-
-##############################################################################
-
-
-def mediCosts(yobs, horizons, magi, gamma_n, Nn):
-    """
-    Compute Medicare costs directly.
-    Birth years, life horizons, MAGI time series, inflation time series gamma_n,
-    and total number of years in the plan are provided.
-    """
-    thisyear = date.today().year
-    Ni = len(yobs)
-    medicosts = np.zeros(Nn)
-    for n in range(Nn):
-        medicount = 0
-        for i in range(Ni):
-            if thisyear + n - yobs[i] >= 65 and n < horizons[i]:
-                medicount += 1
-
-        if medicount == 0:
-            continue
-
-        fac = medicount * gamma_n[n]
-        medicosts[n] += fac * irmaaFees[0]
-        nx = max(0, n - 2)
-        for q in range(1, 6):
-            if magi[nx] > gamma_n[n] * irmaaBrackets[medicount - 1][q]:
-                medicosts[n] += fac * irmaaFees[q]
-
-    return medicosts
-
-
-def taxParams(yobs, i_d, n_d, N_n):
-    """
-    Return 3 time series:
-    1) Standard deductions at year n (sigma_n).
-    2) Tax rate in year n (theta_tn)
-    3) Delta from top to bottom of tax brackets (Delta_tn)
-    This is pure speculation on future values.
-    Returned values are not indexed for inflation.
-    """
-    # Compute the deltas in-place between brackets, starting from the end.
-    deltaBrackets_2024 = np.array(taxBrackets_2024)
-    deltaBrackets_2026 = np.array(taxBrackets_2026)
-    for t in range(6, 0, -1):
-        for i in range(2):
-            deltaBrackets_2024[i, t] -= deltaBrackets_2024[i, t - 1]
-            deltaBrackets_2026[i, t] -= deltaBrackets_2026[i, t - 1]
-
-    # Prepare the 3 arrays to return - use transpose for easy slicing.
-    sigma = np.zeros((N_n))
-    Delta = np.zeros((N_n, 7))
-    theta = np.zeros((N_n, 7))
-
-    filingStatus = len(yobs) - 1
-    souls = list(range(len(yobs)))
-    thisyear = date.today().year
-
-    for n in range(N_n):
-        # First check if shortest-lived individual is still with us.
-        if n == n_d:
-            souls.remove(i_d)
-            filingStatus -= 1
-
-        if thisyear + n < 2026:
-            sigma[n] = stdDeduction_2024[filingStatus]
-            Delta[n, :] = deltaBrackets_2024[filingStatus, :]
-        else:
-            sigma[n] = stdDeduction_2026[filingStatus]
-            Delta[n, :] = deltaBrackets_2026[filingStatus, :]
-
-        # Add 65+ additional exemption(s).
-        for i in souls:
-            if thisyear + n - yobs[i] >= 65:
-                sigma[n] += extraDeduction_65[filingStatus]
-
-        # Fill in future tax rates for year n.
-        if thisyear + n < 2026:
-            theta[n, :] = rates_2024[:]
-        else:
-            theta[n, :] = rates_2026[:]
-
-    Delta = Delta.transpose()
-    theta = theta.transpose()
-
-    # Return series unadjusted for inflation, in STD order.
-    return sigma, theta, Delta
-
-
-def taxBrackets(N_i, n_d, N_n):
-    """
-    Return dictionary containing future tax brackets
-    unadjusted for inflation for plotting.
-    """
-    assert 0 < N_i and N_i <= 2, 'Cannot process %d individuals.' % N_i
-    # This 2 is the number of years left in TCJA from 2024.
-    ytc = 2
-    status = N_i - 1
-    n_d = min(n_d, N_n)
-
-    data = {}
-    for t in range(len(taxBracketNames) - 1):
-        array = np.zeros(N_n)
-        array[0:ytc] = taxBrackets_2024[status][t]
-        array[ytc:n_d] = taxBrackets_2026[status][t]
-        array[n_d:N_n] = taxBrackets_2026[0][t]
-        data[taxBracketNames[t]] = array
-
-    return data
-
-
-def rho_in(yobs, N_n):
-    """
-    Return Required Minimum Distribution fractions for each individual.
-    This implementation does not support spouses with more than
-    10-year difference.
-    It starts at age 73 until it goes to 75 in 2033.
-    """
-    # Notice that table starts at age 72.
-    rmdTable = [
-        27.4,
-        26.5,
-        25.5,
-        24.6,
-        23.7,
-        22.9,
-        22.0,
-        21.1,
-        20.2,
-        19.4,
-        18.5,
-        17.7,
-        16.8,
-        16.0,
-        15.2,
-        14.4,
-        13.7,
-        12.9,
-        12.2,
-        11.5,
-        10.8,
-        10.1,
-        9.5,
-        8.9,
-        8.4,
-        7.8,
-        7.3,
-        6.8,
-        6.4,
-        6.0,
-        5.6,
-        5.2,
-        4.9,
-        4.6,
-    ]
-
-    N_i = len(yobs)
-    if N_i == 2 and abs(yobs[0] - yobs[1]) > 10:
-        raise RuntimeError('RMD: Unsupported age difference of more than 10 years.')
-
-    rho = np.zeros((N_i, N_n))
-    thisyear = date.today().year
-    for i in range(N_i):
-        agenow = thisyear - yobs[i]
-        for n in range(N_n):
-            year = thisyear + n
-            yage = agenow + n
-
-            # Account for increase of RMD age between 2023 and 2032.
-            if (yage < 73) or (year > 2032 and yage < 75):
-                pass  # rho[i][n] = 0
-            else:
-                rho[i][n] = 1.0 / rmdTable[yage - 72]
-
-    return rho

owlplanner-2025.1.24.dist-info/RECORD

@@ -1,16 +0,0 @@
-owlplanner/__init__.py,sha256=QqrdT0Qks20osBTg7h0vJHAxpP9lL7DA99xb0nYbtw4,254
-owlplanner/abcapi.py,sha256=eemIsdbtzdWCIj5VuuswgphxXMcxJ_GZfUlDi6lttFM,6658
-owlplanner/config.py,sha256=ouADb6YES5Zgv0UwnEK9Axwvs8drp-ahboQjI4WTrr0,12069
-owlplanner/logging.py,sha256=pXg_mMgBll-kklqaDRLDNVUFo-5DAa-yqTKtiVrhNWw,2530
-owlplanner/plan.py,sha256=hBDT8twND4ddXxfnm3O9MG3HAtwbPAyfhej1BzbrZpE,115173
-owlplanner/progress.py,sha256=YZjL5_m4MMgKPlWlhhKacPLt54tVhVGF1eXxxZapMYs,386
-owlplanner/rates.py,sha256=MY-jnTdld50gRytPa_LtlS0RwTDFbhN-YlgCg9fF1jw,22801
-owlplanner/tax2024.py,sha256=qiGZCWv02Y8Ip3lmQCZT1kFpsnFYwj5cHlpB2Lh1dt8,6820
-owlplanner/tax2025.py,sha256=W3yXKC3rgcqPjZMguOyejgsox9J42w3ogBNN1mIBHBI,6965
-owlplanner/timelists.py,sha256=n1ZWCN8cyW1o9sAJLKZRDzZITgwjMWUUKcGjXqyXcNE,4729
-owlplanner/utils.py,sha256=adIwqGVQFfvekke0JCxYJD3PKHbptVCj3NrQT2TQIB4,2351
-owlplanner/version.py,sha256=UAr2KgRbggn8uPi5Qz9zJrAznnf2fpeRuFB_a4TVwhE,27
-owlplanner-2025.1.24.dist-info/METADATA,sha256=cdMc1W357-STYficByVJ_CSNA0Xycqzd3ka0_ITSktA,64228
-owlplanner-2025.1.24.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-owlplanner-2025.1.24.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-owlplanner-2025.1.24.dist-info/RECORD,,