Skip to main content

Range Analysis — Overview

Range Analysis measures the high–low range of a repeating time window and shows how price moved inside it. The window can be a slice of each trading day, an expiry cycle, or a calendar span.

Page/range-analysis (Developer sidebar, DEVELOPER rank)
Frontendfrontend/src/pages/RangeAnalysis/
Backendbackend/app/api/range_analysis.py, prefix /api/range-analysis, same DEVELOPER access check as the other data routes
RulesNeoWave wave-chart rules: Wave Chart Construction (NeoWave), mirrored in backend/CLAUDE.md section 4

Architecture​

Tab 1 (User Input) rangeEngine.js (pure JS) backend /api/range-analysis
───────────────── ──────────────────────── ───────────────────────────
exchange / symbol ───────────────────────────────────────────────────────▶ /symbols (dropdown)
expiry basis ───────────────────────────────────────────────────────▶ /expiries (expiry calendar)
(always) ───────────────────────────────────────────────────────▶ /calendar (holidays, sessions)
time frame rules ─▶ validateConfig / resolveWindows ─▶ right panel: rule, next windows, all windows
[Run] ─▶ planRun → windows + {from, to, step}
│ NSE / MCX ──────────────────────▶ /prices (base bars)
│ BSE → generateBars (mock)
buildResult ◀───────┘
Tabs 2 and 3 ◀─ { cfg, windows[ {label, start, end, candle, bars, base, …} ], prices }

The window logic runs in the browser. rangeEngine.js holds all of it: validation, window resolution, NeoWave order, and aggregation. The backend only supplies data. V2 may move planRun / buildResult server-side for very large 1-minute ranges.

Frontend files​

FileRole
RangeAnalysis.jsxPage shell and tabs. Loads symbols, expiries and the calendar (React Query, 30 min cache), and runs the analysis (fetches /prices or uses mock data for BSE).
rangeEngine.jsConstants, validation, resolveWindows (raw windows → no-overlap → session cut), expiry and trading calendars, planRun, buildResult, NeoWave orderOf, wavePoints, countMonowaves, childBars, mock bar generator.
InputTab.jsxTab 1 form and right panel: rule, next windows, all windows, named errors.
CandleTab.jsx / WaveTab.jsxTabs 2 and 3 (two-column layout).
ExcelChart.jsx / SidePanes.jsxExcel-style child chart and the right-hand child and details panes.

The AmiBroker-style canvas chart itself (candle / bar / wave / line, selector, B/E range markers, zoom and pan) is no longer page-specific — it moved to the shared frontend/src/components/TEChart.jsx so other pages (e.g. Corporate Actions) can reuse it. See Frontend Guide "Reusable Components" for its full props reference.

Time convention​

Every timestamp is exchange wall-clock time stored as if it were UTC, in seconds: 09:15 IST is stored as 09:15Z. The charts can then show exchange time without any timezone conversion. The backend returns /prices timestamps in the same convention.

Window boundaries: windows are half-open on the bar start time, so a bar belongs to a window when start <= t < end.

API reference​

All endpoints are GET requests.

/symbols?exchange=NSE|MCX​

Symbols for the dropdown.

  • NSE: index underlyings (scr_master typ 2) that have index futures.
  • MCX: active symbols only — a typ = 20 row with a contract that has not expired (edate >= CURRENT_DATE) and rows in scr_mcxsp_eod. That's 28 of the 151 rows on the VPS; the spot condition drops MCXBULLDEX / MCXMETLDEX. The spot condition is skipped if the spot table doesn't exist.

/expiries?exchange=&symbol=&basis=FUT|OPT​

Returns {monthly, weekly, weeklyFirst, weeklyLast, dataFrom, dataTo}.

  • NSE: monthly expiries = index futures expiries. Weekly expiries = option expiries that are not monthly, fall on or before the last futures expiry, are more than 3 days from any monthly expiry, and are within 14 days of another weekly candidate.
  • MCX: futures or options expiries, depending on basis. There are no weekly expiries.

/calendar?exchange=NSE|BSE|MCX​

Returns {holidays, specialSessions, holidaysTo, latestEod}.

  • holidays: full closures. For MCX, only rows that are closed in both sessions.
  • specialSessions: days with their own hours:
    • kind: "special" — specialdays rows (weekend sessions, Muhurat);
    • kind: "partial" — MCX evening-only days (17:00 to close): explicit session-flag rows, plus NSE weekday holidays that are not MCX full holidays. Dates after holidaysTo are marked assumed.
  • holidaysTo: how far the calendar is known. For MCX this is the later of the newest holiday row and the latest MCX EOD date, because MCX holidays are derived from traded dates. After the 2026-09-26 rebuild, the newest row is 2026-04-03 but the calendar is known to 2026-09-23.
  • BSE uses the NSE rows.

/prices?exchange=NSE|MCX&symbol=&from=&to=&step=1|75​

Returns base bars as columns: {source, resolution, count, bars: {t, o, h, l, c}}.

  • NSE: spot from the IEOD Parquet store via Con_Price_Getter (nseieod rule 2).
    • GDFL stamps each bar's end time (09:15:59), so times are floored to the bar start.
    • With step=75, bars are grouped from 09:15.
    • A symbol with no spot data returns 404 (for example FINNIFTY today). There is no fallback to futures, because NeoWave requires spot.
  • MCX: spot daily bars from scr_mcxsp_eod, with t set to the day at 09:00. If the reference database has no such table, it is read from the local database.
  • BSE: not served; the page uses mock prices.

Configuration​

# backend/.env (local development only)
RANGE_ANALYSIS_DB=VPS # read this router's data from the VPS DB; LOCAL = this machine
VPS_DB_REMOTE_HOST=103.178.166.188 # VPS_DB_HOST is "localhost" from the VPS's own point of view
  • Read-only: the VPS connection is opened with default_transaction_read_only=on, so the database refuses any write.
  • On the VPS itself (APP_ENV=VPS) the setting is ignored, because the app's own database already is the VPS one.
  • NSE prices always come from the IEOD store of the machine running the backend. A local store is only as current as its last pack.

Operations and troubleshooting​

SymptomCause / fix
Every /api/range-analysis/... call returns 404The backend was started before the router existed or changed. Restart it; run uvicorn with --reload in development. .env changes always need a manual restart.
"Holiday calendar not loaded: trading days are Mon to Fri"/calendar failed (often the 404 above).
Right panel says "Expiries: Mock calendar" for NSE/MCX/expiries failed. The note next to it shows the error.
Run says "No NSE spot data for X"That index has no spot series in the IEOD store.
NSE windows after a date are all skippedThe IEOD store ends there. Pack or sync newer data.
MCX prices stop at a datescr_mcxsp_eod is behind. See mcx_spot_downloader.py.
MCX evening-only days marked "assumed"They fall after holidaysTo. Rebuild the MCX calendar: python -m mcxeod.mcx_history.

Testing without the UI​

  • Backend: fastapi.testclient.TestClient(app) inside one with block. The pooled async connections don't survive the separate event loops that one-off calls create.
  • Engine: rangeEngine.js has no imports, so it runs directly in Node. Copy it to a .mjs file and call validateConfig, planRun, buildResult and so on with saved API responses.