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

owlplanner/rates.py

@@ -35,9 +35,8 @@ import os
 import sys
 from datetime import date
 
-from owlplanner import logging
+from owlplanner import mylogging as log
 from owlplanner import utils as u
-from owlplanner import plots
 
 # All data goes from 1928 to 2024. Update the TO value when data
 # becomes available for subsequent years.
@@ -78,7 +77,7 @@ 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
@@ -160,7 +159,7 @@ class Rates(object):
         Default constructor.
         """
         if mylog is None:
-            self.mylog = logging.Logger()
+            self.mylog = log.Logger()
         else:
             self.mylog = mylog
 
@@ -383,13 +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.
-    """
-    fig = plots.show_rates_distributions(frm, to, SP500, BondsBaa, TNotes, Inflation, FROM)
-    return fig
-    # plt.show()
-    # return None

owlplanner/timelists.py

@@ -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.05"
+__version__ = "2025.05.12"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.5.5
+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/plots.py

@@ -1,296 +0,0 @@
-"""
-
-Owl/plots
----------
-
-A retirement planner using linear programming optimization.
-
-This module contains all plotting functions used by the Owl project.
-
-Copyright (C) 2025 -- Martin-D. Lacasse
-
-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
-import matplotlib.ticker as tk
-import io
-import os
-
-os.environ["JUPYTER_PLATFORM_DIRS"] = "1"
-import seaborn as sbn
-
-from owlplanner import utils as u
-
-
-def line_income_plot(x, series, style, title, yformat="\\$k"):
-    """
-    Core line plotter function.
-    """
-    fig, ax = plt.subplots(figsize=(6, 4))
-    plt.grid(visible="both")
-
-    for sname in series:
-        ax.plot(x, series[sname], label=sname, ls=style[sname])
-
-    ax.legend(loc="upper left", reverse=True, fontsize=8, framealpha=0.3)
-    ax.set_title(title)
-    ax.set_xlabel("year")
-    ax.set_ylabel(yformat)
-    ax.xaxis.set_major_locator(tk.MaxNLocator(integer=True))
-    if "k" in yformat:
-        ax.get_yaxis().set_major_formatter(tk.FuncFormatter(lambda x, p: format(int(x / 1000), ",")))
-        # Give range to y values in unindexed flat profiles.
-        ymin, ymax = ax.get_ylim()
-        if ymax - ymin < 5000:
-            ax.set_ylim((ymin * 0.95, ymax * 1.05))
-
-    return fig, ax
-
-
-def stack_plot(x, inames, title, irange, series, snames, location, yformat="\\$k"):
-    """
-    Core function for stacked plots.
-    """
-    nonzeroSeries = {}
-    for sname in snames:
-        for i in irange:
-            tmp = series[sname][i]
-            if sum(tmp) > 1.0:
-                nonzeroSeries[sname + " " + inames[i]] = tmp
-
-    if len(nonzeroSeries) == 0:
-        return None, None
-
-    fig, ax = plt.subplots(figsize=(6, 4))
-    plt.grid(visible="both")
-
-    ax.stackplot(x, nonzeroSeries.values(), labels=nonzeroSeries.keys(), alpha=0.6)
-    ax.legend(loc=location, reverse=True, fontsize=8, ncol=2, framealpha=0.5)
-    ax.set_title(title)
-    ax.set_xlabel("year")
-    ax.xaxis.set_major_locator(tk.MaxNLocator(integer=True))
-    if "k" in yformat:
-        ax.set_ylabel(yformat)
-        ax.get_yaxis().set_major_formatter(tk.FuncFormatter(lambda x, p: format(int(x / 1000), ",")))
-    elif yformat == "percent":
-        ax.set_ylabel("%")
-        ax.get_yaxis().set_major_formatter(tk.FuncFormatter(lambda x, p: format(int(100 * x), ",")))
-    else:
-        raise RuntimeError(f"Unknown yformat: {yformat}.")
-
-    return fig, ax
-
-
-def show_histogram_results(objective, df, N, year_n, n_d=None, N_i=1, phi_j=None):
-    """
-    Show a histogram of values from historical data or Monte Carlo simulations.
-    """
-    description = io.StringIO()
-
-    pSuccess = u.pc(len(df) / N)
-    print(f"Success rate: {pSuccess} on {N} samples.", file=description)
-    title = f"$N$ = {N}, $P$ = {pSuccess}"
-    means = df.mean(axis=0, numeric_only=True)
-    medians = df.median(axis=0, numeric_only=True)
-
-    my = 2 * [year_n[-1]]
-    if N_i == 2 and n_d is not None and n_d < len(year_n):
-        my[0] = year_n[n_d - 1]
-
-    # Don't show partial bequest of zero if spouse is full beneficiary,
-    # or if solution led to empty accounts at the end of first spouse's life.
-    if (phi_j is not None and np.all(phi_j == 1)) or medians.iloc[0] < 1:
-        if medians.iloc[0] < 1:
-            print(f"Optimized solutions all have null partial bequest in year {my[0]}.", file=description)
-        df.drop("partial", axis=1, inplace=True)
-        means = df.mean(axis=0, numeric_only=True)
-        medians = df.median(axis=0, numeric_only=True)
-
-    df /= 1000
-    if len(df) > 0:
-        thisyear = year_n[0]
-        if objective == "maxBequest":
-            fig, axes = plt.subplots()
-            # Show both partial and final bequests in the same histogram.
-            sbn.histplot(df, multiple="dodge", kde=True, ax=axes)
-            legend = []
-            # Don't know why but legend is reversed from df.
-            for q in range(len(means) - 1, -1, -1):
-                dmedian = u.d(medians.iloc[q], latex=True)
-                dmean = u.d(means.iloc[q], latex=True)
-                legend.append(f"{my[q]}: $M$: {dmedian}, $\\bar{{x}}$: {dmean}")
-            plt.legend(legend, shadow=True)
-            plt.xlabel(f"{thisyear} $k")
-            plt.title(objective)
-            leads = [f"partial {my[0]}", f"  final {my[1]}"]
-        elif len(means) == 2:
-            # Show partial bequest and net spending as two separate histograms.
-            fig, axes = plt.subplots(1, 2, figsize=(10, 5))
-            cols = ["partial", objective]
-            leads = [f"partial {my[0]}", objective]
-            for q in range(2):
-                sbn.histplot(df[cols[q]], kde=True, ax=axes[q])
-                dmedian = u.d(medians.iloc[q], latex=True)
-                dmean = u.d(means.iloc[q], latex=True)
-                legend = [f"$M$: {dmedian}, $\\bar{{x}}$: {dmean}"]
-                axes[q].set_label(legend)
-                axes[q].legend(labels=legend)
-                axes[q].set_title(leads[q])
-                axes[q].set_xlabel(f"{thisyear} $k")
-        else:
-            # Show net spending as single histogram.
-            fig, axes = plt.subplots()
-            sbn.histplot(df[objective], kde=True, ax=axes)
-            dmedian = u.d(medians.iloc[0], latex=True)
-            dmean = u.d(means.iloc[0], latex=True)
-            legend = [f"$M$: {dmedian}, $\\bar{{x}}$: {dmean}"]
-            plt.legend(legend, shadow=True)
-            plt.xlabel(f"{thisyear} $k")
-            plt.title(objective)
-            leads = [objective]
-
-        plt.suptitle(title)
-
-        for q in range(len(means)):
-            print(f"{leads[q]:>12}: Median ({thisyear} $): {u.d(medians.iloc[q])}", file=description)
-            print(f"{leads[q]:>12}:   Mean ({thisyear} $): {u.d(means.iloc[q])}", file=description)
-            mmin = 1000 * df.iloc[:, q].min()
-            mmax = 1000 * df.iloc[:, q].max()
-            print(f"{leads[q]:>12}:           Range: {u.d(mmin)} - {u.d(mmax)}", file=description)
-            nzeros = len(df.iloc[:, q][df.iloc[:, q] < 0.001])
-            print(f"{leads[q]:>12}:    N zero solns: {nzeros}", file=description)
-
-        return fig, description
-
-    return None, description
-
-
-def show_rates_correlations(name, tau_kn, N_n, rate_method, rate_frm=None, rate_to=None, tag="", share_range=False):
-    """
-    Plot correlations between various rates.
-    """
-    rate_names = [
-        "S&P500 (incl. div.)",
-        "Baa Corp. Bonds",
-        "10-y T-Notes",
-        "Inflation",
-    ]
-
-    df = pd.DataFrame()
-    for k, name in enumerate(rate_names):
-        data = 100 * tau_kn[k]
-        df[name] = data
-
-    g = sbn.PairGrid(df, diag_sharey=False, height=1.8, aspect=1)
-    if share_range:
-        minval = df.min().min() - 5
-        maxval = df.max().max() + 5
-        g.set(xlim=(minval, maxval), ylim=(minval, maxval))
-    g.map_upper(sbn.scatterplot)
-    g.map_lower(sbn.kdeplot)
-    g.map_diag(sbn.histplot, color="orange")
-
-    # Put zero axes on off-diagonal plots.
-    imod = len(rate_names) + 1
-    for i, ax in enumerate(g.axes.flat):
-        ax.axvline(x=0, color="grey", linewidth=1, linestyle=":")
-        if i % imod != 0:
-            ax.axhline(y=0, color="grey", linewidth=1, linestyle=":")
-
-    title = name + "\n"
-    title += f"Rates Correlations (N={N_n}) {rate_method}"
-    if rate_method in ["historical", "histochastic"]:
-        title += f" ({rate_frm}-{rate_to})"
-
-    if tag != "":
-        title += " - " + tag
-
-    g.fig.suptitle(title, y=1.08)
-    return g.fig
-
-
-def show_rates(name, tau_kn, year_n, year_frac_left, N_k, rate_method, rate_frm=None, rate_to=None, tag=""):
-    """
-    Plot rate values used over the time horizon.
-    """
-    fig, ax = plt.subplots(figsize=(6, 4))
-    plt.grid(visible="both")
-    title = name + "\nReturn & Inflation Rates (" + str(rate_method)
-    if rate_method in ["historical", "histochastic", "historical average"]:
-        title += f" {rate_frm}-{rate_to}"
-    title += ")"
-
-    if tag != "":
-        title += " - " + tag
-
-    rate_name = [
-        "S&P500 (incl. div.)",
-        "Baa Corp. Bonds",
-        "10-y T-Notes",
-        "Inflation",
-    ]
-    ltype = ["-", "-.", ":", "--"]
-    for k in range(N_k):
-        if year_frac_left == 1:
-            data = 100 * tau_kn[k]
-            years = year_n
-        else:
-            data = 100 * tau_kn[k, 1:]
-            years = year_n[1:]
-
-        # Use ddof=1 to match pandas.
-        label = (
-            rate_name[k] + " <" + "{:.1f}".format(np.mean(data)) + " +/- {:.1f}".format(np.std(data, ddof=1)) + "%>"
-        )
-        ax.plot(years, data, label=label, ls=ltype[k % N_k])
-
-    ax.xaxis.set_major_locator(tk.MaxNLocator(integer=True))
-    ax.legend(loc="best", reverse=False, fontsize=8, framealpha=0.7)
-    ax.set_title(title)
-    ax.set_xlabel("year")
-    ax.set_ylabel("%")
-    return fig
-
-
-def show_rates_distributions(frm, to, SP500, BondsBaa, TNotes, Inflation, FROM):
-    """
-    Plot histograms of the rates distributions.
-    """
-    title = f"Rates from {frm} to {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(dat2, 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)
-
-    return fig

owlplanner-2025.5.5.dist-info/RECORD

@@ -1,18 +0,0 @@
-owlplanner/__init__.py,sha256=QJgqS0MrRlBUFuI3PY2LbtD-Xxk1keNnbbPmSsdyZL0,552
-owlplanner/abcapi.py,sha256=m0vtoEzz9HJV7fOK_d7OnK7ha2Qbf7wLLPCJ9YZzR1k,6851
-owlplanner/config.py,sha256=DP-E8EPhkWvMmgPKp26rIrcppkITQyedgLfEyFrySpg,12554
-owlplanner/logging.py,sha256=tYMw04O-XYSzjTj36fmKJGLcE1VkK6k6oJNeqtKXzuc,2530
-owlplanner/plan.py,sha256=9mWj7AXXSTTfaa9bqqUqjPFuiPYf3HtCH31c0Y7Sryg,110615
-owlplanner/plots.py,sha256=0bvKzvPFfUSymWvMV2gGXnQy3-LpjcywYrfJ2-W_8M0,10476
-owlplanner/progress.py,sha256=8jlCvvtgDI89zXVNMBg1-lnEyhpPvKQS2X5oAIpoOVQ,384
-owlplanner/rates.py,sha256=ct-CmRiuxUxslkoBy14j5p19_FesldQiPvMgw470FKE,15108
-owlplanner/tax2025.py,sha256=wmlZpYeeGNrbyn5g7wOFqhWbggppodtHqc-ex5XRooI,7850
-owlplanner/timelists.py,sha256=6eqdnpwmNje9sNw1Hy9Gd-2Wcpgjor1TH4sVnFrpLo4,4033
-owlplanner/utils.py,sha256=WpJgn79YZfH8UCkcmhd-AZlxlGuz1i1-UDBRXImsY6I,2485
-owlplanner/version.py,sha256=suJjWyGl2pv1HKBSdqeb6B361ikXPlXHjEEfihKlKrk,28
-owlplanner/data/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-owlplanner/data/rates.csv,sha256=6fxg56BVVORrj9wJlUGFdGXKvOX5r7CSca8uhUbbuIU,3734
-owlplanner-2025.5.5.dist-info/METADATA,sha256=0QKQkzgOLIwhD32o7WFrIACVzPf15TXHke0uEU--dn0,53926
-owlplanner-2025.5.5.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-owlplanner-2025.5.5.dist-info/licenses/LICENSE,sha256=IwGE9guuL-ryRPEKi6wFPI_zOhg7zDZbTYuHbSt_SAk,35823
-owlplanner-2025.5.5.dist-info/RECORD,,