Method Reference

This page contains generated API reference sections by module for the ActuaFlow package.

ActuaFlow Core

GLM Models

Freq/Sev Workflow

Aggregate (Combined) Frequency-Severity Models

Combines frequency and severity models to compute pure premium and loaded premium.

Features: - Combined frequency-severity models - Pure premium calculation - Factor table creation - Premium loading application - Elasticity computations

Author: Michael Watson License: MPL-2.0

class actuaflow.freqsev.aggregate.AggregateModel(frequency_model, severity_model)

Bases: object

Combined frequency-severity model for pure premium calculation.

Pure Premium = Frequency × Severity

Parameters:

• frequency_model (FrequencyModel) – Fitted frequency model

• severity_model (SeverityModel) – Fitted severity model

base_frequency_

Base frequency (intercept on response scale)

Type:

float

base_severity_

Base severity (intercept on response scale)

Type:

float

base_pure_premium_

Base pure premium (frequency × severity)

Type:

float

Examples

>>> agg_model = AggregateModel(freq_model, sev_model)
>>> factor_table = agg_model.create_factor_table()
>>> premium = agg_model.predict_pure_premium(newdata)

create_factor_table()

Create combined rating factor table.

Multiplies frequency and severity relativities for each factor level.

Returns:

Combined factor table with columns: - Variable: Factor name - Level: Factor level - Frequency_Relativity: Frequency relativity - Severity_Relativity: Severity relativity - Combined_Relativity: Product of freq × sev - Pure_Premium: Base premium × combined relativity

Return type:

pd.DataFrame

predict_pure_premium(data, exposure=None)

Predict pure premium for new data.

Pure Premium = Predicted Frequency × Predicted Severity

Parameters:

• data (pd.DataFrame) – New data for prediction

• exposure (str, optional) – Exposure column (if provided, returns total expected loss)

Returns:

Pure premium predictions

Return type:

pd.Series

actuaflow.freqsev.aggregate.calculate_premium(pure_premium, loadings, exposure=None)

Calculate loaded premium from pure premium with sequential loadings.

Sequential Loading Formula: 1. Adjust for inflation: PP × (1 + inflation) 2. Add expenses: / (1 - expense_ratio) 3. Add commission: / (1 - commission) 4. Add profit: × (1 + profit_margin) 5. Add taxes: / (1 - tax_rate)

Parameters:

• pure_premium (pd.Series) – Pure premium (frequency × severity)

• loadings (dict) – Dictionary of loading factors: - inflation: Expected claim inflation rate - expense_ratio: Operating expense ratio - commission: Agent commission rate - profit_margin: Target profit margin - tax_rate: Premium tax rate

• exposure (pd.Series, optional) – Exposure for computing per-unit rates

Returns:

Premium breakdown with columns: - pure_premium: Original pure premium - after_inflation: After inflation adjustment - after_expenses: After expense loading - after_commission: After commission loading - after_profit: After profit margin - loaded_premium: Final loaded premium - premium_per_unit: (if exposure provided)

Return type:

pd.DataFrame

actuaflow.freqsev.aggregate.combine_models(frequency_model, severity_model)

Convenience function to combine frequency and severity models.

Parameters:

• frequency_model (FrequencyModel) – Fitted frequency model

• severity_model (SeverityModel) – Fitted severity model

Returns:

Combined model

Return type:

AggregateModel

actuaflow.freqsev.aggregate.premium_waterfall(pure_premium_total, loadings)

Create premium loading waterfall for visualization.

Shows step-by-step premium build-up from pure premium to loaded premium.

Parameters:

• pure_premium_total (float) – Total pure premium

• loadings (dict) – Loading factors

Returns:

Waterfall table with columns: - Step: Loading step name - Amount: Premium at this step - Increase: Incremental increase - Increase_Pct: Increase as % of pure premium

Return type:

pd.DataFrame

Exposure & Portfolio

Exposure Rating Tools

Comprehensive rating functions for computing rates and applying class plans.

Features: - Rate per exposure computation with loadings - Class plan creation from factor relativities - Rating table generation for production systems - Relativity application and aggregation

Author: Michael Watson License: MPL-2.0

actuaflow.exposure.rating.apply_exposure_curve(base_rate, exposure, exposure_curve)

Adjust a base rate using an ExposureCurve factor.

Return type:

Union[float, Series, ndarray]

actuaflow.exposure.rating.apply_relativities(base_value, factor_relativities)

Apply multiplicative relativities to a base value.

Result = Base × Rel_1 × Rel_2 × …

Parameters:

• base_value (float) – Base value (rate, premium, etc.)

• factor_relativities (dict) – {factor_name: relativity_value}

Returns:

Adjusted value

Return type:

float

Examples

>>> rate = apply_relativities(
...     base_value=100.0,
...     factor_relativities={'age': 1.2, 'territory': 0.9}
... )
>>> # Result: 100 × 1.2 × 0.9 = 108.0

