fawp-index 0.20.0

FAWP Alpha Index — Information-Control Exclusion Principle detector

fawp-index

---

🔴 Try it live — no install needed

→ fawp-scanner.info

Scan any stock, ETF, or crypto in your browser. Enter tickers → Fetch data → See regime detection in real time.

Powered by fawp-index v0.20.0 · pip install it for full local control

---

Your model still predicts. But you've already lost control.

fawp-index detects the moment a system crosses into the Information-Control Exclusion Principle regime — where predictive information persists but the ability to act on it has collapsed.

Domain	What predicts	What collapses
📈 Quant finance	Factor alpha signal	Market execution edge (crowding)
🌀 Dynamical systems	State forecasts	Stabilising control authority
🌊 Weather / climate	Forecast skill	Intervention window
🌍 Seismic	Precursor signal	Stress release control
🤖 ML systems	Model predictions	Ability to retrain / intervene

---

What it looks like

Scanner tab — severity pills, sparklines, ODW bars:

Each row shows the asset, severity tier (FAWP 🔴 / HIGH / WATCH / CLEAR), a 6-window score sparkline with trend arrow, and a proportional ODW bar showing where in the τ range the detection window sits.

Click any flagged asset to expand the "Why flagged?" card.

Leaderboard — four ranked categories always visible below the table:

Top FAWP · Rising Risk · Collapsing Control · Strongest ODW

Curves tab — interactive MI curves, leverage gap fill, ODW shading:

Select any asset + window. Pred MI (amber) vs Steer MI (blue dashed). Red shading = ODW. Dotted line = ε threshold.

---

Live demo

fawp-scanner.info — interactive dashboard running on live data. No install required. Scan equities, crypto, and sectors in your browser.

---

Install

pip install fawp-index                   # core
pip install "fawp-index[plot]"           # + matplotlib figures
pip install "fawp-index[dashboard]"      # + Streamlit dashboard
pip install "fawp-index[fast]"           # + Numba JIT (5–15× faster null scans)
pip install "fawp-index[all]"            # everything

---

One-command demo

pip install "fawp-index[dashboard]"
fawp-demo                          # opens browser with synthetic data instantly
fawp-demo --asset BTC-USD SPY QQQ  # real tickers via yfinance

No CSV. No API key. No config. Just install and run.

---

60-second quickstart

import numpy as np
from fawp_index import FAWPAlphaIndex

# Simulate: strong prediction, collapsed steering = FAWP
pred   = np.random.randn(5000)
future = pred[20:] + np.random.randn(4980) * 0.3   # forecastable
action = np.random.randn(4980) * 0.001              # near-zero = no steering
obs    = np.random.randn(4980) * 0.1

result = FAWPAlphaIndex().compute(pred[:4980], future, action, obs)
print(result.summary())
result.plot()   # pip install "fawp-index[plot]"

Output:

==================================================
FAWP Alpha Index v2.1 — Results Summary
==================================================
Agency Horizon (tau_h):  1
Peak Alpha Index:        0.2847
Peak Alpha at tau:       3
FAWP regime detected:   YES
FAWP tau range:          [1, 2, 3, 4, 5]
==================================================

---

Run the benchmarks (zero data needed)

The fastest way to see it work:

pip install "fawp-index[plot]"
python -c "
from fawp_index import run_benchmarks
suite = run_benchmarks()
print(suite.summary())
suite.verify_all()
"

Case                  Expected   Detected   Result
----------------------------------------------------
clean_control         FAWP       FAWP       ✅ PASS
prediction_only       none       none       ✅ PASS
control_only          none       none       ✅ PASS
noisy_false_positive  none       none       ✅ PASS
delayed_collapse      FAWP       FAWP       ✅ PASS
All 5 assertions passed.

---

Market scanner

import pandas as pd
from fawp_index.market import scan_fawp_market

df   = pd.read_csv("SPY.csv", parse_dates=["Date"], index_col="Date")
scan = scan_fawp_market(df, ticker="SPY", close_col="Close", volume_col="Volume")

print(scan.summary())
scan.plot(prices=df["Close"])
scan.to_html("spy_fawp.html")

Financial interpretation:

• pred channel I(returnₜ ; returnₜ₊Δ) — is the market still forecastable?
• steer channel I(signed_flowₜ ; returnₜ₊τ) — do your orders still move price?
• FAWP window — you can forecast direction, but your orders no longer move price

---

Watchlist scanner

from fawp_index.watchlist import scan_watchlist

# Fetch and scan automatically via yfinance:
result = scan_watchlist(
    ["SPY", "QQQ", "GLD", "BTC-USD", "ETH-USD"],
    period     = "2y",
    timeframes = ["1d", "1wk"],
)

