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

owlplanner/socialsecurity.py

@@ -18,8 +18,23 @@ import numpy as np
 
 def getFRAs(yobs):
     """
-    Return full retirement age based on birth year.
-    Returns an array of fractional age.
+    Return full retirement age (FRA) based on birth year.
+
+    The FRA is determined by birth year according to Social Security rules:
+    - Birth year >= 1960: FRA is 67
+    - Birth year < 1960: FRA increases by 2 months for each year after 1954
+
+    Parameters
+    ----------
+    yobs : array-like
+        Array of birth years, one for each individual.
+
+    Returns
+    -------
+    numpy.ndarray
+        Array of FRA values in fractional years (1/12 increments), one for each individual.
+        Ages are returned in Social Security age format. Comparisons to FRA should be
+        done using Social Security age (which accounts for birthday-on-first adjustments).
     """
     fras = np.zeros(len(yobs))
 
@@ -35,7 +50,32 @@ def getFRAs(yobs):
 
 def getSpousalBenefits(pias):
     """
-    Compute spousal benefit. Returns an array.
+    Compute the maximum spousal benefit amount for each individual.
+
+    The spousal benefit is calculated as 50% of the spouse's Primary Insurance Amount (PIA),
+    minus the individual's own PIA. The result is the additional benefit the individual
+    would receive as a spouse, which cannot be negative.
+
+    Note: This calculation is not affected by which day of the month is the birthday.
+
+    Parameters
+    ----------
+    pias : array-like
+        Array of Primary Insurance Amounts (monthly benefit at FRA), one for each individual.
+        Must have exactly 1 or 2 entries.
+
+    Returns
+    -------
+    numpy.ndarray
+        Array of spousal benefit amounts (monthly), one for each individual.
+        For a single individual, returns [0].
+        For two individuals, returns the additional spousal benefit each would receive
+        (which is max(0, 0.5 * spouse_PIA - own_PIA)).
+
+    Raises
+    ------
+    ValueError
+        If the pias array does not have exactly 1 or 2 entries.
     """
     icount = len(pias)
     benefits = np.zeros(icount)
@@ -51,15 +91,51 @@ def getSpousalBenefits(pias):
     return benefits
 
 
-def getSelfFactor(fra, age):
+def getSelfFactor(fra, convage, bornOnFirst):
     """
-    Return factor to multiply PIA given the age when SS starts.
-    Year of FRA and age can be fractional.
+    Return the reduction/increase factor to multiply PIA based on claiming age.
+
+    This function calculates the adjustment factor for self benefits based on when
+    Social Security benefits start relative to Full Retirement Age (FRA):
+    - Before FRA: Benefits are reduced (minimum 70% at age 62)
+    - At FRA: Full benefit (100% of PIA)
+    - After FRA: Benefits are increased by 8% per year (up to 132% at age 70)
+
+    The function automatically adjusts for Social Security age if the birthday is on
+    the first day of the month (adds 1/12 year to conventional age).
+
+    Parameters
+    ----------
+    fra : float
+        Full Retirement Age in years (can be fractional with 1/12 increments).
+    convage : float
+        Conventional age when benefits start, in years (can be fractional with 1/12 increments).
+        Must be between 62 and 70 inclusive.
+    bornOnFirst : bool
+        True if birthday is on the first day of the month, False otherwise.
+        If True, the function adds 1/12 year to convert to Social Security age.
+
+    Returns
+    -------
+    float
+        Factor to multiply PIA. Examples:
+        - 0.75 = 75% of PIA (claiming at 62 with FRA of 66)
+        - 1.0 = 100% of PIA (claiming at FRA)
+        - 1.32 = 132% of PIA (claiming at 70 with FRA of 66)
+
+    Raises
+    ------
+    ValueError
+        If convage is less than 62 or greater than 70.
     """
-    if age < 62 or age > 70:
-        raise ValueError(f"Age {age} out of range.")
+    if convage < 62 or convage > 70:
+        raise ValueError(f"Age {convage} out of range.")
 
