Term Structure Models API

Term structure models for yield curve fitting.

nelson_siegel(maturities, rates, initial_params=None)

Fit the Nelson-Siegel model to yield curve data.

The Nelson-Siegel model is defined as: r(t) = β₀ + β₁ * (1 - exp(-t/τ))/(t/τ) + β₂ * ((1 - exp(-t/τ))/(t/τ) - exp(-t/τ))

Parameters:

Name	Type	Description	Default
maturities	list of float	Maturities in years for the observed rates	required
rates	list of float	Observed interest rates (as decimals)	required
initial_params	list of float	Initial parameters [β₀, β₁, β₂, τ], by default [0.03, -0.02, -0.01, 1.5]	None

Returns:

Type	Description
dict	Fitted parameters and model details

Examples:

>>> from pypulate.asset import nelson_siegel
>>> result = nelson_siegel(
...     maturities=[0.25, 0.5, 1, 2, 3, 5, 7, 10, 20, 30],
...     rates=[0.01, 0.015, 0.02, 0.025, 0.028, 0.03, 0.031, 0.032, 0.033, 0.034]
... )
>>> # Get the fitted parameters
>>> beta0, beta1, beta2, tau = result['parameters']
>>> print(f"Long-term rate (β₀): {beta0:.2%}")
Long-term rate (β₀): 3.40%
>>> # Predict rate at a specific maturity
>>> rate_4y = result['predict_func'](4)
>>> print(f"4-year rate: {rate_4y:.2%}")
4-year rate: 2.93%

svensson(maturities, rates, initial_params=None)

Fit the Svensson model to yield curve data.

The Svensson model is defined as: r(t) = β₀ + β₁ * (1 - exp(-t/τ₁))/(t/τ₁) + β₂ * ((1 - exp(-t/τ₁))/(t/τ₁) - exp(-t/τ₁)) + β₃ * ((1 - exp(-t/τ₂))/(t/τ₂) - exp(-t/τ₂))

Parameters:

Name	Type	Description	Default
maturities	list of float	Maturities in years for the observed rates	required
rates	list of float	Observed interest rates (as decimals)	required
initial_params	list of float	Initial parameters [β₀, β₁, β₂, β₃, τ₁, τ₂], by default [0.03, -0.02, -0.01, 0.01, 1.5, 10]	None

Returns:

Type	Description
dict	Fitted parameters and model details

Examples:

>>> from pypulate.asset import svensson
>>> result = svensson(
...     maturities=[0.25, 0.5, 1, 2, 3, 5, 7, 10, 20, 30],
...     rates=[0.01, 0.015, 0.02, 0.025, 0.028, 0.03, 0.031, 0.032, 0.033, 0.034]
... )
>>> # Get the fitted parameters
>>> beta0, beta1, beta2, beta3, tau1, tau2 = result['parameters']
>>> print(f"Long-term rate (β₀): {beta0:.2%}")
Long-term rate (β₀): 3.40%
>>> # Predict rate at a specific maturity
>>> rate_4y = result['predict_func'](4)
>>> print(f"4-year rate: {rate_4y:.2%}")
4-year rate: 2.93%