docs: add utility doctest examples by EKtheSage · Pull Request #804 · casact/chainladder-python

EKtheSage · 2026-05-16T08:25:18Z

Summary: Add Sphinx doctest examples for the PatsyFormula utility docs. Split from the larger #792 work and intentionally excludes .github/workflows/sync-main-to-docs.yml. Refs #704

Note

Low Risk
Documentation and test-only changes; utility implementations are unchanged aside from expanded docstrings.

Overview
Adds Sphinx doctest examples to utility API docstrings in utility_functions.py: read_pickle, read_json, concat, minimum, maximum, and PatsyFormula (including TweedieGLM / DevelopmentML workflows). Each block uses .. testsetup::, .. testcode::, and .. testoutput:: so docs can execute and verify the snippets.

Tests in test_utilities.py back related behavior: pickle round-trip for a fitted Development (test_to_pickle_read_pickle), cl.maximum vs NumPy (test_maximum), and Friedland USPP sample keys loading with the expected three value columns (test_load_sample_uspp).

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

codecov · 2026-05-16T08:34:39Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 88.91%. Comparing base (b24f209) to head (f23fe84).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #804      +/-   ##
==========================================
+ Coverage   88.79%   88.91%   +0.11%     
==========================================
  Files          89       89              
  Lines        5060     5060              
  Branches      646      646              
==========================================
+ Hits         4493     4499       +6     
+ Misses        423      417       -6     
  Partials      144      144

Flag	Coverage Δ
unittests	`88.91% <ø> (+0.11%)`	⬆️

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 · 2026-05-16T14:59:40Z

please pull main and incorporate recent changes

henrydingliu · 2026-05-17T06:03:18Z

+
+    .. testcode::
+
+        clrd = cl.load_sample("clrd").groupby("LOB").sum().iloc[:2]


test demonstrates that concatting identical columns doesn't do anything, which doesn't match the example text.

henrydingliu · 2026-05-17T06:05:35Z

 def minimum(x1, x2):
+    """Element-wise minimum of two triangles (delegates to ``Triangle.minimum``).
+
+    Examples


we need more basic docstring before a doctest. what's x1? what's x2?

henrydingliu · 2026-05-17T06:05:53Z

+
+    Examples
+    --------
+    Cap a triangle cell-by-cell by comparing it with another triangle of limits.


are we certain this is true? can x2 be a scalar?

henrydingliu · 2026-05-17T06:14:41Z

 def read_json(json_str, array_backend=None):
+    """Deserialize JSON produced by ``to_json`` (triangle, estimator, or pipeline).
+
+    Examples


this example feels empty without seeing the actual json string. please follow the example from pandas

henrydingliu · 2026-05-17T06:18:45Z

+        print(round(float(by_dev.ldf_.values[0, 0, 0, 0]), 6))
+        print(round(float(by_both.ldf_.values[0, 0, 0, 0]), 6))
+
+    .. testoutput::


should we be showing all the numbers?

…henrydingliu

…henrydingliu - read_pickle: show fitted Development estimator round-trip via pickle, verify transform works after restore - read_json: show full Pipeline serialization round-trip with step names and params - concat: show paid+incurred column join enabling MunichAdjustment directly - minimum: compare volume vs simple CL ultimates, pick element-wise lower for low-side scenario - maximum: same comparison, pick element-wise higher for high-side scenario - PatsyFormula: clarify when to use custom DevelopmentML pipeline vs TweedieGLM; show ldf_ output instead of coefficient count

henrydingliu · 2026-05-18T16:46:03Z

+        import chainladder as cl
+
+        tri = cl.load_sample("raa")
+        dev = cl.Development(average="volume").fit(tri)


to demonstrate that to_pickle does something, we should use non-default parameters. something like avg = simple, n = 4.

henrydingliu · 2026-05-18T16:47:00Z

+        dev.to_pickle(p)
+        restored = cl.read_pickle(p)
+        os.remove(p)
+        print(restored.transform(tri).ldf_.values[0, 0, 0, :4].round(4))


can we print the full ldf_ from both the original and the restored estimators?

henrydingliu · 2026-05-18T16:53:15Z

+        combined = cl.concat([paid, incurred], axis=1)
+        adj = cl.MunichAdjustment(paid_to_incurred=("CumPaidLoss", "IncurLoss"))
+        result = adj.fit_transform(combined)
+        print(result.ldf_["CumPaidLoss"].values[0, 0, 0, :4].round(4))


good use case for concat. can we focus the test output around concat only?

kennethshsu · 2026-05-28T23:54:33Z

@EKtheSage are you interested in finishing up this PR?

- read_pickle: use non-default params (average=simple, n_periods=4), print ldf_ from both original and restored estimators, and call .transform() on restored to prove it is still functional - read_json: show the full serialized JSON string before round-tripping, following pandas docstring style - concat: remove MunichAdjustment output; focus on concat result only by printing combined.columns - minimum/maximum: add prose descriptions for x1 and x2 parameters, confirming x2 can be a scalar - maximum: trim testoutput to show only high_side result