-    diff = fra - age
+    # Add a month to conventional age if born on the first.
+    offset = 0 if not bornOnFirst else 1/12
+    ssage = convage + offset
+
+    diff = fra - ssage
     if diff <= 0:
         return 1. - .08 * diff
     elif diff <= 3:
@@ -70,15 +146,50 @@ def getSelfFactor(fra, age):
         return .8 - 0.05 * (diff - 3)
 
 
-def getSpousalFactor(fra, age):
+def getSpousalFactor(fra, convage, bornOnFirst):
     """
-    Return factor to multiply spousal benefit given the age when benefit starts.
-    Year of FRA and age can be fractional.
+    Return the reduction factor to multiply spousal benefits based on claiming age.
+
+    This function calculates the adjustment factor for spousal benefits based on when
+    benefits start relative to Full Retirement Age (FRA):
+    - Before FRA: Benefits are reduced (minimum 32.5% at age 62)
+    - At or after FRA: Full spousal benefit (50% of spouse's PIA, no increase for delay)
+
+    The function automatically adjusts for Social Security age if the birthday is on
+    the first day of the month (adds 1/12 year to conventional age).
+
+    Parameters
+    ----------
+    fra : float
+        Full Retirement Age in years (can be fractional with 1/12 increments).
+    convage : float
+        Conventional age when benefits start, in years (can be fractional with 1/12 increments).
+        Must be at least 62 (no maximum, but no increase beyond FRA).
+    bornOnFirst : bool
+        True if birthday is on the first day of the month, False otherwise.
+        If True, the function adds 1/12 year to convert to Social Security age.
+
+    Returns
+    -------
+    float
+        Factor to multiply spousal benefit. Examples:
+        - 0.325 = 32.5% reduction factor (claiming at 62 with FRA of 66)
+        - 1.0 = 100% of spousal benefit (claiming at or after FRA)
+        Note: Unlike self benefits, spousal benefits do not increase beyond FRA.
+
+    Raises
+    ------
+    ValueError
+        If convage is less than 62.
     """
-    if age < 62:
-        raise ValueError(f"Age {age} out of range.")
+    if convage < 62:
+        raise ValueError(f"Age {convage} out of range.")
+
+    # Add a month to conventional age if born on the first.
+    offset = 0 if not bornOnFirst else 1/12
+    ssage = convage + offset
 
-    diff = fra - age
+    diff = fra - ssage
     if diff <= 0:
         return 1.
     elif diff <= 3:

owlplanner/tax2025.py

@@ -273,6 +273,26 @@ def taxBrackets(N_i, n_d, N_n, yOBBBA=2099):
     return data
 
 
