climada_petals.engine.cat_bonds package

climada_petals.engine.cat_bonds.helpers_tutorial_cat_bonds module

climada_petals.engine.cat_bonds.helpers_tutorial_cat_bonds.create_earthquake_mmi_impact_function(impf_id=1, haz_type='EQ')

Create a stylized earthquake impact function for MMI-based hazards.

The curve uses separate smooth transitions for the affected asset share (PAA) and the mean damage degree conditional on being affected (MDD).

Parameters:

• impf_id (int, optional) – Impact function identifier.

• haz_type (str, optional) – Hazard type associated with the impact function.

Returns:

Impact function set containing a single MMI-based impact function.

Return type:

ImpactFuncSet

climada_petals.engine.cat_bonds.helpers_tutorial_cat_bonds.remap_event_years_even(hazard, start_year=1980, n_years=1000)

This function is intended for tropical cyclone data sets based on STORM which can be downloaded from the CLIMADA data API. In these data sets, all events are assigned the same year which is not suitable for CAT bond simulations that rely on the distribution of events over time. This function remaps the event years to be evenly distributed over a specified number of years while preserving the original month/day seasonality of the events.

climada_petals.engine.cat_bonds.mlt_bond_simulation module

climada_petals.engine.cat_bonds.pooling_functions module

climada_petals.engine.cat_bonds.premium_class module

class climada_petals.engine.cat_bonds.premium_class.PremiumCalculations(bond_simulation_class)

Bases: object

Premium calculation utilities for catastrophe bond simulations.

This class provides premium estimation methods based on Chatoro regression, IBRD bond curve fitting, and Sharpe ratio benchmarks.

Parameters:

bond_simulation_class (object) – Bond simulation instance exposing loss_metrics, df_loss_month, and term attributes.

__init__(bond_simulation_class)

Initialize with a bond simulation object.

Parameters:

bond_simulation_class (object) – Bond simulation instance exposing loss_metrics, df_loss_month, and term attributes.

calc_chatoro_premium(peak_multi: int, investment_graded: int, hybrid_trigger: int, GCIndex=None, BBSpread=None)

Calculate premium using the Chatoro et al. (2022) regression model.

Parameters:

• peak_multi (float) – Indicator wether the cat bond is considered peak peril or if it is covering multiple perils. If either is ture = 1, else 0.

• investment_graded (int) – Indicator for investment-grade status (e.g., 1 for yes, 0 for no).

• hybrid_trigger (int) – Indicator for hybrid trigger structure (e.g., 1 for yes, 0 for no).

• GCIndex (float, optional) – Guy Carpenter Global Property Catastrophe Rate on Line Index value.

• BBSpread (float, optional) – ICE BofA BB US High Yield Index OAS value.

• Sets

• ——-

• chatoro_prem_rate (float) – Calculated Chatoro premium rate.

monoExp(x, a, k, b)

Exponential function for risk multiple curve fitting.

Parameters:

• x (float or np.ndarray) – Input value(s) for the expected loss.

• a (float) – Amplitude parameter.

• k (float) – Decay rate parameter.

• b (float) – Offset parameter.

Returns:

Evaluated exponential function values.

Return type:

float or np.ndarray

calc_ibrd_premium(peril=None, year=None)

Fits a monotonic exponential curve to catastrophe bond data for bonds issued by the World Bank to estimate premium parameters. This function loads IBRD bond data from a csv file, optionally filters the data by peril type or issuing year, and fits a monotonic exponential function to the relationship between expected loss and risk multiple. The fitted parameters are returned.

Parameters:

• peril (str, optional) – Peril type to filter the bonds. If None, no filtering by peril is applied.

• year (list[int] or int, optional) – Issuing year(s) to filter the bonds. If None, no filtering by year is applied.

• Sets

• ——-

• ibrd_prem_rate (float) – The estimated premium rate based on the fitted curve and the bond’s expected annual loss.

find_sharpe(premium: float, monthly_losses: DataFrame, target_sharpe: float)

Calculates the squared difference between the Sharpe ratio of a cat bond cash flow and a target Sharpe ratio. The function simulates the annual cash flows of a catastrophe bond investment, adjusting for losses and premium payments. It computes the average return and standard deviation of the net cash flows, then calculates the Sharpe ratio and returns the squared difference from the target Sharpe ratio.

Parameters:

• premium (float) – Annual premium rate paid to the investor.

• monthly_losses (pandas.DataFrame) – DataFrame with columns ‘losses’ (list of loss amounts per event) and ‘months’ (list of event months) for each year.

• target_sharpe (float) – Target Sharpe ratio to compare against.

Returns:

Squared difference between the calculated Sharpe ratio and the target Sharpe ratio.

Return type:

float

calc_benchmark_premium(target_sharpe: float)

Calculates the initial premium required to achieve a target Sharpe ratio for a given set of annual losses. This function uses numerical optimization to find the premium value that results in the desired Sharpe ratio.

Parameters:

target_sharpe (float) – Desired Sharpe ratio to be achieved.

Returns:

Optimal premium value that achieves the target Sharpe ratio.

Return type:

float

