Time Series & Calendrical Data
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Time Series and Calendrical Data management in AlphaPy provides a robust infrastructure for handling temporal relationships, date-based features, and domain-specific scheduling (such as market holidays or sports seasons). This system is central to the project's ability to transform raw data into time-aligned predictors, particularly within the MarketFlow and SportFlow pipelines.
The architecture relies on custom date formats (RDate) for efficient calendrical calculations and uses a structured "Space" concept to define the subject, schema, and temporal fractal of data. These components ensure that machine learning models receive consistent, sequenced data regardless of whether the domain involves financial markets or sporting events.
Sources: alphapy/calendrical.py:1-24, alphapy/space.py:48-73, alphapy/sport_flow.py:596-608
Calendrical Calculations & RDate
AlphaPy implements a proprietary date format called RDate (an integer representation of dates) to facilitate rapid arithmetic for complex scheduling. This module includes logic for Gregorian conversions, holiday identification, and business day calculations.
Core Conversion Logic
The system converts between standard Gregorian dates (Year, Month, Day) and RDate integers to simplify subtracting dates and finding relative offsets.
This diagram shows the conversion flow between Gregorian formats and the internal RDate representation used for calculations.
Sources: alphapy/calendrical.py:151-177, alphapy/calendrical.py:346-382, alphapy/calendrical.py:448-471
Key Calendrical Functions
| Function | Description | Return Type |
|---|---|---|
gdate_to_rdate | Converts Y/M/D to internal RDate integer. | int |
rdate_to_gdate | Converts RDate to Y/M/D tuple. | (int, int, int) |
biz_day_month | Calculates the business day number within a specific month. | int |
leap_year | Determines if a year is a Gregorian leap year. | bool |
nth_kday | Finds the Nth occurrence of a specific day (e.g., 3rd Friday). | int |
Sources: alphapy/calendrical.py:52-78, alphapy/calendrical.py:276-296, alphapy/calendrical.py:417-432
Data Spaces & Fractals
The Space class provides a namespace for organizing time series data based on its subject, the nature of the data, and its temporal resolution (fractal).
Namespace Structure
A Space is identified by a joined string using a specific delimiter (underscore).
- Subject: Group identifier (e.g., "stock", "game").
- Schema: Data type (e.g., "prices", "scores").
- Fractal: Time resolution (e.g., "5m", "1d", "1g").
Sources: alphapy/space.py:34-73
Intraday Fractals
Intraday time series are identified by specific Pandas time offset aliases defined globally.
| Alias | Description |
|---|---|
| H | Hour |
| T / min | Minute |
| S | Second |
| L / ms | Millisecond |
| U / us | Microsecond |
| N | Nanosecond |
Sources: alphapy/globals.py:59-61
Time Series Analysis Flow
The analysis module handles the temporal alignment of features. It sequences data by lagging features and shifting targets based on specified forecast periods.
Data Sequencing Process
The sequencing logic ensures that the model only trains on data where the target is known and the predictors are available relative to the forecasting horizon.
Sources: alphapy/analysis.py:122-212, alphapy/utilities.py:149-174
Sport-Specific Time Series
In SportFlow, time series features are generated based on game intervals rather than fixed clock time. The system calculates deltas between games and tracks streaks.
Temporal Feature Generation
The system calculates several time-relative metrics for teams:
days_since_first_game: Cumulative days in the season.days_since_previous_game: Rest period between events.rolling_window/expanding: Moving averages for performance metrics like point margins.
Sources: alphapy/sport_flow.py:207-224, alphapy/sport_flow.py:369-383
Date Validation
Dates provided via command line are validated using a standard format parser.
def valid_date(date_string):
try:
date_time = datetime.strptime(date_string, "%Y-%m-%d")
return date_string
except:
message = "Not a valid date: '{0}'.".format(date_string)
raise argparse.ArgumentTypeError(message)
Sources: alphapy/utilities.py:183-207
Holiday and Event Scheduling
The calendrical module provides a map of standard holidays which are used to adjust business day calculations.
Holiday Map Example
The following holidays are explicitly supported with logic for "observed" dates (shifting Sunday holidays to Monday):
- New Year's Day
- Martin Luther King Jr. Day
- Good Friday / Easter
- Memorial Day
- Independence Day
- Thanksgiving
- Christmas
Sources: alphapy/calendrical.py:734-750, alphapy/calendrical.py:488-506
Summary
The Time Series and Calendrical Data infrastructure provides the temporal backbone for AlphaPy. By abstracting date arithmetic into RDate integers and providing high-level sequencing in the analysis layer, the project ensures that models are trained on valid, time-aligned datasets. The use of "Spaces" and "Fractals" further allows the engine to scale across different time resolutions and domains like finance and sports.