+def computeNIIT(N_i, MAGI_n, I_n, Q_n, n_d, N_n):
+    """
+    Compute ACA tax on Dividends (Q) and Interests (I).
+    For accounting for rent and/or trust income, one can easily add a column
+    to the Wages and Contributions file and add yearly amount to Q_n + I_n below.
+    """
+    J_n = np.zeros(N_n)
+    status = N_i - 1
+
+    for n in range(N_n):
+        if status and n == n_d:
+            status -= 1
+
+        Gmax = niitThreshold[status]
+        if MAGI_n[n] > Gmax:
+            J_n[n] = niitRate * min(MAGI_n[n] - Gmax, I_n[n] + Q_n[n])
+
+    return J_n
+
+
 def rho_in(yobs, N_n):
     """
     Return Required Minimum Distribution fractions for each individual.

owlplanner/tax2026.py

@@ -20,20 +20,12 @@ import numpy as np
 from datetime import date
 
 
-##############################################################################
-# Prepare the data.
-
-taxBracketNames = ["10%", "12/15%", "22/25%", "24/28%", "32/33%", "35%", "37/40%"]
-
-rates_OBBBA = np.array([0.10, 0.12, 0.22, 0.24, 0.32, 0.35, 0.370])
-rates_preTCJA = np.array([0.10, 0.15, 0.25, 0.28, 0.33, 0.35, 0.396])
-
 ###############################################################################
 # Start of section where rates need to be actualized every year.
 ###############################################################################
 # Single [0] and married filing jointly [1].
 
-# These are 2025 current.
+# These are current for 2026, i.e., applying to tax year 2025.
 taxBrackets_OBBBA = np.array(
     [
         [12400, 50400, 105700, 201775, 256225, 640600, 9999999],
@@ -41,17 +33,20 @@ taxBrackets_OBBBA = np.array(
     ]
 )
 
+# These are current for 2026 (2025TY).
 irmaaBrackets = np.array(
     [
-        [0, 106000, 133000, 167000, 200000, 500000],
-        [0, 212000, 266000, 334000, 400000, 750000],
+        [0, 109000, 137000, 171000, 205000, 500000],
+        [0, 218000, 274000, 342000, 410000, 750000],
     ]
 )
 
-# Index [0] stores the standard Medicare part B premium.
+# These are current for 2026 (2025TY).
+# Index [0] stores the standard Medicare part B basic premium.
 # Following values are incremental IRMAA part B monthly fees.
-irmaaFees = 12 * np.array([185.00, 74.00, 111.00, 110.90, 111.00, 37.00])
+irmaaFees = 12 * np.array([202.90, 81.20, 121.70, 121.70, 121.70, 40.70])
 
+#########################################################################
 # Make projection for pre-TCJA using 2017 to current year.
 # taxBrackets_2017 = np.array(
 #    [ [9325, 37950, 91900, 191650, 416700, 418400, 9999999],
@@ -60,41 +55,60 @@ irmaaFees = 12 * np.array([185.00, 74.00, 111.00, 110.90, 111.00, 37.00])
 #
 # stdDeduction_2017 = [6350, 12700]
 #
-# For 2025, I used a 30.5% adjustment from 2017, rounded to closest 50.
+# COLA from 2017: [2.0, 2.8, 1.6, 1.3, 5.9, 8.7, 3.2, 2.5, 2.8]
+# For 2026, I used a 35.1% adjustment from 2017, rounded to closest 10.
 #
 # These are speculated.
 taxBrackets_preTCJA = np.array(
     [
-        [12150, 49550, 119950, 250200, 544000, 546200, 9999999],  # Single
-        [24350, 99100, 199850, 304600, 543950, 614450, 9999999],  # MFJ
+        [12600, 51270, 124160, 258920, 562960, 565260, 9999999],   # Single
+        [25200, 102540, 206840, 315260, 562960, 635920, 9999999],  # MFJ
     ]
 )
 
-# These are 2025 current.
+# These are speculated (adjusted for inflation to 2026).
+stdDeduction_preTCJA = np.array([8580, 17160])   # Single, MFJ
+#########################################################################
+
+# These are current for 2026 (2025TY).
 stdDeduction_OBBBA = np.array([16100, 32200])    # Single, MFJ
-# These are speculated (adjusted for inflation to 2026). TODO
-stdDeduction_preTCJA = np.array([8300, 16600])  # Single, MFJ
 
-# These are current (adjusted for inflation) per individual.
-extra65Deduction = np.array([2000, 1600])       # Single, MFJ
+# These are current for 2026  (2025TY) per individual.
+extra65Deduction = np.array([2000, 1600])        # Single, MFJ
 
-# Thresholds setting capital gains brackets 0%, 15%, 20% (adjusted for inflation).
+# These are current for 2026 (2025TY).
+# Thresholds setting capital gains brackets 0%, 15%, 20%.
 capGainRates = np.array(
     [
-        [48350, 533400],
-        [96700, 600050],
+        [49450, 545500],
+        [98900, 613700],
     ]
 )
 
+###############################################################################
+# End of section where rates need to be actualized every year.
+###############################################################################
+
+###############################################################################
+# Data that is unlikely to change.
+###############################################################################
+
 # Thresholds for net investment income tax (not adjusted for inflation).
 niitThreshold = np.array([200000, 250000])
 niitRate = 0.038
 
-# Thresholds for 65+ bonus for circumventing tax on social security.
+# Thresholds for 65+ bonus of $6k per individual for circumventing tax
+# on social security for low-income households. This expires in 2029.
+# These numbers are hard-coded below as the tax code will likely change
+# the rules for eligibility and will require a code review.
+# Bonus decreases linearly above threshold by 1% / $1k over threshold.
 bonusThreshold = np.array([75000, 150000])
 
-###############################################################################
-# End of section where rates need to be actualized every year.
+taxBracketNames = ["10%", "12/15%", "22/25%", "24/28%", "32/33%", "35%", "37/40%"]
+
+rates_OBBBA = np.array([0.10, 0.12, 0.22, 0.24, 0.32, 0.35, 0.370])
+rates_preTCJA = np.array([0.10, 0.15, 0.25, 0.28, 0.33, 0.35, 0.396])
+
 ###############################################################################
 
 
@@ -273,6 +287,26 @@ def taxBrackets(N_i, n_d, N_n, yOBBBA=2099):
     return data
 
 
+def computeNIIT(N_i, MAGI_n, I_n, Q_n, n_d, N_n):
+    """
+    Compute ACA tax on Dividends (Q) and Interests (I).
+    For accounting for rent and/or trust income, one can easily add a column
+    to the Wages and Contributions file and add yearly amount to Q_n + I_n below.
+    """
+    J_n = np.zeros(N_n)
+    status = N_i - 1
+
+    for n in range(N_n):
+        if status and n == n_d:
+            status -= 1
+
+        Gmax = niitThreshold[status]
+        if MAGI_n[n] > Gmax:
+            J_n[n] = niitRate * min(MAGI_n[n] - Gmax, I_n[n] + Q_n[n])
+
+    return J_n
+
+
 def rho_in(yobs, N_n):
     """
     Return Required Minimum Distribution fractions for each individual.

