CreditProtectionPeriod#

class rateslib.periods.CreditProtectionPeriod(*, payment, notional=NoInput.blank, currency=NoInput.blank, ex_dividend=NoInput.blank, start, end, frequency, convention=NoInput.blank, termination=NoInput.blank, stub=False, roll=NoInput.blank, calendar=NoInput.blank, adjuster=NoInput.blank)#

Bases: _BasePeriod

A Period defined by a credit event and contingent notional payment.

The immediate expected valuation of the Period cashflow is defined as;

\[\mathbb{E^Q}[V(m_T)C_T] = -N(1-RR) \int_{max(m_{a.s}, m_{today})}^{m_{a.e}} w_{loc:col}(m_s) Q(m_s) \lambda(s) ds\]

where the integral is numerically determined.

There is no analytical delta for this Period type and hence \(\xi\) is not defined.

Examples

In [1]: cp = CreditProtectionPeriod(
   ...:     start=dt(2000, 3, 20),
   ...:     end=dt(2000, 6, 20),
   ...:     payment=dt(2000, 6, 20),
   ...:     frequency="Q",
   ...: )
   ...: 

In [2]: cp.cashflows()
Out[2]: 
{'Type': 'CreditProtectionPeriod',
 'Ccy': 'USD',
 'Payment': datetime.datetime(2000, 6, 20, 0, 0),
 'Notional': 1000000.0,
 'Period': 'Regular',
 'Convention': 'Act360',
 'DCF': 0.25555555555555554,
 'Acc Start': datetime.datetime(2000, 3, 20, 0, 0),
 'Acc End': datetime.datetime(2000, 6, 20, 0, 0),
 'DF': None,
 'Cashflow': None,
 'NPV': None,
 'FX Rate': 1.0,
 'Base Ccy': 'USD',
 'NPV Ccy': None,
 'Collateral': None,
 'Survival': None,
 'Recovery': None}

Parameters:

. –

Note

The following define generalised settlement parameters.
currency (str, optional (set by ‘defaults’)) – The physical settlement currency of the Period.
notional (float, Dual, Dual2, Variable, optional (set by ‘defaults’)) – The notional amount of the Period expressed in notional currency.
payment (datetime, required) – The payment date of the Period cashflow.
ex_dividend (datetime, optional (set as ‘payment’)) –
The ex-dividend date of the Period. Settlements occurring after this date are assumed to be non-receivable.

Note

The following parameters are scheduling period parameters
start (datetime, required) – The identified start date of the Period.
end (datetime, required) – The identified end date of the Period.
frequency (Frequency, str, required) – The Frequency associated with the Period.
convention (Convention, str, optional (set by ‘defaults’)) – The day count Convention associated with the Period.
termination (datetime, optional) – The termination date of an external Schedule.
calendar (Calendar, optional) – The calendar associated with the Period.
stub (bool, str, optional (set as False)) – Whether the Period is defined as a stub according to some external Schedule.
adjuster (Adjuster, optional) – The date Adjuster applied to unadjusted dates in the external Schedule to arrive at adjusted accrual dates.

Attributes Summary

`credit_params`	The `_CreditParams` of the Period.
`period_params`	The `_PeriodParams` of the Period.
`settlement_params`	The `_SettlementParams` of the Period.

Methods Summary

`analytic_delta`(*[, rate_curve, index_curve, ...])	Calculate the analytic rate delta of the Period converted to any other base accounting currency.
`analytic_rec_risk`([rate_curve, disc_curve, ...])	Calculate the exposure of the NPV to a change in recovery rate.
`cashflow`(*[, rate_curve, disc_curve, ...])
`cashflows`(*[, rate_curve, disc_curve, ...])	Return aggregated cashflow data for the Period.
`immediate_local_npv`(*[, rate_curve, ...])	Calculate the immediate NPV of the Period in local settlement currency.
`local_analytic_rate_fixings`(*[, rate_curve, ...])	Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period.
`local_fixings`(identifiers[, scalars, ...])	Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.
`local_npv`(*[, rate_curve, index_curve, ...])	Calculate the NPV of the Period in local settlement currency.
`npv`(*[, rate_curve, index_curve, ...])	Calculate the NPV of the Period converted to any other base accounting currency.
`reset_fixings`([state])	Resets any fixings values of the Period derived using the given data state.
`try_cashflow`(*[, rate_curve, disc_curve, ...])	Replicate `cashflow()` with lazy exception handling.
`try_immediate_analytic_rate_fixings`([...])	Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period with immediate value, with lazy error raising.
`try_immediate_local_analytic_delta`(*[, ...])	Calculate the immediate, analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.
`try_immediate_local_npv`(*[, rate_curve, ...])	Replicate `immediate_local_npv()` with lazy exception handling.
`try_local_analytic_delta`(*[, rate_curve, ...])	Calculate the analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.
`try_local_npv`(*[, rate_curve, index_curve, ...])	Replicate `local_npv()` with lazy exception handling.

