Timeframes

ChartDeck's resolutions from seconds to months, tick and range bars, how bars line up in UTC, and the timeframe.* values a script reads.

The chart's timeframe decides what one bar is: a second, an hour, a week, 100 trades or a fixed price range. Your script runs on whatever the chart shows, so a good script checks the timeframe when it matters, for example to pick a sensible default length or to refuse a setup that makes no sense on a weekly chart.

#The timeframes ChartDeck offers

Timeframes are written as short strings. These are the ones a chart can show:

Which seconds, tick and range sizes you can open depends on your plan; the other timeframes are on every plan.

Note the case: 1M is one month, while one minute is plain 1. In a script, "60" and "240" are the hourly timeframes; there is no "1H".

#How bars line up

Every time-based bar starts on a fixed UTC boundary, the same on every venue and for every user:

• Seconds, minutes and days start on whole multiples of their length counted from 1 January 1970 UTC. A 4-hour bar starts at 00:00, 04:00, 08:00 … UTC; a 2-day bar starts on alternate UTC midnights.
• Weeks start on Monday 00:00 UTC (ISO weeks).
• Months start on the 1st at 00:00 UTC. Multi-month bars are anchored to January: 3M bars are calendar quarters, 6M bars are half-years, 12M bars are calendar years.

Because nothing shifts with daylight saving, a daily bar is always the UTC day. If you want a day that starts at another hour, build it yourself with a session (see sessions).

#What a script can read

The timeframe namespace describes the chart's timeframe:

timeframe.period and timeframe.main_period are the same in normal code. They differ inside a request: there timeframe.period is the requested timeframe, while timeframe.main_period still names the chart's.

And three functions:

• timeframe.in_seconds(tf) is the length of a timeframe in seconds ("" or no argument = the chart's). A month counts as its average length, 30.44 days.
• timeframe.from_seconds(s) goes the other way: timeframe.from_seconds(3600) is "60", 86400 is "1D", 604800 is "1W".
• timeframe.change(tf) is true on the first chart bar of a new period of tf: timeframe.change("1W") fires on the first bar of each week.

const newWeek = timeframe.change("1W")
bgcolor(newWeek ? color.new(color.accent, 80) : na, { title: "Week start" })

#Adapting to the timeframe

A length that suits a 5-minute chart is usually wrong on a daily one. You can let the input's default follow the chart: an input.int default may be a condition on the timeframe, and the settings dialog shows "Auto" with the value it picked until the user types their own (see inputs).

You can also convert a duration into bars yourself with timeframe.in_seconds(), or let the user type a duration with input.duration, which turns "4h" or "2d" into a number of bars on the chart's timeframe.

#A whole example: an average over a fixed time span

This moving average always covers the same stretch of time, whatever the timeframe: one day on a 15-minute chart is 96 bars, on a 1-hour chart 24 bars. It refuses to run on tick and range charts, where a bar has no length, and tells the user why.

//@chartscript 1
indicator("Time-span average", { overlay: true })

const span = input.string("1D", "Span", { options: ["4H", "1D", "1W"] })
const spanSecs = span == "4H" ? 4 * 3600 : span == "1D" ? 86400 : 7 * 86400

if (timeframe.isticks) {
    runtime.error("Tick and range bars have no fixed length: switch to a time-based timeframe.")
}

const barSecs = timeframe.in_seconds()
const len = math.max(1, math.min(5000, int(math.round(spanSecs / barSecs))))
const avg = ta.sma(close, len)
plot(len >= 2 ? avg : na, "Average", color.accent, 2)

state info: label = na
if (barstate.islast) {
    label.delete(info)
    info = label.new(
        bar_index,
        avg,
        span + " = " + str.tostring(len) + " bars of " + timeframe.period,
        { style: label.style_label_left, textcolor: color.text, color: color.new(color.muted, 70) }
    )
}

runtime.error stops the script and shows the message on the chart, which is kinder than drawing a meaningless line.

#Tick and range charts

On a tick or range chart the script runs on those bars like on any other: open, high, low, close and volume are the bar's own, built from the trades. What changes is time:

• time is the time of the bar's first trade. Bars come irregularly: hundreds a minute in a busy market, a few an hour in a quiet one.
• timeframe.isticks is true (on range charts too) and timeframe.period is "100T", "100R" or "50P".
• A bar has no length, so timeframe.in_seconds() and time_close carry no meaning there. Measure time with time - time[1] instead.
• A request for a tick or range timeframe is not supported and gives na, and so does a request for the chart's own timeframe ("") on such a chart. Requests for time-based timeframes ("60", "1D") work and line up by time.
• Seconds timeframes ("1S" to "45S") can be requested from any chart, with a short history: Seconds timeframes.

Non-standard charts covers Heikin Ashi and the other chart types.