owlplanner 2025.5.3__py3-none-any.whl → 2025.5.12__py3-none-any.whl

owlplanner/rates.py

@@ -35,7 +35,7 @@ import os
 import sys
 from datetime import date
 
-from owlplanner import logging
+from owlplanner import mylogging as log
 from owlplanner import utils as u
 
 # All data goes from 1928 to 2024. Update the TO value when data
@@ -48,7 +48,7 @@ file = os.path.join(where, "data/rates.csv")
 try:
     df = pd.read_csv(file)
 except Exception as e:
-    raise RuntimeError(f"Could not find rates data file: {e}")
+    raise RuntimeError(f"Could not find rates data file: {e}") from e
 
 
 # Annual rate of return (%) of S&P 500 since 1928, including dividends.
@@ -77,14 +77,17 @@ def getRatesDistributions(frm, to, mylog=None):
     the different rates. Function returns means and covariance matrix.
     """
     if mylog is None:
-        mylog = logging.Logger()
+        mylog = log.Logger()
 
     # Convert years to index and check range.
     frm -= FROM
     to -= FROM
-    assert 0 <= frm and frm <= len(SP500), 'Range "from" out of bounds.'
-    assert 0 <= to and to <= len(SP500), 'Range "to" out of bounds.'
-    assert frm <= to, '"from" must be smaller than "to".'
+    if not (0 <= frm and frm <= len(SP500)):
+        raise ValueError(f"Range 'from' {frm} out of bounds.")
+    if not (0 <= to and to <= len(SP500)):
+        raise ValueError(f"Range 'to' {to} out of bounds.")
+    if frm >= to:
+        raise ValueError(f'"from" {frm} must be smaller than "to" {to}.')
 
     series = {
         "SP500": SP500,
@@ -124,9 +127,12 @@ def historicalValue(amount, year):
     valued at the beginning of the year specified.
     """
     thisyear = date.today().year
-    assert TO == thisyear - 1, f"Rates file needs to be updated to be current to {thisyear}."
-    assert year >= FROM, f"Only data from {FROM} is available."
-    assert year <= thisyear, f"Year must be < {thisyear} for historical data."
+    if TO != thisyear - 1:
+        raise RuntimeError(f"Rates file needs to be updated to be current to {thisyear}.")
+    if year < FROM:
+        raise ValueError(f"Only data from {FROM} is available.")
+    if year > thisyear:
+        raise ValueError(f"Year must be < {thisyear} for historical data.")
 
     span = thisyear - year
     ub = len(Inflation)
