Skip to content

factrix.metrics.mfe_mae

MFE/MAE — per-event price path excursion analysis.

Answers: "what does the price path look like after events?"

Requires bar-by-bar price data within the event window. If price is not available, compute_mfe_mae returns an empty DataFrame and mfe_mae returns a short-circuit MetricResult (value=NaN, metadata["reason"]) — never None.

Metrics

mfe_mae — aggregate summary (p50, p75, ratio)

Notes

Pipeline. Per-event MFE / MAE excursion over a fixed window (per-event step), then cross-event quantile / ratio summary; descriptive (no formal H₀).

factrix.metrics.mfe_mae.mfe_mae 

mfe_mae(mfe_mae_df: DataFrame) -> MetricResult

Aggregate MFE/MAE statistics.

The static event floor (sample_threshold=SampleThreshold(min_events=MIN_EVENTS_HARD)) gates the summary on the per-event MFE/MAE count. Pre-flight reads the raw non-zero factor count as a loose upper bound.

Reports MFE/MAE ratio as the primary value — higher is better (favorable excursion exceeds adverse excursion).

Parameters:

Name Type Description Default
mfe_mae_df DataFrame

Output of compute_mfe_mae().

 required

Returns:

Type Description
MetricResult

MetricResult with value=MFE_p50/|MAE_p75| ratio. On insufficient
MetricResult

data (empty input or fewer than MIN_EVENTS_HARD rows), returns a
MetricResult

short-circuit MetricResult (value=NaN, metadata["reason"]
MetricResult

set) so all metrics share a single return contract.
Notes

Headline ratio = quantile(mfe, 0.50) / |quantile(mae, 0.75)|. Z-normalised siblings mfe_z_p50 / mae_z_p75 / mfe_mae_ratio_z are reported when mfe_z / mae_z are present and pass the same minimum-events threshold.

factrix pairs the MFE median against the MAE 75th percentile (not the median) because the asymmetric quantile pair captures risk-adjusted favourability: a strategy with median favourable excursion that exceeds typical adverse excursion in the worst quartile is the practically useful regime.

Examples:

Chain from :func:compute_mfe_mae output:

>>> import factrix as fx
>>> from factrix.preprocess import compute_forward_return
>>> from factrix.metrics.mfe_mae import compute_mfe_mae, mfe_mae
>>> panel = compute_forward_return(
...     fx.datasets.make_event_panel(n_assets=50, n_dates=400, seed=0),
...     forward_periods=5,
... )
>>> per_event = compute_mfe_mae(panel, window=20)
>>> result = mfe_mae(per_event)
>>> result.name == ""
True

Use cases

  • Peak favourable vs adverse excursion

    For each event, find the peak gain (MFE) and peak loss (MAE) over the post-event window, plus bars-to-peak. Descriptive of the shape of the post-event price path, not just its endpoint.

  • Risk-adjusted favourability

    Headline ratio \(\mathrm{MFE}_{p50} / |\mathrm{MAE}_{p75}|\) pairs the median favourable excursion against the 75th percentile adverse excursion — captures whether typical upside exceeds worst- quartile downside.

  • Cross-horizon / cross-regime comparison

    Z-scored variants mfe_z / mae_z (divided by \(\hat\sigma \sqrt{W}\)) absorb the \(\sqrt{W \cdot \sigma^2}\) horizon scaling of order statistics — the apples-to-apples quantity for comparing event setups across windows or volatility regimes.

Choosing a function

Goal Function
Per-event MFE / MAE / bars-to-peak table for downstream cuts compute_mfe_mae
Aggregate distribution summary (quantiles, ratio, z-scored siblings) mfe_mae

Worked example — per-event excursion then summary

compute_mfe_mae → mfe_mae on a synthetic event panel

import factrix as fx
from factrix.metrics.mfe_mae import compute_mfe_mae, mfe_mae

panel = fx.datasets.make_event_panel(
    n_assets=200, n_dates=500, event_rate=0.02,
    post_event_drift_bps=40.0, seed=2024,
)

per_event = compute_mfe_mae(panel, window=20, estimation_window=60)
print(per_event.head())
# ┌────────────┬──────────┬────────┬─────────┬────────┬────────┐
# │ date       ┆ asset_id ┆  mfe   ┆  mae    ┆ mfe_z  ┆ mae_z  │
# ├────────────┼──────────┼────────┼─────────┼────────┼────────┤
# │ 2024-01-04 ┆ A0001    ┆ 0.031  ┆ -0.018  ┆  0.74  ┆ -0.43  │
# │  ...       ┆ ...      ┆  ...   ┆  ...    ┆  ...   ┆  ...   │
# └────────────┴──────────┴────────┴─────────┴────────┴────────┘

out = mfe_mae(per_event)
print(out.value,
      out.metadata["mfe_p50"], out.metadata["mae_p75"],
      out.metadata.get("mfe_mae_ratio_z"))
# 1.27  0.024  -0.019  1.31   (approximate)

See also