actuaflow.exposure.rating.compute_credibility_weighted_rate(manual_rate, experience_rate, credibility)

Compute credibility-weighted rate.

Blends manual (a priori) rate with experience (a posteriori) rate.

Credibility Formula: Rate = Z × Experience_Rate + (1 - Z) × Manual_Rate

where Z is the credibility factor (0 to 1).

Parameters:

• manual_rate (float) – Manual (class plan) rate

• experience_rate (float) – Experience-based rate

• credibility (float) – Credibility factor (0 = full manual, 1 = full experience)

Returns:

Credibility-weighted rate

Return type:

float

Examples

>>> rate = compute_credibility_weighted_rate(
...     manual_rate=100.0,
...     experience_rate=120.0,
...     credibility=0.3
... )
>>> # Result: 0.3 × 120 + 0.7 × 100 = 106.0

actuaflow.exposure.rating.compute_experience_mod(actual_losses, expected_losses, credibility=None, cap=None)

Compute experience modification factor.

Experience Mod = [Z × (Actual / Expected) + (1 - Z) × 1.0]

Parameters:

• actual_losses (float) – Actual incurred losses

• expected_losses (float) – Expected losses (from class rate)

• credibility (float, optional) – Credibility factor. If None, uses full credibility (Z=1)

• cap (float, optional) – Maximum allowed modification (e.g., 2.0 for 200% cap)

Returns:

Experience modification factor

Return type:

float

Examples

>>> exp_mod = compute_experience_mod(
...     actual_losses=120000,
...     expected_losses=100000,
...     credibility=0.5,
...     cap=2.0
... )
>>> # Result: 0.5 × (120/100) + 0.5 × 1.0 = 1.1

actuaflow.exposure.rating.compute_rate_per_exposure(pure_premium, exposure, loadings=None)

Compute rate per unit exposure.

Rate = (Pure Premium / Exposure) × Loading Factor

Parameters:

• pure_premium (array-like or float) – Pure premium (total expected loss)

• exposure (array-like or float) – Exposure (e.g., policy years, sales, payroll)

• loadings (dict, optional) – Loading factors (if None, uses pure premium rate)

Returns:

rate – Rate per unit exposure

Return type:

array-like or float

Examples

>>> rate = compute_rate_per_exposure(
...     pure_premium=1000,
...     exposure=10,
...     loadings={'profit': 0.05, 'expenses': 0.15}
... )

actuaflow.exposure.rating.create_class_plan(data, rating_factors, base_rate, relativities, exposure_col='exposure', min_rate=None, max_rate=None)

Create a class plan rate table by applying factor relativities to base rate.

Class Plan Formula: Rate = Base Rate × Factor_1_Relativity × Factor_2_Relativity × …

Parameters:

• data (pd.DataFrame) – Data with rating factor values

• rating_factors (list of str) – Rating factor column names

• base_rate (float) – Base rate per unit exposure

• relativities (dict) – Nested dict of {factor: {level: relativity}}

• exposure_col (str) – Exposure column name

• min_rate (float, optional) – Minimum allowed rate

• max_rate (float, optional) – Maximum allowed rate

Returns:

Data with added ‘rate’ and ‘premium’ columns

Return type:

pd.DataFrame

Examples

>>> relativities = {
...     'age_group': {'18-25': 1.5, '26-35': 1.0, '36+': 0.8},
...     'vehicle_type': {'sedan': 1.0, 'suv': 1.2, 'sports': 1.8}
... }
>>> rates = create_class_plan(
...     data=policies,
...     rating_factors=['age_group', 'vehicle_type'],
...     base_rate=100.0,
...     relativities=relativities
... )

actuaflow.exposure.rating.create_rating_table(factor_combinations, base_rate, relativities)

Create a complete rating table for all factor combinations.

Useful for creating lookup tables for production rating systems.

Parameters:

• factor_combinations (pd.DataFrame) – All combinations of rating factors

• base_rate (float) – Base rate

• relativities (dict) – Nested relativities dict

Returns:

Rating table with rate for each combination

Return type:

pd.DataFrame

Examples

>>> import itertools
>>> ages = ['18-25', '26-35', '36+']
>>> vehicles = ['sedan', 'suv', 'sports']
>>> combos = pd.DataFrame(
...     list(itertools.product(ages, vehicles)),
...     columns=['age_group', 'vehicle_type']
... )
>>> rating_table = create_rating_table(combos, 100.0, relativities)

Trending and Inflation Adjustment Tools

Functions for adjusting historical losses to current cost levels.

Features: - Historical loss trending to current levels - Inflation adjustment calculations - Trend factor computation between dates - Exposure and premium projection - Loss development to ultimate - On-level premium adjustment

Author: Michael Watson License: MPL-2.0

actuaflow.exposure.trending.apply_inflation(base_amount, inflation_rate)

Apply one-year inflation adjustment.

Inflated Amount = Base Amount × (1 + inflation_rate)

Parameters:

• base_amount (float or array-like) – Base amount at current price level

• inflation_rate (float) – Expected inflation rate

