Credit Instruments

Bonds

class rivapy.instruments.bond_specifications.BondBaseSpecification(obj_id: str, issue_date: date | datetime, maturity_date: date | datetime, currency: Currency | str = 'EUR', notional: NotionalStructure | float = 100.0, amortization_scheme: str | AmortizationScheme | None = None, issuer: str = None, securitization_level: SecuritizationLevel | str = 'NONE', rating: Rating | str = 'NONE', day_count_convention: DayCounterType | str = 'ACT360', business_day_convention: RollConvention | str = 'ModifiedFollowing', roll_convention: RollRule | str = 'NONE', calendar: HolidayBase | str = {})[source]

Base class for bond-like instrument specifications.

This class implements common properties shared by bonds, deposits and other deterministic cashflow instruments such as issue/maturity dates, notional handling, currency and basic validation. Subclasses should implement instrument-specific schedule and cashflow behaviour.

Base bond specification.

Parameters:

  • obj_id (str) – (Preferably) Unique label of the bond, e.g. ISIN.

  • issue_date (_Union[date, datetime]) – Date of bond issuance.

  • maturity_date (_Union[date, datetime]) – Bond’s maturity/expiry date. Must lie after the issue_date.

  • currency (str, optional) – Currency as alphabetic, Defaults to ‘EUR’.

  • notional (float, optional) – Bond’s notional/face value. Must be positive. Defaults to 100.0.

  • issuer (str, optional) – Name/id of issuer. Defaults to None.

  • securitization_level (_Union[SecuritizationLevel, str], optional) – Securitization level. Defaults to None.

  • rating (_Union[Rating, str]) – Paper rating.

static _create_sample(n_samples: int, seed: int = None, ref_date=None, issuers: List[str] = None, sec_levels: List[str] = None, currencies: List[str] = None) → List[dict][source]

Create a small list of example bond specifications for testing.

This helper generates a list of dictionaries that mimic the kwargs used to construct bond specifications. It is intended for internal testing and examples only.

Parameters:

  • n_samples (int) – Number of sample entries to generate.

  • seed (int, optional) – RNG seed for reproducible samples.

  • ref_date (date | datetime, optional) – Reference date for issue/maturity generation.

  • issuers (List[str], optional) – Optional pool of issuer names to sample from.

  • sec_levels (List[str], optional) – Optional securitization levels to sample from.

  • currencies (List[str], optional) – Optional currencies to sample from.

Returns:

List of parameter dictionaries usable to create bond specs.

Return type:

List[dict]

property business_day_convention: str

Getter for FRA’s day count convention.

Returns:

FRA’s day count convention.

Return type:

str

property calendar

Getter for the calendar used for business day adjustment.

Returns:

The calendar used for business day adjustment.

property currency: str

Getter for bond’s currency.

Returns:

Bond’s ISO 4217 currency code

Return type:

str

property day_count_convention: str

Getter for instruments’s day count convention.

Returns:

instruments’s day count convention.

Return type:

str

property issue_date: date

Getter for bond’s issue date.

Returns:

Bond’s issue date.

Return type:

date

property issuer: str

Getter for instrument’s issuer.

Returns:

Instrument’s issuer.

Return type:

str

property maturity_date: date

Getter for bond’s maturity date.

Returns:

Bond’s maturity date.

Return type:

date

property notional: NotionalStructure

Getter for bond’s face value.

Returns:

Bond’s face value.

Return type:

float

notional_amount(index: date | datetime | int = None) → float[source]

Get the notional amount at a specific date.

Parameters:

index (_Union[date, datetime, int]) – The index for which to get the notional amount, may be a date or an integer index. If None, returns the full notional structure.

Returns:

The notional amount at the specified index.

Return type:

float

property rating: str
property roll_convention: str

Getter for the roll convention used for business day adjustment.

Returns:

The roll convention used for business day adjustment.

Return type:

str

property securitization_level: str

Getter for instrument’s securitisation level.

Returns:

Instrument’s securitisation level.

Return type:

str

set_amortization_scheme(amortization_scheme) → AmortizationScheme[source]

Resolve an amortization scheme descriptor into an AmortizationScheme.

Accepts one of:

  • None: returns a ZeroAmortizationScheme

  • str: resolves the identifier via AmortizationScheme._from_string

  • AmortizationScheme instance: returned unchanged

Parameters:

amortization_scheme (None | str | AmortizationScheme) – descriptor.

Returns:

concrete amortization scheme object.

Return type:

AmortizationScheme

Raises:

ValueError – if the provided argument type is not supported.

set_notional_structure(notional, amortization_scheme) → NotionalStructure[source]

Create or validate the notional structure for this instrument.

The function accepts numeric notionals (int/float) and converts them to a concrete NotionalStructure (constant, linear, or variable) depending on the provided amortization scheme. If a NotionalStructure instance is provided it is validated / passed through.

Parameters:

  • notional (NotionalStructure | int | float) – notional or notional descriptor.

  • amortization_scheme (AmortizationScheme | None) – resolved amortization scheme that controls which notional structure is appropriate.

Returns:

instance representing the instrument notional.

Return type:

NotionalStructure

Raises:

ValueError – when inputs cannot be converted into a valid notional structure.

Credit Default Swaps

class rivapy.instruments.cds_specification.CDSSpecification(premium: float, premium_pay_dates: List[datetime], protection_start: datetime, notional: float = 1.0, expiry: datetime = None, recovery: float = None, issuer: str = '', cash_settled: bool = True)[source]

Bases: object

