Plotting

Draws one number per bar as a column: a line, a histogram, an area or one of the other styles below. The number comes from whatever you computed; plot computes nothing itself. The title is required and names the column in the legend and in the settings dialog, where a user can restyle it.

plot(
    value: series number,
    title: string,
    color?: color = none,
    width?: number = 1.5,
    style?: string = "line",
    offset?: number = 0,
    overlay?: bool = none,
    precision?: number = none,
    format?: string = none,
    scale?: string = "right"
) -> plot

Returns

plot

First value

bar 0

version 1
study("MACD", precision = 2)

m = macd(close, 12, 26, 9)

level(0, "Zero", fade(gray, 55), style = "solid")

// Declared first, so it sits under the two lines.
plot(m[2], "Histogram", color = m[2] > 0 ? fade(lime, 30) : fade(red, 30), style = "histogram")
plot(m[0], "MACD", aqua, width = 2)
plot(m[1], "Signal", orange)

The six styles:

A value read once a day and drawn as a line slopes from one reading to the next, and every point on the slope is a number the script never had. Draw it as a step:

version 1
study("Previous day high", overlay = true, precision = 2)
plot(req.timeframe("1D", high), "Previous day high", aqua, width = 2, style = "step")

Colour. One argument takes both a fixed colour and a colour that changes per bar. Pass aqua and the plot is always aqua; pass an expression such as hist > 0 ? lime : red and each bar gets its own. Leave it out and the host, the application drawing the chart such as the /trading page, picks the next colour from its palette. See Colors.

Offset. offset moves where the column is drawn, never what it holds. A positive offset draws values to the right, into the space past the newest bar; a negative one draws them back over history, which is how a pivot, known only some bars later, is drawn on the bar it formed on:

version 1
study("Pivot highs", overlay = true, precision = 2)

// A pivot is reported 5 bars after it forms, so draw it 5 bars back.
ph = pivotHigh(high, 5, 5)
plot(ph, "Pivot high", orange, style = "lineWithMarkers", offset = -5)

The offset is a whole number fixed before the first bar, so offset = -rightBars on an input is refused. When the pivot's right side is an input, declare a second input with the negative default, or write the literal as above.

Pane and axis. A plot lands in the pane the declaration chose. overlay = true on one plot moves just that column onto the price pane. scale picks the axis within the pane:

precision (decimals, a whole number) and format ("price", "percent" or "volume") on a plot format the axis the plot maps to, not that one line, because an axis is shared. On a plot drawn over the price pane that reformats the instrument's own axis; in a study declared with overlay = true, the compiler warns about it with OS8007. Set them on the declaration of a study with its own pane instead. Formatting is display only: format = "percent" divides nothing by a hundred and precision = 2 rounds nothing; use round() to change a value.

Remarks. A plot has a value from bar 0, and its line starts wherever its value first exists. The title has no default, so plot(x) is error OS3012. Plots are drawn in the order they are declared, so declare a histogram before the lines that should sit on top of it. A stop that changes sides is best drawn as two plots, each none while the other is in use, so the line never cuts vertically through the candles on the flip bar.

See also. plotCandles(), fill(), level(), Plots, Colors

Draws bar-shaped output from four series of your own: a candle per bar with a body from open to close and wicks to the high and low. The candle takes colorUp where its close is at or above its open and colorDown where it is below. Use it for smoothed candles, or for a coarser timeframe's candle drawn over a finer chart.

plotCandles(
    open: series number,
    high: series number,
    low: series number,
    close: series number,
    title: string,
    colorUp?: color = #00ff00ff,
    colorDown?: color = #ff0000ff,
    wickColor?: color = none,
    borderColor?: color = none
) -> plot

Returns

plot

First value

bar 0

version 1
study("Averaged candles", precision = 2)

// Each candle opens halfway through the previous one and closes at the
// average of its own four prices, which smooths out the noise.
var avgOpen = none
avgClose = ohlc4
avgOpen = isNone(avgOpen) ? (open + close) / 2 : (avgOpen + avgClose[1]) / 2
avgHigh = max(high, max(avgOpen, avgClose))
avgLow  = min(low, min(avgOpen, avgClose))

plotCandles(avgOpen, avgHigh, avgLow, avgClose, "Averaged", colorUp = teal, colorDown = maroon)

Remarks. Where the sources are none, as during warmup, no candle is drawn. The handle is a plot, so fill() can name it; a band drawn to it follows its close. wickColor and borderColor default to none, which draws the wick and the border in the body's own colour for that bar; set them only to override that. Drawn over the price pane, faded colours keep the instrument's own candles readable underneath. plotCandles draws its own candles; to recolour the instrument's candles, use barColor().

See also. plot(), req.timeframe(), barColor(), Plots

Draws one horizontal line straight across the study's pane at one price: 70 and 30 on an oscillator, zero under a histogram, yesterday's high on a price chart. A level takes no column, has no history and shows no value in the legend, which is what makes it the right tool for a threshold and the wrong one for a measurement.

level(
    price: series number,
    title?: string = "",
    color?: color = #808080ff,
    style?: string = "dashed",
    width?: number = 1
) -> level

Returns

level

First value

bar 0

version 1
study("RSI with zones", precision = 2, range = [0, 100])

len = input(14, "Length", min = 2, max = 200)

level(70, "Overbought", fade(red, 40))
level(50, "Middle", fade(gray, 70), style = "dotted")
level(30, "Oversold", fade(lime, 40))

plot(rsi(close, len), "RSI", purple, width = 2)