@@ -153,7 +159,7 @@ class Rates(object):
         Default constructor.
         """
         if mylog is None:
-            self.mylog = logging.Logger()
+            self.mylog = log.Logger()
         else:
             self.mylog = mylog
 
@@ -223,18 +229,24 @@ class Rates(object):
             self.mylog.vprint("Using conservative fixed rates values:", *[u.pc(k) for k in self.means])
             self._setFixedRates(self._conservRates)
         elif method == "user":
-            assert values is not None, "Fixed values must be provided with the user option."
-            assert len(values) == Nk, f"Values must have {Nk} items."
+            if values is None:
+                raise ValueError("Fixed values must be provided with the user option.")
+            if len(values) != Nk:
+                raise ValueError(f"Values must have {Nk} items.")
             self.means = np.array(values, dtype=float)
             # Convert percent to decimal for storing.
             self.means /= 100.0
             self.mylog.vprint("Setting rates using fixed user values:", *[u.pc(k) for k in self.means])
             self._setFixedRates(self.means)
         elif method == "stochastic":
-            assert values is not None, "Mean values must be provided with the stochastic option."
-            assert stdev is not None, "Standard deviations must be provided with the stochastic option."
-            assert len(values) == Nk, f"Values must have {Nk} items."
-            assert len(stdev) == Nk, f"stdev must have {Nk} items."
+            if values is None:
+                raise ValueError("Mean values must be provided with the stochastic option.")
+            if stdev is None:
+                raise ValueError("Standard deviations must be provided with the stochastic option.")
+            if len(values) != Nk:
+                raise ValueError(f"Values must have {Nk} items.")
+            if len(stdev) != Nk:
+                raise ValueError(f"stdev must have {Nk} items.")
             self.means = np.array(values, dtype=float)
             self.stdev = np.array(stdev, dtype=float)
             # Convert percent to decimal for storing.
@@ -262,7 +274,8 @@ class Rates(object):
                     raise RuntimeError(f"Unable to process correlation shape of {corrarr.shape}.")
 
             self.corr = corrarr
-            assert np.array_equal(self.corr, self.corr.T), "Correlation matrix must be symmetric."
+            if not np.array_equal(self.corr, self.corr.T):
+                raise ValueError("Correlation matrix must be symmetric.")
             # Now build covariance matrix from stdev and correlation matrix.
             # Multiply each row by a vector element-wise. Then columns.
             covar = self.corr * self.stdev
@@ -273,10 +286,14 @@ class Rates(object):
             self.mylog.vprint("\t and correlation matrix:\n\t\t", str(self.corr).replace("\n", "\n\t\t"))
         else:
             # Then methods relying on historical data range.
-            assert frm is not None, "From year must be provided with this option."
-            assert FROM <= frm and frm <= TO, f"Lower range 'frm={frm}' out of bounds."
-            assert FROM <= to and to <= TO, f"Upper range 'to={to}' out of bounds."
-            assert frm < to, "Unacceptable range."
+            if frm is None:
+                raise ValueError("From year must be provided with this option.")
+            if not (FROM <= frm <= TO):
+                raise ValueError(f"Lower range 'frm={frm}' out of bounds.")
+            if not (FROM <= to <= TO):
+                raise ValueError(f"Upper range 'to={to}' out of bounds.")
+            if not (frm < to):
+                raise ValueError("Unacceptable range.")
             self.frm = frm
             self.to = to
 
@@ -300,7 +317,8 @@ class Rates(object):
 
     def _setFixedRates(self, rates):
         Nk = len(self._defRates)
-        assert len(rates) == Nk, f"Rate list provided must have {Nk} entries."
+        if len(rates) != Nk:
+            raise ValueError(f"Rate list provided must have {Nk} entries.")
         self._myRates = np.array(rates)
         self._rateMethod = self._fixedRates
 
@@ -364,49 +382,3 @@ class Rates(object):
         srates = np.random.multivariate_normal(self.means, self.covar)
 
         return srates
-
-
-def showRatesDistributions(frm=FROM, to=TO):
-    """
-    Plot histograms of the rates distributions.
-    """
-    import matplotlib.pyplot as plt
-
-    title = "Rates from " + str(frm) + " to " + str(to)
-    # Bring year values to indices.
-    frm -= FROM
-    to -= FROM
-
-    nbins = int((to - frm) / 4)
-    fig, ax = plt.subplots(1, 4, sharey=True, sharex=True, tight_layout=True)
-
-    dat0 = np.array(SP500[frm:to])
-    dat1 = np.array(BondsBaa[frm:to])
-    dat2 = np.array(TNotes[frm:to])
-    dat3 = np.array(Inflation[frm:to])
-
-    fig.suptitle(title)
-    ax[0].set_title("S&P500")
-    label = "<>: " + u.pc(np.mean(dat0), 2, 1)
-    ax[0].hist(dat0, bins=nbins, label=label)
-    ax[0].legend(loc="upper left", fontsize=8, framealpha=0.7)
-
-    ax[1].set_title("BondsBaa")
-    label = "<>: " + u.pc(np.mean(dat1), 2, 1)
-    ax[1].hist(dat1, bins=nbins, label=label)
-    ax[1].legend(loc="upper left", fontsize=8, framealpha=0.7)
-
-    ax[2].set_title("TNotes")
-    label = "<>: " + u.pc(np.mean(dat2), 2, 1)
-    ax[2].hist(dat1, bins=nbins, label=label)
-    ax[2].legend(loc="upper left", fontsize=8, framealpha=0.7)
-
-    ax[3].set_title("Inflation")
-    label = "<>: " + u.pc(np.mean(dat3), 2, 1)
-    ax[3].hist(dat3, bins=nbins, label=label)
-    ax[3].legend(loc="upper left", fontsize=8, framealpha=0.7)
-
-    plt.show()
-
-    # return fig, ax
-    return None

owlplanner/tax2025.py

@@ -172,7 +172,8 @@ def taxBrackets(N_i, n_d, N_n, y_TCJA):
     Return dictionary containing future tax brackets
     unadjusted for inflation for plotting.
     """
