Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• README.rst
• alphapy/main.py
• alphapy/model.py
• alphapy/market_flow.py
• alphapy/sport_flow.py
• alphapy/estimators.py
• alphapy/globals.py
• alphapy/analysis.py
• alphapy/frame.py

AlphaPy is a machine learning framework designed for speculators and data scientists, primarily leveraging scikit-learn, pandas, and Keras. The system is structured as a pipeline-oriented architecture that automates feature engineering, model selection, ensemble creation, and evaluation. It provides specialized flows for financial markets (MarketFlow) and sports betting (SportFlow), enabling users to test predictive models and manage portfolios or betting systems.

Sources: README.rst:1-15, alphapy/main.py:53-60

Core System Components

The architecture is built around several key modules that handle data structures, model lifecycle management, and domain-specific logic.

The Model Object

The Model class is the central data structure that unifies algorithms and metadata. It stores training/testing data, specifications, estimators, and performance metrics.

Attribute	Description
specs	Dictionary of model configurations from model.yml.
algolist	List of algorithms to be trained (e.g., 'RF', 'XGB').
estimators	Dictionary mapping algorithm names to fitted estimator objects.
preds / probas	Dictionaries storing predictions and classification probabilities.
metrics	Evaluation results (e.g., accuracy, log_loss, ROC AUC).

Sources: alphapy/model.py:73-138

Execution Pipelines

AlphaPy operates through two primary execution modes:

1. Training Pipeline: Handles data ingestion, splitting, comprehensive feature engineering (transforms, interactions, selection), model fitting, hyperparameter optimization, and ensemble blending.
2. Prediction Pipeline: Loads a previously saved model and feature map to generate predictions on new, unseen data.

Sources: alphapy/main.py:76-218, alphapy/main.py:228-306

Data Flow Architecture

The following diagram illustrates the high-level flow of data from raw input to finalized predictions within the training pipeline:

The pipeline ensures that feature engineering steps (like interactions and low-variance removal) are applied consistently across training and testing partitions.
Sources: alphapy/main.py:80-218

Domain-Specific Subsystems

AlphaPy extends its core pipeline into two specialized domains: financial markets and sports analytics.

MarketFlow

MarketFlow is designed for financial time-series analysis. It incorporates technical analysis variables, portfolio management, and system testing. It utilizes a Space concept to manage subjects, schemas, and time fractals (e.g., intraday vs. daily).

• Variables: Automated creation of standard variables like phigh (probability >= 0.7) and plow (probability <= 0.3).
• System Execution: Support for long/short entry and exit logic, including holding periods and scaling.

Sources: alphapy/market_flow.py:90-192, alphapy/market_flow.py:270-292

SportFlow

SportFlow manages data structures for sports betting, focusing on team-based statistics and seasonal data. It generates features like winning streaks, cover margins against the spread, and over/under margins.

Feature Engineering and Model Selection

Estimator Management

The estimators module acts as a factory, mapping string aliases (e.g., 'RF' for RandomForest, 'XGB' for XGBoost) to their respective implementations. It supports optional third-party packages like xgboost, lightgbm, and catboost.

Sources: alphapy/estimators.py:126-168

Model Evaluation and Blending

AlphaPy implements a "Brute Force" evaluation strategy, calculating all possible scikit-learn metrics for classification and regression. If multiple algorithms are specified, the system creates a Blended Model using:

• Logistic Regression for classification blending.
• Ridge Regression for regression blending.

Sources: alphapy/model.py:534-585, alphapy/model.py:596-650

Project Structure and Configuration

The project relies on a structured directory layout for configuration and output:

Directory	Purpose
config/	Contains model.yml, algos.yml, and domain-specific configs.
input/	Stores processed training and testing datasets.
model/	Stores serialized predictors (.pkl or .h5) and feature maps.
output/	Final predictions, probabilities, and rankings.
plots/	Visualizations like ROC curves, confusion matrices, and feature importance.

Sources: alphapy/main.py:369-375, alphapy/model.py:236-302

Summary

The AlphaPy architecture is a modular, pipeline-driven framework that abstracts the complexities of the machine learning lifecycle. By combining a flexible core (via the Model class and training/prediction pipelines) with specialized domain layers (MarketFlow and SportFlow), it provides a unified environment for developing and deploying predictive models in financial and competitive contexts.

Sources: alphapy/model.py:73-100, alphapy/analysis.py:125-145, alphapy/market_flow.py:202-220