[ENH] Add Triangle.percentage_of_ultimate() method for loss development pattern visualization

[Hendrik240298]

Description

chainladder-python currently lacks a visualization method for loss development patterns expressed as percentage of ultimate. This visualization shows cumulative losses divided by ultimate losses across development periods, commonly used in actuarial analysis to examine emergence patterns and compare individual origins against average development. Such visualization helps identify unusual development patterns and supports validation of development assumptions.
Overall, this capability can be valuable across actuarial applications where understanding development velocity is important, including loss reserving analysis, pattern validation, and benchmarking development assumptions across different lines of business or portfolios.

Is your feature request at odds with the scope of the package?

• Yes, absolutely!
• No, but it's still worth discussing.
• N/A (this request is not a codebase enhancement).

Describe the solution you'd like, or your current workaround.

Add a percentage_of_ultimate() method to the Triangle class that creates matplotlib visualizations showing:

• Individual origin development curves (observed data only)
• Average development pattern with multiple weighting methods (volume, simple, regression, Zehnwirth & Barnett numeric)
• Configurable display options for origins, averaging methods, and figure sizing

Method signature:

def percentage_of_ultimate(
    self,
    show_by_origin: bool = True,
    show_average_pattern: bool = True,
    show_origin_years_in_legend: bool = True,
    selected_origins: list = None,
    average: str | float = "volume",
    figsize: tuple = (12, 8)
) -> Figure

Mathematical approach:
The method calculates percentage of ultimate as Cumulative Losses / Ultimate Losses for each development period. Ultimate projections are derived using Development() patterns without tail estimation - the calculation extends observed development through the available CDF factors only.

The method supports volume, simple, regression, and Zehnwirth & Barnett numeric averaging methods (e.g., average=1.5) and works exclusively with raw triangles to provide individual origin analysis.

Key limitations:

• Currently works exclusively with raw triangles (not fitted Development objects or CDF triangles)
• Requires matplotlib for visualization
• Most effective for single triangle analysis

Usage example:

import chainladder as cl

# Load triangle and analyze development patterns
raa = cl.load_sample('raa')

# Basic visualization
fig = raa.percentage_of_ultimate()

# Custom analysis with different averaging
fig = raa.percentage_of_ultimate(
    average="simple",
    selected_origins=[1985, 1987, 1990],
    show_average_pattern=True
)

Plots:

Example of percentage of ultimate for RAA data with volume-weighted average pattern (all origins)

Example of percentage of ultimate for quarterly data set showing selected origins

Do you have any additional supporting notes?

Implementation status: Working implementation available.

Technical details:

• Proposed location: chainladder/core/display.py (follows existing heatmap() pattern)
• Dependencies: matplotlib (consistent with current visualization methods)
• Backend compatibility: Works with numpy, sparse, cupy, and dask backends
• Breaking changes: None - pure addition to Triangle class

Validation:

• Tested with RAA sample data and quarterly development triangles
• Integration confirmed with existing chainladder workflow

[kennethshsu]

Hi @Hendrik240298,

Thanks for the question and suggestion.

Since this package is not quite a graphing package, may I suggest that we use the supported basic mathematical operations to accomplish this? For example, we can quickly get the emergence triangle by dividing a triangle object with an array. See below.

import chainladder as cl
raa = cl.load_sample("raa")
cl_model = cl.Chainladder().fit(raa)
emergence = raa / cl_model.ultimate_
emergence

Once we have the emergence triangle object, we can go back out to pandas with emergence.to_frame() and graph whatever we like. What do you think about this?

[Hendrik240298]

Hi @kennethshsu,
Thanks for your concise answer! You are absolutely right - your straightforward approach yields the same results and is much cleaner.
There is no need for adding a Triangle.percentage_of_ultimate() as the visualization need can be easily met with existing operations.
Since this visualization of the development pattern seems generally useful, would it make sense to add a brief showcase to the Example Gallery? I would be happy to make a draft if you think it is worthwhile.

[kennethshsu]

Hi @Hendrik240298, that's great, glad that you find the solution acceptable.

Yes, we should definitely make an example and have something like this in the example gallery, I think that will be super beneficial to other users. Yes, please do send a draft and submit a pull request if you like!

[henrydingliu]

using incurred / ultimate to derive the development pattern can fail if there's any accident period without any loss amount. a more robust approach would be to transpose the reciprocal of cdf_.

[Hendrik240298]

Thanks for the comment, @henrydingliu! I think we might be looking at slightly different use cases here.

Your approach with the reciprocal of cdf_ would be great for showing the average development pattern across all origins and I also used it in my initial proposed Triangle.percentage_of_ultimate() method.
For emergence visualization though, I am trying to show how each individual origin actually developed - so origin 1981 might emerge differently than origin 1982 based on their actual incurred development.

Regarding your concern about accident periods without loss amounts - I tested this with the raa sample triangle by setting the whole incurred row to NaN for 1985 and @kennethshsu's approach handles it seemingly correctly: when incurred is NaN, the respective emergence entry is also NaN, which is what we expect. The approach appears robust in my testing.

Both approaches could be valuable to visualize. Maybe we could include both in the example - plotting the average expected pattern against the actual emergence by origin?

[henrydingliu]

ah, I misread the original. Good stuff!