Skip to content
All library documents

Using Fama-French and AQR Factors for Risk Adjustment and Benchmarking

Notebook Machine Learning for Trading

Summary

This document introduces public Fama-French and AQR factor return datasets as inputs for benchmarking, risk attribution, and factor research. It describes market, size, value, profitability, investment, and momentum factors from the Fama-French library, alongside AQR series covering quality, low-beta, and alternative value concepts. Data is available at monthly frequency, with daily Fama-French data and date-range filtering supported by the loaders.

The workflow covers downloading and caching datasets, loading and profiling them, and calculating annualized mean, volatility, and Sharpe statistics from monthly returns. Coverage starts in 1926 for the Fama-French data described, while AQR coverage varies by factor; the providers define their own series and formats. The material is a data access and exploration guide rather than evidence that any factor earns persistent returns. Researchers must account for provider definitions, update timing, and the limits of summary statistics when applying factors to risk adjustment or performance evaluation.

Key ideas

  • Fama-French datasets provide market, size, value, profitability, investment, and momentum returns for research benchmarks.
  • AQR datasets include quality, low-beta, and alternative value factor series with factor-specific coverage.
  • Monthly and daily frequencies can be loaded, and analyses can be restricted to a date range.
  • Annualized mean, volatility, and Sharpe calculations offer basic summaries but do not establish future factor performance.
  • Factor definitions and data formats are provider-defined, so results depend on the selected series and its coverage.

Tags

Factor investingEquitiesStatisticsBacktesting
Full text
# Academic Factor Data Dataset


# Academic Factor Data Dataset

Fama-French and AQR factor returns for benchmarking and risk adjustment.

| Property | Value |
|----------|-------|
| **Provider** | Ken French Library, AQR |
| **Asset Class** | Factor Returns |
| **Frequency** | Monthly (daily available) |
| **Factors** | FF3, FF5, Momentum, QMJ, BAB |
| **Coverage** | 1926-present (FF), varies (AQR) |
| **Size** | ~5 MB |
| **API Key** | None (free) |
| **Loader** | `load_ff_factors()`, `load_aqr_factors()` |

```python
"""Academic Factor Data - download, explore, and update workflow."""

from pathlib import Path

import polars as pl
```

## 1. Configuration

Academic factor data is **provider-defined** (no local config file). Each provider
maintains their own factor definitions and data format.

```python
print("=== Academic Factor Configuration ===")
print("\nFama-French (Ken French Library):")
print("  - FF3: Mkt-RF, SMB, HML")
print("  - FF5: FF3 + RMW, CMA")
print("  - Momentum: MOM")
print("  - Coverage: 1926-present")
print("\nAQR Research:")
print("  - QMJ: Quality Minus Junk")
print("  - BAB: Betting Against Beta")
print("  - VME: Value Minus Everything")
print("  - HML Devil: Industry-adjusted value")
print("  - Coverage: varies by factor")
```

## 2. API Key Setup

**No API key required.** Both Ken French Library and AQR provide free public access.

```python
print("Ken French Library: Free, no API key required")
print("  URL: https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html")
print("\nAQR Research: Free, no API key required")
print("  URL: https://www.aqr.com/Insights/Datasets")
```

## 3. Download Data

The `ml4t-data` library handles downloading and caching factor data.

```python
def download_ff_factors(
    datasets: list[str] | None = None, frequency: str = "monthly", dry_run: bool = False
):
    """Download Fama-French factor data.

    Args:
        datasets: Specific datasets to download (default: core factors)
        frequency: "monthly" or "daily"
        dry_run: If True, show what would be downloaded
    """
    from ml4t.data.providers.fama_french import FamaFrenchProvider

    from utils import ML4T_DATA_PATH

    output_dir = ML4T_DATA_PATH / "factors" / "fama-french"

    # Default core datasets
    if datasets is None:
        datasets = ["ff3", "ff5", "mom"]

    print("=== Fama-French Download ===")
    print(f"Datasets: {datasets}")
    print(f"Frequency: {frequency}")
    print(f"Output: {output_dir}")

    if dry_run:
        print("\n[DRY RUN] Would download:")
        for ds in datasets:
            print(f"  - {ds}")
        return

    output_dir.mkdir(parents=True, exist_ok=True)
    provider = FamaFrenchProvider(cache_path=output_dir, use_cache=True)

    print(f"\nDownloading {len(datasets)} datasets...")
    for dataset in datasets:
        print(f"  {dataset}...", end=" ", flush=True)
        try:
            df = provider.fetch(dataset, frequency=frequency)
            print(f"OK ({len(df):,} rows)")
        except Exception as e:
            print(f"ERROR: {e}")

    print("\n=== Complete ===")
    print(f"Data saved to: {output_dir}")


def download_aqr_factors(datasets: list[str] | None = None, dry_run: bool = False):
    """Download AQR factor data.

    Args:
        datasets: Specific datasets to download (default: core factors)
        dry_run: If True, show what would be downloaded
    """
    from ml4t.data.providers.aqr import AQRProvider

    from utils import ML4T_DATA_PATH

    output_dir = ML4T_DATA_PATH / "factors" / "aqr"

    # Default core datasets
    if datasets is None:
        datasets = ["qmj", "bab"]

    print("=== AQR Download ===")
    print(f"Datasets: {datasets}")
    print(f"Output: {output_dir}")

    if dry_run:
        print("\n[DRY RUN] Would download:")
        for ds in datasets:
            print(f"  - {ds}")
        return

    output_dir.mkdir(parents=True, exist_ok=True)
    provider = AQRProvider(cache_path=output_dir)

    print(f"\nDownloading {len(datasets)} datasets...")
    for dataset in datasets:
        print(f"  {dataset}...", end=" ", flush=True)
        try:
            df = provider.fetch(dataset)
            print(f"OK ({len(df):,} rows)")
        except Exception as e:
            print(f"ERROR: {e}")

    print("\n=== Complete ===")
    print(f"Data saved to: {output_dir}")
```

