> ## Documentation Index
> Fetch the complete documentation index at: https://quantcontext.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# factor_analysis

> Decompose strategy returns into Fama-French factors using OLS regression

**When to use:** The user wants to understand where returns come from:is it alpha or factor exposure? Any query about "factor analysis", "decompose returns", "where does alpha come from", "factor exposure", "Fama-French", or "what's driving the returns" should use this tool.

**What it returns:** Alpha (daily and annualized) with t-statistic, factor loadings (market, size, value, momentum) with t-statistics, R-squared, residual volatility, and interpretation hints.

## Parameters

<ParamField query="equity_curve" type="list[object]" required>
  List of `{date, value}` objects representing portfolio value over time. Typically the `full_equity_curve` field from `backtest_strategy`. Requires 30+ data points.
</ParamField>

## Example Input

```json theme={null}
{
  "equity_curve": [
    { "date": "2023-01-03", "value": 100000 },
    { "date": "2023-01-04", "value": 100500 },
    { "date": "2023-01-05", "value": 100234 }
  ]
}
```

## Example Response

```json theme={null}
{
  "alpha_daily": 0.000182,
  "alpha_annualized": 0.0469,
  "alpha_tstat": 1.87,
  "factors": {
    "Mkt-RF": { "loading": 0.8234, "tstat": 12.41 },
    "SMB":    { "loading": 0.2156, "tstat": 3.22 },
    "HML":    { "loading": 0.4891, "tstat": 5.67 },
    "Mom":    { "loading": -0.0812, "tstat": -1.03 }
  },
  "r_squared": 0.7823,
  "residual_vol": 0.1241,
  "interpretation": {
    "alpha": "Alpha is NOT statistically significant (t-stat=1.87, need |t| >= 2)",
    "factors": "Dominant factor: HML (loading=0.4891)",
    "r_squared": "High R-squared (0.7823):most return variance explained by known factors"
  }
}
```

## Interpreting the Output

### Alpha

<Warning>
  For a single pre-specified strategy, `|t| >= 2` (\~95% confidence) is a reasonable significance threshold. If the strategy was discovered by testing many parameter combinations, a higher bar applies — Harvey, Liu & Zhu (2016) suggest t > 3.0 after multiple testing correction.
</Warning>

* **Significant alpha** (`|t| >= 2`):The strategy generates returns beyond systematic factor exposure. The alpha cannot be easily replicated with factor ETFs.
* **Insignificant alpha** (`|t| < 2`):Returns may be explained by factor exposure alone. Extending the backtest period may resolve this.

### Factor Loadings

| Factor   | What it means                                                               |
| -------- | --------------------------------------------------------------------------- |
| `Mkt-RF` | Market beta. Loading > 1 amplifies both gains and losses.                   |
| `SMB`    | Size factor. Positive = small-cap tilt. Negative = large-cap tilt.          |
| `HML`    | Value factor. Positive = value tilt (cheap stocks). Negative = growth tilt. |
| `Mom`    | Momentum factor. Positive = momentum tilt (recent winners).                 |

The magnitude of each loading indicates exposure strength. A loading of 0.5 on HML means 0.5 units of value factor exposure per unit of portfolio return.

### R-squared

* **High R-squared (> 0.7)**:Most return variance is explained by the four factors. The strategy is largely replicable with factor ETFs.
* **Low R-squared (\< 0.4)**:Significant idiosyncratic return. The strategy is doing something the factors don't capture.

## What to do next

<CardGroup cols={2}>
  <Card title="High R-squared, low alpha" icon="chart-pie">
    The strategy is a factor bet. Consider whether you can get equivalent exposure cheaper with factor ETFs (e.g. VLUE for HML, MTUM for momentum).
  </Card>

  <Card title="Significant alpha" icon="trophy">
    The strategy has genuine edge. Consider increasing allocation, then validate with out-of-sample data or paper trading.
  </Card>

  <Card title="Compare strategies" icon="code-compare">
    Run factor analysis on multiple strategies to find the one with the most differentiated return source.
  </Card>

  <Card title="Extend the backtest" icon="calendar">
    If alpha t-stat is close to 2 but not quite there, run a longer backtest to increase statistical power.
  </Card>
</CardGroup>