result.rank_by("score")        # strongest current regime score
result.rank_by("gap")          # widest leverage gap (bits)
result.rank_by("persistence")  # longest active regime
result.active_regimes()        # only currently flagged assets
result.top_n(5, "score")

result.to_html("watchlist.html")

---

Saved watchlists

# Create and persist named watchlists
fawp-watchlist create tech AAPL MSFT NVDA AMD
fawp-watchlist create crypto BTC-USD ETH-USD SOL-USD --period 1y
fawp-watchlist scan tech --leaderboard --explain --out tech.html
fawp-watchlist list
fawp-watchlist show tech

---

Leaderboard

from fawp_index.leaderboard import Leaderboard

result = scan_watchlist(["SPY", "QQQ", "GLD", "BTC-USD"], period="2y")
lb = Leaderboard.from_watchlist(result)

print(lb.summary())
lb.to_html("leaderboard.html")

Four ranked categories: Top FAWP · Rising Risk · Collapsing Control · Strongest ODW

---

Explain score

from fawp_index.explain import explain_asset

result = scan_watchlist(["SPY", "QQQ"], period="2y")
top = result.rank_by("score")[0]
print(explain_asset(top))

============================================================
  SPY  [1d]
============================================================
  FAWP Score   : 81/100
  Status       : 🔴 HIGH  —  FAWP ACTIVE  (12 days)
------------------------------------------------------------
  Prediction   : elevated (0.142 bits)
  Steering     : collapsed (0.0001 bits ≈ zero)
  Leverage gap : large (0.141 bits)
  ODW          : detected (τ = 1–12)
------------------------------------------------------------
  Why flagged:
    • FAWP active 12 days — score rising 3 consecutive windows
    • Steering MI below ε at 11 of 12 tau values
    • Leverage gap 0.141 bits
    • ODW spans 12 tau steps (τ 1–12)
------------------------------------------------------------
  Recommendation:
  Prediction persists but execution edge has collapsed.
  Reduce size or investigate crowding / latency conditions.
============================================================

---

Alerts

from fawp_index.alerts import AlertEngine, AlertSeverity

engine = AlertEngine(
    gap_threshold=0.05,
    cooldown_hours=4,                        # suppress repeats within 4h
    min_consecutive_windows=2,               # only fire after 2 flagged windows
    score_change_threshold=0.02,             # only if score changed ≥ 0.02
    min_severity=AlertSeverity.MEDIUM,       # ignore LOW signals
    state_path="fawp_state.json",
)
engine.add_terminal()
engine.add_telegram(token="BOT_TOKEN", chat_id="CHAT_ID")
engine.add_discord(webhook_url="https://discord.com/api/webhooks/...")
engine.add_email(smtp_host="smtp.gmail.com", username="[e-mail]",
                 password="app_password", to_addrs=["[e-mail]"])
engine.add_webhook("https://hooks.slack.com/services/...")

result = scan_watchlist(dfs)
alerts = engine.check(result)
engine.daily_summary(result)

---

Significance testing

from fawp_index import ODWDetector, fawp_significance

odw = ODWDetector.from_e9_2_data()
sig = fawp_significance(odw, n_bootstrap=200)

print(sig.summary())
# p_fawp=1.000  p_null=0.145  significant=YES
# ci_tau_h=[31,31]  ci_peak_gap=[1.538, 1.562] bits

---

Benchmark suite

from fawp_index import run_benchmarks

suite = run_benchmarks()
suite.verify_all()
suite.to_html("benchmarks.html")

Case	Expected	Description
clean_control	✅ FAWP	Textbook: steering collapses, prediction survives
prediction_only	❌ None	Predictable system, no steering channel
control_only	❌ None	Active controller, no predictive horizon
noisy_false_positive	❌ None	Noisy stable — designed to trap detectors
delayed_collapse	✅ FAWP	Fast-collapsing unstable system, narrow ODW

---

Dashboard

pip install "fawp-index[dashboard]"
fawp-dashboard                     # opens on http://localhost:8501

# Or from repo:
cd dashboard && streamlit run app.py

Dashboard features (v0.20.0):

• Severity pills (FAWP / HIGH / WATCH / CLEAR) with pulsing indicators
• Sparkline score trend per asset with ▲/▼ arrows
• ODW proportional bar showing window position in τ range
• Filter bar (All / FAWP only / Watching / Rising)
• Inline "Why flagged?" explain cards
• Mini leaderboard (Top FAWP · Rising Risk · Collapsing Control · Strongest ODW)
• Scan metadata: timestamp, duration, ε, window, τmax

---

CLI

