owlplanner 2025.5.5__py3-none-any.whl → 2025.5.15__py3-none-any.whl

owlplanner/__init__.py

@@ -2,5 +2,7 @@ from owlplanner.plan import Plan                                              #
 from owlplanner.plan import clone                                             # noqa: F401
 from owlplanner.config import readConfig                                      # noqa: F401
 from owlplanner.rates import getRatesDistributions                            # noqa: F401
-from owlplanner.rates import showRatesDistributions                           # noqa: F401
 from owlplanner.version import __version__                                    # noqa: F401
+
+# Make the package importable as 'owlplanner'
+__all__ = ['Plan', 'clone', 'readConfig', 'getRatesDistributions', '__version__']

owlplanner/config.py

@@ -16,7 +16,7 @@ from datetime import date
 import os
 
 from owlplanner import plan
-from owlplanner import logging
+from owlplanner import mylogging as log
 from owlplanner.rates import FROM, TO
 
 
@@ -143,7 +143,7 @@ def readConfig(file, *, verbose=True, logstreams=None, readContributions=True):
     A new plan is created and returned.
     Argument file can be a filename, a file, or a stringIO.
     """
-    mylog = logging.Logger(verbose, logstreams)
+    mylog = log.Logger(verbose, logstreams)
 
     accountTypes = ["taxable", "tax-deferred", "tax-free"]
 

owlplanner/plan.py

@@ -16,26 +16,21 @@ Disclaimer: This program comes with no guarantee. Use at your own risk.
 ###########################################################################
 import numpy as np
 import pandas as pd
-import matplotlib.pyplot as plt
 from datetime import date, datetime
 from functools import wraps
 from openpyxl import Workbook
 from openpyxl.utils.dataframe import dataframe_to_rows
 import time
 
-from owlplanner import utils as u
-from owlplanner import tax2025 as tx
-from owlplanner import abcapi as abc
-from owlplanner import rates
-from owlplanner import config
-from owlplanner import timelists
-from owlplanner import logging
-from owlplanner import progress
-from owlplanner import plots
-
-
-# This makes all graphs to have the same height.
-plt.rcParams.update({'figure.autolayout': True})
+from . import utils as u
+from . import tax2025 as tx
+from . import abcapi as abc
+from . import rates
+from . import config
+from . import timelists
+from . import mylogging as log
+from . import progress
+from .plotting.factory import PlotFactory
 
 
 def _genGamma_n(tau):
@@ -246,6 +241,8 @@ class Plan(object):
         self._description = ''
         self.defaultPlots = "nominal"
         self.defaultSolver = "HiGHS"
+        self._plotterName = None
+        self.setPlotBackend("matplotlib")
 
         self.N_i = len(yobs)
         if not (0 <= self.N_i <= 2):
@@ -257,7 +254,7 @@ class Plan(object):
         if inames[0] == "" or (self.N_i == 2 and inames[1] == ""):
             raise ValueError("Name for each individual must be provided.")
 
-        self.filingStatus = ["single", "married"][self.N_i - 1]
+        self.filingStatus = ("single", "married")[self.N_i - 1]
         # Default year TCJA is speculated to expire.
         self.yTCJA = 2026
         self.inames = inames
@@ -314,7 +311,7 @@ class Plan(object):
         self.lambdha = 0
 
         # Scenario starts at the beginning of this year and ends at the end of the last year.
-        s = ["", "s"][self.N_i - 1]
+        s = ("", "s")[self.N_i - 1]
         self.mylog.vprint(f"Preparing scenario of {self.N_n} years for {self.N_i} individual{s}.")
         for i in range(self.N_i):
             endyear = thisyear + self.horizons[i] - 1
@@ -349,7 +346,7 @@ class Plan(object):
         self.mylog = logger
 
     def setLogstreams(self, verbose, logstreams):
-        self.mylog = logging.Logger(verbose, logstreams)
+        self.mylog = log.Logger(verbose, logstreams)
         # self.mylog.vprint(f"Setting logstreams to {logstreams}.")
 
     def logger(self):
@@ -403,13 +400,11 @@ class Plan(object):
         if value is None:
             return self.defaultPlots
 
-        opts = ["nominal", "today"]
-        if value in opts:
-            return value
+        opts = ("nominal", "today")
+        if value not in opts:
+            raise ValueError(f"Value type must be one of: {opts}")
 
-        raise ValueError(f"Value type must be one of: {opts}")
-
-        return None
+        return value
 
     def rename(self, newname):
         """
