Finance Module

The finance module provides financial mathematics tools including interest theory, yield curves, and duration/convexity calculations.

Finance Module

Interest theory, yield curve construction, duration, and convexity measures.

This module provides tools for: - Interest rate calculations - Yield curve construction and analysis - Duration and convexity measures - Present value calculations - Bond pricing and analysis

class actuneo.finance.DurationConvexity(yield_curve: YieldCurve | None = None)

Bases: object

A class for calculating duration and convexity measures for bonds and fixed income portfolios.

__init__(yield_curve: YieldCurve | None = None)

Initialize DurationConvexity calculator.

Parameters:

yield_curve – YieldCurve instance for spot rate calculations

bond_convexity(face_value: float, coupon_rate: float, maturity: float, yield_rate: float, frequency: int = 2) → float

Calculate convexity for a standard bond.

Parameters:

• face_value – Face value of the bond

• coupon_rate – Annual coupon rate (decimal)

• maturity – Time to maturity in years

• yield_rate – Yield to maturity (decimal)

• frequency – Coupon payment frequency per year

Returns:

Convexity

bond_duration(face_value: float, coupon_rate: float, maturity: float, yield_rate: float, frequency: int = 2) → float

Calculate Macaulay duration for a standard bond.

Parameters:

• face_value – Face value of the bond

• coupon_rate – Annual coupon rate (decimal)

• maturity – Time to maturity in years

• yield_rate – Yield to maturity (decimal)

• frequency – Coupon payment frequency per year

Returns:

Macaulay duration

convexity(cash_flows: List[float], times: List[float], yield_rate: float) → float

Calculate convexity.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• yield_rate – Yield rate (decimal)

Returns:

Convexity measure

key_rate_duration(cash_flows: List[float], times: List[float], key_rates: List[float], yield_curve: YieldCurve) → dict

Calculate key rate durations.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• key_rates – List of key rate maturities

• yield_curve – YieldCurve instance

Returns:

Dictionary of key rate durations

macaulay_duration(cash_flows: List[float], times: List[float], yield_rate: float) → float

Calculate Macaulay duration.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• yield_rate – Yield rate (decimal)

Returns:

Macaulay duration

modified_duration(cash_flows: List[float], times: List[float], yield_rate: float) → float

Calculate modified duration.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• yield_rate – Yield rate (decimal)

Returns:

Modified duration

portfolio_duration(positions: List[dict], yield_rate: float | None = None) → float

Calculate portfolio duration.

Parameters:

• positions – List of position dictionaries with keys: ‘cash_flows’, ‘times’, ‘weight’ or ‘market_value’

• yield_rate – Common yield rate for all positions

Returns:

Portfolio duration (modified duration)

price_change_approximation(duration: float, convexity: float, yield_change: float, current_price: float) → float

Approximate price change using duration-convexity approximation.

Parameters:

• duration – Modified duration

• convexity – Convexity measure

• yield_change – Change in yield (decimal)

• current_price – Current bond price

Returns:

Approximate price change

class actuneo.finance.InterestTheory(interest_rate: float = 0.05, compounding_frequency: int = 1)

Bases: object

A class for performing various interest rate calculations and time value of money computations.

__init__(interest_rate: float = 0.05, compounding_frequency: int = 1)

Initialize InterestTheory with interest rate and compounding frequency.

Parameters:

• interest_rate – Annual interest rate (decimal)

• compounding_frequency – Compounding frequency per year (1=annual, 2=semi-annual, etc.)

annuity_future_value(payment: float, periods: int, interest_rate: float | None = None, immediate: bool = True) → float

Calculate future value of an annuity.

Parameters:

• payment – Periodic payment amount

• periods – Number of periods

• interest_rate – Override default interest rate

• immediate – True for immediate annuity, False for annuity-due

Returns:

Future value of annuity

annuity_present_value(payment: float, periods: int, interest_rate: float | None = None, immediate: bool = True) → float

Calculate present value of an annuity.

Parameters:

• payment – Periodic payment amount

• periods – Number of periods

• interest_rate – Override default interest rate

• immediate – True for immediate annuity, False for annuity-due

Returns:

Present value of annuity

effective_annual_rate(nominal_rate: float, compounding_freq: int) → float

Convert nominal rate to effective annual rate.

Parameters:

• nominal_rate – Nominal annual interest rate

• compounding_freq – Compounding frequency per year

Returns:

Effective annual rate

future_value(present_value: float, periods: int | float, interest_rate: float | None = None) → float

Calculate future value of a present amount.

Parameters:

• present_value – Present value amount

• periods – Number of periods

• interest_rate – Override default interest rate

Returns:

Future value

inflation_adjusted_value(nominal_value: float, inflation_rate: float, periods: int | float) → float

Calculate inflation-adjusted (real) value.

Parameters:

• nominal_value – Nominal value

• inflation_rate – Annual inflation rate

• periods – Number of periods

Returns:

Real value adjusted for inflation

loan_balance(principal: float, periods: int, payments_made: int, interest_rate: float | None = None) → float

Calculate remaining loan balance after certain number of payments.

Parameters:

• principal – Original loan principal

• periods – Total number of periods

• payments_made – Number of payments already made

• interest_rate – Override default interest rate

Returns:

Remaining balance

loan_payment(principal: float, periods: int, interest_rate: float | None = None) → float

Calculate periodic loan payment amount.

Parameters:

• principal – Loan principal amount

• periods – Number of periods

• interest_rate – Override default interest rate

Returns:

Periodic payment amount

nominal_rate(effective_rate: float, compounding_freq: int) → float

Convert effective annual rate to nominal rate.

Parameters:

• effective_rate – Effective annual interest rate

• compounding_freq – Compounding frequency per year

Returns:

Nominal annual rate

present_value(future_value: float, periods: int | float, interest_rate: float | None = None) → float

Calculate present value of a future amount.

Parameters:

• future_value – Future value amount

• periods – Number of periods

• interest_rate – Override default interest rate

Returns:

Present value

real_interest_rate(nominal_rate: float, inflation_rate: float) → float

Calculate real interest rate using Fisher equation.

Parameters:

• nominal_rate – Nominal interest rate

• inflation_rate – Inflation rate

Returns:

Real interest rate

class actuneo.finance.YieldCurve(maturities: List[float] | ndarray, yields: List[float] | ndarray, interpolation_method: str = 'linear')

Bases: object

A class for constructing and analyzing yield curves.

Supports various interpolation methods and provides tools for spot rates, forward rates, and yield curve analysis.

__init__(maturities: List[float] | ndarray, yields: List[float] | ndarray, interpolation_method: str = 'linear')

Initialize YieldCurve with maturity and yield data.

Parameters:

• maturities – Time to maturity (in years)

• yields – Yield rates (decimal)

• interpolation_method – Method for interpolation (‘linear’, ‘cubic’, ‘nelson_siegel’)

bootstrap_spot_rates() → Dict[float, float]

Bootstrap spot rates from coupon bond prices. This is a simplified version assuming the yields are already spot rates.

Returns:

Dictionary of maturity -> spot rate

classmethod from_par_rates(maturities: List[float], par_rates: List[float], coupon_freq: int = 2) → YieldCurve

Create YieldCurve from par bond yields.

Parameters:

• maturities – Time to maturity

• par_rates – Par bond yields

• coupon_freq – Coupon payment frequency per year

Returns:

YieldCurve instance

classmethod from_zero_rates(maturities: List[float], zero_rates: List[float]) → YieldCurve

Create YieldCurve from zero rates.

Parameters:

• maturities – Time to maturity

• zero_rates – Zero coupon rates

Returns:

YieldCurve instance

get_discount_factor(maturity: float) → float

Calculate discount factor for a given maturity.

Parameters:

maturity – Time to maturity in years

Returns:

Discount factor

get_forward_rate(start_time: float, end_time: float) → float

Calculate forward rate between two time periods.

Parameters:

• start_time – Start time in years

• end_time – End time in years

Returns:

Forward rate from start_time to end_time

get_spot_rate(maturity: float) → float

Get spot rate for a specific maturity. For simplicity, assumes spot rate equals yield for same maturity.

Parameters:

maturity – Time to maturity in years

Returns:

Spot rate

get_yield(maturity: float) → float

Get yield for a specific maturity using interpolation.

Parameters:

maturity – Time to maturity in years

Returns:

Interpolated yield rate

plot_yield_curve(show_forward_rates: bool = False, **kwargs)

Plot the yield curve.

Parameters:

• show_forward_rates – Whether to show forward rate curve

• **kwargs – Additional arguments for plotting

InterestTheory

class actuneo.finance.InterestTheory(interest_rate: float = 0.05, compounding_frequency: int = 1)

Bases: object

A class for performing various interest rate calculations and time value of money computations.

__init__(interest_rate: float = 0.05, compounding_frequency: int = 1)

Initialize InterestTheory with interest rate and compounding frequency.

Parameters:

• interest_rate – Annual interest rate (decimal)

• compounding_frequency – Compounding frequency per year (1=annual, 2=semi-annual, etc.)

annuity_future_value(payment: float, periods: int, interest_rate: float | None = None, immediate: bool = True) → float

Calculate future value of an annuity.

Parameters:

• payment – Periodic payment amount

• periods – Number of periods

• interest_rate – Override default interest rate

• immediate – True for immediate annuity, False for annuity-due

Returns:

Future value of annuity

annuity_present_value(payment: float, periods: int, interest_rate: float | None = None, immediate: bool = True) → float

Calculate present value of an annuity.

Parameters:

• payment – Periodic payment amount

• periods – Number of periods

• interest_rate – Override default interest rate

• immediate – True for immediate annuity, False for annuity-due

Returns:

Present value of annuity

effective_annual_rate(nominal_rate: float, compounding_freq: int) → float

Convert nominal rate to effective annual rate.

Parameters:

• nominal_rate – Nominal annual interest rate

• compounding_freq – Compounding frequency per year

Returns:

Effective annual rate

future_value(present_value: float, periods: int | float, interest_rate: float | None = None) → float

Calculate future value of a present amount.

Parameters:

• present_value – Present value amount

• periods – Number of periods

• interest_rate – Override default interest rate

Returns:

Future value

inflation_adjusted_value(nominal_value: float, inflation_rate: float, periods: int | float) → float

Calculate inflation-adjusted (real) value.

Parameters:

• nominal_value – Nominal value

• inflation_rate – Annual inflation rate

• periods – Number of periods

Returns:

Real value adjusted for inflation

loan_balance(principal: float, periods: int, payments_made: int, interest_rate: float | None = None) → float

Calculate remaining loan balance after certain number of payments.

Parameters:

• principal – Original loan principal

• periods – Total number of periods

• payments_made – Number of payments already made

• interest_rate – Override default interest rate

Returns:

Remaining balance

loan_payment(principal: float, periods: int, interest_rate: float | None = None) → float

Calculate periodic loan payment amount.

Parameters:

• principal – Loan principal amount

• periods – Number of periods

• interest_rate – Override default interest rate

Returns:

Periodic payment amount

nominal_rate(effective_rate: float, compounding_freq: int) → float

Convert effective annual rate to nominal rate.

Parameters:

• effective_rate – Effective annual interest rate

• compounding_freq – Compounding frequency per year

Returns:

Nominal annual rate

present_value(future_value: float, periods: int | float, interest_rate: float | None = None) → float

Calculate present value of a future amount.

Parameters:

• future_value – Future value amount

• periods – Number of periods

• interest_rate – Override default interest rate

Returns:

Present value

real_interest_rate(nominal_rate: float, inflation_rate: float) → float

Calculate real interest rate using Fisher equation.

Parameters:

• nominal_rate – Nominal interest rate

• inflation_rate – Inflation rate

Returns:

Real interest rate

YieldCurve

class actuneo.finance.YieldCurve(maturities: List[float] | ndarray, yields: List[float] | ndarray, interpolation_method: str = 'linear')

Bases: object

A class for constructing and analyzing yield curves.

Supports various interpolation methods and provides tools for spot rates, forward rates, and yield curve analysis.

__init__(maturities: List[float] | ndarray, yields: List[float] | ndarray, interpolation_method: str = 'linear')

Initialize YieldCurve with maturity and yield data.

Parameters:

• maturities – Time to maturity (in years)

• yields – Yield rates (decimal)

• interpolation_method – Method for interpolation (‘linear’, ‘cubic’, ‘nelson_siegel’)

bootstrap_spot_rates() → Dict[float, float]

Bootstrap spot rates from coupon bond prices. This is a simplified version assuming the yields are already spot rates.

Returns:

Dictionary of maturity -> spot rate

