refactor on lease projection/model

yellowbean · yellowbean · commit 9db875b09f72 · 2025-05-10T23:39:23.000+08:00
diff --git a/absbox/local/base.py b/absbox/local/base.py
@@ -39,9 +39,9 @@
 china_mortgage_delinq_flow_fields_d = [china_date] + china_mortgage_delinq_flow_fields
 english_mortgage_delinq_flow_fields_d = [english_date] + english_mortgage_delinq_flow_fields
 
-## Rental
-china_rental_flow = ['待收金额', '租金']
-english_rental_flow = ['Balance', 'Rental']
+## Rental/Lease flow
+china_rental_flow = ['待收金额', '租金', '违约']
+english_rental_flow = ['Balance', 'Rental', 'Default']
 china_rental_flow_d = [china_date] + china_rental_flow
 english_rental_flow_d = [english_date] + english_rental_flow
 
diff --git a/absbox/local/component.py b/absbox/local/component.py
@@ -1410,9 +1410,9 @@ def mkAmortPlan(x) -> dict:
             return mkTag(("NO_FirstN", [n, mkAmortPlan(_pt)]))
         case ("IO_FirstN", n, _pt):
             return mkTag(("IO_FirstN", [n, mkAmortPlan(_pt)]))
-        case ("计划还款", ts, Dp) | ("Schedule", ts, Dp):
+        case ("计划还款", ts, Dp) | ("Schedule", ts, Dp) | ("schedule", ts, Dp):
             return mkTag(("ScheduleRepayment", [mkTs("RatioCurve", ts), mkDatePattern(Dp)]))
-        case ("计划还款", ts) | ("Schedule", ts):
+        case ("计划还款", ts) | ("Schedule", ts) | ("schedule", ts):
             return mkTag(("ScheduleRepayment", [mkTs("RatioCurve", ts), None]))
         case ("Balloon", n):
             return mkTag(("Balloon", n))
@@ -1524,6 +1524,15 @@ def mkLeaseStepUp(x):
             return mkTag(("ByAmountCurve", vList(bs, vNum)))
         case _ :
             raise RuntimeError(f"Failed to match {x}:mkLeaseStepUp")
+
+def mkLeaseCalc(x):
+    match x:
+        case ("byDay", dr, dp):
+            return mkTag(("ByDayRate", [dr, mkDatePattern(dp)]))
+        case ("byPeriod", rental, period):
+            return mkTag(("ByPeriodRetnal", [rental, period]))
+        case _ :
+            raise RuntimeError(f"Failed to match {x}:mkLeaseCalc")
         
 
 def mkAsset(x):
@@ -1600,25 +1609,28 @@ def mkAsset(x):
                 vNum(currentBalance),
                 vInt(remainTerms),
                 mkAssetStatus(status)]))