@@ -454,6 +449,18 @@ class Plan(object):
         self.defaultPlots = self._checkValue(value)
         self.mylog.vprint(f"Setting plots default value to {value}.")
 
+    def setPlotBackend(self, backend: str):
+        """
+        Set plotting backend.
+        """
+
+        if backend not in ("matplotlib", "plotly"):
+            raise ValueError(f"Backend {backend} not a valid option.")
+
+        if backend != self._plotterName:
+            self._plotter = PlotFactory.createBackend(backend)
+            self.mylog.vprint(f"Setting plotting backend to {backend}.")
+
     def setDividendRate(self, mu):
         """
         Set dividend tax rate. Rate is in percent. Default 2%.
@@ -1100,7 +1107,7 @@ class Plan(object):
         return None
 
     def _setup_constraint_shortcuts(self, options):
-        # Set up all the local variables as attributes for use in helpers
+        # Set up all the local variables as attributes for use in helpers.
         oppCostX = options.get("oppCostX", 0.)
         self.xnet = 1 - oppCostX / 100.
         self.optionsUnits = u.getUnits(options.get("units", "k"))
@@ -1390,11 +1397,15 @@ class Plan(object):
         """
         Run historical scenarios on plan over a range of years.
         """
+
         if yend + self.N_n > self.year_n[0]:
             yend = self.year_n[0] - self.N_n - 1
             self.mylog.vprint(f"Warning: Upper bound for year range re-adjusted to {yend}.")
-        N = yend - ystart + 1
 
+        if yend < ystart:
+            raise ValueError(f"Starting year is too large to support a lifespan of {self.N_n} years.")
+
+        N = yend - ystart + 1
         self.mylog.vprint(f"Running historical range from {ystart} to {yend}.")
 
         self.mylog.setVerbose(verbose)
@@ -1405,7 +1416,7 @@ class Plan(object):
             columns = ["partial", "final"]
         else:
             self.mylog.print(f"Invalid objective {objective}.")
-            return None
+            raise ValueError(f"Invalid objective {objective}.")
 
         df = pd.DataFrame(columns=columns)
 
@@ -1429,10 +1440,11 @@ class Plan(object):
         progcall.finish()
         self.mylog.resetVerbose()
 
+        fig, description = self._plotter.plot_histogram_results(objective, df, N, self.year_n,
+                                                                self.n_d, self.N_i, self.phi_j)
+        self.mylog.print(description.getvalue())
+
         if figure:
-            fig, description = plots.show_histogram_results(objective, df, N, self.year_n,
-                                                            self.n_d, self.N_i, self.phi_j)
-            self.mylog.print(description.getvalue())
             return fig, description.getvalue()
 
         return N, df
@@ -1442,7 +1454,7 @@ class Plan(object):
         """
         Run Monte Carlo simulations on plan.
         """
-        if self.rateMethod not in ["stochastic", "histochastic"]:
+        if self.rateMethod not in ("stochastic", "histochastic"):
             self.mylog.print("It is pointless to run Monte Carlo simulations with fixed rates.")
             return
 
@@ -1486,10 +1498,11 @@ class Plan(object):
         progcall.finish()
         self.mylog.resetVerbose()
 
+        fig, description = self._plotter.plot_histogram_results(objective, df, N, self.year_n,
+                                                                self.n_d, self.N_i, self.phi_j)
+        self.mylog.print(description.getvalue())
+
         if figure:
-            fig, description = plots.show_histogram_results(objective, df, N, self.year_n,
-                                                            self.n_d, self.N_i, self.phi_j)
-            self.mylog.print(description.getvalue())
             return fig, description.getvalue()
 
         return N, df
@@ -1625,7 +1638,8 @@ class Plan(object):
         while True:
             solution, xx, solverSuccess, solverMsg = solverMethod(objective, options)
 
-            if not solverSuccess:
+            if not solverSuccess or solution is None:
+                self.mylog.vprint("Solver failed:", solverMsg, solverSuccess)
                 break
 
             if not withMedicare:
@@ -1675,8 +1689,13 @@ class Plan(object):
         """
         from scipy import optimize
 
