Event Calendar & Global Rates Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Event Calendar and Global Rates Integration system is responsible for aggregating, parsing, and standardizing global monetary policy events and interest rate decisions. Its primary purpose is to provide the regime detection engine with a structured timeline of central bank activities, which are used as critical evidence for identifying economic transitions and market regimes.
This system leverages specialized adapters to fetch data directly from official central bank sources—such as the Bank of England (BoE) and the European Central Bank (ECB)—and uses an orchestrator to manage the flow of data into the project's persistence layer. The resulting event calendar serves as a point-in-time reference for historical analysis and future policy expectations.
System Architecture & Orchestration
The integration architecture follows a provider-orchestrator pattern. The EventSourceOrchestrator manages multiple bank-specific adapters, executing data fetches and consolidating results into a unified format.
Orchestration Flow
The orchestrator initializes various adapters (e.g., OfficialBOEAdapter, OfficialECBAdapter) and coordinates the retrieval of "Event Candidates." These candidates are then processed to determine if they meet confidence thresholds or require manual review before being committed to the AcquisitionStore.
The orchestrator ensures that every fetch operation records the raw HTML source as a text artifact for audit purposes.
Sources: src/regime_data_fetch/event_sources/orchestrator.py:12-45, src/regime_data_fetch/event_sources/official_ecb.py:46-85
Data Acquisition Adapters
Adapters are specialized classes designed to interact with specific central bank websites. They handle the nuances of different HTML structures and document types (e.g., press releases, calendars, and yearly archives).
European Central Bank (ECB) Integration
The OfficialECBAdapter fetches data from both the archive index and the current Governing Council calendar. It uses regular expressions to extract event dates and titles, specifically looking for "monetary policy decisions."
Key components include:
ARCHIVE_INDEX_URL: Used to discover historical yearly snippets.CURRENT_CALENDAR_URL: Used to fetch upcoming scheduled meetings.parse_ecb_decision_archive: Extracts events from historical list pages.
Bank of England (BoE) Integration
The OfficialBOEAdapter performs similar functions for the UK central bank, focusing on Monetary Policy Committee (MPC) decisions. It categorizes events by importance and tracks scheduled future dates versus historical actuals.
Sources: src/regime_data_fetch/event_sources/official_ecb.py:15-35, 105-135, src/regime_data_fetch/event_sources/official_boe.py
Event Data Model
All fetched events are normalized into an EventCandidate structure before being processed. This ensures consistency across diverse global sources.
| Field | Type | Description |
|---|---|---|
date | dt.date | The date the event occurred or is scheduled. |
event_type | str | Categorization (e.g., ECB_decision, BOE_MPC_decision). |
market | str | Usually GLOBAL for central bank rates. |
importance | str | Significance level (e.g., high). |
confidence | str | Reliability of the parsed data (high, medium). |
is_future_scheduled | bool | True if the event is a placeholder for a future meeting. |
Sources: src/regime_data_fetch/event_sources/official_ecb.py:158-175, src/regime_data_fetch/event_sources/orchestrator.py:30-40
Engine Integration & Calibration
In the detection engine, the event calendar is used to create sessions-based features. The EventCalendar class within the engine mapping handles the conversion of raw event dates into trading session indices.
Usage in V2 Calibration
The run_v2_calibration.py script utilizes the event calendar to build the MarketContext. This context is foundational for fitting Hidden Markov Models (HMM) and Gaussian Mixture Models (GMM).
Key Functions & Implementation Details
fetch_text_result
A common utility used by adapters to retrieve web content. It returns a FetchTextResult containing the status and the raw text or an error message.
Sources: src/regime_data_fetch/event_sources/official_ecb.py:12-25
_dedupe
Adapters implement internal deduplication to ensure that events found in both historical archives and current calendars do not create duplicate entries in the store.
Sources: src/regime_data_fetch/event_sources/official_ecb.py:192-205
_record_html
A critical audit function that stores the exact HTML used for parsing into the AcquisitionStore, including metadata like NYSE calendar assumptions and timezones.
Sources: src/regime_data_fetch/event_sources/official_ecb.py:208-225
Conclusion
The Event Calendar & Global Rates Integration module provides the project with a robust, auditable pipeline for central bank data. By decoupling bank-specific parsing logic into adapters and centralizing management through an orchestrator, the system maintains high data integrity. This structured event timeline is essential for the V2 calibration process and the ongoing accuracy of regime detection.