Seasonality

A seasonality view lays the same calendar window (a year, a quarter or a month) of several years on top of each other. Each year is one line, normalised to a common start, so you can see whether a market tends to rise or fall at certain times of year. An optional average path, with the range of the years shaded around it, sums them up.

import { createChart, createSeasonality, dataSource } from '@chart-on/core';

const chart = createChart(container, { plugins: [dataSource()] });
chart.setDataSource(source);

const view = createSeasonality(chart, {
  symbol: 'WHEAT',      // daily bars, loaded through the chart's data source
  years: 5,             // the newest five years with data
  window: 'year',       // or 'quarter' / 'month'
  normalize: 'percent', // or 'indexed' (each year starts at 100) / 'none' (prices)
  average: 'mean',      // or 'median'; leave out for no average
});
await view.ready;

The time axis shows the window's calendar: month names and days, not real dates. The crosshair label shows the date in the window (30 Apr), and the legend shows each year's value at that position.

The view owns the chart's time axis, so give it a chart of its own: one without a loaded symbol (setSymbol) or main series data. createSeasonality throws otherwise.

Data

symbol loads daily bars (1d) through the chart's data source, or through source when you pass one. The view pages back until history reaches 1 January of the oldest year it needs, and live bars update the newest year. ready settles once the first load finishes, and rejects with the ChartError when it fails.

Bars you already have go in bars instead, and setBars replaces them later:

const view = createSeasonality(chart, { bars: dailyBars, years: [2019, 2021, 2023] });

years is either a count (the newest years with data in the window) or a list of years. Years without data are left out.

Windows

window: 'year' compares whole calendar years. 'quarter' and 'month' compare one quarter or month each year: period picks it (1-4 or 1-12) and defaults to the one holding the newest bar.

// Every July, by trading day.
createSeasonality(chart, { symbol: 'IND50', window: 'month', period: 7, align: 'trading' });

Alignment, leap days and gaps

align: 'calendar' (the default) puts the same date at the same position every year. Positions follow a leap-year calendar, so a year window has 366 of them and 1 March is position 60 in every year. 29 February only has a value in leap years.

Days without a bar (weekends, holidays) are handled by gaps:

• 'carry' (default): repeat the last close over them, from the year's first bar to its last. Common years carry 28 February over the leap day. Every year then has a value at every position it spans, so the average path is not skewed by weekends falling on different dates.
• 'skip': leave them empty. Lines join across the gap, and the average at that position uses only the years with a bar there.

align: 'trading' lines up the nth bar of the window instead. Positions are trading days, the axis and crosshair show their numbers (Day 42), and there are no gaps. A year with fewer trading days ends earlier.

Neither mode fills before a year's first bar in the window or after its last, so the current year ends at the newest bar.

Average and range

average: 'mean' or 'median' adds the average path of the years (dashed), and shades the min/max range of the years behind the lines. At each position the average uses the years with a value there. range: false keeps the average without the shading, and averageColor sets their colour (the theme's line by default).

Showing and hiding years

Each year is a line series titled with the year, so the legend's eye button hides it. setYearVisible(year, visible) does the same from code. Hiding a year only changes that line: the other years and the average are not recomputed, and the average still includes the hidden year. A hidden year stays hidden when the view recomputes for new bars or options.

view.setYearVisible(2020, false);
view.isYearVisible(2020); // false
view.yearSeries(2024)?.applyOptions({ lineWidth: 3 });

The newest year is drawn thicker and has the last-value label. colors sets the year colours, oldest year first.

Changing and removing the view

applyOptions changes any option except the data and recomputes every path. dispose removes the view's series and restores the chart's time labels.

view.applyOptions({ window: 'quarter', normalize: 'indexed' });
view.dispose();

Without a chart

computeSeasonality(bars, options, zone?) is the pure computation behind the view: the normalised path per year as a Float64Array per position (NaN where a year has no value), and the average with its min and max. seasonalPosition(time, window, zone?) gives a date's year, period and calendar position, and seasonalSlots(window, period) the number of calendar positions in a window. Dates are read in zone (UTC by default; the view passes the chart's timezone).