### Download Fama-French Factors

```python
# Uncomment to download
# download_ff_factors()
```

### Download AQR Factors

```python
# Uncomment to download
# download_aqr_factors()
```

### Dry Run (Preview)

```python
download_ff_factors(dry_run=True)
```

## 4. Load and Explore

Once downloaded, use the loaders throughout the book:

```python
from data import load_aqr_factors, load_ff_factors
```

### Fama-French Factors

```python
# Load Fama-French factors
ff = load_ff_factors()

print(f"Shape: {ff.shape}")
print(f"Columns: {ff.columns}")
print(f"Date range: {ff['timestamp'].min()} to {ff['timestamp'].max()}")
print(f"Memory: {ff.estimated_size('mb'):.1f} MB")
```

```python
# Preview
ff.tail(10)
```

```python
# Factor statistics (annualized)
factor_cols = [c for c in ff.columns if c not in ["timestamp", "date"]]
print("Factor Annualized Statistics (%):")
for col in factor_cols[:6]:
    series = ff[col].drop_nulls()
    mean_annual = series.mean() * 12  # Monthly to annual
    vol_annual = series.std() * (12**0.5)
    sharpe = mean_annual / vol_annual if vol_annual > 0 else 0
    print(f"  {col:8s}: mean={mean_annual:6.2f}, vol={vol_annual:6.2f}, SR={sharpe:.2f}")
```

### AQR Factors

```python
# Load AQR factors
aqr = load_aqr_factors()

print(f"Shape: {aqr.shape}")
print(f"Columns: {aqr.columns}")
print(f"Date range: {aqr['timestamp'].min()} to {aqr['timestamp'].max()}")
```

```python
# Preview
aqr.tail(10)
```

## 5. Data Profile

```python
from ml4t.data.storage.data_profile import get_profile_path, load_profile

from utils import ML4T_DATA_PATH

for provider, subdir in [("Fama-French", "fama-french"), ("AQR", "aqr")]:
    profile_path = get_profile_path(ML4T_DATA_PATH / "factors" / subdir)
    profile = load_profile(profile_path)
    if profile is None:
        print(f"No {provider} profile at {profile_path}")
    else:
        print(f"=== {provider} Profile ===")
        print(f"Written by {profile.source}")
        print(profile.summary())

print(
    "\nff_download.py and aqr_download.py unzip the providers' own CSV releases and do\n"
    "not go through ml4t.data.storage.data_profile, so neither carries a profile today.\n"
    "Nothing in this notebook writes one either."
)
```

## 6. Loader Options

The loaders support filtering by frequency and date range:

```python
# Daily frequency
ff_daily = load_ff_factors(frequency="daily")
print(f"FF daily: {ff_daily.shape}")
```

```python
# Date range
recent_ff = load_ff_factors(start_date="2020-01-01")
print(f"FF 2020+: {recent_ff.shape}")
```

## 7. Documentation

### Fama-French Factors

From Ken French's Data Library:

| Factor | Description |
|--------|-------------|
| Mkt-RF | Market excess return |
| SMB | Small Minus Big (size) |
| HML | High Minus Low (value) |
| RMW | Robust Minus Weak (profitability) |
| CMA | Conservative Minus Aggressive (investment) |
| Mom | Momentum (12-1 month return) |

[Ken French Data Library](https://mba.tuck.dartmouth.edu/pages/faculty/ken.french/data_library.html)

### AQR Factors

Alternative factors from AQR Capital:

| Factor | Description |
|--------|-------------|
| QMJ | Quality Minus Junk (profitability, growth, safety) |
| BAB | Betting Against Beta (low-beta premium) |
| VME | Value Minus Everything (alternative value) |
| HML Devil | Value with industry adjustment |

[AQR Datasets](https://www.aqr.com/Insights/Datasets)

## 8. Updating Data

To update with the latest data:

```python
# Update Fama-French factors
download_ff_factors()

# Update AQR factors
download_aqr_factors()
```

Factor data is typically updated monthly.

## Summary

| Item | Value |
|------|-------|
| Providers | Ken French, AQR |
| Frequencies | Monthly, Daily |
| Coverage | 1926-present (FF), varies (AQR) |
| API Key | None (free) |
| Loaders | `load_ff_factors()`, `load_aqr_factors()` |

**Primary use**: Risk attribution, alpha measurement, factor investing research.

Shown in full with attribution under the source's licence. Licence: MIT

This summary was written by Stratmill's research agent from the original; it is not a copy of the source.