EKtheSage · 2026-06-08T16:08:55Z

@henrydingliu thanks for the detailed review. All comments have been addressed in the latest commit. Summary below:

to_pickle / read_pickle (lines 291, 301, 307)

Used a Development transformer with non-default params (average='simple', n_periods=4) to demonstrate pickling does something meaningful
Now prints ldf_ from both the original and restored estimators side-by-side to show parameters are preserved
Added an explicit restored.transform(tri) call to prove the restored estimator is still functional as a transformer

read_json (line 451)

Replaced the Pipeline round-trip with a Development example that prints the full serialized JSON string before reconstructing, following pandas docstring style

concat (lines 678, 696)

Removed the MunichAdjustment code and output; the example now focuses on concat itself by printing list(combined.columns) to show the two columns were merged into one triangle

minimum / maximum parameters (lines 793, 795)

Added prose descriptions for x1 and x2 in both functions, clarifying that x2 can be a scalar (element-wise comparison against a constant value)

maximum output (line 891)

Removed the intermediate ult_vol and ult_sim print lines; testoutput now shows only the high_side result

…ctions

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

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

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

henrydingliu · 2026-06-09T01:25:46Z

@EKtheSage I don't think all the edits came through on this one either

…um test - read_pickle: print the full ldf_ from the original, restored, and transformed estimators instead of the first four factors - PatsyFormula: print the full ldf_ patterns for both GLM formulations and for the custom DevelopmentML pipeline - test_maximum: assert the element-wise maximum directly instead of the NaN-tolerant inequalities flagged in review

EKtheSage · 2026-06-11T21:16:25Z

@henrydingliu thanks for checking. The earlier commit did land, but two of your comments were implemented incorrectly in it: the read_pickle example printed only the first four factors instead of the full ldf_, and your "should we be showing all the numbers" comment on the PatsyFormula example was misread as a request to trim output when you meant the opposite. The latest commit prints the full ldf_ arrays in the read_pickle example and both PatsyFormula examples, and also strengthens the new test_maximum assertion that bugbot flagged. Doctests pass locally.

…amples

henrydingliu · 2026-06-12T00:01:09Z

    assert not missing, f"sdist is missing sample CSVs: {sorted(missing)}"


+def test_load_sample_uspp() -> None:


we did a sizable refactor on load_sample a couple of weeks back. can you please review the current load_sample test(s) in here and see if this new test is redundant?

henrydingliu · 2026-06-12T00:09:15Z

everything looks great. small nitpick on one potentially redundant test.

EKtheSage requested review from genedan, henrydingliu, jbogaardt and kennethshsu as code owners May 16, 2026 08:25

EKtheSage mentioned this pull request May 16, 2026

API Reference Examples #704

Open

cursor Bot reviewed May 16, 2026

View reviewed changes

Comment thread chainladder/utils/utility_functions.py Outdated

EKtheSage mentioned this pull request May 16, 2026

docs: add doctest Examples for correlation, Munich, tails, adjustments, workflow, and utils #792

Closed

3 tasks

docs: add utility doctest examples

9175ae7

EKtheSage force-pushed the docs/704-utility-examples branch from 0a7c2f9 to 9175ae7 Compare May 16, 2026 20:31

docs: address utility review feedback

b159d36

henrydingliu reviewed May 17, 2026

View reviewed changes

Comment thread chainladder/utils/utility_functions.py

henrydingliu reviewed May 17, 2026

View reviewed changes

henrydingliu reviewed May 18, 2026

View reviewed changes

kennethshsu assigned EKtheSage and henrydingliu May 18, 2026

Ethan Kang added 2 commits June 8, 2026 14:18

tests: add explicit coverage for uspp Friedland triangles in load_sample

c0c7822

tests: add coverage for read_pickle/to_pickle and maximum utility fun…

13c3d48

…ctions

cursor Bot reviewed Jun 8, 2026

View reviewed changes

Comment thread chainladder/utils/tests/test_utilities.py Outdated

Merge remote-tracking branch 'upstream/main' into docs/704-utility-ex…

f23fe84

…amples

henrydingliu reviewed Jun 12, 2026

View reviewed changes


		.. testcode::

		clrd = cl.load_sample("clrd").groupby("LOB").sum().iloc[:2]

		assert not missing, f"sdist is missing sample CSVs: {sorted(missing)}"


		def test_load_sample_uspp() -> None:

Conversation

EKtheSage commented May 16, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented May 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

henrydingliu commented May 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kennethshsu commented May 28, 2026

Uh oh!

EKtheSage commented Jun 8, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

henrydingliu commented Jun 9, 2026

Uh oh!

EKtheSage commented Jun 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

henrydingliu commented Jun 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

EKtheSage commented May 16, 2026 •

edited by cursor Bot

Loading

codecov Bot commented May 16, 2026 •

edited

Loading