pal.frequency_severity module
Frequency-severity modeling for actuarial applications.
This module provides classes and functions for modeling compound distributions commonly used in insurance and actuarial science, where claims are modeled as the sum of a random number (frequency) of random amounts (severity).
Key components: - FrequencySeverityModel: Main class for compound distribution modeling - FreqSevSims: Container for frequency-severity simulation results - Utility functions for simulation index management
The frequency-severity approach is fundamental in actuarial modeling for: - Aggregate claims modeling - Risk assessment and capital modeling - Insurance pricing and reserving
Example
>>> from pal.distributions import Poisson, LogNormal
>>> freq_dist = Poisson(5.0) # Expected 5 claims
>>> sev_dist = LogNormal(mean=10000, sigma=0.5) # Claim amounts
>>> model = FrequencySeverityModel(freq_dist, sev_dist)
>>> simulations = model.simulate(n_sims=10000)
- class pal.frequency_severity.FrequencySeverityModel(freq_dist, sev_dist)[source]
Bases:
objectConstructs and simulates from Frequency-Severity, or Compound distributions.
- __init__(freq_dist, sev_dist)[source]
Initialize a frequency-severity model.
- Parameters:
freq_dist (
DistributionBase) – Distribution for frequency component.sev_dist (
DistributionBase) – Distribution for severity component.
- generate(n_sims=None, rng=None)[source]
Generate simulations from the Frequency-Severity model.
- Return type:
Parameters: - n_sims (int): Number of simulations to generate. If None, uses the
default value from the config.
- rng (np.random.Generator, optional): Random number generator. Uses
config.rng if None.
Returns: - FreqSevSims: Object containing the generated simulations.
- class pal.frequency_severity.FreqSevSims(sim_index, values, n_sims)[source]
Bases:
ProteusStochasticVariableA class for storing and manipulating Frequency-Severity simulations.
FreqSevSims objects provide convenience methods for aggregating and summarizing the simulations.
>>> sim_index = np.array([0, 0, 1, 1, 1, 2, 2, 2, 2]) >>> values = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> n_sims = 3 >>> fs = FreqSevSims(sim_index, values, n_sims) >>> fs.aggregate() StochasticScalar([ 3., 12., 30.]) >>> fs.occurrence() StochasticScalar([2., 5., 9.])
They can be operated on using standard mathematical operations, as well as as numpy ufuncs and functions.
>>> fs + 1 FreqSevSims(...) >>> np.maximum(fs, 5) FreqSevSims(...) >>> np.where(fs > 5, 1, 0) FreqSevSims(...)
FreqSevSims objects can be multiplied, added, subtracted, divided, and compared with other FreqSevSims objects, provided that the simulation indices match.
>>> fs1 = FreqSevSims(sim_index, values, n_sims) >>> fs2 = FreqSevSims(sim_index, values, n_sims) >>> fs1 + fs2 FreqSevSims(...)
- __init__(sim_index, values, n_sims)[source]
Create a new FreqSevSims object out the list of simulation indices.
Creates a FreqSevSims object from simulation indices and corresponding values. Note, the simulation indices are assumed to be ordered and 0-indexed.
- aggregate()[source]
Calculates the aggregate loss for each simulation.
Sums all individual event losses within each simulation to get the total loss per simulation. This converts event-level FreqSevSims data to simulation-level StochasticScalar data suitable for statistical analysis.
Example
>>> sim_index = np.array([0, 0, 1, 1, 1, 2, 2, 2, 2]) >>> values = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> n_sims = 3 >>> fs = FreqSevSims(sim_index, values, n_sims) >>> aggregate_losses: StochasticScalar = fs.aggregate() >>> aggregate_losses StochasticScalar([3., 12., 30.]) >>> # Now you can apply statistical methods >>> aggregate_losses.mean() 15.0
- Returns:
- Array containing the aggregate loss for each simulation.
Use this for statistical analysis (mean, std, percentiles, etc.).
- Return type:
- occurrence()[source]
Calculates the maximum occurrence loss for each simulation.
Finds the largest individual event loss within each simulation. This converts event-level FreqSevSims data to simulation-level StochasticScalar data suitable for statistical analysis.
Example
>>> sim_index = np.array([0, 0, 1, 1, 1, 2, 2, 2, 2]) >>> values = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> n_sims = 3 >>> fs = FreqSevSims(sim_index, values, n_sims) >>> max_losses: StochasticScalar = fs.occurrence() >>> max_losses StochasticScalar([2., 5., 9.]) >>> # Now you can apply statistical methods >>> max_losses.mean() 5.33
- Returns:
- Array containing the maximum occurrence loss for each
simulation. Use this for statistical analysis (mean, std, percentiles, etc.).
- Return type:
- count()[source]
Counts the number of losses (events) in each simulation.
Returns the frequency count of how many individual losses occurred within each simulation. This is useful for analyzing frequency distributions and understanding claim counts.
Example
>>> sim_index = np.array([0, 0, 1, 1, 1, 2, 2, 2, 2]) >>> values = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> n_sims = 3 >>> fs = FreqSevSims(sim_index, values, n_sims) >>> loss_counts: StochasticScalar = fs.count() >>> loss_counts StochasticScalar([2., 3., 4.]) >>> # Now you can apply statistical methods >>> loss_counts.mean() 3.0 >>> loss_counts.quantile(0.5) 3.0
- Returns:
- Array containing the number of losses for each
simulation. Use this for analyzing frequency distributions.
- Return type:
- all()
Check if all values in the variable are True (non-zero).
- Return type:
- Returns:
True if all values are non-zero, False otherwise.
- any()
Check if any value in the variable is True (non-zero).
- Return type:
- Returns:
True if any value is non-zero, False otherwise.
- astype(dtype)
Convert the underlying values to a specified dtype.
- upsample(n_sims)[source]
Upsamples the FreqSevSims object to the given number of simulations.
- Parameters:
n_sims (
int) – Target number of simulations- Return type:
- Returns:
New FreqSevSims object with upsampled data
- Raises:
ValueError – If self.n_sims is None