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