Economic calendar
Economic events in a script with cal.*: the next and previous release, minutes to it, event windows, FOMC weeks and released figures.
ChartDeck keeps an economic calendar: US releases from the publishers' own schedules (jobs, inflation, growth, the Federal Reserve, Treasury auctions, options expiries) and, from Forex Factory, the main events of the other large economies. The same calendar draws the event flags on your charts. A script reads it with the cal functions, on every plan.
//@chartscript 1
indicator("Before US releases", { overlay: true })
const minutes = input.int(30, "Minutes before a high-impact US event", { minval: 1, maxval: 600 })
const soon = cal.minutes_to_next(cal.high, "US") <= minutes
bgcolor(soon ? color.new(color.down, 85) : na, { title: "A release is close" })
plotshape(cal.in_bar("US", cal.high), "Release in this bar", shape.diamond, location.top, color.accent)#Choosing events
Most functions take the same three filters, in this order for most of them:
| Filter | Meaning | Default |
|---|---|---|
importance | the lowest importance counted: cal.low (1), cal.medium (2) or cal.high (3) | cal.high |
country | "US", "EU", "GB", "JP", "CN", "CA", "AU", "NZ", "CH" or "CRYPTO"; "" = any | "" |
series | one series id, or the start of one: "US.FOMC" is every FOMC event, "US.CPI.YOY" only CPI year on year; "" = any | "" |
cal.in_bar keeps the older order (country, importance, series). The series ids are the calendar's own, such as US.NFP, US.CPI.YOY, US.CORECPI.MOM, US.PCE.YOY, US.GDP.QOQ, US.FOMC.DECISION, US.FOMC.PRESSER, US.ISM.MFG and CRYPTO.OPEX.MONTHLY.
#What each bar sees
Each bar looks from its close (the live bar: from now). The previous event is the last one at or before that time, the next event the first one after it.
| Function | Gives |
|---|---|
cal.in_bar(country, importance, series) | true when an event is scheduled inside the bar |
cal.in_window(minutes_before, minutes_after, ...) | true when the bar overlaps the window around an event |
cal.in_week(...) | true when the bar's UTC week (Monday to Sunday) holds an event: FOMC weeks |
cal.minutes_to_next(...) | whole minutes to the next event, na when none is scheduled |
cal.next_time(...), cal.prev_time(...) | the time (ms) of the next / previous event |
cal.next_name(...), cal.prev_name(...) | its name, such as "CPI y/y" (empty when there is none) |
cal.actual(series) | the released figure of the series' last event, once it was published |
cal.forecast(series), cal.previous(series) | that event's forecast and previous figure |
cal.since() | where the events the script got begin (ms) |
//@chartscript 1
indicator("FOMC weeks and CPI surprises", { overlay: true })
// shade the weeks of a rate decision
bgcolor(cal.in_week(cal.high, "US", "US.FOMC.DECISION") ? color.new(color.accent, 92) : na, { title: "FOMC week" })
// mark the bar where CPI came in above its forecast
const surprise = cal.actual("US.CPI.YOY") - cal.forecast("US.CPI.YOY")
plotshape(cal.in_bar("US", cal.high, "US.CPI.YOY") && surprise > 0, "CPI above forecast", shape.triangleup, location.belowbar, color.down)
if (barstate.islast) {
legend.info("Next: " + cal.next_name(cal.high, "US"))
}#History, the present and Bar replay
The calendar holds the events from the chart's first bar (up to 800 days back) to 35 days ahead. A bar in the past sees the schedule as ChartDeck holds it today: an event moved after the fact sits at its final time. Released figures are never early: cal.actual gives a figure only on bars that close after it was published.
In Bar replay the script keeps running and sees only the events at or before the replay time, with the figures published by then, as the chart's own event flags do. So near the replay time there is no next event and cal.minutes_to_next reads na.
Inside a request the calendar reads na and false (warning CS3124): use it on the chart's own bars. The data sources are credited in the calendar panel; a script that reads the calendar uses the same data.