From 38688ad21cb04bc9678861ae589d99d1d022d049 Mon Sep 17 00:00:00 2001 From: Simon Koch-Sultan Date: Sat, 14 Nov 2026 13:42:42 -0500 Subject: [PATCH 1/2] Add Triangle.as_of and document how valuations are stamped MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 (#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). --- chainladder/core/base.py | 22 ++++++++++ chainladder/core/tests/test_triangle.py | 49 ++++++++++++++++++++++ chainladder/core/triangle.py | 56 +++++++++++++++++++++++++ docs/user_guide/triangle.ipynb | 46 ++++++++++++++++++++ 4 files changed, 173 insertions(+) diff --git a/chainladder/core/base.py b/chainladder/core/base.py index f06531e38..e93e6f5f0 100644 --- a/chainladder/core/base.py +++ b/chainladder/core/base.py @@ -733,6 +733,28 @@ def _auto_sparse(self) -> Triangle: @property def valuation(self): + """ + The valuation date of every cell, origin varying fastest. + + Each date is the last instant of its valuation period, one time unit + before the next period starts. The unit is a nanosecond or a + microsecond, depending on the pandas version. On the annual ``raa`` + sample the 1988 diagonal is valued at ``1988-12-31 23:59:59.999999999`` + under pandas 2. + + pandas reads a date bound such as ``"1988-12-31"`` as midnight at the + start of that day, so ``tri.valuation <= "1988-12-31"`` leaves out the + cells valued at the end of 1988, and ``tri.valuation == "1988-12-31"`` + matches none of them. To filter through the end of a period, use + :meth:`~chainladder.Triangle.as_of`, compare against the start of + the next period (``tri.valuation < "1989"``) or compare against + ``valuation_date``. + + Returns + ------- + pandas.DatetimeIndex + One date for each origin and development cell. + """ ddims = self.ddims if self.is_val_tri: out = pd.DataFrame(np.repeat(self.ddims.values[None], len(self.odims), 0)) diff --git a/chainladder/core/tests/test_triangle.py b/chainladder/core/tests/test_triangle.py index d7421018d..8d3c311db 100644 --- a/chainladder/core/tests/test_triangle.py +++ b/chainladder/core/tests/test_triangle.py @@ -4009,3 +4009,52 @@ def test_clrd_samples_one_row_per_cell() -> None: """ assert cl.load_sample("clrd", duplicates="raise").shape[0] == 779 assert cl.load_sample("clrd2025", duplicates="raise").shape[0] == 772 + + +@pytest.mark.parametrize( + "date", + [ + "1988", + 1988, + "1988Q4", + "1988-12", + "1988-12-31", + pd.Timestamp("1988-12-31"), + pd.Period("1988", freq="Y"), + ], +) +def test_as_of_keeps_the_named_period(raa, date) -> None: + """ + ``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"] + result = raa.as_of(date) + assert result.shape == (1, 1, 8, 8) + assert result.valuation_date == expected.valuation_date + assert result == expected + + +def test_as_of_inside_a_period_stops_at_the_previous_one(raa) -> None: + """On an annual triangle a date inside 1988 stops at the end of 1987.""" + result = raa.as_of("1988-06-30") + assert result.shape == (1, 1, 7, 7) + assert result == raa[raa.valuation < "1988"] + + +def test_as_of_quarterly(qtr) -> None: + """A quarter and its last day give the same quarterly slice.""" + expected = qtr[qtr.valuation < "1995-07-01"] + assert qtr.as_of("1995Q2") == expected + assert qtr.as_of("1995-06-30") == expected + assert qtr.as_of("1995-06-30").valuation_date == expected.valuation_date + + +def test_as_of_latest_valuation_returns_the_whole_triangle(raa) -> None: + assert raa.as_of(raa.valuation_date) == raa + assert raa.as_of("2030") == raa + + +def test_as_of_before_the_first_valuation_raises(raa) -> None: + with pytest.raises(ValueError): + raa.as_of("1980") diff --git a/chainladder/core/triangle.py b/chainladder/core/triangle.py index bb76492a5..a6c210d98 100644 --- a/chainladder/core/triangle.py +++ b/chainladder/core/triangle.py @@ -1305,6 +1305,62 @@ def latest_diagonal(self) -> Triangle: ) return obj + def as_of(self, date) -> Triangle: + """ + The Triangle as it stood at the end of a day or period. + + 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 + the day, so ``tri[tri.valuation <= "1988-12-31"]`` leaves out the + cells valued at the end of 1988. ``tri.as_of("1988-12-31")`` keeps + them. + + Parameters + ---------- + 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 + as given. A ``Timestamp``, ``datetime``, ``date`` or + ``numpy.datetime64`` names its whole day, whatever its time. + + Returns + ------- + Triangle + The cells valued on or before the end of the named period. + + Raises + ------ + ValueError + If ``date`` cannot be parsed, or if no cell is valued by then. + + Examples + -------- + + .. testsetup:: + + import chainladder as cl + + .. testcode:: + + raa = cl.load_sample("raa") + print(raa.as_of("1988").shape) + print(raa.as_of("1988-12-31").shape) + print(raa.as_of("1988-06-30").shape) + + .. testoutput:: + + (1, 1, 8, 8) + (1, 1, 8, 8) + (1, 1, 7, 7) + """ + if isinstance(date, (str, int, np.integer, pd.Period)): + period = pd.Period(date) + else: + period = pd.Period(pd.Timestamp(date), freq="D") + return self[self.valuation <= period.end_time] + @property def link_ratio(self) -> Triangle: """ diff --git a/docs/user_guide/triangle.ipynb b/docs/user_guide/triangle.ipynb index 0577473fa..3958a3132 100644 --- a/docs/user_guide/triangle.ipynb +++ b/docs/user_guide/triangle.ipynb @@ -6021,6 +6021,52 @@ "raa[raa.origin > \"1987-01-01\"]" ] }, + { + "cell_type": "markdown", + "id": "triangle-valuation-filter", + "metadata": {}, + "source": [ + "#### Filtering on valuation\n", + "\n", + "Each valuation is stamped at the last instant of its period, so the 1988\n", + "diagonal of the annual ``raa`` sample is valued just before midnight at the end\n", + "of 1988-12-31. pandas reads a date such as ``\"1988-12-31\"`` as midnight at the\n", + "start of that day, so a ``<=`` filter with the period-end date leaves out the\n", + "diagonal valued at the end of 1988." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "triangle-valuation-filter-le", + "metadata": {}, + "outputs": [], + "source": [ + "# Stops at 1987: \"1988-12-31\" means midnight at the start of that day\n", + "raa[raa.valuation <= \"1988-12-31\"].valuation_date" + ] + }, + { + "cell_type": "markdown", + "id": "triangle-as-of", + "metadata": {}, + "source": [ + "To keep everything valued through the end of a day or period, use ``as_of``,\n", + "filter with the start of the next period (``raa.valuation < \"1989\"``) or compare\n", + "against ``valuation_date``." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "triangle-as-of-code", + "metadata": {}, + "outputs": [], + "source": [ + "# Keeps the 1988 diagonal\n", + "raa.as_of(\"1988-12-31\").valuation_date" + ] + }, { "cell_type": "markdown", "id": "57689670", From 1bd54fec362dce397fccfdb5273e6f05755156e6 Mon Sep 17 00:00:00 2001 From: Simon Koch-Sultan Date: Sat, 14 Nov 2026 17:53:24 -0500 Subject: [PATCH 2/2] Compare triangles with equals in the as_of tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit == 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). --- chainladder/core/tests/test_triangle.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/chainladder/core/tests/test_triangle.py b/chainladder/core/tests/test_triangle.py index 8d3c311db..52cb17e9b 100644 --- a/chainladder/core/tests/test_triangle.py +++ b/chainladder/core/tests/test_triangle.py @@ -4032,27 +4032,27 @@ def test_as_of_keeps_the_named_period(raa, date) -> None: result = raa.as_of(date) assert result.shape == (1, 1, 8, 8) assert result.valuation_date == expected.valuation_date - assert result == expected + assert result.equals(expected) def test_as_of_inside_a_period_stops_at_the_previous_one(raa) -> None: """On an annual triangle a date inside 1988 stops at the end of 1987.""" result = raa.as_of("1988-06-30") assert result.shape == (1, 1, 7, 7) - assert result == raa[raa.valuation < "1988"] + assert result.equals(raa[raa.valuation < "1988"]) def test_as_of_quarterly(qtr) -> None: """A quarter and its last day give the same quarterly slice.""" expected = qtr[qtr.valuation < "1995-07-01"] - assert qtr.as_of("1995Q2") == expected - assert qtr.as_of("1995-06-30") == expected + assert qtr.as_of("1995Q2").equals(expected) + assert qtr.as_of("1995-06-30").equals(expected) assert qtr.as_of("1995-06-30").valuation_date == expected.valuation_date def test_as_of_latest_valuation_returns_the_whole_triangle(raa) -> None: - assert raa.as_of(raa.valuation_date) == raa - assert raa.as_of("2030") == raa + assert raa.as_of(raa.valuation_date).equals(raa) + assert raa.as_of("2030").equals(raa) def test_as_of_before_the_first_valuation_raises(raa) -> None: