docs: add utility doctest examples#804
Conversation
EKtheSage
requested review from
genedan,
henrydingliu,
jbogaardt and
kennethshsu
as code owners
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
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 0a7c2f9. Configure here.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #804 +/- ##
=======================================
Coverage 86.23% 86.23%
=======================================
Files 86 86
Lines 4947 4947
Branches 643 643
=======================================
Hits 4266 4266
Misses 484 484
Partials 197 197
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
please pull main and incorporate recent changes |
EKtheSage
force-pushed
the
docs/704-utility-examples
branch
from
0a7c2f9 to
9175ae7
Compare
|
|
||
| .. testcode:: | ||
|
|
||
| clrd = cl.load_sample("clrd").groupby("LOB").sum().iloc[:2] |
There was a problem hiding this comment.
test demonstrates that concatting identical columns doesn't do anything, which doesn't match the example text.
| def minimum(x1, x2): | ||
| """Element-wise minimum of two triangles (delegates to ``Triangle.minimum``). | ||
|
|
||
| Examples |
There was a problem hiding this comment.
we need more basic docstring before a doctest. what's x1? what's x2?
|
|
||
| Examples | ||
| -------- | ||
| Cap a triangle cell-by-cell by comparing it with another triangle of limits. |
There was a problem hiding this comment.
are we certain this is true? can x2 be a scalar?
| def read_json(json_str, array_backend=None): | ||
| """Deserialize JSON produced by ``to_json`` (triangle, estimator, or pipeline). | ||
|
|
||
| Examples |
There was a problem hiding this comment.
this example feels empty without seeing the actual json string. please follow the example from pandas
| 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:: |
There was a problem hiding this comment.
should we be showing all the numbers?
…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
| import chainladder as cl | ||
|
|
||
| tri = cl.load_sample("raa") | ||
| dev = cl.Development(average="volume").fit(tri) |
There was a problem hiding this comment.
to demonstrate that to_pickle does something, we should use non-default parameters. something like avg = simple, n = 4.
| dev.to_pickle(p) | ||
| restored = cl.read_pickle(p) | ||
| os.remove(p) | ||
| print(restored.transform(tri).ldf_.values[0, 0, 0, :4].round(4)) |
There was a problem hiding this comment.
can we print the full ldf_ from both the original and the restored estimators?
| 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)) |
There was a problem hiding this comment.
good use case for concat. can we focus the test output around concat only?
2 participants
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
Low risk: changes are documentation-only (docstrings/doctest examples) and do not modify runtime behavior.
Overview
Adds Sphinx-friendly docstrings with doctest examples to several utilities in
utility_functions.py, includingread_pickle,read_json,concat,minimum,maximum, andPatsyFormula.The new examples demonstrate common workflows (e.g., serializing/restoring estimators and pipelines, combining triangles for
MunichAdjustment, comparing ultimate scenarios, and building formula-based design matrices) to improve documentation coverage and testability.Reviewed by Cursor Bugbot for commit cf48166. Bugbot is set up for automated code reviews on this repo. Configure here.