Returns:

inflated_amount – Amount adjusted for inflation

Return type:

float or array-like

Examples

>>> next_year_losses = apply_inflation(100000, 0.025)
>>> # Result: 102,500

actuaflow.exposure.trending.apply_trend_factor(historical_value, trend_rate, years)

Apply trend factor to adjust historical values to current levels.

Trend Formula: Current Value = Historical Value × (1 + trend_rate) ^ years

Parameters:

• historical_value (float or array-like) – Historical loss amounts or rates

• trend_rate (float) – Annual trend rate (e.g., 0.03 for 3%)

• years (float) – Number of years to trend (can be fractional)

Returns:

current_value – Trended values at current cost level

Return type:

float or array-like

Examples

>>> # Trend 2020 losses to 2024 with 3% annual trend
>>> current_losses = apply_trend_factor(100000, 0.03, 4)
>>> # Result: 100000 × 1.03^4 = 112,551

actuaflow.exposure.trending.compute_trend_factor(from_date, to_date, annual_trend_rate)

Compute trend factor between two dates.

Parameters:

• from_date (str or datetime) – Start date (historical)

• to_date (str or datetime) – End date (current/future)

• annual_trend_rate (float) – Annual trend rate

Returns:

Compound trend factor

Return type:

float

Examples

>>> factor = compute_trend_factor('2020-01-01', '2024-06-01', 0.03)
>>> # Trends from Jan 2020 to Jun 2024 (4.5 years) at 3%

actuaflow.exposure.trending.compute_trend_from_history(loss_data, date_col, amount_col, method='exponential')

Estimate trend rate from historical loss data.

Parameters:

• loss_data (pd.DataFrame) – Historical loss data

• date_col (str) – Date column name

• amount_col (str) – Loss amount column name

• method (str) – ‘exponential’ for exponential fit, ‘linear’ for linear

Returns:

Estimated annual trend rate

Return type:

float

Examples

>>> trend_rate = compute_trend_from_history(
...     losses,
...     date_col='accident_date',
...     amount_col='amount'
... )

actuaflow.exposure.trending.development_to_ultimate(reported_losses, development_factor)

Develop losses to ultimate using loss development factor.

Ultimate Losses = Reported Losses × Development Factor

Parameters:

• reported_losses (float or array-like) – Losses reported to date

• development_factor (float) – Age-to-ultimate development factor (e.g., 1.15 for 15% development)

Returns:

ultimate_losses – Projected ultimate losses

Return type:

float or array-like

Examples

>>> ultimate = development_to_ultimate(100000, 1.15)
>>> # Result: 115,000

actuaflow.exposure.trending.onlevel_adjustment(historical_premium, rate_changes)

Adjust historical premium to current rate level (on-leveling).

Used to adjust earned premium for rate changes that occurred mid-period.

Parameters:

• historical_premium (float or pd.Series) – Earned premium at historical rates

• rate_changes (pd.DataFrame) – Rate changes with columns: - effective_date: Date of rate change - rate_change: Rate change factor (e.g., 1.05 for 5% increase) - fraction: Fraction of exposure period after change

Returns:

onlevel_premium – Premium adjusted to current rate level

Return type:

float or pd.Series

Examples

>>> rate_changes = pd.DataFrame({
...     'effective_date': ['2023-07-01'],
...     'rate_change': [1.05],
...     'fraction': [0.5]  # 6 months of 12-month policy
... })
>>> onlevel = onlevel_adjustment(100000, rate_changes)
>>> # Premium before change: 100000 × 0.5 = 50000 (no adjustment)
>>> # Premium after change: 100000 × 0.5 / 1.05 = 47619 (adjust down)
>>> # On-level: 50000 + 50000 = 100000 (but correctly: 97619)

actuaflow.exposure.trending.parallelogram_method(earned_premium_historical, rate_change_factor, rate_change_date, period_start, period_end)

On-level earned premium using parallelogram method.

Adjusts for rate changes that occurred mid-period.

Parameters:

• earned_premium_historical (float) – Earned premium at historical rates

• rate_change_factor (float) – Rate change factor (e.g., 1.05 for +5%)

• rate_change_date (datetime) – Effective date of rate change

• period_start (datetime) – Start of earned premium period

• period_end (datetime) – End of earned premium period

Returns:

On-level earned premium

Return type:

float

actuaflow.exposure.trending.project_exposures(current_exposures, growth_rate, years=1)

Project future exposures based on growth rate.

Future Exposures = Current Exposures × (1 + growth_rate) ^ years

Parameters:

• current_exposures (float or pd.Series) – Current exposure units

• growth_rate (float) – Annual growth rate

• years (int) – Number of years to project

Returns:

future_exposures – Projected exposures

Return type:

float or pd.Series

Examples

>>> future_exp = project_exposures(10000, 0.05, 3)
>>> # Project 10,000 units forward 3 years at 5% growth
>>> # Result: 11,576

Tariff, Rate Optimization & Compliance

Utilities