🎨 RevertIQ — UX & Experience Specification
- Design Philosophy
RevertIQ should feel:
Quant-trusted: precise numbers, transparent assumptions, and confidence intervals everywhere.
Developer-native: clean JSON, instant copy-to-curl, deterministic runs.
Analyst-readable: tables and visualizations that narrate statistical truth, not hype.
Operator-actionable: simple, at-a-glance summaries that say “when and how to act.”
Educational: clear “Explain Mode” that bridges math → intuition.
Think: Bloomberg Terminal meets Jupyter Notebook, but simplified and API-first.
- Interaction Models Mode Primary Audience Purpose Interface API (primary) Developers, Platforms Programmatic analysis, integration REST, JSON CLI Builders, Operators Fast testing, offline validation Command line Web Dashboard (optional) Analysts, Educators Visualization, reports, explainability Web UI / Notebooks Webhook / Live Tiles Platforms, Prop Desks Monitoring & alerting Push feed
- Persona Journeys 🧱 Persona 1: Quant Developer (“The Builder”)
Goal: Integrate RevertIQ as a pipeline service for quant research or backtesting frameworks.
Experience:
Enters API key → authenticates CLI or SDK.
Submits a POST /analyze job.
Monitors job status (GET /analysis/{id} or webhook).
Consumes the ranked JSON list of best trading windows.
Optionally downloads the provenance and diagnostics block for model documentation.
UX Cues:
Minimalist CLI outputs (ranked table + stats).
Clear logs: data.hash matched, walk-forward complete, fdr=0.10.
CLI example output (human-readable)
Best Windows (OOS Sharpe) Tue 10:45–11:30 S=1.32 Ret/trade=3.4bp pFDR=0.03 t½=27m Wed 09:45–10:30 S=1.11 Ret/trade=2.8bp pFDR=0.07 t½=32m Thu 13:15–14:00 S=0.95 Ret/trade=2.1bp pFDR=0.09 t½=25m
Drift detected post 2025-03. Consider re-tuning monthly.
📊 Persona 2: Quant Researcher (“The Analyst”)
Goal: Deeply interpret and validate the statistical results.
Experience:
Loads the JSON/CSV into a notebook.
Plots heatmaps of Sharpe vs. day/time.
Inspects half-life histograms, FDR distributions.
Reads diagnostics.stationarity to confirm mean-reversion assumption validity.
Exports results for internal reports.
UX Emphasis:
Explainable metrics: everything has meaning (z-in, z-out, hold-cap).
Confidence scaffolding: always display CIs, trade counts, and adjusted p-values.
Reproducibility: “Data hash” and “RevertIQ version” clearly visible.
Visual Components:
Heatmap (DOW × Time Window) of Sharpe ratios
Half-life distribution chart
Cost sensitivity slope plot
Stationarity test summary panel (ADF/KPSS/Hurst)
⚙️ Persona 3: Algorithmic Trader / Prop Desk Operator (“The Operator”)
Goal: Identify and act on the best timeframes for mean-reversion trades.
Experience:
Dashboard view: “Top Reversion Windows” tile per ticker.
Filters: by spread sensitivity, significance, or regime.
Uses live webhooks for alerts: “AAPL — optimal reversion window (Tue 10:45–11:30) now active.”
Adjusts algo parameters or executes scalps accordingly.
UX Emphasis:
Speed and clarity: top 3 actionable windows, cost-adjusted.
Live readiness: color-coded window indicators (green = statistically active).
Mobile-friendly summary: “Edge Index” badge summarizing Sharpe × Significance.
Dashboard Tile Example:
📈 AAPL Mean Reversion Snapshot
Best Historical Window: Tue 10:45–11:30
Expected Return/trade: +3.4 bp (after costs)
OOS Sharpe: 1.32 | Confidence: 97% | t½: 27m
Drift Status:
🧩 Persona 4: Fintech Integrator (“The Platform”)
Goal: Embed RevertIQ data for end-users within their own dashboards.
Experience:
Queries /v1/analyze or /v1/analysis/{id}/windows for data.
Uses fields= query parameter to select minimal JSON fields (for lightweight UI).
Optionally subscribes to a webhook for new analysis runs.
Displays RevertIQ attribution per SLA.
UX Emphasis:
Embeddability: consistent schemas, human-readable field names.
Branding: white-label JSON; optional “powered by RevertIQ” logo pack.
Visualization kit: pre-built DOW/time heatmap component (React + D3 export).
Integration Example (Embedded Widget):
🟩 Tue 10:45–11:30 +3.4 bp | 1.32 Sharpe | 97% confidence 🟨 Wed 09:45–10:30 +2.8 bp | 1.11 Sharpe | 93% 🟨 Thu 13:15–14:00 +2.1 bp | 0.95 Sharpe | 90%
🎓 Persona 5: Quant Educator / Content Creator (“The Teacher”)
Goal: Use RevertIQ data to demonstrate mean-reversion concepts visually.
Experience:
Enables explain_mode=true in API or dashboard.
Receives narrative-form output explaining statistical meaning.
Downloads pre-rendered visuals (PNG/SVG) for slides or articles.
Example Explain Mode Text:
“Between 2023 and 2025, AAPL showed the strongest mean-reversion activity on Tuesdays between 10:45 and 11:30 AM. On average, price deviations of −1.5σ reverted to the mean within ~27 minutes, producing an average per-trade return of +3.4 basis points (after costs). Statistical significance remained above 95%, suggesting persistent intraday liquidity-driven reversion.”
Explain Mode Output Structure:
{ "explain_mode": { "summary": "AAPL exhibits statistically significant mean reversion mid-morning Tuesdays.", "narrative": "...", "visuals": ["heatmap_url", "half_life_plot_url"], "concepts": [ {"term":"Z-Score","definition":"Normalized deviation of price from its rolling mean."}, {"term":"Half-life","definition":"Expected time for deviation to revert halfway to equilibrium."} ] } }
- Cross-Persona Design Principles Principle Description Transparency over mystery Every number must be traceable to a formula or statistical test. Rigor in storytelling Explain results with math and plain English; avoid "AI magic". Low friction access One API call or one CLI command → clear results. Deterministic reproducibility Hashes, versioning, and parameter freezing baked in. Progressive disclosure Simple summary first → deeper diagnostics on demand. User autonomy Let the quant control significance levels, lookbacks, costs. Visual confidence encoding Color, shading, or CI bars show robustness—not raw performance alone.
- Key UX Deliverables (MVP) Deliverable Purpose Target Persona JSON + Heatmap UI Interactive visualization of DOW × Time Sharpe Analyst Top Window Card Compact summary for dashboards / alerts Operator Explain Mode Narrative Education / onboarding Teacher CLI Pretty Table Quick discovery / validation Builder Widget SDK (React) Embeddable UI for platforms Integrator
- Future UX Expansions
“Live Scout” Mode: WebSocket stream comparing live market z-score vs. top historical windows → real-time alert when reversion thresholds align.
Multi-Ticker Matrix: Cross-sectional dashboard to rank all tracked tickers by current mean-reversion health.
Interactive Regression Surface: Adjustable 3D chart (z-in × z-out × Sharpe) for model introspection.
Drift Monitor: Historical timeline of Sharpe deterioration → auto alerts when re-optimization is required.