-    assert 0 < N_i and N_i <= 2, f"Cannot process {N_i} individuals."
+    if not (0 < N_i <= 2):
+        raise ValueError(f"Cannot process {N_i} individuals.")
     n_d = min(n_d, N_n)
     status = N_i - 1
 

owlplanner/timelists.py

@@ -55,7 +55,7 @@ def read(finput, inames, horizons, mylog):
         try:
             dfDict = pd.read_excel(finput, sheet_name=None)
         except Exception as e:
-            raise Exception(f"Could not read file {finput}: {e}.")
+            raise Exception(f"Could not read file {finput}: {e}.") from e
         streamName = f"file '{finput}'"
 
         timeLists = condition(dfDict, inames, horizons, mylog)
@@ -83,7 +83,7 @@ def condition(dfDict, inames, horizons, mylog):
         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)
+                df.drop(col, axis=1, inplace=True)
 
         for item in timeHorizonItems:
             if item not in df.columns:
@@ -114,12 +114,7 @@ def condition(dfDict, inames, horizons, mylog):
 
         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],
+                f"Time horizon for {iname} too short.\n\tIt should end in {endyear}, not {df['year'].iloc[-1]}"
             )
 
     return timeLists

owlplanner/version.py

@@ -1 +1 @@
-__version__ = "2025.05.03"
+__version__ = "2025.05.12"

