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❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #804 +/- ##
==========================================
+ Coverage 86.23% 88.69% +2.46%
==========================================
Files 86 89 +3
Lines 4947 5052 +105
Branches 643 645 +2
==========================================
+ Hits 4266 4481 +215
+ Misses 484 425 -59
+ Partials 197 146 -51
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 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?
|
@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
|
@henrydingliu thanks for the detailed review. All comments have been addressed in the latest commit. Summary below:
|
3 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
Documentation and doctest strings only; no changes to implementation or behavior.
Overview
Adds Sphinx doctest-backed docstrings to several public utilities in
chainladder/utils/utility_functions.py, extending narrative Parameters/Returns text where missing and illustrating real workflows (sample triangles, estimators, round-trips).Serialization:
read_pickledocuments dill round-trip fidelity for fittedDevelopment;read_jsonshows restoring estimator params fromto_jsonoutput.Triangle ops:
concatdemonstrates stacking paid vs incurred alongaxis=1;minimum/maximumshow low- and high-side ultimate scenarios across two chainladder runs.ML prep:
PatsyFormulagains two examples—TweedieGLMwithC(development) + C(origin)and aDevelopmentML+ sklearnPipelineusing the same R-style formulas.Reviewed by Cursor Bugbot for commit 7f5c670. Bugbot is set up for automated code reviews on this repo. Configure here.