The price may be computed from the data. It is read on every bar, and the line drawn is the one from the last bar executed. So a price that exists on only one bar usually draws nothing: hold it in a var instead.

version 1
study("Session open", overlay = true, precision = 2)

// The session's first bar, or the first bar of the IST day where the host
// states no session hours.
newSession = orElse(session.isFirstBar, isNone(time[1]) or not date.isSameDay(time, time[1], "Asia/Kolkata"))

var sessionOpen = none
if newSession
    sessionOpen = open

// Held, so the newest bar has a price to draw.
level(sessionOpen, "Session open", fade(aqua, 25), style = "solid", width = 2)

Remarks. An absent price on the last bar draws no line, which is the way to switch a level off, for example pos.isFlat ? none : pos.avgPrice in a strategy. A level cannot be one end of a fill() (error OS3020); plot the value instead, fully transparent if the line itself should not show. When you want to see where a value used to be, it is not a level: draw it with plot(x, "Title", style = "step"). Give every level a title, since it is the line's only label.

See also. plot(), fill(), Levels, Declarations

Shades the region between two plots. A band turns "which line is higher, and by how much" into a colour a reader takes in at a glance, which is why it suits a volatility band, a moving average cross, or an oscillator shaded to its midline. Its first two arguments are the handles that plot() or plotCandles() returned, not values.

fill(
    plotA: plot,
    plotB: plot,
    color?: color = none,
    colorUp?: color = none,
    colorDown?: color = none,
    opacity?: number = 1,
    overlay?: bool = none
) -> fill

Returns

fill

First value

bar 0

version 1
study("EMA cross, shaded", overlay = true, precision = 2)

fast = ema(close, 9)
slow = ema(close, 21)

pFast = plot(fast, "Fast", aqua, width = 2)
pSlow = plot(slow, "Slow", orange, width = 2)

// pFast comes first, so colorUp paints where the FAST average is higher.
fill(pFast, pSlow, colorUp = fade(lime, 85), colorDown = fade(red, 85))

Giving color together with colorUp or colorDown is error OS3010. Passing a value where a handle belongs is error OS3020:

pClose = plot(close, "Close")
fill(pClose, open)

To shade to a fixed value, which a level() cannot do, plot the value as a column and make it invisible. fade() takes a transparency in percent, so fade(c, 100) is fully transparent.

version 1
study("RSI shaded to 50", precision = 2, range = [0, 100])

pRsi = plot(rsi(close, 14), "RSI", purple, width = 2)
pMid = plot(50, "Midline", fade(gray, 100))
fill(pRsi, pMid, colorUp = fade(lime, 86), colorDown = fade(red, 86))

Remarks. A band stops wherever either of its plots is none and resumes where both return, so it inherits their warmup with no code from you. opacity is a dimmer from 0 to 1 that multiplies whatever transparency the colours already have. It defaults to 1 and is fixed before the first bar; dimming with both opacity and fade() compounds, so pick one. A band and the two plots it names must end up in the same pane, and the compiler does not check it: give both plots the same overlay and offset, and the band the same overlay. On the /trading chart in this release a band takes one colour: a colour computed per bar, such as color = squeezed ? orange : none, is not applied bar by bar, and the band is drawn in plotA's colour faded instead. To switch a band off on some bars there, make one of its plots none on those bars.

See also. plot(), level(), fade(), Fills

Shades the full height of this bar's column, behind the candles, plots and everything else in the pane the study draws in. It is the surface for a fact about a bar that has no price: the first fifteen minutes of the session, an expanded volatility regime, a study that is still warming up.

background(color: color) -> nothing

Returns

nothing

First value

bar 0

version 1
study("Opening window", overlay = true)

window = input("0915-0930", "Shade this window")

background(session.isIn(window) ? fade(silver, 90) : none)

Remarks. background(none) leaves the bar unshaded, which is how a conditional wash switches itself off, so the call rarely needs an if around it. If a script calls it more than once on a bar, the last call wins, and a last call with none clears the shade. It covers the whole bar, so keep colours faint: fade(c, 90), which is 90 percent transparent, is a good place to start. Paint is recomputed on every update of the newest bar and is never deferred the way signal() and alert() are; guard it with bar.isConfirmed if only settled bars should be shaded. A zone with a top and a bottom is not a background; draw it with draw.box().

See also. barColor(), fade(), session.isIn(), Bar colouring and backgrounds

Recolours the instrument's own candles on this bar. A candle's colour already tells the reader whether it closed up or down, so repaint it only to show something they cannot read off the candle, such as the trend or which side of a stop price is on, and pass none on the bars that do not matter.

barColor(color: color) -> nothing

Returns

nothing

First value

bar 0

version 1
study("Trend regime", overlay = true, precision = 2)

paint = input(true, "Recolour the candles")

fast = ema(close, 20)
slow = ema(close, 50)
up = fast > slow

// Three states: during warmup up is none, and the bar keeps its colour.
tint = isNone(up) ? none : (up ? lime : red)
barColor(paint ? tint : none)

plot(fast, "Fast", aqua)
plot(slow, "Slow", orange)

Remarks. up ? lime : red alone would paint every warmup bar red, because an absent condition takes the false branch; test isNone() first, as above. Within one script the last call on a bar wins, including a last call with none. The candles belong to the chart, not to your study: when several studies on one chart call barColor, only one study's colours are drawn and the others' are not, so give users an input to switch your colouring off, as the example does. Like background(), it is recomputed on every update of the newest bar.

See also. background(), plotCandles(), Bar colouring and backgrounds