SportFlow Pipeline
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The SportFlow Pipeline is a specialized module within the AlphaPy framework designed to predict the outcomes of sporting events using machine learning. It provides a structured workflow for processing historical game data, generating sports-specific features (such as win streaks, point margins, and betting spread covers), and training predictive models. The pipeline is designed to handle binary classification tasks, such as predicting whether a team will "cover the spread," or regression tasks for point totals.
The pipeline integrates tightly with the core AlphaPy main_pipeline for model selection, training, and evaluation. It automates the transition from raw game logs to seasonal team statistics, eventually producing a consolidated model frame used for training or real-time prediction.
Sources: alphapy/sport_flow.py:343-345, README.rst:45-50, setup.py:46-52
Pipeline Architecture and Data Flow
The SportFlow architecture operates by transforming game-centric data into team-centric features. It utilizes a multi-stage process: configuration loading, raw data ingestion, feature engineering via seasonal loops, and finally, execution of the AlphaPy machine learning pipeline.
High-Level Workflow
- Initialization: Loads specific sports configurations (
sport.yml) and general model configurations (model.yml). - Data Extraction: Reads historical game records for specified leagues and seasons.
- Team Frame Generation: For every team in a season, it calculates rolling statistics and streaks.
- Delta Calculation: Computes differences between home and away team statistics to create predictive features.
- Model Execution: Passes the processed data to the AlphaPy core for training or prediction.
The diagram shows the sequential flow of data from configuration to final prediction output.
Sources: alphapy/sport_flow.py:343-356, alphapy/sport_flow.py:406-440
Configuration and Parameters
SportFlow relies on two primary configuration files: sport.yml for domain-specific parameters and model.yml for machine learning hyperparameters.
Sport-Specific Configuration (sport.yml)
The get_sport_config function reads parameters that define the league context and feature calculation boundaries.
| Parameter | Type | Description |
|---|---|---|
league | string | Name of the sports league (e.g., NCAAB, NFL). |
points_max | int | Maximum points for random scoring simulation. |
points_min | int | Minimum points for random scoring simulation. |
random_scoring | bool | Whether to generate random scores for testing. |
rolling_window | int | Period for calculating rolling means/sums (e.g., last 10 games). |
seasons | list | List of years/seasons to process. |
Sources: alphapy/sport_flow.py:126-160
Machine Learning Configuration (model.yml)
Standard AlphaPy parameters control the modeling behavior.
Sources: alphapy/examples/NCAAB/config/model.yml:1-85, alphapy/model.py:165-310
Feature Engineering
A significant portion of the SportFlow pipeline is dedicated to generating derived features. These features are categorized into game-level outcomes and team-level seasonal trends.
Sports-Specific Fields
The pipeline tracks a wide array of statistics through the sports_dict and game_dict structures.
| Field Category | Key Features |
|---|---|
| Outcomes | won_on_points, lost_on_points, won_on_spread, over, under |
| Margins | point_margin_game, cover_margin_game, overunder_margin |
| Streaks | point_win_streak, cover_win_streak, over_streak, under_streak |
| Aggregates | point_margin_season_avg, cover_margin_ngames_avg, overunder_season |
Sources: alphapy/sport_flow.py:65-121
Team Statistics Generation
The function generate_team_frame iterates through a team's schedule to calculate cumulative and rolling stats. It handles logic for betting lines, flipping the sign of the line for away teams to maintain consistency in spread-cover calculations.
# Logic for calculating spread cover
if team == row[home_team]:
tf['point_margin_game'].at[index] = get_point_margin(row, 'home.score', 'away.score')
line = row['line']
elif team == row[away_team]:
tf['point_margin_game'].at[index] = get_point_margin(row, 'away.score', 'home.score')
line = -row['line']
tf['cover_margin_game'].at[index] = tf['point_margin_game'].at[index] + line
Sources: alphapy/sport_flow.py:270-285
Integration with AlphaPy Core
Once the model frame is constructed, SportFlow invokes main_pipeline from alphapy.__main__. This triggers the full suite of machine learning operations:
- Data Partitioning: Splitting data into Training, Testing, and Prediction sets based on dates.
- Transformations: Applying scaling (e.g.,
StandardScaler) and encoding (e.g.,LabelEncoder). - Model Training: Training algorithms defined in the config (e.g., Random Forest
RF, XGBoostXGB). - Model Evaluation: Generating metrics such as
roc_auc,accuracy, andf1.
Model Partitioning Sequence
The pipeline ensures that training data precedes prediction data chronologically to prevent look-ahead bias.
Conclusion
The SportFlow Pipeline provides a robust framework for sports analytics by automating the tedious process of transforming linear game logs into deep, historical team-performance features. By leveraging AlphaPy's core capabilities, it allows users to focus on feature selection and strategy rather than infrastructure. Its ability to compute deltas and streaks automatically makes it a powerful tool for predicting both game outcomes and betting market efficiency.