owlplanner 2025.12.5__py3-none-any.whl → 2026.1.26__py3-none-any.whl

owlplanner/timelists.py

@@ -1,24 +1,30 @@
 """
+Time horizon data validation and processing utilities.
 
-Owl/timelists
----
+This module provides utility functions to read and validate timelist data
+from Excel files, including wage, contribution, and other time-based parameters.
 
-A retirement planner using linear programming optimization.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-See companion document for a complete explanation and description
-of all variables and parameters.
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-Utility functions to read and check timelists.
-
-Copyright © 2024 - Martin-D. Lacasse
-
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 from datetime import date
 import pandas as pd
 
+from . import utils as u
+
 
 # Expected headers in each excel sheet, one per individual.
 _timeHorizonItems = [
@@ -34,7 +40,47 @@ _timeHorizonItems = [
 ]
 
 
-def read(finput, inames, horizons, mylog):
+_debtItems = [
+    "active",
+    "name",
+    "type",
+    "year",
+    "term",
+    "amount",
+    "rate",
+]
+
+
+_debtTypes = [
+    "loan",
+    "mortgage",
+]
+
+
+_fixedAssetItems = [
+    "active",
+    "name",
+    "type",
+    "year",
+    "basis",
+    "value",
+    "rate",
+    "yod",
+    "commission",
+]
+
+
+_fixedAssetTypes = [
+    "collectibles",
+    "fixed annuity",
+    "precious metals",
+    "real estate",
+    "residence",
+    "stocks",
+]
+
+
+def read(finput, inames, horizons, mylog, filename=None):
     """
     Read listed parameters from an excel spreadsheet or through
     a dictionary of dataframes through Pandas.
@@ -43,6 +89,20 @@ def read(finput, inames, horizons, mylog):
     IRA ctrb, Roth IRA ctrb, Roth conv, and big-ticket items.
     Supports xls, xlsx, xlsm, xlsb, odf, ods, and odt file extensions.
     Return a dictionary of dataframes by individual's names.
+
+    Parameters
+    ----------
+    finput : file-like object, str, or dict
+        Input file or dictionary of DataFrames
+    inames : list
+        List of individual names
+    horizons : list
+        List of time horizons
+    mylog : logger
+        Logger instance
+    filename : str, optional
+        Explicit filename for logging purposes. If provided, this will be used
+        instead of trying to extract it from finput.
     """
 
     mylog.vprint("Reading wages, contributions, conversions, and big-ticket items over time...")
@@ -52,21 +112,51 @@ def read(finput, inames, horizons, mylog):
         finput = "dictionary of DataFrames"
         streamName = "dictionary of DataFrames"
     else:
+        if filename is not None:
+            streamName = f"file '{filename}'"
+        elif hasattr(finput, "name"):
+            streamName = f"file '{finput.name}'"
+        else:
+            streamName = finput
+
         # Read all worksheets in memory but only process those with proper names.
         try:
-            dfDict = pd.read_excel(finput, sheet_name=None, usecols=_timeHorizonItems)
+            # dfDict = pd.read_excel(finput, sheet_name=None, usecols=_timeHorizonItems)
+            dfDict = pd.read_excel(finput, sheet_name=None)
         except Exception as e:
-            raise Exception(f"Could not read file {finput}: {e}.") from e
-        streamName = f"file '{finput}'"
-
-    timeLists = _condition(dfDict, inames, horizons, mylog)
+            raise Exception(f"Could not read file {streamName}: {e}.") from e
 
+    timeLists = _conditionTimetables(dfDict, inames, horizons, mylog)
     mylog.vprint(f"Successfully read time horizons from {streamName}.")
 
-    return finput, timeLists
+    houseLists = _conditionHouseTables(dfDict, mylog)
+    mylog.vprint(f"Successfully read household tables from {streamName}.")
+
+    return finput, timeLists, houseLists
+
+
+def _checkColumns(df, iname, colList):
+    """
+    Ensure all columns in colList are present. Remove others.
+    """
+    # Drop all columns not in the list.
+    # Make an explicit copy to avoid SettingWithCopyWarning
+    df = df.loc[:, ~df.columns.str.contains("^Unnamed")].copy()
+
+    # Collect columns to drop
+    cols_to_drop = [col for col in df.columns if col == "" or col not in colList]
+    if cols_to_drop:
+        df = df.drop(cols_to_drop, axis=1)
+
+    # Check that all columns in the list are present.
+    for item in colList:
+        if item not in df.columns:
+            raise ValueError(f"Column {item} not found for {iname}.")
 
+    return df
 
-def _condition(dfDict, inames, horizons, mylog):
+
+def _conditionTimetables(dfDict, inames, horizons, mylog):
     """
     Make sure that time horizons contain all years up to life expectancy,
     and that values are positive (except big-ticket items).