Attributes Documentation

credit_params#: The _CreditParams of the Period.

period_params#: The _PeriodParams of the Period.

settlement_params#: The _SettlementParams of the Period.

Methods Documentation

analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the analytic rate delta of the Period converted to any other base accounting currency.

This method converts a local settlement currency value to a base accounting currency according to:

\[A^{bas}(m_s, m_f) = f_{loc:bas}(m_f) A(m_s, m_f)\]

Hint

If the cashflows are unspecified or incalculable due to missing information this method will raise an exception. For a function that returns a Result indicating success or failure use try_local_analytic_delta().

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
base (str, optional) – The currency to convert the local settlement NPV to.
local (bool, optional) – An override flag to return a dict of values indexed by string currency.
settlement (datetime, optional, (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional, (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable or dict

analytic_rec_risk(rate_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, base=NoInput.blank)#

Calculate the exposure of the NPV to a change in recovery rate.

For parameters see BasePeriod.analytic_delta()

Return type:: float

cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

cashflows(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Return aggregated cashflow data for the Period.

Warning

This method is a convenience method to provide a visual representation of all associated calculation data. Calling this method to extracting certain values should be avoided. It is more efficient to source relevant parameters or calculations from object attributes or other methods directly.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
base (str, optional) – The currency to convert the local settlement NPV to.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

dict of values

immediate_local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the immediate NPV of the Period in local settlement currency.

This method does not adjust for ex-dividend and is an immediate measure according to,

\[P_0 = \mathbb{E^Q} [V(m_T) C(m_T)]\]

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[float, Dual, Dual2, Variable]

local_analytic_rate_fixings(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

local_fixings(identifiers, scalars=NoInput.blank, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the sensitivity to fixings of the Instrument, expressed in local settlement currency.

Parameters:

indentifiers (Sequence of tuple[str, Series], required) – These are the series string identifiers and the data values that will be used in each Series to determine the sensitivity against.
scalars (Sequence of floats, optional (each set as 1.0)) – A sequence of scalars to multiply the sensitivities by for each on of the identifiers.
rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

DataFrame

local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the NPV of the Period in local settlement currency.

This method adjusts the immediate NPV for ex-dividend, settlement and forward projected value, according to,

\[\begin{split}P(m_s, m_f) = \mathbb{I}(m_s) \frac{1}{v(m_f)} P_0, \qquad \; \mathbb{I}(m_s) = \left \{ \begin{matrix} 0 & m_s > m_{ex} \\ 1 & m_s \leq m_{ex} \end{matrix} \right .\end{split}\]

for forward, \(m_f\), settlement, \(m_s\), and ex-dividend, \(m_{ex}\).

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable

npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, base=NoInput.blank, local=False, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the NPV of the Period converted to any other base accounting currency.

This method converts a local settlement currency value to a base accounting currency according to:

\[P^{bas}(m_s, m_f) = f_{loc:bas}(m_f) P(m_s, m_f)\]

Hint

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
base (str, optional) – The currency to convert the local settlement NPV to.
local (bool, optional) – An override flag to return a dict of NPV values indexed by string currency.
settlement (datetime, optional, (set as immediate date)) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional, (set as settlement)) – The future date to project the PV to using the disc_curve.

Return type:

float, Dual, Dual2, Variable or dict of such indexed by string currency.

Notes

If base is not provided then this function will return the value obtained from local_npv().

If base is provided this then an FXForwards object may be required to perform conversions. An FXRates object is also allowed for this conversion although best practice does not recommend it due to possible settlement date conflicts.

reset_fixings(state=NoInput.blank)#

Resets any fixings values of the Period derived using the given data state.

Examples

In [3]: fp = FloatPeriod(
   ...:     start=dt(2026, 1, 12),
   ...:     end=dt(2026, 1, 16),
   ...:     payment=dt(2026, 1, 16),
   ...:     frequency="M",
   ...:     fixing_method="rfr_payment_delay",
   ...:     method_param=0,
   ...:     rate_fixings="sofr"
   ...: )
   ...: 

In [4]: fixings.add(
   ...:     name="sofr_1B",
   ...:     series=Series(
   ...:         index=[dt(2026, 1, 12), dt(2026, 1, 13), dt(2026, 1, 14), dt(2026, 1, 15)],
   ...:         data=[3.1, 3.2, 3.3, 3.4]
   ...:     )
   ...: )
   ...: 

# value is populated from given data
In [5]: assert 3.245 < fp.rate_params.rate_fixing.value < 3.255

In [6]: fp.reset_fixings()

# private data related to fixing is removed and requires new data lookup
In [7]: fp.rate_params.rate_fixing._value
Out[7]: <NoInput.blank: 0>

In [8]: fp.rate_params.rate_fixing._populated
Out[8]: Series([], dtype: float64)

Parameters:: state (int, optional) – The state id of the data series that set the fixing. Only fixings determined by this data will be reset. If not given resets all fixings.

try_cashflow(*, rate_curve=NoInput.blank, disc_curve=NoInput.blank, index_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Replicate cashflow() with lazy exception handling.

Return type:: Result[float, Dual, Dual2, Variable]

try_immediate_analytic_rate_fixings(rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Return a DataFrame of financial sensitivity to published interest rate fixings, expressed in local settlement currency of the Period with immediate value, with lazy error raising.

If the Period has no sensitivity to rates fixings this DataFrame is empty.

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForwards object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[DataFrame]

try_immediate_local_analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Calculate the immediate, analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.

This method does not adjust for ex-dividend and is an immediate measure according to,

\[A_0 = \frac{\partial P_0}{\partial \xi}, \quad \text{for some, } \xi\]

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForward object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.

Return type:

Result[float, Dual, Dual2, Variable]

try_immediate_local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank)#

Replicate immediate_local_npv() with lazy exception handling.

Return type:: Result[float, Dual, Dual2, Variable]

try_local_analytic_delta(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Calculate the analytic rate delta of a Period expressed in local settlement currency, with lazy error raising.

This method adjusts the immediate NPV for ex-dividend and forward projected value, according to,

\[\begin{split}A(m_s, m_f) = \mathbb{I}(m_s) \frac{1}{v(m_f)} A_0, \qquad \; \mathbb{I}(m_s) = \left \{ \begin{matrix} 0 & m_s > m_{ex} \\ 1 & m_s \leq m_{ex} \end{matrix} \right .\end{split}\]

for forward, \(m_f\), settlement, \(m_s\), and ex-dividend, \(m_{ex}\).

Parameters:

rate_curve (_BaseCurve or dict of such indexed by string tenor, optional) – Used to forecast floating period rates, if necessary.
index_curve (_BaseCurve, optional) – Used to forecast index values for indexation, if necessary.
disc_curve (_BaseCurve, optional) – Used to discount cashflows.
fx (FXForwards, optional) – The FXForward object used for forecasting the fx_fixing for deliverable cashflows, if necessary. Or, an class:~rateslib.fx.FXRates object purely for immediate currency conversion.
fx_vol (FXDeltaVolSmile, FXSabrSmile, FXDeltaVolSurface, FXSabrSurface, optional) – The FX volatility Smile or Surface object used for determining Black calendar day implied volatility values.
settlement (datetime, optional) – The assumed settlement date of the PV determination. Used only to evaluate ex-dividend status.
forward (datetime, optional) – The future date to project the PV to using the disc_curve.

Return type:

Result[float, Dual, Dual2, Variable]

try_local_npv(*, rate_curve=NoInput.blank, index_curve=NoInput.blank, disc_curve=NoInput.blank, fx=NoInput.blank, fx_vol=NoInput.blank, settlement=NoInput.blank, forward=NoInput.blank)#

Replicate local_npv() with lazy exception handling.

Return type:: Result[float, Dual, Dual2, Variable]

CreditProtectionPeriod#

This Page