diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 423378a6..f359f621 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,3 +6,5 @@ ## Additional Context for Reviewers + +- [ ] I passed tests locally for both code (`pytest`) and documentation changes (`uv run jb build docs --builder=custom --custom-builder=doctest`) diff --git a/chainladder/methods/benktander.py b/chainladder/methods/benktander.py index 2a7d42f8..6681d5b8 100644 --- a/chainladder/methods/benktander.py +++ b/chainladder/methods/benktander.py @@ -16,6 +16,8 @@ class Benktander(MethodBase): then use 1.0 n_iters: int, optional (default=1) Number of iterations to use in the Benktander model. + When n_iters=1, the result is equivalent to the BornhuetterFerguson method. + When n_iters>>1, the result converges to the traditional Chainladder model. apriori_sigma: float, optional (default=0.0) Standard deviation of the apriori. When used in conjunction with the bootstrap model, the model samples aprioris from a lognormal distribution @@ -49,53 +51,83 @@ class Benktander(MethodBase): .. testcode:: - tr = cl.load_sample('ukmotor') - apriori = cl.Chainladder().fit(tr).ultimate_ * 0 + 14000 + xyz = cl.load_sample("xyz") - With ``n_iters=1`` Benktander reproduces Bornhuetter-Ferguson exactly. + ibnr = cl.Benktander().fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal).ibnr_ + print(ibnr) + + .. testoutput:: + + 2261 + 1998 NaN + 1999 115.472127 + 2000 914.033812 + 2001 2432.394513 + 2002 6037.026677 + 2003 13928.934651 + 2004 33925.451475 + 2005 69724.761575 + 2006 73410.593920 + 2007 52977.560411 + 2008 45873.769490 + + When `n_iters=1`, the model is exactly the same as the BornhuetterFerguson model. .. testcode:: - print( - cl.Benktander(apriori=1.0, n_iters=1).fit( - tr, sample_weight=apriori - ).ultimate_ + xyz = cl.load_sample("xyz") + + bk_ibnr = ( + cl.Benktander(n_iters=1) + .fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal) + .ibnr_ + ) + bf_ibnr = ( + cl.BornhuetterFerguson() + .fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal) + .ibnr_ ) + print(bk_ibnr - bf_ibnr) .. testoutput:: - 2261 - 2007 12690.000000 - 2008 13121.098503 - 2009 14028.278620 - 2010 13272.048822 - 2011 13911.968891 - 2012 15614.145287 - 2013 16029.501746 - - Increasing ``n_iters`` pulls the immature origins toward the chainladder - estimate. The 2013 origin shows this most: ``16029`` at ``n_iters=1``, - rising to ``19110`` at ``n_iters=4`` and approaching the chainladder - ultimate of ``20680``. + 2261 + 1998 NaN + 1999 NaN + 2000 NaN + 2001 NaN + 2002 NaN + 2003 NaN + 2004 NaN + 2005 NaN + 2006 NaN + 2007 NaN + 2008 NaN + + When `n_iters>>1`, the model converges to the traditional Chainladder model. .. testcode:: - print( - cl.Benktander(apriori=1.0, n_iters=4).fit( - tr, sample_weight=apriori - ).ultimate_ - ) + xyz = cl.load_sample("xyz") + + bk_ibnr = cl.Benktander(n_iters=1000).fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal).ibnr_ + cl_ibnr = cl.Chainladder().fit(xyz["Paid"]).ibnr_ + print(bk_ibnr - cl_ibnr) .. testoutput:: 2261 - 2007 12690.000000 - 2008 13096.902490 - 2009 14030.535854 - 2010 13138.365841 - 2011 13880.984774 - 2012 16719.527550 - 2013 19110.806503 + 1998 NaN + 1999 NaN + 2000 NaN + 2001 1.455192e-11 + 2002 -7.275958e-12 + 2003 7.275958e-12 + 2004 1.455192e-11 + 2005 -1.455192e-11 + 2006 2.910383e-11 + 2007 -5.820766e-11 + 2008 -7.275958e-11 """ def __init__(self, apriori=1.0, n_iters=1, apriori_sigma=0, random_state=None): @@ -132,13 +164,30 @@ def fit(self, X, y=None, sample_weight=None): .. testcode:: - tr = cl.load_sample('ukmotor') - apriori = cl.Chainladder().fit(tr).ultimate_ * 0 + 14000 - print(cl.Benktander(apriori=1.0, n_iters=2).fit(tr, sample_weight=apriori)) + xyz = cl.load_sample("xyz") + + ultimate = ( + cl.Benktander(apriori=1, n_iters=2) + .fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal) + .ultimate_ + ) + print(ultimate) .. testoutput:: - Benktander(n_iters=2) + 2261 + 1998 15822.000000 + 1999 24908.397003 + 2000 37547.676656 + 2001 40511.198946 + 2002 49417.354765 + 2003 50042.095135 + 2004 82437.601111 + 2005 95417.171135 + 2006 88485.508416 + 2007 66882.788227 + 2008 50708.755370 + """ if sample_weight is None: raise ValueError("sample_weight is required.") diff --git a/chainladder/methods/bornferg.py b/chainladder/methods/bornferg.py index 07c606cd..695a6f49 100644 --- a/chainladder/methods/bornferg.py +++ b/chainladder/methods/bornferg.py @@ -10,9 +10,14 @@ class BornhuetterFerguson(Benktander): Parameters ---------- apriori: float, optional (default=1.0) - Multiplier for the sample_weight used in the Bornhuetter Ferguson - method. If sample_weight is already an apriori measure of ultimate, - then use 1.0 + Multiplier for the `sample_weight` used in the Bornhuetter Ferguson + method. If `sample_weight` is already an apriori measure of ultimate, + then use 1.0. + The recommended pratice is to seperate the model parameter assumption + and data apart. + For example, if the apriori s 80% of premium, it is recommended to set + the aprior as 0.8 and leave the premium data in `sample_weight` argument + unmodified. apriori_sigma: float, optional (default=0.0) Standard deviation of the apriori. When used in conjunction with the bootstrap model, the model samples aprioris from a lognormal distribution @@ -35,14 +40,10 @@ class BornhuetterFerguson(Benktander): Examples -------- Bornhuetter-Ferguson requires an apriori expected ultimate per origin, - supplied through ``sample_weight``. ``sample_weight`` must be a - chainladder Triangle aligned with ``X``, not a scalar; passing - ``sample_weight=14000`` would raise ``AttributeError`` because the model - accesses ``.shape``. + supplied through ``sample_weight``. A common idiom for building a flat per-origin apriori is to take any - same-shape Triangle, zero it out, and add the desired value. Below uses - the chainladder ultimate as the shape donor. + same-shape Triangle, zero it out, and add the desired value. Here is an example. .. testsetup:: @@ -50,40 +51,49 @@ class BornhuetterFerguson(Benktander): .. testcode:: - tr = cl.load_sample('ukmotor') - cl_ult = cl.Chainladder().fit(tr).ultimate_ - apriori = cl_ult * 0 + float(cl_ult.sum()) / 7 - print(apriori) + raa = cl.load_sample("raa") + premium = raa.latest_diagonal * 0 + 40_000 # zero out and add 40,000 to each origin + + ibnr = cl.BornhuetterFerguson(apriori=0.7).fit(X=raa, sample_weight=premium).ibnr_ + print(ibnr) .. testoutput:: 2261 - 2007 14903.967562 - 2008 14903.967562 - 2009 14903.967562 - 2010 14903.967562 - 2011 14903.967562 - 2012 14903.967562 - 2013 14903.967562 - - Fit with that apriori. The BF ultimates pull the immature origins toward - the apriori while leaving mature origins close to chainladder. + 1981 NaN + 1982 255.707763 + 1983 717.772687 + 1984 1596.061515 + 1985 2658.738155 + 1986 5239.441491 + 1987 8574.335344 + 1988 12714.889984 + 1989 18585.219714 + 1990 24861.068855 + + One might be tempted to set never set the aprior and modify the sample_weight directly, and they will result in the same answer, but this is not the recommended practice. It not only add confusion, but it alos mixes the model parameter assumption and data together. .. testcode:: - model = cl.BornhuetterFerguson(apriori=1.0).fit(tr, sample_weight=apriori) - print(model.ultimate_) + raa = cl.load_sample("raa") + premium = raa.latest_diagonal * 0 + 40_000 * 0.7 # premium is modified by 70% + + ibnr = cl.BornhuetterFerguson().fit(X=raa, sample_weight=premium).ibnr_ + print(ibnr) .. testoutput:: 2261 - 2007 12690.000000 - 2008 13145.318280 - 2009 14095.125641 - 2010 13412.748068 - 2011 14150.549749 - 2012 15999.244850 - 2013 16658.824705 + 1981 NaN + 1982 255.707763 + 1983 717.772687 + 1984 1596.061515 + 1985 2658.738155 + 1986 5239.441491 + 1987 8574.335344 + 1988 12714.889984 + 1989 18585.219714 + 1990 24861.068855 """ def __init__(self, apriori=1.0, apriori_sigma=0.0, random_state=None): diff --git a/chainladder/methods/capecod.py b/chainladder/methods/capecod.py index c6959ffc..0d132d82 100644 --- a/chainladder/methods/capecod.py +++ b/chainladder/methods/capecod.py @@ -12,28 +12,34 @@ class CapeCod(Benktander): Parameters ---------- - trend: float (default=0.0) - The cape cod trend assumption. Any Trend transformer on X will + trend: float, optional (default=0.0) + The cape cod trend assumption. Any Trend transformer on X will override this argument. - decay: float (defaut=1.0) - The cape cod decay assumption + decay: float, optional (default=1.0) + The cape cod decay assumption. This parameter is required by the + Generalized Cape Cod Method, as discussed in [Using Best Practices to + Determine a Best Reserve Estimate](https://www.casact.org/sites/default/files/database/forum_98fforum_struhuss.pdf) + by Struzzieri and Hussian. As the `decay` factor approaches 1 + (the default value), the result approaches the traditional Cape Cod + method. As the `decay` factor approaches 0, the result approaches + the `Chainladder` method. n_iters: int, optional (default=1) Number of iterations to use in the Benktander model. + groupby: str or list, optional (default=None) + An option to group levels of the triangle index together for the + purposes of deriving the apriori measures. If omitted, each level of + the triangle index will receive its own apriori computation. apriori_sigma: float, optional (default=0.0) Standard deviation of the apriori. When used in conjunction with the bootstrap model, the model samples aprioris from a lognormal distribution using this argument as a standard deviation. random_state: int, RandomState instance or None, optional (default=None) - Seed for sampling from the apriori distribution. This is ignored when + Seed for sampling from the apriori distribution. This is ignored when using as a deterministic method. If int, random_state is the seed used by the random number generator; If RandomState instance, random_state is the random number generator; If None, the random number generator is the RandomState instance used by np.random. - groupby: - An option to group levels of the triangle index together for the - purposes of deriving the apriori measures. If omitted, each level of - the triangle index will receive its own apriori computation. Attributes @@ -61,8 +67,27 @@ class CapeCod(Benktander): .. testcode:: - tr = cl.load_sample('ukmotor') - exposure = cl.Chainladder().fit(tr).ultimate_ * 0 + 20000 + xyz = cl.load_sample("xyz") + + ibnr = ( + cl.CapeCod().fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal).ibnr_ + ) + print(ibnr) + + .. testoutput:: + + 2261 + 1998 NaN + 1999 88.211299 + 2000 698.247374 + 2001 1858.151261 + 2002 4611.796594 + 2003 10640.571396 + 2004 25916.281295 + 2005 53264.037933 + 2006 56079.713590 + 2007 40470.540502 + 2008 35043.822927 With default ``decay=1`` and ``trend=0``, every origin receives the same apriori loss ratio: the exposure-weighted mean loss ratio across all @@ -70,19 +95,27 @@ class CapeCod(Benktander): .. testcode:: - model = cl.CapeCod().fit(tr, sample_weight=exposure) - print(model.apriori_) + apriori = ( + cl.CapeCod() + .fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal) + .apriori_ + ) + print(apriori) .. testoutput:: 2261 - 2007 0.706225 - 2008 0.706225 - 2009 0.706225 - 2010 0.706225 - 2011 0.706225 - 2012 0.706225 - 2013 0.706225 + 1998 0.763919 + 1999 0.763919 + 2000 0.763919 + 2001 0.763919 + 2002 0.763919 + 2003 0.763919 + 2004 0.763919 + 2005 0.763919 + 2006 0.763919 + 2007 0.763919 + 2008 0.763919 Setting ``decay`` below 1 down-weights distant origins when computing each origin's apriori, so each origin receives its own loss-ratio @@ -90,36 +123,52 @@ class CapeCod(Benktander): .. testcode:: - print(cl.CapeCod(decay=0.5).fit(tr, sample_weight=exposure).apriori_) + apriori = cl.CapeCod(decay=0.5).fit( + X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal + ).apriori_ + print(apriori) .. testoutput:: 2261 - 2007 0.653584 - 2008 0.666113 - 2009 0.683132 - 2010 0.689123 - 2011 0.717497 - 2012 0.776364 - 2013 0.836006 + 1998 0.797751 + 1999 0.799990 + 2000 0.804890 + 2001 0.793706 + 2002 0.777420 + 2003 0.748556 + 2004 0.740594 + 2005 0.687204 + 2006 0.705757 + 2007 0.784466 + 2008 0.830368 Setting ``trend`` projects the loss ratio forward over the experience - period. With ``decay=1``, all origins share the trended apriori. + period. .. testcode:: - print(cl.CapeCod(trend=0.05).fit(tr, sample_weight=exposure).apriori_) + apriori = ( + cl.CapeCod(decay=0.5, trend=0.03) + .fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal) + .apriori_ + ) + print(apriori) .. testoutput:: 2261 - 2007 0.836096 - 2008 0.836096 - 2009 0.836096 - 2010 0.836096 - 2011 0.836096 - 2012 0.836096 - 2013 0.836096 + 1998 1.027105 + 1999 1.014959 + 2000 1.001927 + 2001 0.966406 + 2002 0.924906 + 2003 0.869767 + 2004 0.841331 + 2005 0.765515 + 2006 0.773005 + 2007 0.847345 + 2008 0.890327 """ def __init__( diff --git a/chainladder/methods/expectedloss.py b/chainladder/methods/expectedloss.py index ea09cc99..44444a2e 100644 --- a/chainladder/methods/expectedloss.py +++ b/chainladder/methods/expectedloss.py @@ -5,7 +5,9 @@ class ExpectedLoss(Benktander): - """The deterministic Expected Loss IBNR model + """The deterministic Expected Loss IBNR model, it ignores all data in the + triangle, and only uses the sample_weight modified by the apriori to + calculate the ultimate losses. Parameters ---------- @@ -31,6 +33,67 @@ class ExpectedLoss(Benktander): The ultimate losses per the method ibnr_: Triangle The IBNR per the method + + Examples + -------- + + .. testsetup:: + + import chainladder as cl + + .. testcode:: + + xyz = cl.load_sample("xyz") + + ibnr = ( + cl.ExpectedLoss() + .fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal) + .ibnr_ + ) + print(ibnr) + + .. testoutput:: + + 2261 + 1998 4178.0 + 1999 6683.0 + 2000 8218.0 + 2001 11481.0 + 2002 16746.0 + 2003 29855.0 + 2004 46511.0 + 2005 98125.0 + 2006 84759.0 + 2007 50573.0 + 2008 44388.0 + + We can specify the apriori as a percentage of the premium. + + .. testcode:: + + xyz = cl.load_sample("xyz") + + ibnr = ( + cl.ExpectedLoss(apriori=0.9) + .fit(X=xyz["Paid"], sample_weight=xyz["Premium"].latest_diagonal) + .ibnr_ + ) + print(ibnr) + + .. testoutput:: + + 2261 + 1998 2178.0 + 1999 3533.0 + 2000 3718.0 + 2001 6481.0 + 2002 10627.7 + 2003 22937.5 + 2004 36578.8 + 2005 84309.9 + 2006 74001.2 + 2007 44329.2 + 2008 39608.3 """ def __init__(self, apriori=1.0, apriori_sigma=0.0, random_state=None): diff --git a/docs/library/api.md b/docs/library/api.md index fd8af1da..0e412b07 100644 --- a/docs/library/api.md +++ b/docs/library/api.md @@ -101,6 +101,7 @@ Classes Chainladder MackChainladder BornhuetterFerguson + ExpectedLoss Benktander CapeCod diff --git a/docs/library/contributing.md b/docs/library/contributing.md index da85d68d..caab7967 100644 --- a/docs/library/contributing.md +++ b/docs/library/contributing.md @@ -116,10 +116,17 @@ Contributions to documentation are especially helpful for new users. - Follow established naming conventions - Include new unit tests with reasonable coverage -All PRs should be run locally before submission: +All PRs should be run locally before submission. +For codebase tests, run: + +```bash +pytest +``` + +For documentation changes, rebuild the docs locally with: ```bash -pytest chainladder +uv run jb build docs --builder=custom --custom-builder=doctest ``` Large or unfocused PRs may delay merging. Each PR should address a single issue or feature to maintain clarity and quality. diff --git a/docs/library/generated/chainladder.ExpectedLoss.rst b/docs/library/generated/chainladder.ExpectedLoss.rst new file mode 100644 index 00000000..222db062 --- /dev/null +++ b/docs/library/generated/chainladder.ExpectedLoss.rst @@ -0,0 +1,6 @@ +chainladder.ExpectedLoss +======================== + +.. currentmodule:: chainladder + +.. autoclass:: ExpectedLoss \ No newline at end of file