{owlplanner-2025.5.3.dist-info → owlplanner-2025.5.12.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.5.3
+Version: 2025.5.12
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -695,6 +695,7 @@ Requires-Dist: matplotlib
 Requires-Dist: numpy
 Requires-Dist: openpyxl
 Requires-Dist: pandas
+Requires-Dist: plotly
 Requires-Dist: scipy
 Requires-Dist: seaborn
 Requires-Dist: streamlit
@@ -711,15 +712,17 @@ Description-Content-Type: text/markdown
 -------------------------------------------------------------------------------------
 
 ### TL;DR
-Owl is a retirement planning tool that uses a linear programming optimization algorithm
-to provide guidance on retirement decisions, including Roth conversions.
+Owl is a financial retirement planning tool that uses a linear programming
+optimization algorithm to provide guidance on retirement decisions
+such as contributions, withdrawals, Roth conversions, and more.
 Users can select varying return rates to perform historical back testing,
 stochastic rates for performing Monte Carlo analyses,
 or fixed rates either derived from historical averages, or set by the user.
 
 There are a few ways to run Owl:
 
-- Run Owl directly on the Streamlit Community Server at [owlplanner.streamlit.app](https://owlplanner.streamlit.app).
+- Run Owl directly on the Streamlit Community Server at
+[owlplanner.streamlit.app](https://owlplanner.streamlit.app).
 
 - Run locally on your computer using a Docker image.
 Follow these [instructions](docker/README.md) for this option.
@@ -729,7 +732,7 @@ Follow these [instructions](INSTALL.md) to install Owl from the source code and
 
 -------------------------------------------------------------------------------------
 ## Overview
-This package is a retirement modeling framework for exploring the sensitivity of retirement financial decisions.
+This package is a 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
 mathematical optimization of relevant decision variables. Two major objective goals can be set: either

owlplanner-2025.5.12.dist-info/RECORD

@@ -0,0 +1,22 @@
+owlplanner/__init__.py,sha256=hJ2i4m2JpHPAKyQLjYOXpJzeEsgcTcKD-Vhm0AIjjWg,592
+owlplanner/abcapi.py,sha256=m0vtoEzz9HJV7fOK_d7OnK7ha2Qbf7wLLPCJ9YZzR1k,6851
+owlplanner/config.py,sha256=qIWzj3Tbz_jhhFqIkaMzXzgWQBN4Uk2km_VIMZSh910,12559
+owlplanner/mylogging.py,sha256=tYMw04O-XYSzjTj36fmKJGLcE1VkK6k6oJNeqtKXzuc,2530
+owlplanner/plan.py,sha256=_Oq2UomWzteYVlT6zJC_A2zXO3YVlXG9xgUMcQfWBJg,106742
+owlplanner/progress.py,sha256=8jlCvvtgDI89zXVNMBg1-lnEyhpPvKQS2X5oAIpoOVQ,384
+owlplanner/rates.py,sha256=MiaibxJY82JGpAhGyF2BJTm5-rmVAUuG8KLApVQhjvU,14816
+owlplanner/tax2025.py,sha256=wmlZpYeeGNrbyn5g7wOFqhWbggppodtHqc-ex5XRooI,7850
+owlplanner/timelists.py,sha256=wNYnJqxJ6QqE6jHh5lfFqYngfw5wUFrI15LSsM5ae8s,3949
+owlplanner/utils.py,sha256=WpJgn79YZfH8UCkcmhd-AZlxlGuz1i1-UDBRXImsY6I,2485
+owlplanner/version.py,sha256=5ZqN4YDTyjz76bfj2w5OuF_20x5Fau01NRLJ8nXtxx8,28
+owlplanner/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+owlplanner/data/rates.csv,sha256=6fxg56BVVORrj9wJlUGFdGXKvOX5r7CSca8uhUbbuIU,3734
+owlplanner/plotting/__init__.py,sha256=VnF6ui78YrTrg1dA6hBIdI02ahzEaHVR3ZEdDe_i880,103
+owlplanner/plotting/base.py,sha256=1bU6iM1pGIE-l9p0GuulX4gRK_7ds96784Wb5oVUUR0,2449
+owlplanner/plotting/factory.py,sha256=i1k8m_ISnJw06f_JWlMvOQ7Q0PgV_BoLm05uLwFPvOQ,883
+owlplanner/plotting/matplotlib_backend.py,sha256=-M4Am7N0D8Nfv_tKNA1TneFYU_DuW_ZsoUBHRQWD_ok,17887
+owlplanner/plotting/plotly_backend.py,sha256=LUmeWYAA_F1vdl-GPehzprVx3oFWehGmc1Oir-kNJ_w,33093
+owlplanner-2025.5.12.dist-info/METADATA,sha256=w0R8yDGSwrRGCouu2Hbe0Cx4tvQInuwm6VcvHcjFN9Q,53983
+owlplanner-2025.5.12.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+owlplanner-2025.5.12.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
+owlplanner-2025.5.12.dist-info/RECORD,,

owlplanner-2025.5.3.dist-info/RECORD

@@ -1,17 +0,0 @@
-owlplanner/__init__.py,sha256=QqrdT0Qks20osBTg7h0vJHAxpP9lL7DA99xb0nYbtw4,254
-owlplanner/abcapi.py,sha256=Lt8OUgbrfOPzAw0HyxyT2wT-IXI3d9Zo26MwyqdX56Y,6617
-owlplanner/config.py,sha256=F6GS3n02VeFX0GCVeM4J7Ra0in4N632W6TZIXk7Yj2w,12519
-owlplanner/logging.py,sha256=tYMw04O-XYSzjTj36fmKJGLcE1VkK6k6oJNeqtKXzuc,2530
-owlplanner/plan.py,sha256=mKSfHqFdG8P9Dlse-VbTnWSEgO2ZDcqAfK3gHYNEIho,119112
-owlplanner/progress.py,sha256=8jlCvvtgDI89zXVNMBg1-lnEyhpPvKQS2X5oAIpoOVQ,384
-owlplanner/rates.py,sha256=gJaoe-gJqWCQV5qVLlHp-Yn9TSJs-PJzeTbOwMCbqWs,15682
-owlplanner/tax2025.py,sha256=JDBtFFAf2bWtKUMuE3W5F0nBhYaKBjmdJj0iayM2iGA,7829
-owlplanner/timelists.py,sha256=tYieZU67FT6TCcQQis36JaXGI7dT6NqD7RvdEjgJL4M,4026
-owlplanner/utils.py,sha256=WpJgn79YZfH8UCkcmhd-AZlxlGuz1i1-UDBRXImsY6I,2485
-owlplanner/version.py,sha256=NZ889ANsXH5BzjEmfYGvqRdWan3eQSUgEGwPnMds764,28
-owlplanner/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-owlplanner/data/rates.csv,sha256=6fxg56BVVORrj9wJlUGFdGXKvOX5r7CSca8uhUbbuIU,3734
-owlplanner-2025.5.3.dist-info/METADATA,sha256=eGnBmMVTpNCvwzG153HRjN1rzzrD0zu1hQn1tV0SroA,53926
-owlplanner-2025.5.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-owlplanner-2025.5.3.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-owlplanner-2025.5.3.dist-info/RECORD,,