NCAAB (SportFlow) Example Setup
Relevant source files
The following files were used as context for generating this wiki page:
The NCAAB (SportFlow) setup is a specialized implementation of the AlphaPy machine learning framework designed to predict the outcomes of sporting events, specifically focused on NCAA Basketball. It utilizes the SportFlow module to process seasonal game data, calculate team-specific statistics, and generate "delta" features representing the differences between competing teams.
The system operates by reading raw game data and transforming it into a format suitable for classification or regression tasks. In the NCAAB example, the primary goal is typically binary classification to determine outcomes like won_on_spread. The pipeline integrates feature engineering, model selection (such as Random Forest and XGBoost), and evaluation metrics to produce predictive models for sports speculation.
Sources: alphapy/sport_flow.py:28-44, alphapy/examples/NCAAB/config/model.yml:25-27
Architecture and Data Flow
The SportFlow architecture follows a multi-stage pipeline that transforms raw historical scores into a predictive feature set. The process begins with reading game records for specific seasons and iterates through team-level data generation before merging them back into a unified model frame.
High-Level SportFlow Pipeline
The diagram below illustrates the sequence of operations from raw data ingestion to final model execution.
The pipeline handles seasonal looping, ensures that data is processed chronologically, and applies rolling windows for average calculations.
Sources: alphapy/sport_flow.py:287-434
Feature Engineering Logic
SportFlow generates features by analyzing game results from the perspective of both the home and away teams. Key metrics include win/loss streaks, point margins, and coverage margins against the betting line.
Core Calculation Functions
The module defines several utility functions to derive sports-specific data:
get_point_margin: Calculates the difference between scores.get_streak: Computes the current winning, losing, or over/under streak based on a boolean series.get_day_offset: Measures the rest period between games.
Delta Feature Generation
A critical component of the NCAAB setup is the generation of "delta" features. This involves subtracting the stats of the away team from the stats of the home team to represent the relative strength of the matchup.
def generate_delta_data(frame, fdict, prefix1, prefix2):
for key, value in list(fdict.items()):
newkey = PSEP.join(['delta', key])
key1 = PSEP.join([prefix1, key])
key2 = PSEP.join([prefix2, key])
frame[newkey] = frame[key1] - frame[key2]
return frame
Sources: alphapy/sport_flow.py:125-277, alphapy/sport_flow.py:279-285
Configuration Management
The NCAAB setup is governed by three primary configuration files: sport.yml, model.yml, and algos.yml. The model.yml file specifically configures the AlphaPy framework for the classification task.
Example Model Configuration (NCAAB)
| Category | Parameter | Value/Description |
|---|---|---|
| Data | target | won_on_spread |
| Data | split | 0.4 (Train/Test split) |
| Model | algorithms | ['RF', 'XGB'] (Random Forest and XGBoost) |
| Model | type | classification |
| Features | scaling | standard |
| Features | variance | threshold: 0.1 |
Sources: alphapy/examples/NCAAB/config/model.yml:1-118
Sport-Specific Data Schema
The sports_dict defines the internal data structure for features calculated during team frame generation.
| Field Name | Type | Description |
|---|---|---|
wins / losses | int | Cumulative season count |
point_margin_game | int | Points difference in a single game |
point_margin_season_avg | float | Cumulative average margin |
cover_margin_game | float | Margin relative to the betting line |
days_since_previous | int | Days of rest between games |
Sources: alphapy/sport_flow.py:61-101
Execution Model
SportFlow can be executed in either Train or Predict mode.
- Train Mode: Processes historical data to build and save a model. It splits data into training and testing partitions based on the dates provided in the command line or configuration.
- Predict Mode: Loads a saved model and feature map to make predictions on new, upcoming game data where the outcome is unknown.
Summary of the NCAAB Example
The NCAAB (SportFlow) example setup demonstrates how to leverage AlphaPy for sports analytics. By transforming sequential game results into team-based performance metrics and ultimately into comparative delta features, the system enables standard machine learning algorithms like Random Forest to predict complex outcomes such as beating the point spread. The use of YAML-based configuration allows for fine-tuning feature selection, interaction terms (poly_degree: 2), and ensemble blending without modifying the core logic.
Sources: alphapy/sport_flow.py:430-460, alphapy/examples/NCAAB/config/model.yml:1-10