@@ -81,14 +171,10 @@ def _condition(dfDict, inames, horizons, mylog):
 
         df = dfDict[iname]
 
-        df = df.loc[:, ~df.columns.str.contains("^Unnamed")]
-        for col in df.columns:
-            if col == "" or col not in _timeHorizonItems:
-                df.drop(col, axis=1, inplace=True)
+        df = _checkColumns(df, iname, _timeHorizonItems)
 
-        for item in _timeHorizonItems:
-            if item not in df.columns:
-                raise ValueError(f"Item {item} not found for {iname}.")
+        # Ensure columns are in the correct order
+        df = df[_timeHorizonItems].copy()
 
         # Only consider lines in proper year range. Go back 5 years for Roth maturation.
         df = df[df["year"] >= (thisyear - 5)]
@@ -97,13 +183,17 @@ def _condition(dfDict, inames, horizons, mylog):
         missing = []
         for n in range(-5, horizons[i]):
             year = thisyear + n
-            if not (df[df["year"] == year]).any(axis=None):
-                df.loc[len(df)] = [year, 0, 0, 0, 0, 0, 0, 0, 0]
+            year_rows = df[df["year"] == year]
+            if year_rows.empty:
+                # Create a new row as a dictionary to ensure correct column mapping.
+                new_row = {col: 0 for col in _timeHorizonItems}
+                new_row["year"] = year
+                df = pd.concat([df, pd.DataFrame([new_row])], ignore_index=True)
                 missing.append(year)
             else:
                 for item in _timeHorizonItems:
-                    if item != "big-ticket items" and df[item].iloc[n] < 0:
-                        raise ValueError(f"Item {item} for {iname} in year {df['year'].iloc[n]} is < 0.")
+                    if item != "big-ticket items" and year_rows[item].iloc[0] < 0:
+                        raise ValueError(f"Item {item} for {iname} in year {year} is < 0.")
 
         if len(missing) > 0:
             mylog.vprint(f"Adding {len(missing)} missing years for {iname}: {missing}.")
@@ -115,8 +205,202 @@ def _condition(dfDict, inames, horizons, mylog):
         timeLists[iname] = df
 
         if df["year"].iloc[-1] != endyear - 1:
-            raise ValueError(
-                f"Time horizon for {iname} too short.\n\tIt should end in {endyear}, not {df['year'].iloc[-1]}"
-            )
+            raise ValueError(f"""Time horizon for {iname} too short.\n\t
+It should end in {endyear}, not {df['year'].iloc[-1]}""")
 
     return timeLists
