Skip to content

riskfreerates

athena.riskfreerates

RiskFreeRateSeries

Bases: Enum

FRED series identifiers for risk-free rates.

Source code in src/athena/riskfreerates.py 
12
13
14
15
16
17
18
19
20
class RiskFreeRateSeries(Enum):
    """FRED series identifiers for risk-free rates."""
    DTB3 = "DTB3"      # 3-Month Treasury Bill Secondary Market Rate
    DTB6 = "DTB6"      # 6-Month Treasury Bill Secondary Market Rate
    DTB1YR = "DTB1YR"  # 1-Year Treasury Bill Secondary Market Rate
    DGS1 = "DGS1"      # 1-Year Treasury Constant Maturity Rate
    DGS2 = "DGS2"      # 2-Year Treasury Constant Maturity Rate
    DGS5 = "DGS5"      # 5-Year Treasury Constant Maturity Rate
    DGS10 = "DGS10"    # 10-Year Treasury Constant Maturity Rate

RiskFreeRateManager

Bases: ABC

Abstract base class for risk-free rate data providers.

Source code in src/athena/riskfreerates.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
class RiskFreeRateManager(ABC):
    """Abstract base class for risk-free rate data providers."""

    def __init__(
        self,
        min_date: date | None = None,
        max_date: date | None = None
    ):
        self.min_date = min_date
        self.max_date = max_date

    @abstractmethod
    def get_rate(self, rate_date: date) -> Decimal:
        """
        Get the annualized risk-free rate for a specific date.

        Args:
            rate_date: The date to get the rate for.

        Returns:
            The annualized rate as a decimal (e.g., Decimal("0.045") for 4.5%).

        Raises:
            ValueError: If no rate is available for the date.
        """
        raise NotImplementedError("This method should be overridden by subclasses.")

    @abstractmethod
    def get_daily_rate(self, rate_date: date, trading_days_per_year: int = 252) -> Decimal:
        """
        Get the daily risk-free rate for a specific date.

        Args:
            rate_date: The date to get the rate for.
            trading_days_per_year: Number of trading days per year (default 252).

        Returns:
            The daily rate as a decimal.

        Raises:
            ValueError: If no rate is available for the date.
        """
        raise NotImplementedError("This method should be overridden by subclasses.")

    @abstractmethod
    def get_rates_for_range(
        self,
        start_date: date,
        end_date: date
    ) -> dict[date, Decimal]:
        """
        Get all available annualized rates for a date range.

        Args:
            start_date: Start of the date range (inclusive).
            end_date: End of the date range (inclusive).

        Returns:
            Dictionary mapping dates to annualized rates.
            Only includes dates where data is available (trading days).
        """
        raise NotImplementedError("This method should be overridden by subclasses.")

    def get_trading_days_per_year(self) -> int:
        """Return the typical number of trading days per year for US markets."""
        return 252

get_rate(rate_date) abstractmethod

Get the annualized risk-free rate for a specific date.

Parameters:

Name Type Description Default
rate_date date

The date to get the rate for.

 required

Returns:

Type Description
Decimal

The annualized rate as a decimal (e.g., Decimal("0.045") for 4.5%).

Raises:

Type Description
ValueError

If no rate is available for the date.
Source code in src/athena/riskfreerates.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
@abstractmethod
def get_rate(self, rate_date: date) -> Decimal:
    """
    Get the annualized risk-free rate for a specific date.

    Args:
        rate_date: The date to get the rate for.

    Returns:
        The annualized rate as a decimal (e.g., Decimal("0.045") for 4.5%).

    Raises:
        ValueError: If no rate is available for the date.
    """
    raise NotImplementedError("This method should be overridden by subclasses.")

get_daily_rate(rate_date, trading_days_per_year=252) abstractmethod

Get the daily risk-free rate for a specific date.

Parameters:

Name Type Description Default
rate_date date

The date to get the rate for.

 required
trading_days_per_year int

Number of trading days per year (default 252).

 252

Returns:

Type Description
Decimal

The daily rate as a decimal.

Raises:

Type Description
ValueError