climada_petals.engine.cat_bonds.sng_bond_simulation module

class climada_petals.engine.cat_bonds.sng_bond_simulation.SingleCountryBondSimulation(subarea_calc, term: int, start_year: int, number_of_terms: int)

Bases: object

Single-country catastrophe bond simulation utilities.

This class simulates losses and returns for a single country’s bond based on per-event payouts and damages.

__init__(subarea_calc, term: int, start_year: int, number_of_terms: int)

Initialize with subarea data and simulation horizon.

Parameters:

• subarea_calc (object) – Subarea calculation instance.

• term (int) – Bond term in years for each simulated period.

• start_year (int) – The starting year of the simulation.

• number_of_terms (int) – Number of consecutive terms to simulate.

init_bond_loss(events_per_year: list[DataFrame])

Calculates the expected losses for a catastrophe bond over its term. This function simulates the bond’s loss experience given a sequence of event data per year and month, tracking payouts, damages, remaining princpal value, and the timing of losses. It returns the relative losses, the total payouts and damages per term, and a DataFrame detailing losses and their corresponding months.

Parameters:

events_per_year (list[pandas.DataFrame]) – A list where each element is a DataFrame representing events in a year. Each DataFrame must contain at least ‘month’ and ‘pay’ columns, where ‘pay’ is the payout for each event.

Returns:

• rel_annual_losses (numpy.ndarray) – Array of relative payouts/losses per year (losses divided by principal).

• rel_monthly_loss (pandas.DataFrame) – DataFrame with columns ‘losses’ and ‘months’, detailing the losses and their corresponding months for each year.

• summed_payouts (float) – The total summed payouts over the bond’s term.

• summed_damages (float) – The total summed damages over the bond’s term.

init_loss_simulation(confidence_levels: list[float] = [0.95, 0.99])

Simulate losses, payouts, damages, and risk metrics for a catastrophe bond.

Parameters:

• confidence_levels (list[float], optional) – Confidence levels for VaR and ES calculation.

• Sets

• ——-

• df_loss_month (pd.DataFrame) – Monthly loss data for all simulations.

• loss_metrics (dict) – Expected loss, attachment probability, total payouts/damages, VaR and ES metrics for given confidence levels.

init_return_simulation(premium: float)

Simulates the performance of a catastrophe bond over the simulation period, premiums and returns. This function models the bond’s payouts, premiums, and returns over a series of simulated years. It aggregates annual and total returns and computes Sharpe ratios.

Parameters:

premium (float) – Annual premium rate for the bond.

Returns:

return_metrics – Dictionary with annual premiums, annual returns, total returns, total premiums, and Sharpe ratio.

Return type:

dict

climada_petals.engine.cat_bonds.subareas module

class climada_petals.engine.cat_bonds.subareas.Subareas(hazard, vulnerability, exposure, subareas_gdf: GeoDataFrame)

Bases: object

Handle subareas for CAT bond spatial aggregation.

Parameters:

• hazard (climada.Hazard) – Hazard object containing event data. Attention: The date attribute is used in the CAT bond simulation. Date must include a year and month.

• vulnerability (climada.Vulnerability) – Vulnerability object containing vulnerability functions.

• exposure (climada.Exposure) – Exposure object containing monetary data and geometry.

• subareas_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing subarea polygons. Must cover the exposure perimeter and include (or will be assigned) a subarea_letter column.

hazard

Hazard object containing event data. Attention: The date attribute is used in the CAT bond simulation. Date must include a year and month.

Type:

climada.Hazard

vulnerability

Vulnerability object containing vulnerability functions.

Type:

climada.Vulnerability

exposure

Exposure object containing monetary data and geometry.

Type:

climada.Exposure

subareas_gdf

GeoDataFrame of subarea polygons with subarea_letter labels.

Type:

geopandas.GeoDataFrame

__init__(hazard, vulnerability, exposure, subareas_gdf: GeoDataFrame)

Initialize a Subareas instance.

Parameters:

• hazard (climada.Hazard) – Hazard object containing event data. Attention: The date attribute is used

• in the CAT bond simulation. Date must include a year and month.

• vulnerability (climada.Vulnerability) – Vulnerability object containing vulnerability functions.

• exposure (climada.Exposure) – Exposure object containing monetary data and geometry.

• subareas_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing subarea polygons.

classmethod from_resolution(hazard, vulnerability, exposure, resolution: float, subareas_gdf: GeoDataFrame | None = None)

Create subareas from a grid resolution and an exposure layer.

Parameters:

• hazard (climada.Hazard) – Hazard object containing event data. Attention: The date attribute is used

• in the CAT bond simulation. Date must include a year and month.

• vulnerability (climada.Vulnerability) – Vulnerability object containing vulnerability functions.

• exposure (climada.Exposure) – Exposure object containing monetary data and geometry.

• resolution (float) – Grid cell size used to generate subareas.

• subareas_gdf (geopandas.GeoDataFrame, optional) – Unused placeholder for compatibility.

Returns:

Initialized instance with generated subareas.

Return type:

Subareas

classmethod from_geodataframe(hazard, vulnerability, exposure, gdf: GeoDataFrame)

