Rates

Treasury yield curve rates for risk-free rate estimation.

class mktlib.rates.MeanMethod(*values)[source]

Bases: StrEnum

Averaging method for rate aggregation.

ARITHMETIC = 'arithmetic'

GEOMETRIC = 'geometric'

class mktlib.rates.TreasuryRate(*values)[source]

Bases: StrEnum

Treasury yield curve instruments available from Treasury.gov.

ONE_MONTH = 'BC_1MONTH'

ONE_AND_HALF_MONTH = 'BC_1_5MONTH'

TWO_MONTH = 'BC_2MONTH'

THREE_MONTH = 'BC_3MONTH'

FOUR_MONTH = 'BC_4MONTH'

SIX_MONTH = 'BC_6MONTH'

ONE_YEAR = 'BC_1YEAR'

TWO_YEAR = 'BC_2YEAR'

THREE_YEAR = 'BC_3YEAR'

FIVE_YEAR = 'BC_5YEAR'

SEVEN_YEAR = 'BC_7YEAR'

TEN_YEAR = 'BC_10YEAR'

TWENTY_YEAR = 'BC_20YEAR'

THIRTY_YEAR = 'BC_30YEAR'

THIRTY_YEAR_DISPLAY = 'BC_30YEARDISPLAY'

mktlib.rates.get_mean_treasury_rate(start, end, instrument=TreasuryRate.THREE_MONTH, method=MeanMethod.ARITHMETIC)[source]

Fetch the mean annualised Treasury rate for a date range.

Parameters:

start (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
end (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
instrument (TreasuryRate) – Which Treasury yield to use.
method (MeanMethod) – Averaging method — arithmetic (default) or geometric.

Return type:

float

mktlib.rates.get_risk_free_rate(start, end, instrument=TreasuryRate.THREE_MONTH)[source]

Fetch the average annualised risk-free rate for a date range.

Returns the arithmetic mean of daily Treasury yields as a decimal (e.g., 0.0436 for 4.36%).

Parameters:

start (date | str) – Date range (inclusive). Accepts date objects or ISO strings ("2024-01-01").
end (date | str) – Date range (inclusive). Accepts date objects or ISO strings ("2024-01-01").
instrument (TreasuryRate) – Which Treasury yield to use. Defaults to the 3-month T-bill, the standard academic proxy for the risk-free rate.

Return type:

float

mktlib.rates.get_treasury_rates(start, end, instrument=None)[source]

Fetch daily Treasury rates as a Polars DataFrame.

Parameters:

start (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
end (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
instrument (TreasuryRate | Sequence[TreasuryRate] | None) – Single instrument → 2-column DataFrame (date, rate). Sequence or None (all) → wide DataFrame with one column per instrument, named by the enum member in lowercase (e.g. "three_month").

Return type:

DataFrame

mktlib.rates.get_treasury_spread(start, end, long=TreasuryRate.TEN_YEAR, short=TreasuryRate.TWO_YEAR)[source]

Fetch the daily spread between two Treasury instruments.

Returns a DataFrame with date and spread columns. Only includes days where both instruments have data.

Parameters:

start (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
end (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
long (TreasuryRate) – Longer-maturity instrument (default: 10-year).
short (TreasuryRate) – Shorter-maturity instrument (default: 2-year).

Return type:

DataFrame

mktlib.rates.get_treasury_spread_matrix(start, end, instruments=None, *, longs=None, shorts=None)[source]

Daily spreads for pairs of Treasury instruments (cross join).

Returns a wide DataFrame with date plus one Float64 column per tenor pair, named spread_{long}_{short} (e.g. spread_ten_year_two_year) and computed as long - short. Only pairs where the long leg has a strictly greater maturity than the short leg are emitted, so self-pairs (always zero) and inverted pairs are skipped. Nulls propagate per-column on days where either leg is missing; rows are not dropped (unlike the single-pair get_treasury_spread()).

Parameters:

start (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
end (date | str) – Date range (inclusive). Accepts date objects or ISO strings.
instruments (Sequence[TreasuryRate] | None) – The universe of tenors available to both legs. None (default) uses every tenor except TreasuryRate.THIRTY_YEAR_DISPLAY (a duplicate of THIRTY_YEAR).
longs (Sequence[TreasuryRate] | None) – Optionally restrict the long / short leg to a subset. None (default) means “any tenor in instruments”. Pass longs a set of long-maturity tenors and shorts a set of short-maturity tenors to compute only that block of the matrix. Ordering follows maturity, not argument order, so the long - short orientation is stable; a leg set with nothing longer than the other yields no columns (a date-only frame) rather than an error.
shorts (Sequence[TreasuryRate] | None) – Optionally restrict the long / short leg to a subset. None (default) means “any tenor in instruments”. Pass longs a set of long-maturity tenors and shorts a set of short-maturity tenors to compute only that block of the matrix. Ordering follows maturity, not argument order, so the long - short orientation is stable; a leg set with nothing longer than the other yields no columns (a date-only frame) rather than an error.

Return type:

DataFrame