-        case ["租赁", {"固定租金": dailyRate, "初始期限": originTerm, "频率": dp, "起始日": startDate, "状态": status, "剩余期限": remainTerms}] \
-                | ["Lease", {"fixRental": dailyRate, "originTerm": originTerm, "freq": dp, "originDate": startDate, "status": status, "remainTerm": remainTerms}]:
+        case ["租赁", {"租金": rental, "初始期限": originTerm, "起始日": startDate}
+                    ,{"当前余额": bal, "剩余期限": remainTerms,"状态": status}] \
+                | ["Lease", {"rental": rental, "originTerm": originTerm, "originDate": startDate}
+                , {"currentBalance": bal,"status": status, "remainTerm": remainTerms}]:
             obligorInfo = getValWithKs(x[1],["obligor","借款人"], mapping=mkObligor)
             return mkTag(("RegularLease"
-                            , [{"originTerm": originTerm, "startDate": startDate, "paymentDates": mkDatePattern(dp), "originRental": dailyRate
+                            , [{"originTerm": originTerm, "startDate": startDate, "originRental": mkLeaseCalc(rental)
                                 ,"obligor": obligorInfo} | mkTag("LeaseInfo")
-                                , 0
-                                , remainTerms
+                                , vNum(bal)
+                                , vInt(remainTerms)
                                 , mkAssetStatus(status)]))
-        case ["租赁", {"初始租金": dailyRate, "初始期限": originTerm, "频率": dp, "起始日": startDate, "状态": status, "剩余期限": remainTerms,"调整":sut}] \
-                | ["Lease", {"initRental": dailyRate, "stepUp":sut, "originTerm": originTerm, "freq": dp, "originDate": startDate, "status": status, "remainTerm": remainTerms}]:
-
+        case ["租赁", {"租金": rental, "初始期限": originTerm, "起始日": startDate, "调整":sut}
+                    ,{"当前余额":bal,"状态": status, "剩余期限": remainTerms}] \
+                | ["Lease", {"rental": rental, "stepUp":sut, "originTerm": originTerm, "originDate": startDate}
+                    ,{"currentBalance":bal, "status": status, "remainTerm": remainTerms}]:
             obligorInfo = getValWithKs(x[1],["obligor","借款人"], mapping=mkObligor)
             _stepUpType = mkLeaseStepUp(sut)
             return mkTag(("StepUpLease"
-                        , [{"originTerm": originTerm, "startDate": startDate, "paymentDates": mkDatePattern(dp), "originRental": dailyRate, "obligor": obligorInfo} | mkTag("LeaseInfo")
+                        , [{"originTerm": originTerm, "startDate": startDate, "originRental": mkLeaseCalc(rental), "obligor": obligorInfo} | mkTag("LeaseInfo")
                         , _stepUpType
-                        , 0
-                        , remainTerms
+                        , vNum(bal)
+                        , vInt(remainTerms)
                         , mkAssetStatus(status)]))
         case ["固定资产",{"起始日":sd,"初始余额":ob,"初始期限":ot,"残值":rb,"周期":p,"摊销":ar,"产能":cap}
                       ,{"剩余期限":rt,"余额":bal}] \
@@ -1745,7 +1757,7 @@ def mkAssumpDefault(x):
         case {"byTerm": rs}:
             return mkTag(("DefaultByTerm", vListOfList(rs, numVal)))
         case _ :
-            raise RuntimeError(f"failed to match {x}")
+            raise RuntimeError(f"failed to match {x}:mkAssumpDefault")
 
 
 def mkAssumpPrepay(x):
@@ -1764,7 +1776,7 @@ def mkAssumpPrepay(x):
         case {"byTerm": rs}:
             return mkTag(("PrepaymentByTerm", vListOfList(rs, numVal)))
         case _ :
-            raise RuntimeError(f"failed to match {x}")
+            raise RuntimeError(f"failed to match {x}:mkAssumpPrepay")
 
 
 def mkAssumpDelinq(x):
@@ -1773,19 +1785,17 @@ def mkAssumpDelinq(x):
         case {"DelinqCDR": cdr, "Lag": lag, "DefaultPct": pct}:
             return mkTag(("DelinqCDR", [cdr, (lag, pct)]))
         case _:
-            raise RuntimeError(f"failed to match {x}")
+            raise RuntimeError(f"failed to match {x}:mkAssumpDelinq")
 
 
 def mkAssumpLeaseGap(x):
     match x:
-        case {"Days":d}:
+        case {"Days":d} | ("days",d):
             return mkTag(("GapDays",vInt(d)))
-        case {"DaysByAmount":(tbl,d)}:
-            return mkTag(("GapDaysByAmount",[tbl, vInt(d)]))
-        case {"DaysByCurve": ts}:
-            return mkTag(("GapDaysByCurve",mkTs("IntCurve",ts)))
+        case ("byCurve", c):
+            return mkTag(("GapDaysByCurve", mkTs("IntCurve",c)))
         case _:
-            raise RuntimeError(f"failed to match {x}")
+            raise RuntimeError(f"failed to match {x}:mkAssumpLeaseGap")
 
 
 def mkAssumpLeaseRent(x):
@@ -1795,18 +1805,26 @@ def mkAssumpLeaseRent(x):
         case {"CurveIncrease":rc} | ("byRateCurve", rc):
             return mkTag(("BaseCurve", mkTs("RateCurve",rc)))
         case _:
-            raise RuntimeError(f"failed to match {x}")
+            raise RuntimeError(f"failed to match {x}:mkAssumpLeaseRent")
 
 
 def mkAssumpLeaseEndType(x):
     match x:
-        case {"byDate":d} | ("byDate",d):
-            return mkTag("CutByDate",vDate(d))
+        case {"byDate":d} | ("byDate", d):
+            return mkTag("CutByDate", vDate(d))
         case {"stopByExtNum":n} | ("byExtTimes",n):
-            return mkTag("StopByExtTimes",vInt(n))
+            return mkTag("StopByExtTimes", vInt(n))
         case _:
-            raise RuntimeError(f"failed to match {x}")
+            raise RuntimeError(f"failed to match {x}:mkAssumpLeaseEndType")
 
+def mkAssumpLeaseDefaultType(x):
+    match x:
+        case ("byContinuation",r):
+            return mkTag(("DefaultByContinuation", vNum(r)))
+        case ("byTermination",r):
+            return mkTag(("DefaultByTermination", vNum(r)))
+        case _:
+            raise RuntimeError(f"failed to match {x}")
 
 
 def mkAssumpRecovery(x):
@@ -1876,7 +1894,7 @@ def mkExtraStress(y):
             r = earlyReturnNone(mkAssumpRecovery,mr)
             return mkTag(("MortgageAssump",[d,p,r,mkExtraStress(mes)]))
         case ("Lease", md, gap, rent, endType):
-            return mkTag(("LeaseAssump",[earlyReturnNone(mkAssumpDefault,md)
+            return mkTag(("LeaseAssump",[earlyReturnNone(mkAssumpLeaseDefaultType,md)
                                         ,mkAssumpLeaseGap(gap)
                                         ,mkAssumpLeaseRent(rent)
                                         ,mkEndType(endType)
diff --git a/absbox/local/util.py b/absbox/local/util.py
@@ -255,9 +255,9 @@ def guess_pool_flow_header(x, l):
             return (english_loan_flow_d, "Date", False)
         case ('LoanFlow', 10, 'english'):
             return (english_loan_flow_d+english_cumStats, "Date", True)
-        case ('LeaseFlow', 3, 'chinese'):
+        case ('LeaseFlow', 4, 'chinese'):
             return (china_rental_flow_d, "日期", False)
-        case ('LeaseFlow', 3, 'english'):
+        case ('LeaseFlow', 4, 'english'):
             return (english_rental_flow_d, "Date", False)
         case ('FixedFlow', 6, 'chinese'):
             return (china_fixed_flow_d, "日期", False)
diff --git a/docs/source/analytics.rst b/docs/source/analytics.rst
@@ -433,7 +433,7 @@ Lease
 .. code-block:: python
 
    r = localAPI.run(deal
-                  ,poolAssump = ("Pool",("Lease",<turnover gap>,<rental assump>,<end date>)
+                  ,poolAssump = ("Pool",("Lease", <default assumption>,<turnover gap>, <rental assump>, <end type>)
                                           ,<delinq assumption>
                                           ,<defaulted assumption>
                                           )
@@ -442,9 +442,34 @@ Lease
 
 Notes:
 
+  * ``<default assumption>`` ->  optional, assumption on gap days between new lease and old lease
   * ``<turnover gap>`` ->  assumption on gap days between new lease and old lease
   * ``<rental assump>`` -> describe the rental increase/decrease over time
-  * ``<end date>`` -> the date when lease projection ends 
+  * ``<end type>`` 
+    * ``("byDate", "2026-09-20")``-> the date when lease projection ends 
+    * ``("byExtTimes",1)``-> how many times lease will roll over
+
+Lease Default
+""""""""""""""""
+User can pass it as ``None`` or default assumptions as below:
+
+* ``('byConitnuation', <default rate in annual>)``
+* ``('byTermination', <default rate in annual>)``
+
+
+Lease Gap
+""""""""""""""
+
+* ``('days', x)`` : the number of days between old lease and new lease
+* ``('byCurve', c)`` : the number of days between old lease and new lease depends on a curve
+
+
+Lease End
+""""""""""""""
+Describle the end type of lease projection,, either by a ``Date`` or a ``Extend Time``
+
+* ``("byDate", "2026-09-20")`` : the date when lease projection ends
+* ``("byExtTimes", 1)`` : how many times lease will roll over for 1 time
 
 Summary
 """"""""""""""""
@@ -462,10 +487,18 @@ Summary
         Lease -> Defaulted
         Performing -> "Lease Gap"
         Performing -> "Rental Curve"
-        "Lease Gap" -> "{'Days':x}"
-        "Lease Gap" -> "{'DaysByAmount':(tbl,x)}"
-        "Rental Curve" -> "{'AnnualIncrease':x}"
-        "Rental Curve" -> "{'CurveIncrease':x}"
+        Performing -> "Default Assumption"
+        Performing -> "End Type"
+        "Default Assumption" -> "By Continuation"
+        "By Continuation" -> "('byContinuation', x)"
+        "Default Assumption" -> "By Termination"
+        "By Termination" -> "('byTermination', x)"
+        "Lease Gap" -> "('days', x)"
+        "Lease Gap" -> "('byCurve', curve)"
+        "Rental Curve" -> "('byAnnualRate', x)"
+        "Rental Curve" -> "('byRateCurve', x)"
+        "End Type" -> "end by date"
+        "End Type" -> "end by extend time"
     }
 
 
diff --git a/docs/source/modeling.rst b/docs/source/modeling.rst
@@ -1427,48 +1427,70 @@ Schedule Repayment
 Lease
 ^^^^^^^^^
 
-`Lease` is an asset with have evenly distributed rental as income or step up feature on the rental over the projection timeline.
+`Lease` is an asset with have evenly distributed rental as income or step up/down feature on the rental over the projection timeline.
 
+syntax:
+  [``"Lease"``, {'rental':<Rental Type>,'originTerm':..,'originDate':..}
+              , {'currentBalance':..,'status':<Status>,'remainTerm':..}]
+
+
+Rental Type
+""""""""""""""
+* Rental by days 
+  * DailyRate -> fix amount on each day
+  * Payment Dates -> :ref:`DatePattern`
+
+    .. code-block:: python 
+
+      ("byDay", <DailyRate>, <Payment Dates>)
+
+* Rental by periods
+  * Rental -> a fix amount on each period
+  * Period -> ``Monthly``, ``Weekly``, ``BiWeekly``, ``Quarterly``, ``SemiAnnually``, ``Annually``
+
+    .. code-block:: python 
 
+      ("byPeriod", <Rental each period>, <Period>)
+
+Lease with fixed retnal
+""""""""""""""""""""""""""
 
 .. code-block:: python
 
   ["Lease"
-   ,{"fixRental": 12.0
+   ,{"rental":("byDay", 12.0, ["DayOfMonth",15])
     ,"originTerm": 96
-    ,"freq": ["DayOfMonth",15]
-    ,"originDate": "2022-01-05"
-    ,"status":"Current"
-    ,"remainTerm":80}]
+    ,"originDate": "2022-01-05"}
+    ,{"status":"Current" ,"remainTerm":80 ,"currentBalance":150}]
 
 step up type lease which rental will increase by pct after each accrue period
 
+Lease with various rental
+""""""""""""""""""""""""""
+
+The ``retnal`` can be increasing/decreasing by a fixed rate or a vector of rate.
+
 .. code-block:: python
 
   ["Lease"
-    ,{"initRental": 24.0
-    ,"originTerm": 36
-    ,"freq": ["DayOfMonth",25]
-    ,"originDate": "2023-01-01"
-    ,"status":"Current"
-    ,"remainTerm":30
-    ,"accrue": ["DayOfMonth",1]
-    ,"pct": 0.05}]
+    ,{"originTerm": 36
+      ,"rental":("byDay", 24.0, ["DayOfMonth",25])
+      ,"originDate": "2023-01-01"
+      ,"stepUp": ("flatRate", 0.05)},
+    {"currentBalance":150 ,"status":"Current" ,"remainTerm":30}]
 
 or user can specify the vector for the rental change 
 
 .. code-block:: python
 
   ["Lease"
-   ,{"initRental": 24.0
-    ,"originTerm": 36
-    ,"freq": ["DayOfMonth",25]
-    ,"originDate": "2023-01-01"
-    ,"status":"Current"
-    ,"remainTerm":30
-    ,"accrue": ["DayOfMonth",3]
-    ,"pct": [0.05,0.065,0.06,-0.07]}]
-
+   ,{"originTerm": 36
+      ,"rental":("byDay", 24.0, ["DayOfMonth",25])
+      ,"originDate": "2023-01-01"
+      ,"stepUp": ("byRates",[0.05,0.065,0.06,-0.07])
+      },
+    ,{"status":"Current" ,"remainTerm":30 ,"currentBalance":150}
+    ]
 
 
 Installment