+
+
+def _conditionHouseTables(dfDict, mylog):
+    """
+    Read debts and fixed assets from Household Financial Profile workbook.
+    """
+    houseDic = {}
+
+    items = {"Debts" : _debtItems, "Fixed Assets": _fixedAssetItems}
+    types = {"Debts" : _debtTypes, "Fixed Assets": _fixedAssetTypes}
+    for page in items.keys():
+        if page in dfDict:
+            df = dfDict[page]
+            df = _checkColumns(df, page, items[page])
+            # Check categorical variables.
+            isInList = df["type"].isin(types[page])
+            df = df[isInList]
+
+            # Convert percentage columns from decimal to percentage if needed
+            # UI uses 0-100 range for percentages (e.g., 4.5 = 4.5%)
+            # If Excel read percentage-formatted cells, values might be decimals (0.045)
+            # Convert values < 1.0 to percentage format (multiply by 100)
+            if page == "Debts" and "rate" in df.columns:
+                # If rate values are less than 1, assume they're decimals (0.045 = 4.5%)
+                # and convert to percentages (4.5) to match UI format (0-100 range)
+                mask = (df["rate"] < 1.0) & (df["rate"] > 0)
+                if mask.any():
+                    df.loc[mask, "rate"] = df.loc[mask, "rate"] * 100.0
+                    mylog.vprint(f"Converted {mask.sum()} rate value(s) from decimal to percentage in Debts table.")
+
+            elif page == "Fixed Assets":
+                # Convert rate and commission if they're decimals
+                # Both should be in 0-100 range to match UI format
+                if "rate" in df.columns:
+                    mask = (df["rate"] < 1.0) & (df["rate"] > 0)
+                    if mask.any():
+                        df.loc[mask, "rate"] = df.loc[mask, "rate"] * 100.0
+                        mylog.vprint(
+                            f"Converted {mask.sum()} rate value(s) from decimal "
+                            f"to percentage in Fixed Assets table."
+                        )
+                if "commission" in df.columns:
+                    mask = (df["commission"] < 1.0) & (df["commission"] > 0)
+                    if mask.any():
+                        df.loc[mask, "commission"] = df.loc[mask, "commission"] * 100.0
+                        mylog.vprint(
+                            f"Converted {mask.sum()} commission value(s) from decimal "
+                            f"to percentage in Fixed Assets table."
+                        )
+                # Validate and reset "year" column (reference year) if in the past
+                if "year" in df.columns:
+                    thisyear = date.today().year
+                    mask = df["year"] < thisyear
+                    if mask.any():
+                        df.loc[mask, "year"] = thisyear
+                        mylog.vprint(
+                            f"Reset {mask.sum()} reference year value(s) to {thisyear} "
+                            f"in Fixed Assets table (years cannot be in the past)."
+                        )
+
+            # Convert "active" column to boolean if it exists.
+            # Excel may read booleans as strings ("True"/"False") or numbers (1/0).
+            if "active" in df.columns:
+                df["active"] = df["active"].apply(u.convert_to_bool).astype(bool)
+
+            houseDic[page] = df
+            mylog.vprint(f"Found {len(df)} valid row(s) in {page} table.")
+        else:
+            houseDic[page] = pd.DataFrame(columns=items[page])
+            mylog.vprint(f"Table for {page} not found. Assuming empty table.")
+
+    return houseDic
+
+
+def conditionDebtsAndFixedAssetsDF(df, tableType, mylog=None):
+    """
+    Condition a DataFrame for Debts or Fixed Assets by:
+    - Creating an empty DataFrame with proper columns if df is None or empty
+    - Resetting the index
+    - Filling NaN values with 0 while preserving boolean columns (like "active")
+
+    Parameters
+    ----------
+    df : pandas.DataFrame or None
+        The DataFrame to condition, or None/empty to create a new empty DataFrame
+    tableType : str
+        Type of table: "Debts" or "Fixed Assets"
+    mylog : logger, optional
+        Logger instance for optional UI/log output
+
+    Returns
+    -------
+    pandas.DataFrame
+        Conditioned DataFrame with proper columns and no NaN values (except boolean columns default to True)
+    """
+    # Map table type to column items
+    items = {"Debts": _debtItems, "Fixed Assets": _fixedAssetItems}
+    if tableType not in items:
+        raise ValueError(f"tableType must be 'Debts' or 'Fixed Assets', got '{tableType}'")
+
+    columnItems = items[tableType]
+
+    df = u.ensure_dataframe(df, pd.DataFrame(columns=columnItems))
+
+    df = df.copy()
+    df.reset_index(drop=True, inplace=True)
+
+    # Ensure all required columns exist
+    for col in columnItems:
+        if col not in df.columns:
+            df[col] = None
+
+    # Only keep the columns we need, in the correct order
+    df = df[columnItems].copy()
+
+    # Define which columns are integers vs floats
+    if tableType == "Debts":
+        int_cols = ["year", "term"]
+        float_cols = ["amount", "rate"]
+    else:  # Fixed Assets
+        int_cols = ["year", "yod"]
+        float_cols = ["basis", "value", "rate", "commission"]
+
+    # Handle empty DataFrame by setting dtypes directly
+    if len(df) == 0:
+        dtype_dict = {}
+        dtype_dict["active"] = bool
+        for col in ["name", "type"]:
+            dtype_dict[col] = "object"  # string columns
+        for col in int_cols:
+            dtype_dict[col] = "int64"
+        for col in float_cols:
+            dtype_dict[col] = "float64"
+        df = df.astype(dtype_dict)
+    else:
+        # Fill NaN values and ensure proper types for non-empty DataFrame
+        for col in df.columns:
+            if col == "active":
+                # Ensure "active" column is boolean, handling strings/numbers from Excel
+                df[col] = df[col].apply(u.convert_to_bool).astype(bool)
+            elif col in ["name", "type"]:
+                # String columns: ensure they are strings, not lists
+                # Streamlit data_editor can return lists for string columns in some cases
+                def convert_to_string(val):
+                    if pd.isna(val) or val is None:
+                        return ""
+                    if isinstance(val, list):
+                        # If it's a list, join the elements (handles Streamlit data_editor edge cases)
+                        # Filter out None/NaN values before joining
+                        cleaned = [str(x) for x in val if x is not None and not pd.isna(x)]
+                        return " ".join(cleaned) if cleaned else ""
+                    return str(val)
+
+                df[col] = df[col].apply(convert_to_string).astype(str)
+                # Replace "nan" string with empty string
+                df[col] = df[col].replace("nan", "").replace("None", "")
+            elif col in int_cols:
+                # Integer columns: convert to int64, fill NaN with 0
+                df[col] = pd.to_numeric(df[col], errors="coerce").fillna(0).astype("int64")
+            elif col in float_cols:
+                # Float columns: convert to float64, fill NaN with 0.0
+                df[col] = pd.to_numeric(df[col], errors="coerce").fillna(0.0).astype("float64")
+
+    # For Fixed Assets, validate and reset "year" column if in the past
+    if tableType == "Fixed Assets" and "year" in df.columns and len(df) > 0:
+        thisyear = date.today().year
+        mask = df["year"] < thisyear
+        if mask.any():
+            df.loc[mask, "year"] = thisyear
+
+    if mylog is not None:
+        mylog.vprint(f"Found {len(df)} valid row(s) in {tableType} table.")
+
+    return df
+
+
+def getTableTypes(tableType):
+    """
+    Get the list of valid types for a given table type.
+
+    Parameters
+    ----------
+    tableType : str
+        Type of table: "Debts" or "Fixed Assets"
+
+    Returns
+    -------
+    list
+        List of valid types for the specified table
+    """
+    types = {"Debts": _debtTypes, "Fixed Assets": _fixedAssetTypes}
+    if tableType not in types:
+        raise ValueError(f"tableType must be 'Debts' or 'Fixed Assets', got '{tableType}'")
+
+    return types[tableType]