Create subareas from an existing GeoDataFrame.

Parameters:

• hazard (climada.Hazard) – Hazard object containing event data. Attention: The date attribute is used

• in the CAT bond simulation. Date must include a year and month.

• vulnerability (climada.Vulnerability) – Vulnerability object containing vulnerability functions.

• exposure (climada.Exposure) – Exposure object containing monetary data and geometry.

• gdf (geopandas.GeoDataFrame) – GeoDataFrame of polygon subareas covering the exposure perimeter.

Returns:

Initialized instance with the provided subareas.

Return type:

Subareas

property exposure

Return the exposure object.

Returns:

Exposure object containing monetary data and geometry.

Return type:

climada.Exposure

plot()

Plot exposure raster with subarea boundaries overlaid.

Return type:

None

count_subareas()

Return the number of subareas.

Returns:

Number of subarea polygons.

Return type:

int

climada_petals.engine.cat_bonds.subarea_calculations module

class climada_petals.engine.cat_bonds.subarea_calculations.SubareaCalculations(subareas, index_stat: float | str, initial_guess: tuple[float, float] | None = None)

Bases: object

Subarea-level calculations for parametric catastrophe bond payout setup.

This class computes impacts, parametric indices, payout thresholds, and pay-versus-damage tables for a set of subareas.

Parameters:

• subareas (object) – Container with exposure, hazard, vulnerability, and subareas_gdf.

• index_stat (str or float) – Statistic for the parametric index (e.g., “mean” or a percentile).

• intitial_guess (tuple[float, float], optional) – Initial guess for minimum and maximum payout trigger thresholds.

subareas

Input container holding exposure, hazard, vulnerability, and subareas.

Type:

object

index_stat

Statistic used to summarize hazard intensity per subarea which is used as parametric index.

Type:

str or float

initial_guess

Initial guess for minimum/maximum thresholds for the payout function.

Type:

tuple[float, float]

__init__(subareas, index_stat: float | str, initial_guess: tuple[float, float] | None = None)

Initialize the subarea calculation helper.

Parameters:

• subareas (object) – Container with exposure, hazard, vulnerability, and subareas_gdf.

• index_stat (str or float) – Statistic used for the parametric index (“mean” or a percentile).

• initial_guess (tuple[float, float], optional) – Initial guess for min/max payout trigger thresholds. When omitted, the 30th and 60th percentiles of hazard intensity are used.

create_pay_vs_dam(attachment_point: float, exhaustion_point: float, methods_attachment_point: str | None = None, methods_exhaustion_point: str | None = None)

Build the pay-versus-damage table for the bond structure.

This runs impact calculation, parametric index creation, payout calibration, and computes pay/damage per event.

Parameters:

• attachment_point (float) – Attachment point value or parameter for the selected method. Is either a monetary amount, a fraction of total exposure, or a return period in years.

• exhaustion_point (float) – Exhaustion point value or parameter for the selected method. Is either a monetary amount, a fraction of total exposure, or a return period in years.

• methods_attachment_point (str, optional) – Interpretation method for attachment (e.g., “Exposure_Share” or “Return_Period”).

• methods_exhaustion_point (str, optional) – Interpretation method for exhaustion (e.g., “Exposure_Share” or “Return_Period”).

Returns:

Sets principal, attachment, results, opt_min_thresh, opt_max_thresh, and pay_vs_dam on the instance.

Return type:

None

climada_petals.engine.cat_bonds.subarea_calculations.calc_payout(min_trig: float, max_trig: float, haz_int: DataFrame, max_pay: float)

Calculates payout values based on a linear payout function using hazard intensities and trigger thresholds.

Parameters:

• min_trig (float) – The minimum trigger threshold for hazard intensity.

• max_trig (float) – The maximum trigger threshold for hazard intensity.

• haz_int (pandas.DataFrame) – DataFrame containing hazard intensity values in the first column.

• max_pay (float) – The maximum payout value.

Returns:

payouts – Array of calculated payout values corresponding to each hazard intensity.

Return type:

numpy.ndarray

climada_petals.engine.cat_bonds.utils_cat_bonds module

climada_petals.engine.cat_bonds.utils_cat_bonds.multi_level_es(losses: Series, confidence_levels: list[float])

Calculate Value at Risk (VaR) and Expected Shortfall (ES) for multiple confidence levels.

Parameters:

• losses (pandas.Series) – Loss samples used to estimate tail risk metrics.

• confidence_levels (list[float]) – Confidence levels (e.g., [0.95, 0.99]).

Returns:

• var_list (list[float]) – VaR values in the order of the given confidence levels.

• es_list (list[float]) – ES values in the order of the given confidence levels.

climada_petals.engine.cat_bonds.utils_cat_bonds.allocate_single_payout(payout: float, nominals: ndarray)

Allocate a single payout across tranche nominals.

Parameters:

• payout (float) – Payout amount to allocate.

• nominals (array-like) – 1D array of tranche nominal values.

Returns:

• remaining_nominals (numpy.ndarray) – Remaining nominal values after the payout.

• payout_per_tranche (numpy.ndarray) – Amount allocated to each tranche.