Skip to content

[DOCS] Show a calendar-period effect with BarnettZehnwirth in the user guide - #1622

Merged
henrydingliu merged 7 commits into
casact:mainfrom
scks1:docs-calendar-wave
Nov 16, 2026
Merged

henrydingliu merged 7 commits into
casact:mainfrom
scks1:docs-calendar-wave

Conversation

@scks1

@scks1 scks1 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary of Changes

Adds a short "Calendar-period effects" subsection at the end of the BarnettZehnwirth part of docs/user_guide/development.ipynb. It uses a synthetic triangle (origins 2011 to 2020, the same expected payment at each development age for every origin) in which every payment made in calendar year 2017 is 50% higher. The triangle is built square through 2029 with Triangle operations, and the example shows it in full with the cells paid after 2020 shaded, so the true unpaid amounts are known. It shows that:

  • Triangle.valuation_correlation (Mack 1994, Appendix H) flags the effect before any model is fitted: the total z of 3 is below the no-effect range of 6.03 to 11.47, and the per-diagonal test flags 2017 and 2020. The text explains why 2018 and 2019 are not flagged, and a heatmap of the link ratios shows the 2017 diagonal.
  • Chainladder overstates every origin's IBNR, by up to 23.8% (origin 2017).
  • Development(drop_valuation=["2016", "2017"]) removes the ratios into and out of the 2017 diagonal but still misses by -6.4% to +12.8%, because the extra 2017 payments stay in the later cumulative amounts.
  • BarnettZehnwirth(formula="C(origin) + C(development) + I(valuation == 6)") recovers the unpaid amounts (errors round to 0.0), with exp(coefficient) = 1.5. This is the calendar (iota) direction of the PTF framework (Barnett and Zehnwirth 2000), already cited in this section.
  • If the same event is scheduled for a future period, a shared indicator I((valuation == 6) | (valuation == 11)) projects it; the one-off indicator then understates origins 2013 to 2020 by 9.7% to 15.8%.

A note says the shared indicator scales the future diagonal multiplicatively, so it fits an event that scales payments in proportion, not one that adds a fixed amount per claim or policy.

In docs/user_guide/triangle.ipynb, the Correlation Tests section now runs the same test on Friedland's Chapter 7, Exhibit III (friedland_uspp): it flags reported claims, and not paid claims, in the two increasing case outstanding strength scenarios.

No code changes. The example does not use TweedieGLM (see #1619).

Related GitHub Issue(s)

None open. #623 (closed) discussed valuation terms in BarnettZehnwirth formulas.

AI/LLM Usage

I drafted this example with Árbol, an AI assistant (running Muse). It wrote the cells, ran them and the notebook tests on main 46727b1, comparing each origin's IBNR with the known unpaid amount of the synthetic triangle. I reviewed the text and the numbers before opening the PR.

Additional Context for Reviewers

The valuation codes (2017 is 6, 2022 is 11) come from BarnettZehnwirth().model_.valuation_encoder_, which counts years from the earliest valuation (learning.py divides the valuation rank by the number of development periods per year). The cells were checked to merge cleanly with #1621, which adds a section earlier in the same notebook, and with #1620, which also edits triangle.ipynb.

Submitter's Checklist

  • I have reviewed and am adhering to the standards outlined in the project Governing Doc.
  • The PR subject title summarizes the changes, with one proper prefix ([FIX], [FEAT], [DOCS], [TST], [CHORE], or [BRK]).
  • I am a human (not a bot), and this PR form is written by a human.

Reviewer's Checklist

  • The implementation addresses the associated issue(s).
  • The implementation is appropriate, maintainable, and follows ARCHITECTURE.md.
  • PR subject title has the proper prefix and the subject is appropriate.
  • Relevant issue(s) are linked.
  • AI/LLM usage is disclosed and appropriate.
  • Documentation and tests are appropriate.
  • CI tests passed, or any failures are acceptable.
  • Leave a comment with the final recommendation (e.g. approve as is, request a secondary review, or flag an area for more review).

Adds a "Calendar-period effects" subsection at the end of the
BarnettZehnwirth section of docs/user_guide/development.ipynb. A
synthetic triangle has every 2017 payment raised by 50%. The cells
compare Chainladder, Development(drop_valuation=["2016", "2017"]) and
BarnettZehnwirth with an I(valuation == 6) term against the known
unpaid amounts, then show a shared indicator for an event scheduled in
a future calendar period, with a note on its multiplicative scaling.

Developed with an AI assistant (Árbol, running Muse).
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Pyright Type Completeness

View the full pyright --verifytypes output for this commit

Project (full chainladder package, at this PR's head): 18.1% of exported symbols fully typed (301 / 1666)

Known Ambiguous Unknown Total
Project (head) 301 96 1269 1666

Other symbols referenced but not exported by chainladder: 24

Known Ambiguous Unknown Total
Other (head) 11 1 12 24

Symbols without documentation:

  • Functions without docstring: 330
  • Functions without default param: 0
  • Classes without docstring: 10

Patch (exported symbols added or changed by this PR): no exported symbol type-completeness changes detected.

@codecov

codecov Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.94%. Comparing base (46727b1) to head (36dee86).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1622   +/-   ##
=======================================
  Coverage   94.94%   94.94%           
=======================================
  Files          99       99           
  Lines        6427     6427           
  Branches      811      811           
=======================================
  Hits         6102     6102           
  Misses        207      207           
  Partials      118      118           
Flag Coverage Δ
unittests 94.94% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@henrydingliu

henrydingliu commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

i'm a big fan of demonstrating how to use this package to solve real world problems, particularly comparing between different approaches. some suggestions to make this even more instructive

  • is there a known dataset that has calendar period effect? maybe check out friedland?
  • regardless of which dataset we use, i would recommend showing the dataset, potentially on a heatmap, to clearly illustrate the calendar year effect
  • we want to promote a more modern workflow, i.e. rely less on visual inspection and more on robust metrics. just so happens that we have a calendar period test that we can add to the top of the example

…on test

Run Triangle.valuation_correlation on the synthetic triangle before any
model is fitted, in both its total and per-diagonal forms, so the example
leads with a test instead of a visual check.

Developed with an AI assistant (Árbol, running Muse).
The heatmap ranks each payment within its development age, so the 2017
payments appear as one diagonal.

Developed with an AI assistant (Árbol, running Muse).
Friedland's Chapter 7, Exhibit III scenarios with increasing case
outstanding strength give a published case of a calendar-period effect
in reported claims. The synthetic triangle stays for the remedies, since
only it has known unpaid amounts.

Developed with an AI assistant (Árbol, running Muse).
@scks1

scks1 commented Nov 15, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, Henry. I pushed three commits that follow your suggestions:

  • The section now opens with Triangle.valuation_correlation (Mack 1994, Appendix H, p_critical=0.1) on the synthetic triangle, before any model is fitted. The total z is 3, below the no-effect range of 7.07 to 12.31, so the test flags it. The per-diagonal test flags the link ratios ending in 2017 (p = 0.031) and in 2020 (p = 0.016).
  • A heatmap of the synthetic incremental payments follows. The 2017 payments are the largest at every development age they reach, so they show as one diagonal.
  • Friedland has one: Chapter 7, Exhibit III (friedland_uspp) includes two scenarios with increasing case outstanding strength. The total test flags reported claims in both of them (z of 4 and 3, against a range of 5.23 to 10.15) and does not flag paid claims in any of the four scenarios. I kept the synthetic triangle for the remedies because only it has known unpaid amounts.

The IBNR numbers are unchanged, and the notebook passes pytest --nbmake on its own and merged with #1621.

(This comment was written with Árbol, an AI assistant, under my direction.)

@henrydingliu

Copy link
Copy Markdown
Member

thanks for the changes. a couple more comments

  • since we are keeping the synthetic data, i would ask that we keep pandas and numpy manipulation to a minimum, and try to use chainladder API as much as possible
  • you can better illustrate the "unpaid is known" aspect by displaying the full synthetic triangle with some color coding of the lower diagonal
  • the valuation correlation on friedland in this section feels a little out of place. could you please move it to https://chainladder-python--1622.org.readthedocs.build/1622/user_guide/triangle.html#correlation-tests?
  • a heatmap of the link ratios would be more illustrative of the calendar year effect
  • the rationale given for the the val correl fail at 2020 applies equally to 2019. how come 2019 didn't fail?

… it in full

Build the square from one long DataFrame with Triangle, add the 2017 shock
with a valuation filter, and split it into the 2020 triangle and the true
unpaid amounts with valuation filters, in place of the pandas groupby and
.loc edits. Give every origin the same expected payments: with a 5% level
trend, ratios equal in exact arithmetic differed by about 1e-10, and
valuation_correlation split those ties.

Show the full square with the cells paid after 2020 shaded and in italics,
and explain diagonal by diagonal why the test flags 2017 and 2020 but not
2018 or 2019.

Developed with an AI assistant (Árbol, running Muse).
Color the link ratios instead of the incremental payments, rounded to the
four decimals heatmap prints so that ratios which print alike share a color.
low and high keep every color pale enough for the dark text to stay
readable.

Developed with an AI assistant (Árbol, running Muse).
…ts section

Run valuation_correlation on the friedland_uspp scenarios in the triangle
guide, next to the raa example, and keep the calendar-period example in
the development guide on the synthetic triangle.

Developed with an AI assistant (Árbol, running Muse).
@scks1

scks1 commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

Thanks. All five are in 4d7cd8d, 273d052 and 36dee86.

  1. The synthetic data is one long DataFrame passed to cl.Triangle. The 2017 shock, the triangle known at the end of 2020 and the true unpaid amounts now come from valuation filters and Triangle arithmetic (square + square[square.valuation.year == 2017] * 0.5, incr_to_cum(), sum("development")), in place of the groupby and .loc edits. The remaining pandas code builds the input frame, the error helper and tables, and the styling of the square.
  2. The full square now shows, with the cells paid after 2020 shaded and in italics, so the marking doesn't rely on color alone.
  3. The Friedland test now sits in Correlation Tests in the triangle guide, right after the raa example.
  4. The heatmap now shows the link ratios, rounded to the four decimals it prints. I passed low=0.5, high=0.5: with the defaults, white text on the mid blues fell to about 2.3:1 contrast.
  5. You're right, and the sentence was wrong: the extra 2017 payments sit in the starting amounts of the 2018, 2019 and 2020 ratios alike. The test counts ratios above and below each age's median. At 12-24 and 24-36 most ratios are untouched and equal, so the median is the untouched value and those ratios don't count. On 2020, six ratios are below and none above (p = 0.031). On 2019, five are below and one is above: origin 2011's 96-108 ratio. Only two origins have a 96-108 ratio, both starting after 2017, so the median falls between them, and 2011's is the larger because its 2017 payment came at a later age, where payments are smaller. One against five gives p = 0.219, so 2019 passes. The notebook explains this diagonal by diagonal now.

The old "seven of nine" for 2020 was also wrong. The 5% origin trend made ratios that are equal in exact arithmetic differ by about 1e-10, and the test split those ties. Every origin now has the same expected payments, so the ties are exact and the counts in the text match the test. The no-effect range moves to 6.03 to 11.47, and the Chainladder error for 2017 to 23.8%.

(This comment was written with Árbol, an AI assistant, under my direction.)

@henrydingliu
henrydingliu merged commit 7b95178 into casact:main Nov 16, 2026
11 checks passed
@scks1
scks1 deleted the docs-calendar-wave branch November 16, 2026 08:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants