Visuals overview

A script produces two kinds of output: numbers, and pictures made from numbers. This page is the map of the pictures. It names every call in OpenScript (also called OpenAlgo Script) that draws on a chart, says what each one is good at, and gives you four questions that pick the right one. Read it before the detailed pages, so that when you want a line, a band, a marker or a shaded zone you already know which call to reach for.

The four questions are always the same:

1. Is the thing one value per bar, or a shape that spans several bars?
2. Does it have a price to sit at, or is it a fact about the whole bar?
3. Is it fixed before the first bar runs, or does it appear and disappear as bars arrive?
4. Which pane should a reader find it in?

Answer those four and the call chooses itself.

One study, one of each surface

Here is a complete overlay study (one drawn over the price candles) that uses most of the drawing calls at once, so you can see them side by side. Save it in the Scripts panel of the /trading page and apply it to any NSE chart.

version 1
study("Surface tour", overlay = true)

len = input(20, "Length", min = 2, max = 500)

basis = sma(close, len)
band  = 2 * stdev(close, len)

// Two named plots, so the fill has two columns to shade between.
pUpper = plot(basis + band, "Upper", aqua)
pLower = plot(basis - band, "Lower", aqua)
plot(basis, "Basis", orange, width = 2)

fill(pUpper, pLower, color = aqua, opacity = 0.08)

// A regime has no price to sit at, so it is painted rather than plotted.
// Absent during warmup, so the candles keep their own colours there.
trendColor = isNone(basis) ? none : (close > basis ? lime : red)
barColor(trendColor)
background(close > basis + band ? fade(orange, 93) : none)

// An event, on the one bar it happened.
if crossUp(close, basis + band)
    signal("BREAKOUT", at = "above", shape = "triangleUp")

Read it as: three plotted lines, one shaded band between two of them, a colour on every candle, a faint wash on the bars where price closed above the upper band, and a marker on the bars where it first crossed out.

The surfaces

Everything a script draws lands on one of seven surfaces.

Plots, fills and markers together look like this on a real chart. This HalfTrend study on a BHEL 15 minute chart draws its trend level as two plots, blue while the trend is up and red while it is down, shades a channel beside the level with two fills, and puts a labelled marker on each flip:

Two more calls produce output that is not drawn at all. People look for them here, so they belong on the map: alert() raises an alert on the bar it runs on, and print() writes a value to the script's log. See Alerts from scripts and Debugging.

If you want this, use that

Keep this table open while you write. The last column names the page that covers the call in full.

Three rows of that table are worth their reasons, because they are where people most often reach for the wrong call.

A crossing is not a plot. A crossing happens on one bar. A plotted column carries one value on every bar, so the only way it can show an event is by being absent everywhere else, which spends a whole column on one dot. signal() is the call for an event: one call, one named marker, with at and shape when you care where it sits and what it looks like.

A regime is not a price. "The trend is up", "the opening range is still forming", "volatility is unusually high": none of these has a price to sit at. Drawing one as a line puts a flat series through the price scale saying something that has nothing to do with price. background() shades the bar's whole column and barColor() recolours the candle itself. Both take none to mean "leave this bar alone", which is how a conditional paint switches itself off.

A fixed reference is not a plot either. A line at 70 does not need a column of identical numbers, a value in the legend and a group of rows in the settings dialog. level() draws it with one call and none of those.

Where each call may appear

Some drawing calls declare the fixed shape of the study, and the rest are per-bar events. This rule catches everyone once.

So you never hide a plot by wrapping it in an if:

trending = adx(14, 14)[0] > 25
ema20 = ema(close, 20)

if trending
    plot(ema20, "EMA 20", aqua)

You hide it by giving it the absent value, none, on the bars where you do not want it:

trending = adx(14, 14)[0] > 25
ema20 = ema(close, 20)

plot(trending ? ema20 : none, "EMA 20", aqua)

The same idea works on every surface. Absence reaching a drawing surface is a gap, never a zero, and that one rule is what makes "hide it with none" work everywhere without a second mechanism. Absent values explains where none comes from.

What costs a plot slot

A plot slot is one plotted column. It keeps a value for every bar, shows its current value in the study's legend (the row at the top of the pane with the study's name), and gets its own group in the Style tab of the settings dialog, where the user can change its colour, opacity, thickness, line style and plot style without editing your script. Only two calls create one.

Two consequences come up in real scripts.

A function with several outputs costs one slot per output you draw. macd() returns three numbers in one array, from one call and one piece of state. Drawing all three is three plot calls and three slots. Drawing only the histogram is one slot, and the other two outputs cost nothing.

A shaded band needs its two edge plots even when you do not want the lines. When the band is the whole point, keep the plots and make them invisible with a fully transparent colour. fade() takes transparency, and 100 is invisible:

basis = sma(close, 20)
band  = 2 * stdev(close, 20)

pUpper = plot(basis + band, "Upper", fade(aqua, 100))
pLower = plot(basis - band, "Lower", fade(aqua, 100))
fill(pUpper, pLower, color = aqua, opacity = 0.08)

An invisible plot draws nothing, and the legend leaves out its value. Name the band's colour yourself, as here: a band given no colour takes its first plot's colour, and that colour is invisible.

Only plots appear in the Style tab. When you pass a colour input straight to a plot, by the input's own name, the plot's colour in the Style tab and the input are one setting. See Inputs and Settings and style.

Which pane a thing lands in

A study is either drawn over the instrument's candles or given a pane of its own, and the declaration decides which. overlay defaults to false, so a study with no overlay argument gets its own pane below the price.

version 1
study("Relative strength", precision = 2, range = [0, 100])

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

The declaration sets the default for everything the file draws. Two calls can override it item by item, and the rest cannot.

barColor is the one that surprises people, and it is deliberate: a trend reading computed in a pane below the chart is most useful painted onto the candles the trader is watching, and forcing the study to be an overlay just to reach them would mean giving up its own axis. The candles are one object, so when two studies both colour them, only one study's colouring is shown, decided by the order of the studies on the chart.

A study with its own pane and no plot at all draws no markers, because its markers have no line to sit on.

Within a pane, a plot's scale argument picks the price axis it maps to:

Declaration options that shape the picture

Five options on study(...) decide how the whole study is drawn. Each must be fixed when the script compiles. They are covered in full in Declarations.

The order things are painted in

The /trading chart paints each pane in four layers, bottom to top:

Four facts are enough to design with:

• Bands and backgrounds sit behind the candles and lines, so they never hide them. A strong one still drowns their colours, so keep both faint. fade(silver, 92) reads as a tint; silver at full strength reads as a bug.
• A fill given no colour takes its first plot's colour at twelve percent strength. Name a colour and you get that colour, dimmed only by opacity, which starts at 1.
• Within one study, plots are painted in the order you declare them, so a plot declared first sits under the ones declared after it. That is the cheapest control you have over what covers what.
• An absent value removes a layer for that bar rather than painting a zero over what is underneath.

Two more worked examples

An oscillator with its own pane, scale and lines

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

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

r = rsi(close, len)

// Levels, not plots: horizontal lines with no columns and no legend values.
level(70, "Overbought", fade(red, 40))
level(30, "Oversold", fade(lime, 40))

pOsc = plot(r, "RSI", purple, width = 2)

// The midline exists only so the fill has a second column to name.
// Fully transparent, so it draws no line of its own.
pMid = plot(50, "Midline", fade(gray, 100))

fill(pOsc, pMid, colorUp = fade(lime, 86), colorDown = fade(red, 86))

range = [0, 100] fixes the pane's scale, so 70 sits at the same height on every chart you open. That is the reason to fix a range: a reading with real bounds should keep them on screen.

A pane study that reaches onto the price chart

version 1
study("Trend strength", precision = 2, range = [0, 100])

diLen  = input(14, "DI length",  min = 1, max = 100)
adxLen = input(14, "ADX length", min = 1, max = 100)

strength = adx(diLen, adxLen)[0]

// Computed at the top level, on every bar. A stateful call placed inside a
// branch would only advance on the bars that branch ran.
e20 = ema(close, 20)

level(25, "Trending above here", fade(gray, 50))
plot(strength, "ADX", purple, width = 2)

// This one column belongs where the trader is looking, not down here.
plot(strength > 25 ? e20 : none, "EMA 20 while trending", orange, width = 2, overlay = true)

// And the candles themselves carry the regime: greyed out while the market
// is not trending, left alone while it is and during warmup.
barColor(isNone(strength) or strength > 25 ? none : fade(gray, 60))

Three things are worth noticing. The study owns a pane, yet one of its columns is on the price pane and so is its bar colouring. The average is computed on every bar and only the drawing is conditional: computing it inside the ternary or an if would raise warning OS8001 and leave holes in the line. And barColor(none) on the trending bars leaves those candles their own colour, which is a stronger picture than painting them a second colour. The isNone test keeps the warmup bars, where adx() has no value yet, from being greyed out as if they were quiet.

Choosing between a plot, a level and a drawing

These three overlap, and picking the wrong one gives a script that works and then becomes painful to change.

The tie-breaker: if the thing has a value on every bar, plot it. If it has one value that the whole pane should show at a single height, make it a level. If it starts somewhere in the past and ends somewhere else, draw it.

Related: Plots, Levels, Fills, Colors, Bar colouring and backgrounds, Labels and shapes, Lines and boxes, Tables, Plotting reference.