Constructor for credit default swap

Parameters:

  • premium (float) – The premium as fraction of notional paid at each premium date.

  • premium_pay_dates (List[datetime]) – List of dates for premium payments.

  • protection_start (datetime) – Date when protection starts

  • notional (foat) – Notional

  • expiry (datetime, optional) – [description]. Defaults to None.

  • recovery (float, optional) – The protection is only paid for the real loss (notional minus recovery). If recovery is not specified, it is assumed that recovery as specified in contract. If no fixed recovery is specified[description]. Defaults to None.

  • issuer (str, optional) – [description]. Defaults to ‘’.

  • cash_settled (bool, optional) – Flag indicating o instrument is physical settled (the protection buyer )

validate()[source]

Some simple validation

Deposits

class rivapy.instruments.deposit_specifications.DepositSpecification(obj_id: str, issue_date: date | datetime | None = None, maturity_date: date | datetime | None = None, currency: Currency | str = 'EUR', notional: NotionalStructure | float = 100.0, rate: float = 0.0, term: Period | str | None = None, day_count_convention: DayCounterType | str = 'ACT360', business_day_convention: RollConvention | str = 'ModifiedFollowing', roll_convention: RollRule | str = 'EOM', spot_days: int = 2, calendar: HolidayBase | str = {}, issuer: Issuer | str | None = None, securitization_level: SecuritizationLevel | str = 'NONE', payment_days: int = 0, adjust_start_date: bool = True, adjust_end_date: bool = False)[source]

Create a short-term deposit specification.

Accrual start is adjusted according to the provided business day convention. Payment occurs on the maturity date (plus any settlement/payment days). For overnight (“O/N”) and tomorrow-next (“T/N”) deposits the :pyarg:`spot_days` is set to 0 and 1, respectively.

Parameters:

  • obj_id (str) – Identifier for the deposit (e.g. ISIN or internal id).

  • issue_date (date | datetime, optional) – Fixing date and start date (of accrual period) of the deposit is calculated based on the provided issue date given :pyarg:`spot_days` and :pyarg:`adjust_start_date`. Required if :pyarg:`maturity_date` is computed from :pyarg:`term`.

  • maturity_date (date | datetime, optional) – Maturity date. If None and :pyarg:`term` is provided, the maturity will be derived from :pyarg:`issue_date` and :pyarg:`term`. Corresponds to end date (of accrual period). If non business day, always adjusted according to :pyarg:`business_day_convention` while end date adjustment is controlled by :pyarg:`adjust_end_date`.

  • currency (Currency | str, optional) – Currency code or enum. Defaults to “EUR”.

  • notional (NotionalStructure | float, optional) – Face value; maybe passed as float or notional structure, amount must be positive. Defaults to 100.0.

  • rate (float, optional) – Fixed deposit rate (coupon). Defaults to 0.0.

  • term (Period | str, optional) – Tenor of the deposit (e.g. “3M”, “1Y”, “O/N”, “T/N”).

  • day_count_convention (DayCounterType | str, optional) – Day count convention. Defaults to :pydata:`DayCounterType.ACT360`.

  • business_day_convention (RollConvention | str, optional) – Business day convention used for rolling dates. Defaults to :pydata:`RollConvention.MODIFIED_FOLLOWING`.

  • roll_convention (RollRule | str, optional) – Roll rule when building schedules. Defaults to :pydata:`RollRule.EOM`.

  • spot_days (int, optional) – Settlement lag in days. Defaults to 2; overridden to 0 for O/N and 1 for T/N when :pyarg:`term` is set accordingly.

  • calendar (HolidayBase | str, optional) – Holiday calendar to use. Defaults to ECB.

  • issuer (Issuer | str, optional) – Issuer identifier.

  • securitization_level (SecuritizationLevel | str, optional) – Securitization level. Defaults to :pydata:`SecuritizationLevel.NONE`.

  • payment_days (int, optional) – Days after maturity when payment occurs. Defaults to 0.

  • adjust_start_date (bool, optional) – If True, roll :pyarg:`issue_date` forward to a business day when required, to ensure accrual starts on a business day. The adjusted date will be used for calculations. Defaults to True.

  • adjust_end_date (bool, optional) – If True, roll :pyarg:`maturity_date` forward to a business day when required, to ensure accrual ends on a business day. The adjusted date will be used for calculations. Defaults to False.

Raises:

ValueError – If neither :pyarg:`maturity_date` nor :pyarg:`term` is provided, or if :pyarg:`issue_date` is required to compute :pyarg:`maturity_date` but is missing.

static _create_sample(n_samples: int, seed: int = None, ref_date=None, issuers: List[str] = None, sec_levels: List[str] = None, currencies: List[str] = None) → List[DepositSpecification][source]

Create a small list of example bond specifications for testing.

This helper generates a list of dictionaries that mimic the kwargs used to construct bond specifications. It is intended for internal testing and examples only.

Parameters:

  • n_samples (int) – Number of sample entries to generate.

  • seed (int, optional) – RNG seed for reproducible samples.

  • ref_date (date | datetime, optional) – Reference date for issue/maturity generation.

  • issuers (List[str], optional) – Optional pool of issuer names to sample from.

  • sec_levels (List[str], optional) – Optional securitization levels to sample from.

  • currencies (List[str], optional) – Optional currencies to sample from.

Returns:

List of parameter dictionaries usable to create bond specs.

Return type:

List[dict]

get_end_date()[source]
ins_type()[source]

Return instrument type

Returns:

Forward rate agreement

Return type:

Instrument