Skip to content

[FEAT] Add Triangle.as_of and document how valuations are stamped - #1620

Open
scks1 wants to merge 2 commits into
casact:mainfrom
scks1:valuation-as-of-1608
Open

scks1 wants to merge 2 commits into
casact:mainfrom
scks1:valuation-as-of-1608

Conversation

@scks1

@scks1 scks1 commented Nov 14, 2026

Copy link
Copy Markdown
Contributor

Summary of Changes

Triangle.valuation stamps each cell at the last instant of its period, while pandas reads a date bound as midnight at the start of the day, so raa[raa.valuation <= "1988-12-31"] returns the triangle as of 1987 (#1608). As agreed in #1608, this PR adds the docs note and a helper, and leaves the stamping alone until #1304 is merged:

  • a docstring on valuation that says how the dates are stamped and how to filter through the end of a period;
  • Triangle.as_of(date), which keeps every cell valued on or before the end of the period date names. A string or integer names the period it spells ("1988", 1988, "1988Q2", "1988-06", "1988-06-30"), a pandas.Period is used as given, and a Timestamp, datetime, date or numpy.datetime64 counts as its whole day. It returns self[self.valuation <= period.end_time];
  • a short "Filtering on valuation" passage with two cells in the Accessors section of the triangle user guide.

Tests: seven ways of naming 1988 give the same result as raa[raa.valuation < "1989"]; a date inside 1988 stops at 1987; "1995Q2" and "1995-06-30" give the same slice of the quarterly sample; the latest valuation date and a later date return the whole triangle; a date before the first valuation raises.

Related GitHub Issue(s)

Part of #1608 (the docs note and the helper). The stamping question stays open there until #1304 is merged.

AI/LLM Usage

This change was made with Árbol, an AI assistant running on Muse, working under my direction. It wrote the change, the tests and the docs, ran the checks and drafted this description. I reviewed the diff and the results before submitting.

Additional Context for Reviewers

The as_of behaviour (keep every cell valued on or before the end of the named day or period) is the one agreed in #1608. The midnight-stamping change is left for after #1304, as discussed there.

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).

Triangle.valuation stamps each cell at the last instant of its period,
while pandas reads a date bound as midnight at the start of the day, so
a valuation <= filter with a period-end date drops that period (casact#1608).
Say so in the valuation docstring and the triangle user guide, and add
as_of, which keeps every cell valued on or before the end of the named
day or period.

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

github-actions Bot commented Nov 14, 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.0% of exported symbols fully typed (301 / 1672)

Known Ambiguous Unknown Total
Project (head) 301 96 1275 1672

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: 332
  • 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 0 6 6
Patch symbol details
Symbol Status Change
chainladder.core.tests.test_triangle.test_as_of_before_the_first_valuation_raises ❌ unknown new
chainladder.core.tests.test_triangle.test_as_of_inside_a_period_stops_at_the_previous_one ❌ unknown new
chainladder.core.tests.test_triangle.test_as_of_keeps_the_named_period ❌ unknown new
chainladder.core.tests.test_triangle.test_as_of_latest_valuation_returns_the_whole_triangle ❌ unknown new
chainladder.core.tests.test_triangle.test_as_of_quarterly ❌ unknown new
chainladder.core.triangle.Triangle.as_of ❌ unknown new

@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.94%. Comparing base (1457b76) to head (1bd54fe).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main    #1620   +/-   ##
=======================================
  Coverage   94.94%   94.94%           
=======================================
  Files          99       99           
  Lines        6425     6432    +7     
  Branches      811      812    +1     
=======================================
+ Hits         6100     6107    +7     
  Misses        207      207           
  Partials      118      118           
Flag Coverage Δ
unittests 94.94% <100.00%> (+<0.01%) ⬆️

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.

== between two triangles is deprecated in favour of Triangle.equals and
emits a FutureWarning, so the new as_of tests call equals directly.

Developed with an AI assistant (Árbol, running Muse).
Comment thread chainladder/core/base.py

@property
def valuation(self):
"""

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks for writing this all out. unfortunately we aren't displaying the docstring of every property, so this isn't showing up in the API reference.

date : str, int, pandas.Period or date-like
A string or integer names the period it spells: ``"1988"`` or
``1988`` is the year 1988, ``"1988Q2"`` a quarter, ``"1988-06"``
a month and ``"1988-06-30"`` a day. A ``pandas.Period`` is used

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you list these out in bullets?

.. testcode::

raa = cl.load_sample("raa")
print(raa.as_of("1988").shape)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

printing the actual as_of triangle would be a much stronger example


Keeps every cell valued on or before the end of the period that
``date`` names. Valuations are stamped at the last instant of their
period, while pandas reads a date bound as midnight at the start of

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is a tad verbose.

also "valuation period" is pure hallucinated term in this context. AI isn't comprehending that .end_time is just a short-cut implementation.

``as_of`` keeps the diagonal valued at the end of the named period, which
a ``valuation <=`` filter with the same date leaves out (#1608).
"""
expected = raa[raa.valuation < "1989"]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you confirm that tri[tri.valuation < year_str] is explicitly tested somewhere?

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