-        # mip_rel_gap smaller than 1e-6 can lead to oscillatory solutions.
-        milpOptions = {"disp": False, "mip_rel_gap": 1e-7}
+        # Optimize solver parameters
+        milpOptions = {
+            "disp": False,
+            "mip_rel_gap": 1e-7,
+            "presolve": True,
+            "node_limit": 10000  # Limit search nodes for faster solutions
+        }
 
         self._buildConstraints(objective, options)
         Alu, lbvec, ubvec = self.A.arrays()
@@ -2047,10 +2066,10 @@ class Plan(object):
         dic[f"Net spending for year {now}"] = u.d(self.g_n[0] / self.yearFracLeft)
         dic[f"Net spending remaining in year {now}"] = u.d(self.g_n[0])
 
-        totIncome = np.sum(self.g_n, axis=0)
-        totIncomeNow = np.sum(self.g_n / self.gamma_n[:-1], axis=0)
-        dic["Total net spending"] = f"{u.d(totIncomeNow)}"
-        dic["[Total net spending]"] = f"{u.d(totIncome)}"
+        totSpending = np.sum(self.g_n, axis=0)
+        totSpendingNow = np.sum(self.g_n / self.gamma_n[:-1], axis=0)
+        dic["Total net spending"] = f"{u.d(totSpendingNow)}"
+        dic["[Total net spending]"] = f"{u.d(totSpending)}"
 
         totRoth = np.sum(self.x_in, axis=(0, 1))
         totRothNow = np.sum(np.sum(self.x_in, axis=0) / self.gamma_n[:-1], axis=0)
@@ -2150,13 +2169,25 @@ class Plan(object):
             self.mylog.vprint(f"Warning: Cannot plot correlations for {self.rateMethod} rate method.")
             return None
 
-        fig = plots.show_rates_correlations(self._name, self.tau_kn, self.N_n, self.rateMethod,
-                                            self.rateFrm, self.rateTo, tag, shareRange)
+        fig = self._plotter.plot_rates_correlations(self._name, self.tau_kn, self.N_n, self.rateMethod,
+                                                    self.rateFrm, self.rateTo, tag, shareRange)
+
+        if figure:
+            return fig
 
+        self._plotter.jupyter_renderer(fig)
+        return None
+
+    def showRatesDistributions(self, frm=rates.FROM, to=rates.TO, figure=False):
+        """
+        Plot histograms of the rates distributions.
+        """
+        fig = self._plotter.plot_rates_distributions(frm, to, rates.SP500, rates.BondsBaa,
+                                                     rates.TNotes, rates.Inflation, rates.FROM)
         if figure:
             return fig
 
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
     def showRates(self, tag="", figure=False):
@@ -2169,13 +2200,13 @@ class Plan(object):
             self.mylog.vprint("Warning: Rate method must be selected before plotting.")
             return None
 
-        fig = plots.show_rates(self._name, self.tau_kn, self.year_n, self.yearFracLeft,
-                               self.N_k, self.rateMethod, self.rateFrm, self.rateTo, tag)
+        fig = self._plotter.plot_rates(self._name, self.tau_kn, self.year_n, self.yearFracLeft,
+                                       self.N_k, self.rateMethod, self.rateFrm, self.rateTo, tag)
 
         if figure:
             return fig
 
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
     def showProfile(self, tag="", figure=False):
@@ -2187,19 +2218,15 @@ class Plan(object):
         if self.xi_n is None:
             self.mylog.vprint("Warning: Profile must be selected before plotting.")
             return None
-
         title = self._name + "\nSpending Profile"
-        if tag != "":
+        if tag:
             title += " - " + tag