# Detect FAWP in a CSV:
fawp-index detect   data.csv --state price --action trade_size --plot

# Rolling market scan:
fawp-index market   SPY.csv --close Close --volume Volume --out report.html

# Scan a watchlist:
fawp-index watchlist spy.csv qqq.csv gld.csv --labels SPY QQQ GLD --out wl.html

# Scan with leaderboard + explain:
fawp-scan --preset equities --leaderboard --explain

# Saved watchlists:
fawp-watchlist create tech AAPL MSFT NVDA AMD
fawp-watchlist scan tech --rank-by gap --out tech.html

# Significance test:
fawp-index significance data.csv --state price --action trade

# Benchmark suite:
fawp-index benchmarks --verify

# Version:
fawp-index version

---

DataFrame API

from fawp_index import fawp_from_dataframe, fawp_rolling

# Single detection:
result = fawp_from_dataframe(df, pred_col="factor", action_col="trade", future_col="fwd_return")

# Rolling — adds fawp_pred_mi, fawp_steer_mi, fawp_gap, fawp_in_regime columns:
df_annotated = fawp_rolling(df, pred_col="returns", action_col="volume")
df_annotated[df_annotated["fawp_in_regime"]]

---

Calibration constants

All calibration anchors are in fawp_index.constants, derived directly from the published papers:

from fawp_index.constants import (
    EPSILON_STEERING_RAW,      # 0.01 bits — raw steering threshold (E8/E9 standard)
    EPSILON_STEERING_CORRECTED,# 1e-4 bits — post-null-correction threshold
    BETA_NULL_QUANTILE,        # 0.99 — conservative null floor quantile
    PERSISTENCE_WINDOW_M,      # 5 — Sm(τ) window width
    PERSISTENCE_RULE_M,        # 3 — m-of-n gate (E9.1 confirmed)
    PERSISTENCE_RULE_N,        # 4
    FLAGSHIP_A,                # 1.02 — E8/E9 canonical unstable regime
    FLAGSHIP_K,                # 0.8
    TAU_PLUS_H_E9,             # 31 — E9.2 agency horizon
    TAU_F_E9,                  # 36 — E9.2 functional cliff
    PEAK_GAP_BITS_E9,          # 1.55 bits — E9.2 peak leverage gap
)

---

The mathematics

The FAWP Alpha Index v2.1 (SECRET Eq. 9):

α₂(τ) = 𝟙[τ≥1] · g(τ) · (Sₘ(τ) − Ĩ_steer(τ)) · (1 + κ · R_log(τ))

• g(τ) — gate: fires when Sₘ(τ) > η AND Ĩ_steer(τ) ≤ ε
• Sₘ(τ) — windowed-min corrected predictive MI (multi-step persistence)
• Ĩ_steer(τ) — null-corrected steering MI
• R_log(τ) — log-slope resonance amplifier near the horizon
• Calibrated: β=0.99, m=5, η=ε=10⁻⁴ bits, δ=10⁻⁶

The agency horizon τ_h is where steering MI first falls below ε. Near τ_h, predictive MI surges — the empirical signature of the Information-Control Exclusion Principle.

---

Citation

@software{clayton2026fawpindex,
  author  = {Ralph Clayton},
  title   = {fawp-index: Information-Control Exclusion Principle detector},
  year    = {2026},
  version = {0.20.0},
  url     = {https://github.com/DrRalphClayton/fawp-index},
  doi     = {10.5281/zenodo.18673949}
}

@article{clayton2026agency,
  author = {Ralph Clayton},
  title  = {Forecasting Without Power: Agency Horizons and the Leverage Gap},
  year   = {2026},
  doi    = {10.5281/zenodo.18663547}
}

---

Links

• 🌐 Live demo: fawp-scanner.info
• 📦 PyPI: pypi.org/project/fawp-index
• 📂 GitHub: github.com/DrRalphClayton/fawp-index
• 📄 Paper (E1–E7): doi:10.5281/zenodo.18663547
• 📄 Paper (E8): doi:10.5281/zenodo.18673949
• 📗 Book: Forecasting Without Power — Ralph Clayton (2026)
• 📊 Docs: docs/ — quickstart, examples, market, watchlist, alerts, significance, benchmarks, dashboard

---

Module docs

File	Contents
docs/quickstart.md	Getting started guide
docs/examples.md	Example gallery — common use cases
docs/market.md	Market scanner API
docs/watchlist.md	Watchlist scanner + ranking
docs/alerts.md	Alert engine + channel setup
docs/significance.md	Significance testing
docs/benchmarks.md	Benchmark cases + verification
docs/dashboard.md	Dashboard install + deploy

---

MIT License · Ralph Clayton · 2026