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

# Factor Engine

> Quantitative factor mining and evaluation for systematic strategies

The factor engine computes quantitative signals (factors) from market data and evaluates their predictive power. Factors provide systematic, backtestable features for strategy development.

<Note>
  The factor engine is opt-in. Set `FACTOR_ENGINE_ENABLED=true` in your environment to activate it. It increases CPU and memory usage due to continuous computation across all tracked symbols.
</Note>

## What are factors?

A **factor** is a numeric value derived from market data that aims to predict future returns. Factors capture properties like momentum, mean reversion, volatility clustering, and volume patterns.

Unlike ad-hoc technical indicators, factors are:

* **Normalized** — comparable across different symbols and time periods
* **Evaluated** — effectiveness is measured through statistical metrics
* **Composable** — combined into multi-factor strategies

## Built-in factors

The engine includes 64 expressions organized across six categories:

<Tabs>
  <Tab title="Trend">
    | Factor              | Expression               | Description                          |
    | ------------------- | ------------------------ | ------------------------------------ |
    | `trend_ema_cross`   | `ema(20) / ema(50) - 1`  | EMA crossover momentum               |
    | `trend_strength`    | `adx(14)`                | Trend strength via ADX               |
    | `trend_direction`   | `sign(close - ema(200))` | Binary trend direction               |
    | `price_momentum`    | `roc(close, 20)`         | 20-period rate of change             |
    | `trend_persistence` | `hurst(close, 100)`      | Hurst exponent for trend persistence |
  </Tab>

  <Tab title="Momentum">
    | Factor           | Expression           | Description               |
    | ---------------- | -------------------- | ------------------------- |
    | `rsi_factor`     | `normalize(rsi(14))` | Normalized RSI            |
    | `macd_momentum`  | `macd_hist(12,26,9)` | MACD histogram            |
    | `stoch_momentum` | `stoch_k(14,3)`      | Stochastic oscillator     |
    | `roc_5`          | `roc(close, 5)`      | Short-term rate of change |
    | `williams_r`     | `williams_r(14)`     | Williams %R               |
  </Tab>

  <Tab title="Volatility">
    | Factor         | Expression          | Description                         |
    | -------------- | ------------------- | ----------------------------------- |
    | `realized_vol` | `std(returns, 20)`  | 20-period realized volatility       |
    | `atr_factor`   | `atr(14) / close`   | Normalized ATR                      |
    | `bb_width`     | `bbwidth(20, 2)`    | Bollinger Band width                |
    | `vol_regime`   | `vol(20) / vol(60)` | Short vs long-term volatility ratio |
    | `garman_klass` | `gk_vol(20)`        | Garman-Klass volatility estimator   |
  </Tab>

  <Tab title="Volume">
    | Factor               | Expression                 | Description                |
    | -------------------- | -------------------------- | -------------------------- |
    | `volume_momentum`    | `volume / sma(volume, 20)` | Volume relative to average |
    | `obv_slope`          | `slope(obv, 20)`           | On-balance volume trend    |
    | `vwap_deviation`     | `(close - vwap) / atr(14)` | Deviation from VWAP        |
    | `volume_price_trend` | `vpt(20)`                  | Volume-price trend         |
    | `mfi_factor`         | `mfi(14)`                  | Money flow index           |
  </Tab>

  <Tab title="Statistical">
    | Factor            | Expression                 | Description                  |
    | ----------------- | -------------------------- | ---------------------------- |
    | `skewness`        | `skew(returns, 60)`        | Return distribution skewness |
    | `kurtosis`        | `kurt(returns, 60)`        | Return distribution kurtosis |
    | `z_score`         | `zscore(close, 50)`        | Z-score vs rolling mean      |
    | `autocorrelation` | `autocorr(returns, 1, 20)` | Lag-1 return autocorrelation |
    | `mean_reversion`  | `-1 * zscore(close, 20)`   | Mean reversion score         |
  </Tab>

  <Tab title="Composite">
    | Factor             | Expression                           | Description                  |
    | ------------------ | ------------------------------------ | ---------------------------- |
    | `quality`          | `sharpe(20) * (1 - max_dd(20))`      | Risk-adjusted quality        |
    | `momentum_quality` | `roc(20) * (1 / vol(20))`            | Volatility-adjusted momentum |
    | `trend_vol`        | `adx(14) * atr_factor`               | Trend strength × volatility  |
    | `composite_score`  | `rank_avg(momentum, quality, trend)` | Multi-factor composite       |
  </Tab>
</Tabs>

## Custom factor creation

Define custom factors using the expression engine:

```bash theme={null}
curl -X POST https://api.production.hyperoru.com/api/factors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_momentum",
    "expression": "roc(close, 10) * (volume / sma(volume, 20))",
    "description": "Volume-weighted 10-period momentum"
  }'
```

## Expression engine syntax

The expression engine supports arithmetic operations, built-in functions, and nesting:

| Syntax     | Example                          | Description                   |
| ---------- | -------------------------------- | ----------------------------- |
| Arithmetic | `a + b`, `a * b`, `a / b`        | Standard math operators       |
| Functions  | `ema(close, 20)`                 | Technical indicator functions |
| Nesting    | `ema(rsi(14), 5)`                | Compose functions             |
| Constants  | `100`, `2.5`                     | Literal numbers               |
| References | `close`, `volume`, `high`, `low` | Price/volume fields           |

## Factor effectiveness metrics

Each factor is continuously evaluated for predictive power:

| Metric                           | Description                                                         | Good Value          |
| -------------------------------- | ------------------------------------------------------------------- | ------------------- |
| **IC** (Information Coefficient) | Correlation between factor values and forward returns               | > 0.03              |
| **ICIR** (IC Information Ratio)  | Mean IC / Std(IC), measures consistency                             | > 0.5               |
| **Win Rate**                     | Fraction of periods where factor direction matches return direction | > 55%               |
| **Turnover**                     | How frequently factor rankings change                               | Depends on strategy |

```bash theme={null}
curl "https://api.production.hyperoru.com/api/factors/{factor_id}/effectiveness?lookback=90d" \
  -H "Authorization: Bearer $TOKEN"
```

## Factor computation pipeline

```mermaid theme={null}
graph LR
    A[Market Data] --> B[Expression Parser]
    B --> C[Factor Computation]
    C --> D[Normalization]
    D --> E[Effectiveness Eval]
    E --> F[FactorCache]
    F --> G[Strategies & API]
```

The pipeline runs on a configurable schedule (typically every 1–5 minutes) and caches results in the FactorCache for instant access by strategies and the API.