short-rate-models

A Python package for short-rate and affine term-structure models. The current library keeps the teaching-friendly Merton and Vasicek APIs from the first four blog posts, while adding a state-space-capable affine core for later series work.

Companion library to the blog at steveya.github.io.

Installation

pip install git+https://github.com/steveya/short-rate-models.git

Requires Python >= 3.10 and NumPy.

What Changed

The package now has three layers:

• a backward-compatible model surface for MertonModel and VasicekModel
• an affine/state-space base layer with bond_price, yield_curve, observation_system, and exact transition systems
• minimal infrastructure for simulation and linear-Gaussian filtering

This is the bridge from the early scalar short-rate posts to the later affine and macro-finance series.

Quick Start

Merton Model

from short_rate_models import MertonModel

model = MertonModel(mu=0.02, sigma=0.02, lam=0.5, r0=0.03)

print(model.drift(measure="P"))   # 0.02
print(model.drift(measure="Q"))   # 0.01
print(model.bond_price(t=0.0, T=5.0, r=0.03))

Vasicek Model

from short_rate_models import VasicekModel

model = VasicekModel(kappa=0.15, theta=0.05, sigma=0.01, r0=0.03, lam=0.25)

times, rates = model.simulate(t=5.0, dt=1 / 252, seed=42)
curve = model.yield_curve(t=0.0, maturities=[1.0, 2.0, 5.0, 10.0], state=[0.03])

State-Space Utilities

import numpy as np

from short_rate_models import LinearGaussianKalmanFilter, VasicekModel

model = VasicekModel(kappa=0.25, theta=0.04, sigma=0.01, r0=0.03)
transition_matrix, transition_offset, transition_covariance = model.transition_system(
    dt=1 / 12,
    measure="P",
)

kalman = LinearGaussianKalmanFilter(
    transition_matrix=transition_matrix,
    transition_offset=transition_offset,
    transition_covariance=transition_covariance,
)

intercepts, loadings = model.observation_system(maturities=[1.0, 2.0, 5.0])
results = kalman.filter(
    observations=np.array([[0.03, 0.032, 0.035]]),
    observation_matrix=loadings,
    observation_offset=intercepts,
    observation_covariance=np.eye(3) * 1e-4,
    initial_mean=np.array([0.03]),
    initial_covariance=np.array([[0.05]]),
)

Alphaforge Integration

from short_rate_models import (
    KimOrphanidesSurveyModel,
    from_alphaforge_survey_panel,
    from_alphaforge_yield_panel,
)

prepared_yields = from_alphaforge_yield_panel(dataset.yields)
prepared_surveys = from_alphaforge_survey_panel(dataset.surveys)

model, results = KimOrphanidesSurveyModel.fit(
    yields=prepared_yields.frame,
    surveys=prepared_surveys.frame,
)

Core Interfaces

Base Layers

• BaseModel: latent-state interface with state_dimension, initial_state, transition_system, transition, and measure-aware drift and diffusion
• BaseAffineModel: affine pricing helpers with affine_coefficients, bond_price, yield_curve, observation_system, and observation

Exports

• MertonModel
• VasicekModel
• GaussianDiscreteTermStructureModel
• SurveyForecastTermStructureModel
• KimOrphanidesSurveyModel
• KimWrightTermPremiumModel
• PolicyRuleTermStructureModel
• LocalMomentumTermStructureModel
• MacroFinanceTermStructureModel
• LinearGaussianKalmanFilter
• from_alphaforge_yield_panel
• from_alphaforge_macro_panel
• from_alphaforge_survey_panel
• simulate_path
• nelson_siegel_loadings

Backward Compatibility

The canonical import paths are now:

from short_rate_models.models.merton import MertonModel
from short_rate_models.models.vasicek import VasicekModel

The historical short_rate_models.model.* imports still work through a compatibility alias.

Existing bond_price(t, T, r=...) and bond_yield(t, T, r=...) calls remain supported. The newer state-space methods accept state=[...] and explicit measure="P" or measure="Q" arguments.

The research-model classes also expose reduced fit(...) class methods for notebook-driven empirical work:

• KimOrphanidesSurveyModel.fit(...)
• PolicyRuleTermStructureModel.fit(...)
• LocalMomentumTermStructureModel.fit(...)
• MacroFinanceTermStructureModel.fit(...)

Package Direction

The repository name remains short-rate-models for now. Internally, the package is already structured for the next steps in the series:

• affine term-structure bridge models
• yield-curve observation equations
• Kalman-filter-based estimation scaffolds
• survey-augmented long-run-expectations models
• policy-rule term-structure models
• local-momentum and mean-reversion extensions
• reduced macro-finance term-structure models

License

MIT