If no rate is available for the date.
Source code in src/athena/riskfreerates.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
@abstractmethod
def get_daily_rate(self, rate_date: date, trading_days_per_year: int = 252) -> Decimal:
    """
    Get the daily risk-free rate for a specific date.

    Args:
        rate_date: The date to get the rate for.
        trading_days_per_year: Number of trading days per year (default 252).

    Returns:
        The daily rate as a decimal.

    Raises:
        ValueError: If no rate is available for the date.
    """
    raise NotImplementedError("This method should be overridden by subclasses.")

get_rates_for_range(start_date, end_date) abstractmethod

Get all available annualized rates for a date range.

Parameters:

Name Type Description Default
start_date date

Start of the date range (inclusive).

 required
end_date date

End of the date range (inclusive).

 required

Returns:

Type Description
dict[date, Decimal]

Dictionary mapping dates to annualized rates.
dict[date, Decimal]

Only includes dates where data is available (trading days).
Source code in src/athena/riskfreerates.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@abstractmethod
def get_rates_for_range(
    self,
    start_date: date,
    end_date: date
) -> dict[date, Decimal]:
    """
    Get all available annualized rates for a date range.

    Args:
        start_date: Start of the date range (inclusive).
        end_date: End of the date range (inclusive).

    Returns:
        Dictionary mapping dates to annualized rates.
        Only includes dates where data is available (trading days).
    """
    raise NotImplementedError("This method should be overridden by subclasses.")

get_trading_days_per_year()

Return the typical number of trading days per year for US markets.

Source code in src/athena/riskfreerates.py 
86
87
88
def get_trading_days_per_year(self) -> int:
    """Return the typical number of trading days per year for US markets."""
    return 252

FixedRiskFreeRateManager

Bases: RiskFreeRateManager

Returns a fixed risk-free rate for all dates.

Source code in src/athena/riskfreerates.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
class FixedRiskFreeRateManager(RiskFreeRateManager):
    """Returns a fixed risk-free rate for all dates."""

    def __init__(self, annual_rate: Decimal = Decimal("0.05")):
        """
        Initialize with a fixed annual rate.

        Args:
            annual_rate: The fixed annual rate as a decimal (e.g., 0.05 for 5%).
        """
        super().__init__()
        self.annual_rate = annual_rate

    def get_rate(self, rate_date: date) -> Decimal:
        return self.annual_rate

    def get_daily_rate(self, rate_date: date, trading_days_per_year: int = 252) -> Decimal:
        return self.annual_rate / trading_days_per_year

    def get_rates_for_range(
        self,
        start_date: date,
        end_date: date
    ) -> dict[date, Decimal]:
        result: dict[date, Decimal] = {}
        current = start_date
        while current <= end_date:
            result[current] = self.annual_rate
            current += timedelta(days=1)
        return result

__init__(annual_rate=Decimal('0.05'))

Initialize with a fixed annual rate.

Parameters:

Name Type Description Default
annual_rate Decimal

The fixed annual rate as a decimal (e.g., 0.05 for 5%).

 Decimal('0.05')
Source code in src/athena/riskfreerates.py 
 94
 95
 96
 97
 98
 99
100
101
102
def __init__(self, annual_rate: Decimal = Decimal("0.05")):
    """
    Initialize with a fixed annual rate.

    Args:
        annual_rate: The fixed annual rate as a decimal (e.g., 0.05 for 5%).
    """
    super().__init__()
    self.annual_rate = annual_rate

FREDRiskFreeRateManager

Bases: RiskFreeRateManager

Risk-free rate manager using FRED (Federal Reserve Economic Data).

Fetches Treasury Bill rates directly from FRED's CSV endpoint. Data is cached locally to avoid repeated downloads.

Source code in src/athena/riskfreerates.py 
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
class FREDRiskFreeRateManager(RiskFreeRateManager):
    """
    Risk-free rate manager using FRED (Federal Reserve Economic Data).

    Fetches Treasury Bill rates directly from FRED's CSV endpoint.
    Data is cached locally to avoid repeated downloads.
    """

    def __init__(
        self,
        series: RiskFreeRateSeries = RiskFreeRateSeries.DTB3,
        min_date: date | None = None,
        max_date: date | None = None,
        use_cache: bool = True
    ):
        """
        Initialize the FRED risk-free rate manager.

        Args:
            series: The FRED series to use (default: DTB3 - 3-Month T-Bill).
            min_date: Earliest date to fetch data for (default: 5 years ago).
            max_date: Latest date to fetch data for (default: today).
            use_cache: Whether to use local caching (default: True).
        """
        if min_date is None:
            min_date = date.today() - timedelta(days=5 * 365)
        if max_date is None:
            max_date = date.today()

        super().__init__(min_date, max_date)

        self.series = series
        self.use_cache = use_cache

        # Dictionary to store rates: {date: Decimal}
        # Rates are stored as decimals (e.g., 0.045 for 4.5%)
        self.rates: dict[date, Decimal] = {}

        # Build the FRED CSV URL
        url = self._build_url(min_date, max_date)

        # Generate cache file path
        cache_key = hashlib.md5(
            f"{series.value}_{min_date}_{max_date}".encode()
        ).hexdigest()[:12]
        self._cache_path = (
            Path.cwd() / ".cache" / "fred_risk_free_rates" / f"{series.value}_{cache_key}.csv"
        )

        self._fetch_and_parse_data(url)

    def _build_url(self, start_date: date, end_date: date) -> str:
        """Build the FRED CSV download URL."""
        # Format dates as YYYY-MM-DD
        cosd = start_date.strftime("%Y-%m-%d")
        coed = end_date.strftime("%Y-%m-%d")
        today = date.today().strftime("%Y-%m-%d")

        # Simplified FRED URL - only the essential parameters
        url = (
            f"https://fred.stlouisfed.org/graph/fredgraph.csv?"
            f"id={self.series.value}&"
            f"cosd={cosd}&"
            f"coed={coed}&"
            f"fq=Daily&"
            f"fam=avg&"
            f"vintage_date={today}&"
            f"revision_date={today}"
        )
        return url

    def _is_cache_valid(self) -> bool:
        """Check if cache file exists and was modified today."""
        if not self._cache_path.exists():
            return False
        mtime = datetime.fromtimestamp(self._cache_path.stat().st_mtime)
        return mtime.date() == date.today()

    def _fetch_and_parse_data(self, url: str) -> None:
        """Fetch CSV data from FRED and parse it into rates."""
        data: str

        if self.use_cache and self._is_cache_valid():
            data = self._cache_path.read_text(encoding='utf-8')
        else:
            headers = {
                'User-Agent': (
                    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) '
                    'AppleWebKit/537.36 (KHTML, like Gecko) '
                    'Chrome/120.0.0.0 Safari/537.36'
                ),
                'Accept': 'text/csv,text/plain,*/*',
                'Accept-Language': 'en-US,en;q=0.5',
            }
            req = urllib.request.Request(url, headers=headers)
            with urllib.request.urlopen(req) as response:
                data = response.read().decode('utf-8')

            if self.use_cache:
                self._cache_path.parent.mkdir(parents=True, exist_ok=True)
                self._cache_path.write_text(data, encoding='utf-8')

        # Parse CSV
        # FRED CSV format:
        # DATE,DTB3
        # 2021-01-15,0.09
        # 2021-01-19,0.08
        # ...
        # Note: Missing data is marked as "."
        reader = csv.reader(io.StringIO(data))
        rows = list(reader)

        if len(rows) < 2:
            return

        # First row is header, data starts at row 1
        for row in rows[1:]:
            if len(row) < 2:
                continue

            date_str = row[0].strip()
            value_str = row[1].strip()

            # Skip missing data (FRED uses "." for missing values)
            if value_str == "." or not value_str:
                continue

            try:
                # Parse date (YYYY-MM-DD format)
                rate_date = datetime.strptime(date_str, "%Y-%m-%d").date()

                # FRED returns rates as percentage points (e.g., 4.5 means 4.5%)
                # Convert to decimal (e.g., 0.045)
                rate_pct = Decimal(value_str)
                rate_decimal = rate_pct / 100

                self.rates[rate_date] = rate_decimal

            except (ValueError, ArithmeticError):
                continue

    def _get_rate_with_lookback(self, rate_date: date, max_lookback_days: int = 14) -> Decimal | None:
        """
        Get rate for a date, looking back if not available.

        Args:
            rate_date: The target date.
            max_lookback_days: Maximum days to look back for data.

        Returns:
            The rate if found, None otherwise.
        """
        for days_back in range(max_lookback_days + 1):
            lookup_date = rate_date - timedelta(days=days_back)
            if lookup_date in self.rates:
                return self.rates[lookup_date]
        return None

    def get_rate(self, rate_date: date) -> Decimal:
        """
        Get the annualized risk-free rate for a specific date.

        If no data is available for the exact date (weekend, holiday),
        looks back up to 14 days to find the most recent trading day.

        Args:
            rate_date: The date to get the rate for.

        Returns:
            The annualized rate as a decimal (e.g., Decimal("0.045") for 4.5%).

        Raises:
            ValueError: If no rate is available for the date or recent history.
        """
        rate = self._get_rate_with_lookback(rate_date)
        if rate is None:
            raise ValueError(
                f"No risk-free rate available for {rate_date} "
                f"or the previous 14 days."
            )
        return rate

    def get_daily_rate(self, rate_date: date, trading_days_per_year: int = 252) -> Decimal:
        """
        Get the daily risk-free rate for a specific date.

        Converts the annualized rate to a daily rate by dividing by
        the number of trading days per year.

        Args:
            rate_date: The date to get the rate for.
            trading_days_per_year: Number of trading days per year (default 252).

        Returns:
            The daily rate as a decimal.

        Raises:
            ValueError: If no rate is available for the date.
        """
        annual_rate = self.get_rate(rate_date)
        return annual_rate / trading_days_per_year

    def get_rates_for_range(
        self,
        start_date: date,
        end_date: date
    ) -> dict[date, Decimal]:
        """
        Get all available annualized rates for a date range.

        Only returns dates where actual FRED data exists (trading days).
        Does not interpolate or carry forward rates.

        Args:
            start_date: Start of the date range (inclusive).
            end_date: End of the date range (inclusive).

        Returns:
            Dictionary mapping dates to annualized rates (as decimals).
        """
        result: dict[date, Decimal] = {}
        for rate_date, rate in self.rates.items():
            if start_date <= rate_date <= end_date:
                result[rate_date] = rate
        return result

    def get_available_dates(self) -> list[date]:
        """
        Get all dates for which rate data is available.

        Returns:
            Sorted list of dates with available data.
        """
        return sorted(self.rates.keys())

__init__(series=RiskFreeRateSeries.DTB3, min_date=None, max_date=None, use_cache=True)

Initialize the FRED risk-free rate manager.

Parameters:

Name Type Description Default
series RiskFreeRateSeries

The FRED series to use (default: DTB3 - 3-Month T-Bill).

 DTB3
min_date date | None

Earliest date to fetch data for (default: 5 years ago).

 None
max_date date | None

Latest date to fetch data for (default: today).

 None
use_cache bool

Whether to use local caching (default: True).

 True
Source code in src/athena/riskfreerates.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def __init__(
    self,
    series: RiskFreeRateSeries = RiskFreeRateSeries.DTB3,
    min_date: date | None = None,
    max_date: date | None = None,
    use_cache: bool = True
):
    """
    Initialize the FRED risk-free rate manager.

    Args:
        series: The FRED series to use (default: DTB3 - 3-Month T-Bill).
        min_date: Earliest date to fetch data for (default: 5 years ago).
        max_date: Latest date to fetch data for (default: today).
        use_cache: Whether to use local caching (default: True).
    """
    if min_date is None:
        min_date = date.today() - timedelta(days=5 * 365)
    if max_date is None:
        max_date = date.today()

    super().__init__(min_date, max_date)

    self.series = series
    self.use_cache = use_cache

    # Dictionary to store rates: {date: Decimal}
    # Rates are stored as decimals (e.g., 0.045 for 4.5%)
    self.rates: dict[date, Decimal] = {}

    # Build the FRED CSV URL
    url = self._build_url(min_date, max_date)

    # Generate cache file path
    cache_key = hashlib.md5(
        f"{series.value}_{min_date}_{max_date}".encode()
    ).hexdigest()[:12]
    self._cache_path = (
        Path.cwd() / ".cache" / "fred_risk_free_rates" / f"{series.value}_{cache_key}.csv"
    )

    self._fetch_and_parse_data(url)

get_rate(rate_date)

Get the annualized risk-free rate for a specific date.

If no data is available for the exact date (weekend, holiday), looks back up to 14 days to find the most recent trading day.

Parameters:

Name Type Description Default
rate_date date

The date to get the rate for.

 required

Returns:

Type Description
Decimal

The annualized rate as a decimal (e.g., Decimal("0.045") for 4.5%).

Raises:

Type Description
ValueError

If no rate is available for the date or recent history.
Source code in src/athena/riskfreerates.py 
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
def get_rate(self, rate_date: date) -> Decimal:
    """
    Get the annualized risk-free rate for a specific date.

    If no data is available for the exact date (weekend, holiday),
    looks back up to 14 days to find the most recent trading day.

    Args:
        rate_date: The date to get the rate for.

    Returns:
        The annualized rate as a decimal (e.g., Decimal("0.045") for 4.5%).

    Raises:
        ValueError: If no rate is available for the date or recent history.
    """
    rate = self._get_rate_with_lookback(rate_date)
    if rate is None:
        raise ValueError(
            f"No risk-free rate available for {rate_date} "
            f"or the previous 14 days."
        )
    return rate

get_daily_rate(rate_date, trading_days_per_year=252)

Get the daily risk-free rate for a specific date.

Converts the annualized rate to a daily rate by dividing by the number of trading days per year.

Parameters:

Name Type Description Default
rate_date date

The date to get the rate for.

 required
trading_days_per_year int

Number of trading days per year (default 252).

 252

Returns:

Type Description
Decimal

The daily rate as a decimal.

Raises:

Type Description
ValueError

If no rate is available for the date.
Source code in src/athena/riskfreerates.py 
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
def get_daily_rate(self, rate_date: date, trading_days_per_year: int = 252) -> Decimal:
    """
    Get the daily risk-free rate for a specific date.

    Converts the annualized rate to a daily rate by dividing by
    the number of trading days per year.

    Args:
        rate_date: The date to get the rate for.
        trading_days_per_year: Number of trading days per year (default 252).

    Returns:
        The daily rate as a decimal.

    Raises:
        ValueError: If no rate is available for the date.
    """
    annual_rate = self.get_rate(rate_date)
    return annual_rate / trading_days_per_year

get_rates_for_range(start_date, end_date)

Get all available annualized rates for a date range.

Only returns dates where actual FRED data exists (trading days). Does not interpolate or carry forward rates.

Parameters:

Name Type Description Default
start_date date

Start of the date range (inclusive).

 required
end_date date

End of the date range (inclusive).

 required

Returns:

Type Description
dict[date, Decimal]

Dictionary mapping dates to annualized rates (as decimals).
Source code in src/athena/riskfreerates.py 
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
def get_rates_for_range(
    self,
    start_date: date,
    end_date: date
) -> dict[date, Decimal]:
    """
    Get all available annualized rates for a date range.

    Only returns dates where actual FRED data exists (trading days).
    Does not interpolate or carry forward rates.

    Args:
        start_date: Start of the date range (inclusive).
        end_date: End of the date range (inclusive).

    Returns:
        Dictionary mapping dates to annualized rates (as decimals).
    """
    result: dict[date, Decimal] = {}
    for rate_date, rate in self.rates.items():
        if start_date <= rate_date <= end_date:
            result[rate_date] = rate
    return result

get_available_dates()

Get all dates for which rate data is available.

Returns:

Type Description
list[date]

Sorted list of dates with available data.
Source code in src/athena/riskfreerates.py 
349
350
351
352
353
354
355
356
def get_available_dates(self) -> list[date]:
    """
    Get all dates for which rate data is available.

    Returns:
        Sorted list of dates with available data.
    """
    return sorted(self.rates.keys())