Skip to main content

Range Analysis — Requirements Analysis (V1)

Status — V1 (2026-09-26)

Built: the full Tab 1 input model, the window resolver, real expiry dates, the real trading calendar, real prices for NSE and MCX, and the chart tabs (main chart + child chart + details). Mock: BSE prices and expiries only (no BSE data in the database).

Range Analysis measures the high–low range of a repeating time window. The window can be a slice of every trading day, an expiry cycle, or a calendar span. For each window it shows one candle, then lets you look inside that window bar by bar.

  • Page: /range-analysis (Developer sidebar), frontend/src/pages/RangeAnalysis/
  • API: /api/range-analysis/*, in backend/app/api/range_analysis.py, behind the same DEVELOPER access check as the other data routes

1. Tabs​

TabPurpose
1. User InputDefines the window rule (the crucial part — sections 2–5 below). A live right-hand panel shows the rule in plain English, the next 3 windows, every window in the history range (oldest first, with trading-day counts), and a list of problems named by field.
2. Candlestick ChartOne bar per window on the AmiBroker-style chart (Candle or Wave view, optional MA 20 and log scale). Summary tiles show average, median and max range, range %, how often the high came before the low, and how often the window closed up. A table lists every window and follows the selector. Double-click or Enter opens that window in Tab 3.
3. Wave ChartThe small-timeframe bars inside the selected window on the AmiBroker-style chart: Wave (NeoWave, see section 4a), Candle or Line. Log scale is on by default for Daily/Weekly/Monthly bars. Range markers (B / E or F12 / Shift+F12 at the selector, Shift+click, Esc to clear) pick a sub-span; the side panel shows its high/low with times, range, range %, change, which came first ("assumed" when applicable), and the number of monowaves. With no range set, it shows the whole window.

Chart (both tabs) — AmiChart.jsx, a hand-drawn canvas modelled on AmiBroker:

  • Layout: price pane with a right price axis and a bottom date axis. An info strip shows the selected bar's OHLC, change, range, which came first, MA, and "Bar n/N".
  • Selector (dashed line): click, ←/→ (Shift = 10 bars), Home/End.
  • Navigation: wheel or ↑/↓ to zoom, drag to pan, a crosshair with price and date tags, and a tag for the last close.
  • Themes: light and dark palettes; the dark one matches AmiBroker's #0b0e14 background.

2. Market inputs​

InputRule
TitleRequired (used when strategies are saved in V2).
ExchangeNSE / BSE / MCX. Session: NSE and BSE 09:15–16:00, MCX 09:00–23:59.
SymbolNSE: index underlyings with futures in scr_master (BANKNIFTY, FINNIFTY, MIDCPNIFTY, NIFTY, NIFTYNXT50). MCX: active symbols only — an unexpired contract and spot data (28 of the 151 typ = 20 rows on the VPS). BSE: a fixed list (SENSEX, BANKEX), because BSE has no contracts in the database.
History from / toTyped and shown as dd-mm-yyyy, with a calendar picker. Maximum span per time frame: Day 1 year, Week 2 years, Month 5 years, Quarter/Year 10 years.

3. Time frame and its options​

Time frames are Day, Week, Month, Quarter, Year. Week is disabled for MCX, because MCX has no weekly expiries.

Day​

Start time and end time, both inside the exchange session, with the start before the end. This gives one window per trading day.

Week / Month / Quarter / Year — pick exactly one option​

Option 1 — Expiry to Expiry. The window runs from the open of the first trading day after the previous expiry to the close of this expiry day. The expiry day belongs only to the window it ends. There are no other inputs.

Option 2 — Custom range (calendar).

Time frameFrom / To picker
WeekWeekday Mon … Sat
MonthCalendar day 1 … 31 (a day past the month end clamps to the last day)
QuarterWeek of quarter W1 … W13 (W1 = days 1–7 of the quarter, W13 runs to the quarter end)
YearMonth M1 … M12
  • Start time applies on the From day and end time on the To day. Together they form one continuous span.
  • From must be the same as or before To. When both are the same day, the end time must be after the start time.
  • Week and Month only: if the chosen day is not a trading day, the user chooses Previous or Next trading day. The roll stays inside the period, falling back to the other direction if needed.
  • Quarter and Year: From uses the first trading day of the chosen week or month, and To uses the last trading day.
  • There is no K factor in this option.

Option 3 — Expiry DFE / DTE (K factor).

  • K factor chooses the cycle: K=1 is the current cycle, K=2 the next, and so on. The limits are Week 5, Month 3, Quarter 3, Year 2.
  • From and To are each DFE n or DTE n, counted in trading days inside that K-th cycle:
    • 0 DFE = the previous expiry day
    • 0 DTE = the expiry day
    • Maximum n: Week 5, Month 23, Quarter 66, Year 253
  • Start and end time form one continuous span.
  • Validation: with the same anchor, From DFE must be ≤ To DFE, and From DTE must be ≥ To DTE. Mixing DTE → DFE gives a warning, and cycles where From lands after To are skipped.

Rules for every time frame​

  • Windows never overlap. Each window must start after the previous window's end. If it would start at or before it, it moves to the next trading session's open. If nothing is left, it is dropped and counted as "skipped".
  • Windows ending after History to are dropped. This mainly happens with K > 1, or a cycle that is still open, and there's no data for them yet.

4. Small time frame​

  • Bar size: 5 min, 15 min, 30 min, 1 hour, 75 min, 4 hour, Daily, Weekly, Monthly. Only sizes smaller than the time frame are allowed. Day allows only the intraday sizes; Week adds Daily; Month adds Weekly; Quarter and Year add Monthly.
  • Chart style: Line or Wave. This sets the default on Tab 3, and the user can switch there.
  • Size guard: the page refuses a run estimated at more than ~600,000 base bars (base = 1-min for intraday bar sizes, 75-min for Daily/Weekly/Monthly).

4a. Wave chart — NeoWave rules​

The wave chart follows the project's NeoWave rules in backend/CLAUDE.md section 4. The full construction guide is Wave Chart Construction (NeoWave). In summary:

  • Two points per bar: the high and the low, in the order they occurred, joined by straight lines at even time spacing. Log scale is available for long periods.

  • Order from smaller data (the STF), which always has at least 5 bars inside each chart bar:

    Chart bar (DTF)Order decided from
    5 min … 4 hour1-min bars (the IEOD store's resolution)
    Daily75-min bars (NeoWave STF)
    Weekly / MonthlyDaily bars (NeoWave STF), refined down to 75-min
  • The rule: if the high and low fall in different smaller bars, the earlier one goes first, and the order is confirmed. If they fall in the same smallest bar, the open/close rule decides and the bar is marked "assumed":

    • Open > Close → high first
    • Open < Close → low first
    • Open = Close → the extreme closer to the open goes first
  • Where "assumed" shows: hollow amber markers on the chart, a count above the chart, the tooltip, the "Made first" row, and a * in Tab 2's "First" column.

  • Monowaves: each run in one direction until the line reverses. The count is shown for the selected span.

  • Data: NeoWave requires cash/spot index data only, never futures. The prices are still mock in V1; V2 must use spot.

5. Expiry dates (real)​

GET /api/range-analysis/expiries?exchange=&symbol=&basis= returns the full list for one symbol. The page loads it automatically when the exchange or symbol changes and caches it for 30 minutes.

NSE (scr_master, typ 3 = FUTIDX, typ 5 = OPTIDX)

  • Monthly = index futures expiries. Quarterly uses the Mar/Jun/Sep/Dec monthly expiries, and Yearly uses Dec.
  • Weekly = option expiries that meet all of these:
    • not a futures expiry,
    • on or before the last listed futures expiry (this drops long-dated options such as NIFTY Dec-2030),
    • more than 3 days from any monthly expiry (futures and options sometimes disagree by a day around holidays, for example Mar-2018),
    • within 14 days of another weekly candidate (this drops isolated leftovers).
  • Result: NIFTY weeklies from 14-02-2019. BANKNIFTY weeklies end 13-11-2024 and FINNIFTY weeklies 19-11-2024. The page then warns: "BANKNIFTY weekly expiries stopped after 13-11-2024. Only monthly expiries exist after that date", and Week with a later history range is an error.
  • NIFTY's expiry weekday change from Thursday to Tuesday (Sep 2025) comes through automatically.

MCX (scr_mcx_master, typ 21/23 futures, typ 22/24 options)

  • There are no weekly expiries.
  • The UI asks "Expiries based on: Futures / Options", because MCX options expire a few days before futures (for example CRUDEOIL options 17-09 vs futures 21-09). This choice is shown for Options 1 and 3.

BSE stays on a mock calendar (Thursday expiries), and the page labels it as mock.

Warnings are shown when the history starts before the expiry data does, and when windows run past the last listed expiry.

6. Trading calendar (real)​

GET /api/range-analysis/calendar?exchange= returns holidays and sessions:

  • holidays holds weekdays that were fully closed. exch 1 is NSE, which is also used for BSE, and 2 is MCX.
  • specialdays holds special sessions with their own hours, such as weekend sessions, Budget Day and Muhurat. A special session takes priority over a holiday row on the same date.
  • MCX calendar coverage runs to the later of the newest exch=2 holiday row and the latest MCX EOD date, because MCX holidays are derived from traded dates. After the 2026-09-26 rebuild that is 2026-09-23, although the newest holiday row is 2026-04-03.
  • MCX evening-only days are derived. The MCX holiday rebuild writes only full closures, so a weekday that NSE lists as a holiday but MCX does not is treated as evening session only (17:00 – close). All 218 such past dates have MCX EOD data. Dates after the calendar coverage above (currently 2026-09-23) are marked assumed.
    • Rows with explicit morning_open / evening_open flags are used directly.

How the calendar is used:

  • Trading days drive the Day windows, the "Days" column, DFE/DTE counting, the Prev/Next roll, and the no-overlap shift.
  • Session hours: each window is cut to the session of its first and last day. The label shows the session, for example 2024-03-02 Sat [Special Trading Day 09:15-12:30].
  • Muhurat in the Day time frame: when a special session falls entirely outside the Day slice (for example Muhurat 18:15–19:15 vs 09:15–16:00), it becomes its own Day window covering the whole session. This does not apply to MCX evening-only days — a morning slice on those days simply didn't trade.
  • Mock bars exist only inside each day's session.

7. Data source​

Range Analysis can read from the VPS database while the rest of a local backend stays on the local database:

# backend/.env
RANGE_ANALYSIS_DB=VPS # LOCAL = this machine's DB; ignored when APP_ENV=VPS
VPS_DB_REMOTE_HOST=103.178.166.188 # VPS_DB_HOST is "localhost" from the VPS's own view
  • The VPS connection is opened with default_transaction_read_only=on, so the database itself refuses writes.
  • The right panel shows Expiries (real / loading / mock), Trading days (holidays table, and which database) and Latest EOD.
  • The backend must be restarted after editing .env. --reload watches .py files only.

7a. Prices​

GET /api/range-analysis/prices?exchange=&symbol=&from=&to=&step= returns base bars as columns {t, o, h, l, c}.

ExchangeSourceResolutionNotes
NSESpot from the IEOD Parquet store via Con_Price_Getter (nseieod rule 2)1-min (intraday bar sizes) or 75-min (Daily/Weekly/Monthly)GDFL bar-end times (09:15:59) are floored to the bar start. An index with no spot data (currently FINNIFTY) returns a clear 404; there is no silent fallback to futures (NeoWave needs spot).
MCXSpot from scr_mcxsp_eodDaily only — no intraday MCX store existsDay time frame and intraday bar sizes are disabled for MCX, windows take whole days, and every bar's high/low order is "assumed". Read from the reference database; if the table isn't there (it is not on the VPS yet), the endpoint falls back to the local database.
BSEMock (seeded random walk)—No BSE data in the database.
  • Data coverage follows the stores. On a local machine the IEOD store ends at its last pack (currently 13-07-2026). Windows past it have no bars and are counted as "skipped", and Tab 2 shows the price source and data range.
  • The run in two steps: planRun works out the windows and the dates and base step they need; the page fetches the bars; buildResult builds the Tab 2/3 data. BSE uses runAnalysis (plan + mock bars + build).

7b. Chart layout (Tabs 2 and 3)​

  • Left: the main AmiBroker-style chart.
  • Right, top — child chart: the selected bar at the smaller timeframe, drawn Excel-style (white background by default, one red line, round-number axis, slanted date labels), with Line / Wave and White / Dark toggles.
    • Tab 2: the selected window's bars.
    • Tab 3: the NeoWave STF bars inside the selected bar — 1-min for intraday bars, 75-min for Daily, Daily for Weekly/Monthly, and Daily for MCX.
  • Right, bottom — details: current stats (the selected window in Tab 2, the range in Tab 3), plus a placeholder for the chart-pattern explanations still to be designed.

8. Code map​

FileRole
frontend/src/pages/RangeAnalysis/rangeEngine.jsPure functions: constants, validation, window resolution (resolveWindowsRaw → no-overlap → session cut), real/mock calendars, mock bar generation, aggregation, stats. This is the logic V2 should move server-side.
frontend/src/pages/RangeAnalysis/RangeAnalysis.jsxPage shell and tabs. Loads symbols, expiries and the calendar with React Query and builds the cal object.
frontend/src/pages/RangeAnalysis/InputTab.jsxTab 1 form and right-hand panel.
frontend/src/pages/RangeAnalysis/ExcelChart.jsx, SidePanes.jsxExcel-style child chart, and the right-hand child and details panes.
frontend/src/pages/RangeAnalysis/AmiChart.jsxAmiBroker-style canvas chart (candle / wave / line, selector, range markers, zoom and pan), used by Tabs 2 and 3.
frontend/src/pages/RangeAnalysis/CandleTab.jsxTab 2.
frontend/src/pages/RangeAnalysis/WaveTab.jsxTab 3.
backend/app/api/range_analysis.py/symbols, /expiries, /calendar, /prices, plus the optional read-only VPS session.

V2 — to explore​

  • Real prices — follow-ups.
    • FINNIFTY (and any other index without spot data in the IEOD store) currently can't run.
    • MCX is daily-only until an MCX intraday store exists.
    • scr_mcxsp_eod still needs creating and filling on the VPS.
    • Consider moving planRun / buildResult server-side so large 1-min ranges don't travel as JSON. Move window resolution and aggregation server-side, keeping the same {cfg, windows:[{label,start,end,candle,bars,...}]} shape so the chart tabs stay unchanged. Use the real 1-min order for the Wave chart's high/low sequence.
  • Continuous vs contract prices. For expiry windows, decide between spot, near-month futures, or the contract that expires at the window's end.
  • BSE contracts. Load SENSEX/BANKEX expiries once BSE F&O data exists.
  • MCX calendar. Keep the exch=2 holidays up to date on the VPS, and record evening-only days explicitly (the holiday page's session flags) so the derived and assumed rule is no longer needed. Store the morning/evening split times per era if they changed.
  • Save and reuse definitions. Persist a range definition (title plus rule) to a table, list and reload saved definitions, and link them to Strategy Tracker and Regime Master.
  • Statistics. Range distribution (histogram and percentiles), range vs previous range, time-of-day of the high and low, breakout frequency beyond the previous window's range, filtering by regime.
  • Exports. Export the windows table and statistics to CSV.
  • Muhurat and special sessions in non-Day time frames. Decide whether they should also be their own windows, or stay folded into the span as now.