Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions chainladder/core/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -733,6 +733,28 @@ def _auto_sparse(self) -> Triangle:

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

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))
Expand Down
49 changes: 49 additions & 0 deletions chainladder/core/tests/test_triangle.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"]

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?

result = raa.as_of(date)
assert result.shape == (1, 1, 8, 8)
assert result.valuation_date == expected.valuation_date
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.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").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).equals(raa)
assert raa.as_of("2030").equals(raa)


def test_as_of_before_the_first_valuation_raises(raa) -> None:
with pytest.raises(ValueError):
raa.as_of("1980")
56 changes: 56 additions & 0 deletions chainladder/core/triangle.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

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.

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

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?

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)

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

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:
"""
Expand Down
46 changes: 46 additions & 0 deletions docs/user_guide/triangle.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
Loading