[ENH] Support cumulative on-level factors in ParallelogramOLF

[priyam0k]

Summary of Changes

Adds a cumulative flag to ParallelogramOLF and parallelogram_olf so a rate history can be given as cumulative on-level factors instead of incremental rate changes.

• cumulative=False (default) is the current behavior, fully backwards compatible.
• cumulative=True reads change_col as cumulative factors: each is in force from its effective date to the next, the earliest extends back over the lookback window, and the rate level is 1/factor. Rolling average, vertical_line, and leap-year handling are unchanged. Non-positive factors raise a ValueError.

So the tort example drops the gymnastics:

# before
"RateChange": [(0.67 / 0.75) - 1, 0.75 - 1, 0.00]
# after
"Factor": [0.67, 0.75, 1.00]  # cumulative=True

Related GitHub Issue(s)

closes #922

Also completes a follow-up from #1180 (Chapter 10): its Exhibit II tort step can drop the [-0.1067, -0.25] conversion for a clean [0.67, 0.75, 1.0] with cumulative=True.

Additional Context for Reviewers

New tests in test_parallelogram.py: the issue's tort example, a cumulative-vs-incremental equivalence check across M/D grain and vertical_line True/False, and a non-positive-factor guard.

• I passed tests locally for both code (uv run pytest) and documentation changes (uv run jb build docs --builder=custom --custom-builder=doctest)

---

Note

Medium Risk
Touches premium on-leveling math in a widely used estimator, but the new path is opt-in and covered by equivalence and edge-case tests against the incremental implementation.

Overview
Adds cumulative to ParallelogramOLF and parallelogram_olf so rate history can use cumulative rate-level factors (e.g. 0.67, 0.75, 1.00) instead of converting to incremental decimals. Default cumulative=False keeps existing behavior.

With cumulative=True, each factor applies from its effective date until the next; the earliest factor extends backward over the lookback window. parallelogram_olf maps factors to implied rate levels via 1/factor, uses backward/asof matching on the internal calendar, and rejects non-positive factors. Rolling averages, vertical_line, and leap-year handling stay the same.

_combine_duplicate_dates now collapses same-date rows with last() for cumulative factors (incremental mode still compounds with prod). Docs and tests cover the GH #922 tort example, cumulative vs incremental agreement across grains, pre-window factors, and duplicate effective dates.

^{Reviewed by Cursor Bugbot for commit b5c84ca. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Pyright Type Completeness

View the full pyright --verifytypes output for this commit

Project (full chainladder package, at this PR's head): 15.0% of exported symbols fully typed (196 / 1311)

	Known	Ambiguous	Unknown	Total
Project (head)	196	111	1004	1311

Other symbols referenced but not exported by chainladder: 13

	Known	Ambiguous	Unknown	Total
Other (head)	3	1	9	13

Symbols without documentation:

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

Patch (exported symbols added or changed by this PR): 0.0% fully typed (0 / 6)

	Known	Ambiguous	Unknown	Total
Patch	0	1	5	6

Patch symbol details

Symbol	Status	Change
chainladder.adjustments.parallelogram.ParallelogramOLF.cumulative	⚠️ ambiguous	new
chainladder.adjustments.tests.test_parallelogram.test_cumulative_duplicate_date_last_wins	❌ unknown	new
chainladder.adjustments.tests.test_parallelogram.test_cumulative_factor_predates_window	❌ unknown	new
chainladder.adjustments.tests.test_parallelogram.test_cumulative_matches_incremental	❌ unknown	new
chainladder.adjustments.tests.test_parallelogram.test_cumulative_rejects_non_positive	❌ unknown	new
chainladder.adjustments.tests.test_parallelogram.test_cumulative_tort_reform	❌ unknown	new

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit fbf8e6b. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.17%. Comparing base (10abe53) to head (b5c84ca).
⚠️ Report is 20 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1181      +/-   ##
==========================================
+ Coverage   91.14%   91.17%   +0.03%     
==========================================
  Files          91       91              
  Lines        5365     5395      +30     
  Branches      681      688       +7     
==========================================
+ Hits         4890     4919      +29     
  Misses        340      340              
- Partials      135      136       +1     

Flag	Coverage Δ
unittests	91.17% <100.00%> (+0.03%)	⬆️

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.