classmethod from_par_rates(maturities: List[float], par_rates: List[float], coupon_freq: int = 2) → YieldCurve

Create YieldCurve from par bond yields.

Parameters:

• maturities – Time to maturity

• par_rates – Par bond yields

• coupon_freq – Coupon payment frequency per year

Returns:

YieldCurve instance

classmethod from_zero_rates(maturities: List[float], zero_rates: List[float]) → YieldCurve

Create YieldCurve from zero rates.

Parameters:

• maturities – Time to maturity

• zero_rates – Zero coupon rates

Returns:

YieldCurve instance

get_discount_factor(maturity: float) → float

Calculate discount factor for a given maturity.

Parameters:

maturity – Time to maturity in years

Returns:

Discount factor

get_forward_rate(start_time: float, end_time: float) → float

Calculate forward rate between two time periods.

Parameters:

• start_time – Start time in years

• end_time – End time in years

Returns:

Forward rate from start_time to end_time

get_spot_rate(maturity: float) → float

Get spot rate for a specific maturity. For simplicity, assumes spot rate equals yield for same maturity.

Parameters:

maturity – Time to maturity in years

Returns:

Spot rate

get_yield(maturity: float) → float

Get yield for a specific maturity using interpolation.

Parameters:

maturity – Time to maturity in years

Returns:

Interpolated yield rate

plot_yield_curve(show_forward_rates: bool = False, **kwargs)

Plot the yield curve.

Parameters:

• show_forward_rates – Whether to show forward rate curve

• **kwargs – Additional arguments for plotting

DurationConvexity

class actuneo.finance.DurationConvexity(yield_curve: YieldCurve | None = None)

Bases: object

A class for calculating duration and convexity measures for bonds and fixed income portfolios.

__init__(yield_curve: YieldCurve | None = None)

Initialize DurationConvexity calculator.

Parameters:

yield_curve – YieldCurve instance for spot rate calculations

bond_convexity(face_value: float, coupon_rate: float, maturity: float, yield_rate: float, frequency: int = 2) → float

Calculate convexity for a standard bond.

Parameters:

• face_value – Face value of the bond

• coupon_rate – Annual coupon rate (decimal)

• maturity – Time to maturity in years

• yield_rate – Yield to maturity (decimal)

• frequency – Coupon payment frequency per year

Returns:

Convexity

bond_duration(face_value: float, coupon_rate: float, maturity: float, yield_rate: float, frequency: int = 2) → float

Calculate Macaulay duration for a standard bond.

Parameters:

• face_value – Face value of the bond

• coupon_rate – Annual coupon rate (decimal)

• maturity – Time to maturity in years

• yield_rate – Yield to maturity (decimal)

• frequency – Coupon payment frequency per year

Returns:

Macaulay duration

convexity(cash_flows: List[float], times: List[float], yield_rate: float) → float

Calculate convexity.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• yield_rate – Yield rate (decimal)

Returns:

Convexity measure

key_rate_duration(cash_flows: List[float], times: List[float], key_rates: List[float], yield_curve: YieldCurve) → dict

Calculate key rate durations.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• key_rates – List of key rate maturities

• yield_curve – YieldCurve instance

Returns:

Dictionary of key rate durations

macaulay_duration(cash_flows: List[float], times: List[float], yield_rate: float) → float

Calculate Macaulay duration.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• yield_rate – Yield rate (decimal)

Returns:

Macaulay duration

modified_duration(cash_flows: List[float], times: List[float], yield_rate: float) → float

Calculate modified duration.

Parameters:

• cash_flows – List of cash flow amounts

• times – List of times when cash flows occur

• yield_rate – Yield rate (decimal)

Returns:

Modified duration

portfolio_duration(positions: List[dict], yield_rate: float | None = None) → float

Calculate portfolio duration.

Parameters:

• positions – List of position dictionaries with keys: ‘cash_flows’, ‘times’, ‘weight’ or ‘market_value’

• yield_rate – Common yield rate for all positions

Returns:

Portfolio duration (modified duration)

price_change_approximation(duration: float, convexity: float, yield_change: float, current_price: float) → float

Approximate price change using duration-convexity approximation.

Parameters:

• duration – Modified duration

• convexity – Convexity measure

• yield_change – Change in yield (decimal)

• current_price – Current bond price

Returns:

Approximate price change