-
-        style = {"profile": "-"}
-        series = {"profile": self.xi_n}
-        fig, ax = plots.line_income_plot(self.year_n, series, style, title, yformat="$\\xi$")
+        fig = self._plotter.plot_profile(self.year_n, self.xi_n, title, self.inames)
 
         if figure:
             return fig
 
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
     @_checkCaseStatus
@@ -2213,28 +2240,15 @@ class Plan(object):
         the default behavior of setDefaultPlots().
         """
         value = self._checkValue(value)
-
         title = self._name + "\nNet Available Spending"
-        if tag != "":
+        if tag:
             title += " - " + tag
-
-        style = {"net": "-", "target": ":"}
-        if value == "nominal":
-            series = {"net": self.g_n, "target": (self.g_n[0] / self.xi_n[0]) * self.xiBar_n}
-            yformat = "\\$k (nominal)"
-        else:
-            series = {
-                "net": self.g_n / self.gamma_n[:-1],
-                "target": (self.g_n[0] / self.xi_n[0]) * self.xi_n,
-            }
-            yformat = "\\$k (" + str(self.year_n[0]) + "\\$)"
-
-        fig, ax = plots.line_income_plot(self.year_n, series, style, title, yformat)
-
+        fig = self._plotter.plot_net_spending(self.year_n, self.g_n, self.xi_n, self.xiBar_n,
+                                              self.gamma_n, value, title, self.inames)
         if figure:
             return fig
 
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
     @_checkCaseStatus
@@ -2251,41 +2265,37 @@ class Plan(object):
         the default behavior of setDefaultPlots().
         """
         value = self._checkValue(value)
+        figures = self._plotter.plot_asset_distribution(self.year_n, self.inames, self.b_ijkn,
+                                                        self.gamma_n, value, self._name, tag)
+        if figure:
+            return figures
 
-        if value == "nominal":
-            yformat = "\\$k (nominal)"
-            infladjust = 1
-        else:
-            yformat = "\\$k (" + str(self.year_n[0]) + "\\$)"
-            infladjust = self.gamma_n
-
-        years_n = np.array(self.year_n)
-        years_n = np.append(years_n, [years_n[-1] + 1])
-        y2stack = {}
-        jDic = {"taxable": 0, "tax-deferred": 1, "tax-free": 2}
-        kDic = {"stocks": 0, "C bonds": 1, "T notes": 2, "common": 3}
-        figures = []
-        for jkey in jDic:
-            stackNames = []
-            for kkey in kDic:
-                name = kkey + " / " + jkey
-                stackNames.append(name)
-                y2stack[name] = np.zeros((self.N_i, self.N_n + 1))
-                for i in range(self.N_i):
-                    y2stack[name][i][:] = self.b_ijkn[i][jDic[jkey]][kDic[kkey]][:] / infladjust
+        for fig in figures:
+            self._plotter.jupyter_renderer(fig)
+        return None
 
-            title = self._name + "\nAssets Distribution - " + jkey
-            if tag != "":
-                title += " - " + tag
+    @_checkCaseStatus
+    def showGrossIncome(self, tag="", value=None, figure=False):
+        """
+        Plot income tax and taxable income over time horizon.
 
-            fig, ax = plots.stack_plot(years_n, self.inames, title, range(self.N_i),
-                                       y2stack, stackNames, "upper left", yformat)
-            figures.append(fig)
+        A tag string can be set to add information to the title of the plot.
 
+        The value parameter can be set to *nominal* or *today*, overriding
+        the default behavior of setDefaultPlots().
+        """
+        value = self._checkValue(value)
+        tax_brackets = tx.taxBrackets(self.N_i, self.n_d, self.N_n, self.yTCJA)
+        title = self._name + "\nTaxable Ordinary Income vs. Tax Brackets"
+        if tag:
+            title += " - " + tag
+        fig = self._plotter.plot_gross_income(
+            self.year_n, self.G_n, self.gamma_n, value, title, tax_brackets
+        )
         if figure:
-            return figures
+            return fig
 
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
     def showAllocations(self, tag="", figure=False):
