owlplanner 2025.2.25__tar.gz → 2025.3.7__tar.gz

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/.github/workflows/github-actions-runtests.yml

@@ -5,6 +5,7 @@ name: Python package
 
 run-name: ${{ github.actor }} running tests
 on: [push]
+permissions: read-all
 jobs:
   build:
     runs-on: ubuntu-latest

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/INSTALL.md

@@ -14,7 +14,7 @@ or, if one prefers to have everything on their own computer,
 to install and run a Docker image as described in these [instructions](docker/README.md).
 
 ### Requirements
-You will need Python and `pip` installed on your computer for that purpose.
+You will need Python and `pip` installed on your computer for completing the installation.
 
 ### Installation steps for developers
 These instructions are command-line instructions.
@@ -29,7 +29,8 @@ From the top directory of the source code run:
 python -m build 
 pip install -e .
 ```
-The -e instructs Python to load the live version in the current directory tree. 
+The -e instructs `pip` to install in *editable* mode and use the live version
+in the current directory tree.
 
 ### Running the streamlit frontend 
 Running the Owl user interface locally from Windows:
@@ -42,7 +43,7 @@ Running the Owl user interface locally from Linux or MacOS:
 ```
 
 ### Publishing a version (for reference only)
-Run checks before commit:
+Run checks before all commits:
 ```
 flake8 ui src tests
 pytest

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: owlplanner
-Version: 2025.2.25
+Version: 2025.3.7
 Summary: Owl: Retirement planner with great wisdom
 Project-URL: HomePage, https://github.com/mdlacasse/owl
 Project-URL: Repository, https://github.com/mdlacasse/owl
@@ -711,7 +711,13 @@ Description-Content-Type: text/markdown
 -------------------------------------------------------------------------------------
 
 ### TL;DR
-Owl is a planning tool that uses a linear programming optimization algorithm to provide guidance on retirement decisions. There are a few ways to run Owl.
+Owl is a retirement planning tool that uses a linear programming optimization algorithm
+to provide guidance on retirement decisions, including Roth conversions.
+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).
 
@@ -868,7 +874,7 @@ assets to support, even with no estate being left.
 ---------------------------------------------------------------
 ## Documentation
 
-- Documentation for the app user interface is available from the interface itself.
+- Documentation for the app user interface is available from the interface [itself](https://owlplanner.streamlit.app/Documentation).
 - Installation guide and software requirements can be found [here](INSTALL.md).
 - User guide for the underlying Python package as used in a Jupyter notebook can be found [here](USER_GUIDE.md).
 

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/README.md

@@ -8,7 +8,13 @@
 -------------------------------------------------------------------------------------
 
 ### TL;DR
-Owl is a planning tool that uses a linear programming optimization algorithm to provide guidance on retirement decisions. There are a few ways to run Owl.
+Owl is a retirement planning tool that uses a linear programming optimization algorithm
+to provide guidance on retirement decisions, including Roth conversions.
+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).
 
@@ -165,7 +171,7 @@ assets to support, even with no estate being left.
 ---------------------------------------------------------------
 ## Documentation
 
-- Documentation for the app user interface is available from the interface itself.
+- Documentation for the app user interface is available from the interface [itself](https://owlplanner.streamlit.app/Documentation).
 - Installation guide and software requirements can be found [here](INSTALL.md).
 - User guide for the underlying Python package as used in a Jupyter notebook can be found [here](USER_GUIDE.md).
 

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/examples/case_jack+jill.toml

@@ -1,5 +1,5 @@
 "Plan Name" = "jack+jill"
-Description = "This example case aims to demonstrate some of Owl's capabilities. Jack and Jill are a married couple a few years from retirement. A wages and contributions file called 'jack+jill.xlsx' is associated with this case."
+Description = "This example aims to demonstrate some of Owl's capabilities. Jack and Jill are a married couple a few years from retirement. A wages and contributions file called 'jack+jill.xlsx' is associated with this case. This case uses the historical rate sequence of 1969 as a test case for guiding spending amounts from a near worst-case historical scenario. This case also demonstrates that the optimal strategy for Roth conversions does not necessarily involve surfing a tax bracket."
 
 ["Basic Info"]
 Status = "married"

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/examples/case_john+sally.toml

@@ -1,5 +1,5 @@
 "Plan Name" = "john+sally"
-Description = "This example reproduces the case of John and Sally, discussed by Eric Sajdak. This case can be used to compare the heuristic strategy of surfing a tax bracket for performing Roth conversions to a solution optimized by linear programming. The former is a good approach when one assumes fixed rates. When rates are varying, and the market drops, an optimized solution shows that it is sometime advantageous to convert above the target tax bracket. File 'john+sally.xlsx' contains wages and contributions associated with this case. Run this case with different rates to see the effect on Roth conversions."
+Description = "This example reproduces the case of John and Sally, discussed by Eric Sajdak. This case can be used to compare the heuristic strategy of surfing a tax bracket for performing Roth conversions to a solution optimized by linear programming. The former is a good approach when one assumes fixed rates. When rates are varying, and the market drops, an optimized solution shows that it is sometime advantageous to convert above the target tax bracket. File 'john+sally.xlsx' contains wages and contributions associated with this case. Run this case with different rates to see the effects on Roth conversions."
 
 ["Basic Info"]
 Status = "married"

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/examples/case_jon+jane.toml

@@ -1,5 +1,5 @@
 "Plan Name" = "Jon+Jane"
-Description = "This case is similar to a case discussed by i-orp. It involve Jon and Jane close to retirement, and assumes a base case of optimistic returns of 10% with an inflation of 3.5%. A wages and contributions file called 'jon+jane.xlsx' is associated with this case."
+Description = "This case reproduces a similar case discussed a while back on i-orp. It involves Jon and Jane close to retirement, and assumes a base case of optimistic returns of 10% with an inflation of 3.5%. A wages and contributions file called 'jon+jane.xlsx' is associated with this case."
 
 ["Basic Info"]
 Status = "married"

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "owlplanner"
-version = "2025.02.25"
+version = "2025.03.07"
 authors = [
   { name="Martin-D. Lacasse", email="martin.d.lacasse@gmail.com" },
 ]

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/src/owlplanner/plan.py

@@ -1968,8 +1968,8 @@ class Plan(object):
         self.dist_in = self.w_ijn[:, 1, :] - self.rmd_in
         self.dist_in[self.dist_in < 0] = 0
         self.G_n = np.sum(self.F_tn, axis=0)
-        T_tn = self.F_tn * self.theta_tn
-        self.T_n = np.sum(T_tn, axis=0)
+        self.T_tn = self.F_tn * self.theta_tn
+        self.T_n = np.sum(self.T_tn, axis=0)
 
         tau_0 = np.array(self.tau_kn[0, :])
         tau_0[tau_0 < 0] = 0
@@ -2062,6 +2062,12 @@ class Plan(object):
 
         return mylist
 
+    def summaryDf(self):
+        """
+        Return summary as a dataframe.
+        """
+        return pd.DataFrame(self.summaryDic(), index=[self._name])
+
     def summaryString(self):
         """
         Return summary as a string.
@@ -2081,29 +2087,40 @@ class Plan(object):
         dic = {}
         # Results
         dic["Plan name"] = self._name
-        dic[f"Net yearly spending basis in {now}$"] = u.d(self.g_n[0] / self.xi_n[0])
-        dic[f"Net yearly spending for year {now}"] = u.d(self.g_n[0] / self.yearFracLeft)
+        dic["Net yearly spending basis"] = u.d(self.g_n[0] / self.xi_n[0])
+        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[f"Total net spending in {now}$"] = f"{u.d(totIncomeNow)} ({u.d(totIncome)} nominal)"
+        dic["Total net spending"] = f"{u.d(totIncomeNow)}"
+        dic["- Total net spending (nominal)"] = f"{u.d(totIncome)}"
 
         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)
-        dic[f"Total Roth conversions in {now}$"] = f"{u.d(totRothNow)} ({u.d(totRoth)} nominal)"
+        dic["Total Roth conversions"] = f"{u.d(totRothNow)}"
+        dic["- Total Roth conversions (nominal)"] = f"{u.d(totRoth)}"
 
         taxPaid = np.sum(self.T_n, axis=0)
         taxPaidNow = np.sum(self.T_n / self.gamma_n[:-1], axis=0)
-        dic[f"Total income tax paid on ordinary income in {now}$"] = f"{u.d(taxPaidNow)} ({u.d(taxPaid)} nominal)"
+        dic["Total income tax paid on ordinary income"] = f"{u.d(taxPaidNow)}"
+        dic["- Total income tax paid on ordinary income (nominal)"] = f"{u.d(taxPaid)}"
+        for t in range(self.N_t):
+            taxPaid = np.sum(self.T_tn[t], axis=0)
+            taxPaidNow = np.sum(self.T_tn[t] / self.gamma_n[:-1], axis=0)
+            tname = tx.taxBracketNames[t]
+            dic[f"-- Subtotal in tax bracket {tname}"] = f"{u.d(taxPaidNow)}"
+            dic[f"--- Subtotal in tax bracket {tname} (nominal)"] = f"{u.d(taxPaid)}"
 
         taxPaid = np.sum(self.U_n, axis=0)
         taxPaidNow = np.sum(self.U_n / self.gamma_n[:-1], axis=0)
-        dic[f"Total tax paid on gains and dividends in {now}$"] = f"{u.d(taxPaidNow)} ({u.d(taxPaid)} nominal)"
+        dic["Total tax paid on gains and dividends"] = f"{u.d(taxPaidNow)}"
+        dic["- Total tax paid on gains and dividends (nominal)"] = f"{u.d(taxPaid)}"
 
         taxPaid = np.sum(self.M_n, axis=0)
         taxPaidNow = np.sum(self.M_n / self.gamma_n[:-1], axis=0)
-        dic[f"Total Medicare premiums paid in {now}$"] = f"{u.d(taxPaidNow)} ({u.d(taxPaid)} nominal)"
+        dic["Total Medicare premiums paid"] = f"{u.d(taxPaidNow)}"
+        dic["- Total Medicare premiums paid (nominal)"] = f"{u.d(taxPaid)}"
 
         if self.N_i == 2 and self.n_d < self.N_n:
             p_j = self.partialEstate_j * (1 - self.phi_j)
@@ -2117,30 +2134,40 @@ class Plan(object):
             totSpousalNow = totSpousal / self.gamma_n[nx + 1]
             iname_s = self.inames[self.i_s]
             iname_d = self.inames[self.i_d]
-            dic[f"Spousal wealth transfer from {iname_d} to {iname_s} in year {ynx} (nominal)"] = (
-                f"taxable: {u.d(q_j[0])}  tax-def: {u.d(q_j[1])}  tax-free: {u.d(q_j[2])}")
-
-            dic[f"Sum of spousal bequests to {iname_s} in year {ynx} in {now}$"] = (
-                f"{u.d(totSpousalNow)} ({u.d(totSpousal)} nominal)")
-            dic[
-                f"Post-tax non-spousal bequests from {iname_d} in year {ynx} (nominal)"] = (
-                f"taxable: {u.d(p_j[0])}  tax-def: {u.d(p_j[1])}  tax-free: {u.d(p_j[2])}")
-            dic[
-                f"Sum of post-tax non-spousal bequests from {iname_d} in year {ynx} in {now}$"] = (
-                f"{u.d(totOthersNow)} ({u.d(totOthers)} nominal)")
+            dic[f"Sum of spousal transfer to {iname_s} in year {ynx}"] = (f"{u.d(totSpousalNow)}")
+            dic[f"- Sum of spousal transfer to {iname_s} in year {ynx} (nominal)"] = (
+                f"{u.d(totSpousal)}")
+            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - taxable (nominal)"] = (
+                f"{u.d(q_j[0])}")
+            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - tax-def (nominal)"] = (
+                f"{u.d(q_j[1])}")
+            dic[f"-- Spousal transfer to {iname_s} in year {ynx} - tax-free (nominal)"] = (
+                f"{u.d(q_j[2])}")
+
+            dic[f"Sum of post-tax non-spousal bequests from {iname_d} in year {ynx}"] = (
+                f"{u.d(totOthersNow)}")
+            dic[f"- Sum of post-tax non-spousal bequests from {iname_d} in year {ynx} (nominal)"] = (
+                f"{u.d(totOthers)}")
+            dic[f"-- Post-tax non-spousal bequests from {iname_d} in year {ynx} - taxable (nominal)"] = (
+                f"{u.d(p_j[0])}")
+            dic[f"-- Post-tax non-spousal bequests from {iname_d} in year {ynx} - tax-def (nominal)"] = (
+                f"{u.d(p_j[1])}")
+            dic[f"-- Post-tax non-spousal bequests from {iname_d} in year {ynx} - tax-free (nominal)"] = (
+                f"{u.d(p_j[2])}")
 
         estate = np.sum(self.b_ijn[:, :, self.N_n], axis=0)
         estate[1] *= 1 - self.nu
         lastyear = self.year_n[-1]
-        dic[f"Post-tax account values at the end of final plan year {lastyear} (nominal)"] = (
-            f"taxable: {u.d(estate[0])}  tax-def: {u.d(estate[1])}  tax-free: {u.d(estate[2])}")
-
         totEstate = np.sum(estate)
         totEstateNow = totEstate / self.gamma_n[-1]
-        dic[f"Total estate value at the end of final plan year {lastyear} in {now}$"] = (
-            f"{u.d(totEstateNow)} ({u.d(totEstate)} nominal)")
+        dic[f"Total estate value at the end of {lastyear}"] = (f"{u.d(totEstateNow)}")
+        dic[f"- Total estate value at the end of {lastyear} (nominal)"] = (f"{u.d(totEstate)}")
+        dic[f"-- Post-tax account value at the end of {lastyear} - taxable (nominal)"] = (f"{u.d(estate[0])}")
+        dic[f"-- Post-tax account value at the end of {lastyear} - tax-def (nominal)"] = (f"{u.d(estate[1])}")
+        dic[f"-- Post-tax account value at the end of {lastyear} - tax-free (nominal)"] = (f"{u.d(estate[2])}")
+
         dic["Plan starting date"] = str(self.startDate)
-        dic["Cumulative inflation factor from start date to end of plan"] = f"{self.gamma_n[-1]:.2f}"
+        dic[f"Cumulative inflation factor from start date to end of {lastyear}"] = (f"{self.gamma_n[-1]:.2f}")
         for i in range(self.N_i):
             dic[f"{self.inames[i]:>12}'s {self.horizons[i]:02}-year life horizon"] = (
                 f"{now} -> {now + self.horizons[i] - 1}")

owlplanner-2025.3.7/src/owlplanner/version.py

@@ -0,0 +1 @@
+__version__ = "2025.03.07"

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Asset_Allocation.py

@@ -81,8 +81,7 @@ def checkAllAllocs():
     return result
 
 
-ret = kz.titleBar("allocs")
-kz.caseHeader("Asset Allocation")
+ret = kz.titleBar("Asset Allocation")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Assets.py

@@ -2,8 +2,7 @@ import streamlit as st
 
 import sskeys as kz
 
-ret = kz.titleBar("assets")
-kz.caseHeader("Assets")
+ret = kz.titleBar("Assets")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Create_Case.py

@@ -1,13 +1,14 @@
 from datetime import date
+from io import StringIO
 import streamlit as st
 
 import sskeys as kz
 import owlbridge as owb
+import tomlexamples as tomlex
 
 
 caseChoices = kz.allCaseNames()
-ret = kz.titleBar("setup", caseChoices)
-kz.caseHeader("Create Case")
+ret = kz.titleBar("Create Case", caseChoices)
 
 if ret == kz.newCase:
     st.info("#### Starting a new case from scratch.\n\n" "A name for the scenario must first be provided.")
@@ -23,12 +24,22 @@ elif ret == kz.loadCaseFile:
     # "<a href="Documentation" target="_self">Documentation</a>", unsafe_allow_html=True)
     st.info(
         "#### Starting a case from a *case* parameter file.\n\n"
-        "Look at the :material/help: [Documentation](Documentation) for where to find examples.\n\n"
-        "Alternatively, select `New Case...` to start a case from scratch."
+        "Upload your own case or select one from multiple examples."
+        " Alternatively, you can select `New Case...` in the top selector box to start a case from scratch.\n\n"
+        "Look at the :material/help: [Documentation](Documentation) for more details."
     )
-    confile = st.file_uploader("Upload *case* parameter file...", key="_confile", type=["toml"])
-    if confile is not None:
-        if kz.createCaseFromFile(confile):
+    st.write("#### Upload your own case file")
+    file = st.file_uploader("Upload *case* parameter file...", key="_confile", type=["toml"])
+    if file is not None:
+        mystringio = StringIO(file.read().decode("utf-8"))
+        if kz.createCaseFromFile(mystringio):
+            st.rerun()
+
+    st.write("#### Load a case example")
+    case = st.selectbox("Examples available from GitHub", tomlex.cases, index=None, placeholder="Select a case")
+    if case is not None:
+        mystringio = tomlex.loadExample(case)
+        if kz.createCaseFromFile(mystringio):
             st.rerun()
 else:
     helpmsg = "Case name can be changed by editing it directly."
@@ -110,7 +121,7 @@ else:
     st.divider()
     cantcreate = kz.isIncomplete() or diz1
     if not cantcreate and kz.getKey("plan") is None:
-        st.info("Plan needs to be created once all the information needed has been entered.")
+        st.info("Plan needs to be created once desired changes are completed.")
 
     cantmodify = kz.currentCaseName() == kz.newCase or kz.currentCaseName() == kz.loadCaseFile
     cantcopy = cantmodify or kz.caseHasNoPlan()

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Documentation.py

@@ -34,16 +34,28 @@ formulation of the optimization problem can be found
 
 --------------------------------------------------------------------------------------
 ### Getting started with the user interface
-Functions of each page are described below in the same order as they appear in the sidebar.
+Functions of each page are described below in the same order as they appear in the left sidebar.
 Typically, pages would be accessed in order, starting from the top.
-The `Select case` selection box at the bottom of the margin allows to select an existing case
+
+The `Case selector` box at the top of the page allows to select an existing case
 or create a new one from scratch, or from a *case* parameter file, which
 would then populate all parameter values.
 This box is present in all pages except those in the **Resources** section
-and allows to compare different scenarios.
+and allows to access and compare different scenarios.
+
+A typical workflow for exploring different scenarios involves starting with a base
+case and then duplicating/creating derived scenarios with slight changes in the parameters,
+which are configured in the **Case Setup** section. The comparison between the
+different resulting outcomes is shown on the [Output Files](#output-files) page.
+
+Owl uses a year as the standard time unit. All values are therefore entered and
+reported as yearly values. These include wages, income, rates, social security, etc.
+Dollar values are typically entered in thousands, unless in tables, where they
+are entered and reported in unit dollars.
 
 There are four sections in the user interface:
 **Case Setup**, **Single Scenario**, **Multiple Scenarios**, and **Resources**.
+The sections below follow the same logical order.
 
 -------------------------------------------------
 ### :orange[Case Setup]
@@ -51,7 +63,7 @@ This section contains the steps for creating and configuring case scenarios.
 
 #### Create Case
 This page is where every new scenario begins.
-It controls the creation of scenarios as the `Select case` drop-down menu contains
+It controls the creation of scenarios as the `Case selector` drop-down menu contains
 two additional items when this page is open:
 one to create new cases, and the other to create cases from a *case* parameter file.
 This page also allows you to duplicate and/or rename scenarios, as well as deleting them.
@@ -65,7 +77,7 @@ When duplicating a scenario, make sure to visit all pages in the **Case Setup**
 and verify that all parameters are as intended.
 
 ##### Initializing the life parameters for the realization
-Start with the `Select case` box and choose one of `New case...` or `Upload case file...`.
+Start with the `Case selector` box and choose one of `New case...` or `Upload case file...`.
 
 If `Upload case file...` is selected, a *case* file must be uploaded.
 These files end with the *.toml* extension, are human readable (and therefore editable),
@@ -307,22 +319,28 @@ The first line of the *Sources* worksheets are the most important
 as these lines are the only ones that are actionable.
 
 #### Output Files
-This page allow to save many files for future use.
-First it shows a synopsis of the computed scenario by
+This page allows to compare cases and save files for future use.
+First, it shows a synopsis of the computed scenario by
 displaying sums of income, bequest, and spending values over the duration of the plan.
-The contents of this page can be downloaded as a plain text file by
-clicking the button at the bottom of the section.
-
-Finally, parameters used to generate the case are collected in *toml* format and displayed.
-The `Download case file...` button allows to save the parameters used to generate the
-outcome of this case to a *case* file.
+If multiple cases were configured and run (most likely through duplication and
+modifying the configuration), they will be compared in that panel provided they were made
+for the same individuals. Column on the left shows the values for the selected case
+while those on the right will show the differences.
+The contents of the synopsis can be downloaded as a plain text file by
+clicking the button below it.
 
 Another section called `Excel workbooks` allows
-to save the contents of the tables on the corresponding page to an Excel workbook.
+to save the contents of the tables on the corresponding page as an Excel workbook.
+These data are displayed on the *Worksheets* and the *Wages and Contributions* pages.
+
+Similarly, all parameters used to generate the case are collected in *toml* format and displayed.
+The `Download case file...` button allows to save the parameters of the selected scenario
+to a *case* file.
 
-With the case parameter and the wages and contributions files,
+With the case parameter file and the wages and contributions worksheet,
 the same case can be reproduced at a later time by uploading
-them through the widgets on the `Create Case` and `Wages and Contributions` pages.
+them through the widgets on the `Create Case` and `Wages and Contributions` pages,
+respectively.
 
 --------------------------------------------------------------------------------------
 ### :orange[Multiple Scenarios]

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Fixed_Income.py

@@ -36,8 +36,7 @@ def getToggleInput(i, key, thing):
     st.toggle(thing, on_change=kz.setpull, value=defval, args=[nkey], key="_" + nkey)
 
 
-ret = kz.titleBar("fixed")
-kz.caseHeader("Fixed Income")
+ret = kz.titleBar("Fixed Income")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Graphs.py

@@ -4,8 +4,7 @@ import sskeys as kz
 import owlbridge as owb
 
 
-ret = kz.titleBar("results")
-kz.caseHeader("Graphs")
+ret = kz.titleBar("Graphs")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")
@@ -21,9 +20,10 @@ else:
         ret = kz.getRadio("Dollar amounts in plots", choices, "plots", callback=owb.setDefaultPlots)
 
     with col2:
+        helpmsg = "Click on button if graphs are not all showing."
         st.button(
             "Re-run single case",
-            help="Optimize single scenario.",
+            help=helpmsg,
             on_click=owb.runPlan,
             disabled=kz.caseIsNotRunReady(),
         )

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Historical_Range.py

@@ -4,8 +4,7 @@ import sskeys as kz
 import owlbridge as owb
 
 
-ret = kz.titleBar("historicalRange")
-kz.caseHeader("Historical Range")
+ret = kz.titleBar("Historical Range")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Logs.py

@@ -3,8 +3,7 @@ import streamlit as st
 import sskeys as kz
 
 
-ret = kz.titleBar("logs")
-kz.caseHeader("Logs")
+ret = kz.titleBar("Logs")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Monte_Carlo.py

@@ -4,8 +4,7 @@ import sskeys as kz
 import owlbridge as owb
 
 
-ret = kz.titleBar("MC")
-kz.caseHeader("Monte Carlo")
+ret = kz.titleBar("Monte Carlo")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Optimization_Parameters.py

@@ -16,8 +16,7 @@ def initProfile():
     owb.setProfile(profileChoices[0], False)
 
 
-ret = kz.titleBar("opto")
-kz.caseHeader("Optimization Parameters")
+ret = kz.titleBar("Optimization Parameters")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Output_Files.py

@@ -3,8 +3,7 @@ import streamlit as st
 import sskeys as kz
 import owlbridge as owb
 
-ret = kz.titleBar("summary")
-kz.caseHeader("Output Files")
+ret = kz.titleBar("Output Files")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")
@@ -16,12 +15,14 @@ else:
         st.info("Case status is currently '%s'." % kz.getKey("caseStatus"))
     else:
         caseName = kz.getKey("name")
-        lines = kz.getKey("summary")
-        if lines != "":
+        df = kz.compareSummaries()
+        if df is not None:
             st.write("#### Synopsis")
-            st.code(lines, language=None)
+            st.dataframe(df[1:], use_container_width=True)
+            st.caption("Values are in today's \\$ unless marked otherwise.")
             st.download_button(
-                "Download synopsis", data=lines, file_name=f"Synopsis_{caseName}.txt", mime="text/plain;charset=UTF-8"
+                "Download synopsis", data=df[1:].to_string(), file_name=f"Synopsis_{caseName}.txt",
+                mime="text/plain;charset=UTF-8"
             )
 
         st.divider()
@@ -54,5 +55,6 @@ else:
             st.code(lines, language="toml")
 
             st.download_button(
-                "Download case parameter file", data=lines, file_name=f"case_{caseName}.toml", mime="application/toml"
+                "Download case parameter file", data=lines,
+                file_name=f"case_{caseName}.toml", mime="application/toml"
             )

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Quick_Start.py

@@ -36,7 +36,8 @@ of Jack and Jill provided here as an example:
     - Wages and contributions file named
     [jack+jill.xlsx](https://raw.github.com/mdlacasse/Owl/main/examples/jack+jill.xlsx)
     in Excel format.
-1) Navigate to the **Create Case** page and drag and drop the case parameter file
+1) Navigate to the **Create Case** page and select the case of *jack+jill* among the GitHub examples.
+Alternatively, you can drag and drop the case parameter file
 you just downloaded (*case_jack+jill.toml*).
 1) Navigate to the **Wages and Contributions** page and
 drag and drop the wages and contributions file you downloaded (*jack+jill.xlsx*).
@@ -48,14 +49,13 @@ experiment with different parameters.
 For creating your own cases, you can start
 from scratch by selecting `New Case...` in the selection box while on the **Create Case** page,
 and fill in the information needed on each page in the `Case Setup` section.
-Once a case has been fully parameterized and successfully optimized,
-its parameters can be saved by using the `Download case file...` button on the `Output Files` page.
-
 Alternatively, you can duplicate any existing case by using
 the `Duplicate case` button, and then edit its values to fit your situation.
 
-Multiple cases can coexist and can be called and compared using the `Select case` box
-at the bottom of the margin.
+Once a case has been fully parameterized and successfully optimized,
+its parameters can be saved by using the `Download case file...` button on the `Output Files` page.
+Multiple cases can coexist and can be called and compared using the `Case selector` box
+at the top of the page.
 
 More information can be found on the :material/help: **[Documentation](Documentation)**
 page located in the **Resources** section.

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Rates_Selection.py

@@ -47,8 +47,7 @@ kz.initKey("rateType", rateChoices[0])
 kz.initKey("fixedType", fixedChoices[0])
 kz.initKey("varyingType", varyingChoices[0])
 
-ret = kz.titleBar("rates")
-kz.caseHeader("Rates Selection")
+ret = kz.titleBar("Rates Selection")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Wages_And_Contributions.py

@@ -4,15 +4,15 @@ import sskeys as kz
 import owlbridge as owb
 
 
+# Refresh Wages and Contributions tables as time window likely to change.
 def resetTimeLists():
-    if not kz.getKey("duplicate"):
-        tlists = owb.resetContributions()
-        for i, iname in enumerate(tlists):
-            kz.setKey("timeList" + str(i), tlists[iname])
+    # if not kz.getKey("duplicate"):
+    tlists = owb.resetContributions()
+    for i, iname in enumerate(tlists):
+        kz.setKey("timeList" + str(i), tlists[iname])
 
 
-ret = kz.titleBar("wages")
-kz.caseHeader("Wages and Contributions")
+ret = kz.titleBar("Wages and Contributions")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")
@@ -38,11 +38,12 @@ else:
                 " that has not yet been uploaded."
             )
 
+    st.write("#### Upload a *Wages and Contributions* file")
     kz.initKey("_xlsx", 0)
     stTimeLists = st.file_uploader(
         "Upload values from a wages and contributions file...",
         key="_stTimeLists" + str(kz.getKey("_xlsx")),
-        type=["xlsx"],
+        type=["xlsx", "ods"],
     )
     if stTimeLists is not None:
         if owb.readContributions(stTimeLists):
@@ -51,6 +52,7 @@ else:
             kz.storeKey("_xlsx", kz.getKey("_xlsx") + 1)
             st.rerun()
 
+    st.divider()
     for i in range(n):
         st.write("##### " + kz.getKey("iname" + str(i)) + "'s timetable")
         colfor = {"year": st.column_config.NumberColumn(None, format="%d")}

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/Worksheets.py

@@ -3,8 +3,7 @@ import streamlit as st
 import sskeys as kz
 import owlbridge as owb
 
-ret = kz.titleBar("worksheets")
-kz.caseHeader("Worksheets")
+ret = kz.titleBar("Worksheets")
 
 if ret is None or kz.caseHasNoPlan():
     st.info("Case(s) must be first created before running this page.")

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/owlbridge.py

@@ -122,15 +122,15 @@ def runPlan(plan):
     except Exception as e:
         st.error(f"Solution failed: {e}")
         kz.storeKey("caseStatus", "exception")
-        kz.storeKey("summary", "")
+        kz.storeKey("summaryDf", None)
         return
 
     kz.storeKey("caseStatus", plan.caseStatus)
     if plan.caseStatus == "solved":
-        kz.storeKey("summary", plan.summaryString())
+        kz.storeKey("summaryDf", plan.summaryDf())
         kz.storeKey("casetoml", getCaseString().getvalue())
     else:
-        kz.storeKey("summary", "")
+        kz.storeKey("summaryDf", None)
         kz.storeKey("casetoml", "")
 
 
@@ -381,7 +381,7 @@ def _setAllocationRatios(plan):
 def plotSingleResults(plan):
     c = 0
     n = 3
-    cols = st.columns(n, gap="medium")
+    cols = st.columns(n, gap="small")
     fig = plan.showRates(figure=True)
     if fig:
         cols[c].write("##### Annual Rates")
@@ -400,7 +400,7 @@ def plotSingleResults(plan):
         cols[c].pyplot(fig)
         c = (c + 1) % n
 
-    cols = st.columns(n, gap="medium")
+    cols = st.columns(n, gap="small")
     fig = plan.showSources(figure=True)
     if fig:
         cols[c].write("##### Raw Income Sources")
@@ -544,17 +544,16 @@ def saveCaseFile(plan):
     return BytesIO(encoded_data)
 
 
-def createCaseFromFile(file):
-    strio = StringIO()
+def createCaseFromFile(strio):
+    logstrio = StringIO()
     try:
-        mystringio = StringIO(file.read().decode("utf-8"))
-        plan = owl.readConfig(mystringio, logstreams=[strio], readContributions=False)
+        plan = owl.readConfig(strio, logstreams=[logstrio], readContributions=False)
     except Exception as e:
         st.error(f"Failed to parse case file: {e}")
         return "", {}
 
     name, mydic = genDic(plan)
-    mydic["logs"] = strio
+    mydic["logs"] = logstrio
 
     return name, mydic
 
@@ -565,7 +564,7 @@ def genDic(plan):
     dic["plan"] = plan
     dic["name"] = plan._name
     dic["description"] = plan._description
-    dic["summary"] = ""
+    dic["summaryDf"] = None
     dic["casetoml"] = ""
     dic["caseStatus"] = "new"
     dic["status"] = ["unknown", "single", "married"][plan.N_i]

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/plots.py

@@ -8,6 +8,8 @@ def changeStyle(key):
     val = kz.getGlobalKey("_" + key)
     kz.storeGlobalKey(key, val)
     plt.style.use(val)
+    # This makes all graphs appear have the same height.
+    plt.rcParams.update({'figure.autolayout': True})
 
 
 styles = ["default"]

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/requirements.txt

@@ -7,4 +7,4 @@ scipy
 streamlit
 toml
 # --extra-index-url https://test.pypi.org/simple
-owlplanner >= 2025.02.25
+owlplanner >= 2025.03.07

{owlplanner-2025.2.25 → owlplanner-2025.3.7}/ui/sskeys.py

@@ -3,6 +3,7 @@ Module for storing keys in Streamlit session state.
 """
 
 import streamlit as st
+import pandas as pd
 import copy
 import re
 
@@ -22,8 +23,8 @@ def init():
     ss = st.session_state
     if "cases" not in ss:
         ss.cases = {
-            newCase: {"iname0": "", "status": "unkown", "caseStatus": "new", "summary": ""},
-            loadCaseFile: {"iname0": "", "status": "unkown", "caseStatus": "new", "summary": ""},
+            newCase: {"iname0": "", "status": "unkown", "caseStatus": "new"},
+            loadCaseFile: {"iname0": "", "status": "unkown", "caseStatus": "new"},
         }
 
     # Variable for storing name of current case.
@@ -151,21 +152,6 @@ def caseIsNotMCReady():
     return caseIsNotRunReady() or getKey("rateType") != "varying" or "tochastic" not in getKey("varyingType")
 
 
-def titleBar(nkey, choices=None):
-    if choices is None:
-        choices = onlyCaseNames()
-    helpmsg = "Select an existing case, or create a new one from scratch or from a *case* parameter file."
-    return st.sidebar.selectbox(
-        "Select case",
-        choices,
-        help=helpmsg,
-        index=getIndex(currentCaseName(), choices),
-        key="_" + nkey,
-        on_change=switchToCase,
-        args=[nkey],
-    )
-
-
 def currentCaseDic() -> dict:
     return ss.cases[ss.currentCase]
 
@@ -192,16 +178,17 @@ def duplicateCase():
     ss.cases[dupname] = copy.deepcopy(ss.cases[ss.currentCase])
     ss.cases[ss.currentCase]["plan"] = currentPlan
     ss.cases[dupname]["name"] = dupname
-    ss.cases[dupname]["summary"] = ""
+    ss.cases[dupname]["summaryDf"] = None
     ss.cases[dupname]["duplicate"] = True
     refreshCase(ss.cases[dupname])
     ss.currentCase = dupname
+    st.toast("Case duplicated except for Wages and Contributions tables.")
 
 
-def createCaseFromFile(confile):
+def createCaseFromFile(strio):
     import owlbridge as owb
 
-    name, dic = owb.createCaseFromFile(confile)
+    name, dic = owb.createCaseFromFile(strio)
     if name == "":
         return False
     elif name in ss.cases:
@@ -228,7 +215,7 @@ def createNewCase(case):
         st.error(f"Case name '{casename}' already exists.")
         return
 
-    ss.cases[casename] = {"name": casename, "caseStatus": "unknown", "summary": "", "logs": None}
+    ss.cases[casename] = {"name": casename, "caseStatus": "unknown", "logs": None}
     setCurrentCase(ss._newcase)
 
 
@@ -237,10 +224,11 @@ def renameCase(key):
         return
     newname = ss["_" + key]
     plan = getKey("plan")
-    if plan:
-        plan.rename(newname)
     ss.cases[newname] = ss.cases.pop(ss.currentCase)
     ss.cases[newname]["name"] = newname
+    if plan:
+        plan.rename(newname)
+        ss.cases[newname]["caseStatus"] = "modified"
     setCurrentCase(newname)
 
 
@@ -272,7 +260,7 @@ def storepull(key):
 def setKey(key, val):
     ss.cases[ss.currentCase][key] = val
     ss.cases[ss.currentCase]["caseStatus"] = "modified"
-    # print("setKey", key, val)
+    ss.cases[ss.currentCase]["summaryDf"] = None
     return val
 
 
@@ -325,6 +313,34 @@ def getAccountBalances(ni):
     return bal
 
 
+def compareSummaries():
+    df = getKey("summaryDf")
+    if df is None:
+        return None
+    for case in onlyCaseNames():
+        if case == currentCaseName():
+            continue
+        odf = ss.cases[case]["summaryDf"]
+        if odf is None or set(odf.columns) != set(df.columns):
+            continue
+        df = pd.concat([df, odf])
+
+    if df.shape[0] > 1:
+        # Unroll to subtract $tring representation of numbers.
+        for col in range(1, df.shape[1] - 5):
+            strval = df.iloc[0, col]
+            if isinstance(strval, str) and strval[0] == "$":
+                f0val = float(strval[1:].replace(",", ""))
+                for row in range(1, df.shape[0]):
+                    fnval = float(df.iloc[row, col][1:].replace(",", ""))
+                    diff = fnval - f0val
+                    sign = "\u2191" if diff >= 0 else "\u2193"
+                    sign = "\u2192" if diff == 0 else sign
+                    df.iloc[row, col] = f"{sign} ${abs(diff):,.0f}"
+
+    return df.transpose()
+
+
 def getSolveParameters():
     maximize = getKey("objective")
     if maximize is None:
@@ -488,8 +504,28 @@ def orangeDivider():
     st.html("<style> hr {border-color: orange;}</style><hr>")
 
 
-def caseHeader(txt):
-    # st.html("<div style="text-align: right;color: orange;font-style: italic;">%s</div>" % currentCaseName())
-    st.html("<div style='text-align: left;color: orange;font-style: italic;'>%s</div>" % currentCaseName())
-    st.write("## " + txt)
+def titleBar(txt, choices=None):
+    # st.html(f"<div style='text-align: left;color: orange;font-style: italic;'>{currentCaseName()}</div>")
+    if choices is None:
+        choices = onlyCaseNames()
+        helpmsg = "Select an existing case."
+    else:
+        helpmsg = "Select an existing case, or create a new one from scratch or from a *case* parameter file."
+
+    col1, col2 = st.columns(2, gap="large")
+    with col1:
+        st.write("## " + txt)
+    with col2:
+        nkey = txt
+        ret = st.selectbox(
+            "Case selector",
+            choices,
+            help=helpmsg,
+            index=getIndex(currentCaseName(), choices),
+            key="_" + nkey,
+            on_change=switchToCase,
+            args=[nkey],
+        )
+
     orangeDivider()
+    return ret

owlplanner-2025.3.7/ui/tomlexamples.py

@@ -0,0 +1,16 @@
+import requests
+import streamlit as st
+from io import StringIO
+
+
+cases = ["jack+jill", "joe", "john+sally", "jon+jane", "kim+sam-bequest", "kim+sam-spending"]
+
+
+def loadExample(case):
+    url = f"https://raw.github.com/mdlacasse/owl/main/examples/case_{case}.toml"
+    response = requests.get(url)
+    if response.status_code == 200:
+        return StringIO(response.text)
+    else:
+        st.error(f"Failed to load case parameter file from GitHub: {response.status_code}.")
+        return None

owlplanner-2025.2.25/src/owlplanner/version.py

@@ -1 +0,0 @@
-__version__ = "2025.02.25"