owlplanner/timelists.py

@@ -34,6 +34,43 @@ _timeHorizonItems = [
 ]
 
 
+_debtItems = [
+    "name",
+    "type",
+    "year",
+    "term",
+    "amount",
+    "rate",
+]
+
+
+_debtTypes = [
+    "loan",
+    "mortgage",
+]
+
+
+_fixedAssetItems = [
+    "name",
+    "type",
+    "basis",
+    "value",
+    "rate",
+    "yod",
+    "commission",
+]
+
+
+_fixedAssetTypes = [
+    "collectibles",
+    "fixed annuity",
+    "precious metals",
+    "real estate",
+    "residence",
+    "stocks",
+]
+
+
 def read(finput, inames, horizons, mylog):
     """
     Read listed parameters from an excel spreadsheet or through
@@ -54,19 +91,40 @@ def read(finput, inames, horizons, mylog):
     else:
         # 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)
-
+    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 _condition(dfDict, inames, horizons, mylog):
+def _checkColumns(df, iname, colList):
+    """
+    Ensure all columns in colList are present. Remove others.
+    """
+    # Drop all columns not in the list.
+    df = df.loc[:, ~df.columns.str.contains("^Unnamed")]
+    for col in df.columns:
+        if col == "" or col not in colList:
+            df.drop(col, axis=1, inplace=True)
+
+    # 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 _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 +139,7 @@ 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)
-
-        for item in _timeHorizonItems:
-            if item not in df.columns:
-                raise ValueError(f"Item {item} not found for {iname}.")
+        df = _checkColumns(df, iname, _timeHorizonItems)
 
         # Only consider lines in proper year range. Go back 5 years for Roth maturation.
         df = df[df["year"] >= (thisyear - 5)]
@@ -97,13 +148,14 @@ 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):
+            year_rows = df[df["year"] == year]
+            if year_rows.empty:
                 df.loc[len(df)] = [year, 0, 0, 0, 0, 0, 0, 0, 0]
                 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 +167,64 @@ 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."
+                        )
+
+            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

owlplanner/utils.py

@@ -70,7 +70,7 @@ def getUnits(units) -> int:
     return fac
 
 
-# Next two functins could be a one-line lambda functions.
+# 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 +101,27 @@ 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)

owlplanner/version.py

@@ -1 +1 @@
-__version__ = "2025.12.05"
+__version__ = "2025.12.20"