finm.fixedincome.bonds

finm.fixedincome.bonds#

Bond pricing and risk calculations for fixed income securities.

This module provides basic functions for:

  • Present and future value calculations

  • Bond pricing

  • Yield to maturity calculations

  • Duration and convexity measures

  • Calculate semiannual coupon payment dates for a bond

Module Contents#

Functions#

convexity

Calculate the convexity of a bond.

duration

Calculate the Macaulay duration of a bond.

future_value

Calculate the future value of a present cash flow.

get_coupon_dates

Calculate semiannual coupon payment dates for a bond.

modified_duration

Calculate the modified duration of a bond.

present_value

Calculate the present value of a future cash flow.

yield_to_maturity

Calculate the yield to maturity of a bond using Newton-Raphson method.

API#

finm.fixedincome.bonds.convexity(face_value: float, coupon_rate: float, ytm: float, periods: int, frequency: int = 2) → float[source]#

Calculate the convexity of a bond.

Convexity measures the curvature of the bond price-yield relationship and is used to improve duration-based price change estimates.

Parameters:

  • face_value – The face (par) value of the bond.

  • coupon_rate – The annual coupon rate (as a decimal, e.g., 0.05 for 5%).

  • ytm – The yield to maturity (as a decimal, e.g., 0.05 for 5%).

  • periods – The number of coupon periods remaining until maturity.

  • frequency – The number of coupon payments per year. Defaults to 2.

Returns:

The convexity of the bond.

Example: python     >>> conv = convexity(1000, 0.06, 0.05, 10, frequency=2)     >>> round(conv, 2)     21.74    

finm.fixedincome.bonds.duration(face_value: float, coupon_rate: float, ytm: float, periods: int, frequency: int = 2) → float[source]#

Calculate the Macaulay duration of a bond.

Parameters:

  • face_value – The face (par) value of the bond.

  • coupon_rate – The annual coupon rate (as a decimal, e.g., 0.05 for 5%).

  • ytm – The yield to maturity (as a decimal, e.g., 0.05 for 5%).

  • periods – The number of coupon periods remaining until maturity.

  • frequency – The number of coupon payments per year. Defaults to 2.

Returns:

The Macaulay duration in years.

Example: python     >>> dur = duration(1000, 0.06, 0.05, 10, frequency=2)     >>> round(dur, 4)     4.3295    

finm.fixedincome.bonds.future_value(present_value: float, rate: float, periods: float, compounding: str = 'discrete') → float[source]#

Calculate the future value of a present cash flow.

Parameters:

  • present_value – The present cash flow amount.

  • rate – The interest rate (as a decimal, e.g., 0.05 for 5%).

  • periods – The number of periods for compounding.

  • compounding – The compounding method: ‘discrete’ or ‘continuous’. Defaults to ‘discrete’.

Returns:

The future value of the present cash flow.

Example: python     >>> future_value(1000, 0.05, 2)     1102.5     >>> future_value(1000, 0.05, 2, compounding='continuous')     1105.1709180756477    

finm.fixedincome.bonds.get_coupon_dates(quote_date, maturity_date)[source]#

Calculate semiannual coupon payment dates for a bond.

Parameters:

  • quote_date – The quote date of the bond (str or datetime).

  • maturity_date – The maturity date of the bond (str or datetime).

Returns:

List of semiannual coupon payment dates after the quote date.

Raises:

ValueError – If quote date is not earlier than maturity date.

finm.fixedincome.bonds.modified_duration(face_value: float, coupon_rate: float, ytm: float, periods: int, frequency: int = 2) → float[source]#

Calculate the modified duration of a bond.

Modified duration measures the percentage change in bond price for a 1% change in yield.

Parameters:

  • face_value – The face (par) value of the bond.

  • coupon_rate – The annual coupon rate (as a decimal, e.g., 0.05 for 5%).

  • ytm – The yield to maturity (as a decimal, e.g., 0.05 for 5%).

  • periods – The number of coupon periods remaining until maturity.

  • frequency – The number of coupon payments per year. Defaults to 2.

Returns:

The modified duration.

Example: python     >>> mod_dur = modified_duration(1000, 0.06, 0.05, 10, frequency=2)     >>> round(mod_dur, 4)     4.2239    

finm.fixedincome.bonds.present_value(future_value: float, rate: float, periods: float, compounding: str = 'discrete') → float[source]#

Calculate the present value of a future cash flow.

Parameters:

  • future_value – The future cash flow amount.

  • rate – The discount rate (as a decimal, e.g., 0.05 for 5%).

  • periods – The number of periods until the cash flow is received.

  • compounding – The compounding method: ‘discrete’ or ‘continuous’. Defaults to ‘discrete’.

Returns:

The present value of the future cash flow.

Example: python     >>> present_value(1000, 0.05, 2)     907.0294784580498     >>> present_value(1000, 0.05, 2, compounding='continuous')     904.8374180359595    

finm.fixedincome.bonds.yield_to_maturity(price: float, face_value: float, coupon_rate: float, periods: int, frequency: int = 2, tolerance: float = 1e-08, max_iterations: int = 100) → float[source]#

Calculate the yield to maturity of a bond using Newton-Raphson method.

Parameters:

  • price – The current market price of the bond.

  • face_value – The face (par) value of the bond.

  • coupon_rate – The annual coupon rate (as a decimal, e.g., 0.05 for 5%).

  • periods – The number of coupon periods remaining until maturity.

  • frequency – The number of coupon payments per year. Defaults to 2.

  • tolerance – The convergence tolerance. Defaults to 1e-8.

  • max_iterations – Maximum number of iterations. Defaults to 100.

Returns:

The annualized yield to maturity.

Raises:

ValueError – If YTM calculation does not converge.

Example: python     >>> ytm = yield_to_maturity(1038.90, 1000, 0.06, 10, frequency=2)     >>> round(ytm, 4)     0.05    

Contents