owlplanner/utils.py

@@ -1,17 +1,28 @@
 """
+Utility functions for data formatting and manipulation.
 
-Owl/utils
+This module provides helper functions for formatting currency, percentages,
+and other data transformations used throughout the retirement planner.
 
-This file contains functions for handling data.
+Copyright (C) 2025-2026 The Owlplanner Authors
 
-Copyright © 2024 - Martin-D. Lacasse
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
 
-Disclaimers: This code is for educational purposes only and does not constitute financial advice.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
 
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
 """
 
 ######################################################################
 import numpy as np
+import pandas as pd
 
 
 def d(value, f=0, latex=False) -> str:
@@ -70,7 +81,16 @@ def getUnits(units) -> int:
     return fac
 
 
-# Next two functins could be a one-line lambda functions.
+def get_numeric_option(options, key, default, *, min_value=None) -> float:
+    value = options.get(key, default)
+    if not isinstance(value, (int, float)):
+        raise ValueError(f"{key} {value} is not a number.")
+    if min_value is not None and value < min_value:
+        raise ValueError(f"{key} must be >= {min_value}.")
+    return float(value)
+
+
+# Next two functions could be a one-line lambda functions.
 # e.g., krond = lambda a, b: 1 if a == b else 0
 def krond(a, b) -> int:
     """
@@ -101,3 +121,182 @@ def roundCents(values, decimals=2):
     arr = np.where((-0.009 < arr) & (arr <= 0), 0, arr)
 
     return arr
+
+
+def parseDobs(dobs):
+    """
+    Parse a list of dates and return int32 arrays of year, months, days.
+    """
+    icount = len(dobs)
+    yobs = []
+    mobs = []
+    tobs = []
+    for i in range(icount):
+        ls = dobs[i].split("-")
+        if len(ls) != 3:
+            raise ValueError(f"Date {dobs[i]} not in ISO format.")
+        if not 1 <= int(ls[1]) <= 12:
+            raise ValueError(f"Month in date {dobs[i]} not valid.")
+        if not 1 <= int(ls[2]) <= 31:
+            raise ValueError(f"Day in date {dobs[i]} not valid.")
+
+        yobs.append(ls[0])
+        mobs.append(ls[1])
+        tobs.append(ls[2])
+
+    return np.array(yobs, dtype=np.int32), np.array(mobs, dtype=np.int32), np.array(tobs, dtype=np.int32)
+
+
+def is_row_active(row):
+    """
+    Check if a DataFrame row should be processed based on 'active' column.
+
+    This function handles the common pattern of checking whether a row in a DataFrame
+    should be processed based on its 'active' column value. The logic is:
+    - If 'active' column doesn't exist, the row is considered active (default behavior)
+    - If 'active' value is NaN or None, the row is considered active (default behavior)
+    - If 'active' value is explicitly False (or falsy), the row is considered inactive
+    - Otherwise (True or truthy), the row is considered active
+
+    Parameters
+    ----------
+    row : pd.Series
+        A pandas Series representing a row from a DataFrame. The row should have
+        an 'active' column (or index entry) if the active/inactive status is to be checked.
+
+    Returns
+    -------
+    bool
+        True if the row should be processed (is active), False if it should be skipped (is inactive).
+    """
+    if "active" not in row.index:
+        return True  # Default to active if column doesn't exist
+    active_value = row["active"]
+    if pd.isna(active_value) or active_value is None:
+        return True  # NaN/None means active
+    return bool(active_value)
+
+
+def is_dataframe_empty(df):
+    """
+    Check if a DataFrame is None or empty.
+
+    This function consolidates the common pattern of checking
+    `df is None or df.empty` throughout the codebase.
+
+    Parameters
+    ----------
+    df : pd.DataFrame or None
+        The DataFrame to check. Can be None or an empty DataFrame.
+
+    Returns
+    -------
+    bool
+        True if df is None or empty, False otherwise.
+    """
+    return df is None or df.empty
+
+
+def ensure_dataframe(df, default_empty=None):
+    """
+    Ensure DataFrame is not None or empty, return default if needed.
+
+    This function checks if a DataFrame is None or empty and returns a default
+    value if so. This consolidates the common pattern of checking
+    `df is None or df.empty` throughout the codebase.
+
+    Parameters
+    ----------
+    df : pd.DataFrame or None
+        The DataFrame to check. Can be None or an empty DataFrame.
+    default_empty : any, optional
+        The value to return if df is None or empty. Default is None.
+        Common values are 0.0, np.zeros(N_n), or a default DataFrame.
+
+    Returns
+    -------
+    any
+        Returns default_empty if df is None or empty, otherwise returns df.
+    """
+    if is_dataframe_empty(df):
+        return default_empty
+    return df
+
+
+def get_empty_array_or_value(N_n, default_value=0.0):
+    """
+    Return empty array or single value based on context.
+
+    This helper function returns either a numpy array of zeros with length N_n
+    if N_n is provided, or a single default value if N_n is None.
+
+    Parameters
+    ----------
+    N_n : int or None
+        Length of the array to create. If None, returns default_value instead.
+    default_value : float, optional
+        Default value to return if N_n is None. Default is 0.0.
+
+    Returns
+    -------
+    np.ndarray or float
+        Returns np.zeros(N_n) if N_n is not None, otherwise returns default_value.
+    """
+    if N_n is not None:
+        return np.zeros(N_n)
+    return default_value
+
+
+def convert_to_bool(val):
+    """
+    Convert various input types to boolean.
+
+    Handles conversion from strings, numbers, booleans, and NaN values.
+    Excel may read booleans as strings ("True"/"False") or numbers (1/0),
+    so this function provides robust conversion.
+
+    Parameters
+    ----------
+    val : any
+        Value to convert to boolean. Can be:
+        - bool: returned as-is
+        - str: "True", "False", "1", "0", "yes", "no", etc.
+        - numeric: 1/0 or other numeric values
+        - None/NaN: defaults to True
+
+    Returns
+    -------
+    bool
+        Boolean value. NaN/None and unknown values default to True.
+    """
+    # Check for None first (before pd.isna which can fail on some types)
+    if val is None:
+        return True  # Default to True for None
+
+    # Check for NaN, but handle cases where pd.isna might fail (e.g., empty lists)
+    try:
+        if pd.isna(val):
+            return True  # Default to True for NaN
+    except (ValueError, TypeError):
+        # pd.isna can raise ValueError for empty arrays/lists
+        # or TypeError for unhashable types - treat as non-NaN and continue
+        pass
+    if isinstance(val, bool):
+        return val
+    if isinstance(val, str):
+        # Handle string representations
+        val_lower = val.lower().strip()
+        if val_lower in ("true", "1", "yes", "y"):
+            return True
+        elif val_lower in ("false", "0", "no", "n"):
+            return False
+        else:
+            # Unknown string, default to True
+            return True
+    # Handle numeric values (1/0)
+    try:
+        num_val = float(val)
+        return bool(num_val) if num_val != 0 else False
+    except (ValueError, TypeError):
+        # Can't convert, default to True
+        return True

owlplanner/version.py

@@ -1 +1,20 @@
-__version__ = "2025.12.05"
+"""
+Package version information.
+
+Copyright (C) 2025-2026 The Owlplanner Authors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+"""
+
+__version__ = "2026.01.26"