@@ -2296,46 +2306,16 @@ class Plan(object):
 
         A tag string can be set to add information to the title of the plot.
         """
-        count = self.N_i
-        if self.ARCoord == "spouses":
-            acList = [self.ARCoord]
-            count = 1
-        elif self.ARCoord == "individual":
-            acList = [self.ARCoord]
-        elif self.ARCoord == "account":
-            acList = ["taxable", "tax-deferred", "tax-free"]
-        else:
-            raise ValueError(f"Unknown coordination {self.ARCoord}.")
-
-        figures = []
-        assetDic = {"stocks": 0, "C bonds": 1, "T notes": 2, "common": 3}
-        for i in range(count):
-            y2stack = {}
-            for acType in acList:
-                stackNames = []
-                for key in assetDic:
-                    aname = key + " / " + acType
-                    stackNames.append(aname)
-                    y2stack[aname] = np.zeros((count, self.N_n))
-                    y2stack[aname][i][:] = self.alpha_ijkn[i, acList.index(acType), assetDic[key], : self.N_n]
-
-                    title = self._name + "\nAsset Allocation (%) - " + acType
-                    if self.ARCoord == "spouses":
-                        title += " spouses"
-                    else:
-                        title += " " + self.inames[i]
-
-                if tag != "":
-                    title += " - " + tag
-
-                fig, ax = plots.stack_plot(self.year_n, self.inames, title, [i],
-                                           y2stack, stackNames, "upper left", "percent")
-                figures.append(fig)
-
+        title = self._name + "\nAsset Allocation"
+        if tag:
+            title += " - " + tag
+        figures = self._plotter.plot_allocations(self.year_n, self.inames, self.alpha_ijkn,
+                                                 self.ARCoord, title)
         if figure:
             return figures
 
-        plt.show()
+        for fig in figures:
+            self._plotter.jupyter_renderer(fig)
         return None
 
     @_checkCaseStatus
@@ -2349,31 +2329,15 @@ class Plan(object):
         the default behavior of setDefaultPlots().
         """
         value = self._checkValue(value)
-
         title = self._name + "\nSavings Balance"
-        if tag != "":
+        if tag:
             title += " - " + tag
-
-        stypes = self.savings_in.keys()
-        # Add one year for estate.
-        year_n = np.append(self.year_n, [self.year_n[-1] + 1])
-
-        if value == "nominal":
-            yformat = "\\$k (nominal)"
-            savings_in = self.savings_in
-        else:
-            yformat = "\\$k (" + str(self.year_n[0]) + "\\$)"
-            savings_in = {}
-            for key in self.savings_in:
-                savings_in[key] = self.savings_in[key] / self.gamma_n
-
-        fig, ax = plots.stack_plot(year_n, self.inames, title, range(self.N_i),
-                                   savings_in, stypes, "upper left", yformat)
-
+        fig = self._plotter.plot_accounts(self.year_n, self.savings_in, self.gamma_n,
+                                          value, title, self.inames)
         if figure:
             return fig
 
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
     @_checkCaseStatus
@@ -2387,55 +2351,15 @@ class Plan(object):
         the default behavior of setDefaultPlots().
         """
         value = self._checkValue(value)
-
         title = self._name + "\nRaw Income Sources"
-        stypes = self.sources_in.keys()
-
-        if tag != "":
+        if tag:
             title += " - " + tag
-
-        if value == "nominal":
-            yformat = "\\$k (nominal)"
-            sources_in = self.sources_in
-        else:
-            yformat = "\\$k (" + str(self.year_n[0]) + "\\$)"
-            sources_in = {}
-            for key in stypes:
-                sources_in[key] = self.sources_in[key] / self.gamma_n[:-1]
-
-        fig, ax = plots.stack_plot(self.year_n, self.inames, title, range(self.N_i),
-                                   sources_in, stypes, "upper left", yformat)
-
+        fig = self._plotter.plot_sources(self.year_n, self.sources_in, self.gamma_n,
+                                         value, title, self.inames)
         if figure:
             return fig
 
-        plt.show()
-        return None
-
-    @_checkCaseStatus
-    def _showFeff(self, tag=""):
-        """
-        Plot income tax paid over time.
-
-        A tag string can be set to add information to the title of the plot.
-        """
-        title = self._name + "\nEff f "
-        if tag != "":
-            title += " - " + tag
-
-        various = ["-", "--", "-.", ":"]
-        style = {}
-        series = {}
-        q = 0
-        for t in range(self.N_t):
-            key = "f " + str(t)
-            series[key] = self.F_tn[t] / self.DeltaBar_tn[t]
-            style[key] = various[q % len(various)]
-            q += 1
-
-        fig, ax = plots.line_income_plot(self.year_n, series, style, title, yformat="")
-
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
     @_checkCaseStatus
@@ -2449,87 +2373,17 @@ class Plan(object):
         the default behavior of setDefaultPlots().
         """
         value = self._checkValue(value)
