Conditional-Alpha-Prediction

Conditional-Alpha-Prediction is a quantitative research project for the US equity market that combines market-derived and valuation-derived signals into a probabilistic forecast of future excess returns.

Unlike a traditional DCF model or a standard machine learning regression, the project does not aim to predict a single alpha estimate. Instead, it estimates the conditional distribution of one-year market-relative alpha, allowing the final output to express probabilities, expected upside and downside, tail risks, and other decision-oriented metrics.

The system is intended as an assistive tool for discretionary fundamental research rather than a production trading system. Its primary objective is to explore probabilistic signal fusion under weak signal-to-noise conditions.

---

Core Idea

The project combines two independent views of a company.

Market-side model

A CatBoost regression model estimates an expected alpha (alpha_hat) using market and macro-regime features, including:

• beta
• volatility
• trading volume
• market momentum
• moving-average deviations
• market return
• 10Y Treasury yield

Fundamental-side model

A discounted cash flow model estimates the company's implied upside using publicly available financial statements together with WACC assumptions, capital structure, FCFF, shares outstanding, and current market price.

Probabilistic fusion

Rather than averaging the two signals, they are combined through a Clayton-based vine copula.

This produces a conditional probability distribution instead of a single forecast.

The final report includes:

• Probability of positive alpha
• Median alpha
• Expected alpha
• Expected upside and downside
• Tail probabilities
• Sharpe-like efficiency ratio
• Conditional football-field valuation range

---

Research Hypothesis

The project is intentionally designed around the US equity market during higher-rate macro regimes.

The underlying hypothesis is that DCF-derived implied upside becomes more informative when the 10Y Treasury yield exceeds approximately 3%. Under low-rate environments, valuation alone tends to provide weaker predictive power and therefore is treated as a complementary rather than primary forecasting signal.

For this reason, the copula calibration is performed only on observations satisfying

10Y Treasury Rate >= 3%

The DCF model is not treated as an alpha predictor by itself. Instead, it serves as an orthogonal valuation signal that complements the market-side machine learning model.

---

Dataset

Current research dataset:

Metric	Value
Parsed tickers	2,792
Total valuation rows	4,226
Copula regime observations	2,469
Runtime dataset	2,384

Target variable:

real_alpha = one-year stock return − one-year S&P 500 return

Extreme observations outside

-200% <= real_alpha <= 200%

are removed to stabilize the conditional distribution.

---

Validation

The market-side model is evaluated using repeated out-of-fold validation.

Metric	Score
RMSE	0.3970
Spearman	0.3937
Kendall	0.2762

Although the pure CatBoost model can outperform the fused model on simple ranking metrics, the objective of the project is different.

Instead of improving a point prediction, the copula layer estimates an entire conditional distribution, providing substantially richer information for investment research.

---

Pipeline

The project consists of two independent workflows.

1. Research Pipeline

parser.py
      ↓
train_builder.py
      ↓
ml.py
      ↓
copula_logic.py

Module	Purpose
parser.py	Downloads market data, parses SEC fundamentals and builds ticker datasets.
train_builder.py	Creates the valuation-year dataset and computes realised alpha.
ml.py	Trains the CatBoost market-side alpha model with Optuna tuning.
copula_logic.py	Fits the Clayton vine copula and saves the probabilistic fusion model.

---

2. Runtime Pipeline

main.py
      ↓
modules_processor.py
      ↓
CatBoost inference
      ↓
Copula inference
      ↓
PDF Report

The runtime workflow rebuilds the live feature vector for a selected ticker, estimates the market-side alpha, combines it with the DCF signal through the trained copula, and generates a one-page PDF research report.

---

Report Output

The generated PDF is designed as a compact equity research summary rather than a traditional valuation report.

It includes:

• company ticker
• valuation date
• one-year alpha horizon
• probability of positive alpha
• expected and median alpha
• expected upside and downside
• tail probabilities
• Sharpe-like efficiency ratio
• football-field visualization of the conditional alpha distribution

Unlike a standard football-field valuation, the visualization represents the estimated conditional alpha distribution, not a deterministic valuation range.

---

Data Sources

The project relies exclusively on publicly available and research-friendly data sources.

Source	Purpose
SEC EDGAR Company Facts	Annual financial statements
yfinance	Market prices, volume, index returns and reference data
US 10Y Treasury Yield	Macro-regime variable
Public WACC assumptions	Discount-rate estimation

The project does not rely on proprietary market data.

---

Repository Structure

Conditional-Alpha-Prediction/
│
├── Datasets/
│   ├── companies.csv
│   ├── US_WaccComponents_Timeseries.csv
│   ├── train_dataset.csv
│   └── train_dataset_full.csv
│
├── Models/
│   ├── market_model.cbm
│   └── copula_cfg.json
│
├── Reports/
│   └── report_template.pptm
│
├── parser.py
├── train_builder.py
├── ml.py
├── copula_logic.py
├── modules_processor.py
├── valuation_dcf.py
├── report_export.py
├── main.py
└── requirements.txt

Large intermediate parsing folders and ticker-year JSON files are intentionally omitted from the repository's core artifacts, as they can be regenerated through the research pipeline.

---

Installation

Clone the repository

git clone https://github.com/SamsonChyst/Conditional-Alpha-Prediction.git
cd Conditional-Alpha-Prediction

Create a virtual environment

python -m venv .venv

Activate it

Linux / macOS

source .venv/bin/activate

Windows

.venv\Scripts\activate

Install dependencies

pip install -r requirements.txt

Create a .env file in the project root

Mail="your_email@gmail.com"

The email is used to identify requests sent to the SEC EDGAR API, following the SEC usage guidelines.

---

PowerPoint Requirements

PDF generation relies on a macro-enabled PowerPoint template.

The runtime environment therefore requires:

• Microsoft PowerPoint
• VBA macros enabled
• Reports/report_template.pptm

During the first execution, PowerPoint may request permission to enable macros.

---

Usage

Rebuild the research pipeline

Run the following scripts in order:

python parser.py
python train_builder.py
python ml.py
python copula_logic.py

This pipeline will:

1. Parse market and fundamental data.
2. Build the valuation dataset.
3. Train the CatBoost alpha model.
4. Fit the probabilistic copula model.

The parsing stage may require considerable time depending on the number of companies and API availability.

---

Generate a research report

python main.py

The application requests three inputs:

• ticker
• DCF implied upside
• current 10Y Treasury yield

It then produces a PDF report inside the Reports/ directory.