-
-        style = {"income taxes": "-", "Medicare": "-."}
-
-        if value == "nominal":
-            series = {"income taxes": self.T_n, "Medicare": self.M_n}
-            yformat = "\\$k (nominal)"
-        else:
-            series = {
-                "income taxes": self.T_n / self.gamma_n[:-1],
-                "Medicare": self.M_n / self.gamma_n[:-1],
-            }
-            yformat = "\\$k (" + str(self.year_n[0]) + "\\$)"
-
         title = self._name + "\nIncome Tax"
-        if tag != "":
-            title += " - " + tag
-
-        fig, ax = plots.line_income_plot(self.year_n, series, style, title, yformat)
-
-        if figure:
-            return fig
-
-        plt.show()
-        return None
-
-    @_checkCaseStatus
-    def showGrossIncome(self, tag="", value=None, figure=False):
-        """
-        Plot income tax and taxable income over time horizon.
-
-        A tag string can be set to add information to the title of the plot.
-
-        The value parameter can be set to *nominal* or *today*, overriding
-        the default behavior of setDefaultPlots().
-        """
-        value = self._checkValue(value)
-
-        style = {"taxable income": "-"}
-
-        if value == "nominal":
-            series = {"taxable income": self.G_n}
-            yformat = "\\$k (nominal)"
-            infladjust = self.gamma_n[:-1]
-        else:
-            series = {"taxable income": self.G_n / self.gamma_n[:-1]}
-            yformat = "\\$k (" + str(self.year_n[0]) + "\\$)"
-            infladjust = 1
-
-        title = self._name + "\nTaxable Ordinary Income vs. Tax Brackets"
-        if tag != "":
+        if tag:
             title += " - " + tag
-
-        fig, ax = plots.line_income_plot(self.year_n, series, style, title, yformat)
-
-        data = tx.taxBrackets(self.N_i, self.n_d, self.N_n, self.yTCJA)
-        for key in data:
-            data_adj = data[key] * infladjust
-            ax.plot(self.year_n, data_adj, label=key, ls=":")
-
-        plt.grid(visible="both")
-        ax.legend(loc="upper left", reverse=True, fontsize=8, framealpha=0.3)
-
+        fig = self._plotter.plot_taxes(self.year_n, self.T_n, self.M_n, self.gamma_n,
+                                       value, title, self.inames)
         if figure:
             return fig
 
-        plt.show()
+        self._plotter.jupyter_renderer(fig)
         return None
 
-    # @_checkCaseStatus
-    def saveConfig(self, basename=None):
-        """
-        Save parameters in a configuration file.
-        """
-        if basename is None:
-            basename = "case_" + self._name
-
-        config.saveConfig(self, basename, self.mylog)
-
-        return None
-
-    @_checkCaseStatus
     def saveWorkbook(self, overwrite=False, *, basename=None, saveToFile=True):
         """
         Save instance in an Excel spreadsheet.
@@ -2772,6 +2626,17 @@ class Plan(object):
 
         return None
 
+    def saveConfig(self, basename=None):
+        """
+        Save parameters in a configuration file.
+        """
+        if basename is None:
+            basename = "case_" + self._name
+
+        config.saveConfig(self, basename, self.mylog)
+
+        return None
+
 
 def _saveWorkbook(wb, basename, overwrite, mylog):
     """

owlplanner/plotting/__init__.py

@@ -0,0 +1,7 @@
+"""
+Plotting backends for Owl.
+"""
+
+from .factory import PlotFactory
+
+__all__ = ['PlotFactory']