The most-used function in TradingView is likely study() since it needs to be added to the code of every indicator. What does this function do and how do we use it?

In this article:

Setting indicator properties programmatically in TradingView

In TradingView we programmatically set indicator characteristics, like how the indicator and its values should display on the chart, with the study() function (Pine Script Language Tutorial, n.d.). This function needs to be in the code of every indicator, and its title argument (which sets the indicator’s name) always needs to be set (TradingView, n.d.).

The study() function doesn’t return a value and has the following syntax (TradingView, n.d.):

study(title, shorttitle, overlay, precision, scale, max_bars_back)

These arguments mean the following (Pine Script Language Tutorial, n.d.; TradingView, n.d.):

Argument Description
title Required string argument that sets the indicator’s name, which is used on the chart and in several TradingView windows. This name can be different from the filename that’s used to save the script in the Pine Editor. For more on title, see specifying the name of an indicator programmatically.
shorttitle Optional string argument that gives the indicator an alternative name. This argument overrides the title argument. And so when shorttitle is set, the name specified by title isn’t used as the indicator’s name anymore. See setting an indicator’s name in TradingView to learn more.
overlay Optional true/false argument that, when set to true, displays the script overlaid on the chart’s instrument. When this argument is set to false (its default value) the indicator displays in a separate chart panel. For more, see overlaying an indicator on the chart’s instrument.
precision Optional integer argument that sets the number of digits shown after the floating point of the indicator’s values. This argument defaults to 4 and has a minimum of 0. When set to 0, large numbers are formatted with the ‘K’ (for thousands) and ’M’ (for millions) suffixes. See setting an indicator’s precision to learn more.
scale Optional argument that specifies the price scale that the indicator attaches to. Possible values for this argument are scale.right (default), scale.left, and scale.none (which requires that the overlay argument is set to true). For more on scale, see configuring the indicator’s price scale programmatically.
max_bars_back Optional argument that sets how many historical price bars the indicator needs for its calculations. By default, TradingView automatically computes this value. But when this value cannot be determined automatically, we need to provide it ourselves with the max_bars_back argument. We examine this argument in specifying the max bars back of an indicator.
Note: A TradingView indicator must use the study() function whereas a strategy script needs to implement the strategy() function (TradingView, n.d.). This means we can see by inspecting the script’s source code what kind of script it is.

Before looking at a TradingView example indicator, let’s take a closer look at working with the study() function.

Using the study() function in TradingView Pine

The study() function has several requirements. The first is that every indicator should use this function (TradingView, n.d.). When study() isn’t properly formatted or missing, TradingView generates a ‘the script must have one study() or strategy() function call’ error message:

Example of error message in TradingView Pine
Note: While the study() function can be placed anywhere in the script, it’s commonly placed in the top of the indicator’s code.

Another feature of study() is we should only add this function once to the code. For instance, this is not allowed:

study(title="My example indicator", overlay=true)
study(precision=0)

This generates the ‘cannot call ‘study’ with arguments’ error message – an error that also triggers when the title argument of study() is missing.

Example of error message of study() function in TradingView

Also, we should only use study() with its arguments: title, shorttitle, overlay, precision, scale, and max_bars_back (TradingView, n.d.). If we mistype an argument or use an unrecognised argument like this:

study(title="My example indicator", unknownArgument=true, overlay=true)

That generates an ‘unknown argument’ error message:

Example of missing argument of TradingView's study() function

Now let’s look at using study() in a full programming example.

Example: configuring a TradingView indicator with the study() function

In the programming example below we plot the average highest high and lowest low for a given number of bars. With the study() function we make the indicator plot on the chart’s instrument and have the indicator’s values display with four decimals in the chart’s ‘Data Window’. After discussing the code, we’ll look at how the indicator plots on the chart.

study(title="Smoothed extreme prices", overlay=true, precision=4)

// Inputs
extremeLen = input(title="Extremes Lookback", type=integer, defval=20)
smoothLen  = input(title="Smoothing Length", type=integer, defval=5)

// Compute values
highestHigh = ema(highest(high, extremeLen), smoothLen)
lowestLow   = ema(lowest(low, extremeLen), smoothLen)

// Plot values
plot(series=highestHigh, color=green, linewidth=2)
plot(series=lowestLow, color=red, linewidth=2)

We start with the study() function and set three of its arguments. With title we specify the indicator’s name while overlay set to true displays the indicator on the chart’s instrument (TradingView, n.d.). And with precision we set the indicator’s number of decimals.

Adding input options to the script is next:

extremeLen = input(title="Extremes Lookback", type=integer, defval=20)
smoothLen  = input(title="Smoothing Length", type=integer, defval=5)

We add manual inputs to the script with the input() function (Pine Script Language Tutorial, n.d.), and this function also returns the input’s current value (TradingView, n.d.).

Both inputs are numerical integer inputs. These accept whole numbers only, and are made by setting the type argument of the input() function to integer (Pine Script Language Tutorial, n.d.). We name the first “Extremes Lookback” with the title argument, and this name is what’s placed before the input in the script’s ‘Inputs’ window (see image further down below).

The default value (defval) of that first input is 20 and we assign its value to the extremeLen variable. This way we can use that variable later on when retrieving the recent highest high and lowest low.

The second integer input is named “Smoothing Length” and has 5 as its default value. We store this input’s value in the smoothLen variable, and use that variable later on when smoothing the highest high and lowest low values.

Then we compute the indicator’s values:

highestHigh = ema(highest(high, extremeLen), smoothLen)
lowestLow   = ema(lowest(low, extremeLen), smoothLen)

Both the highestHigh and lowestLow variables are assigned a value returned by ema(). That function calculates an Exponential Moving Average (EMA) that’s based on a series of values and an integer that specifies the EMA length in number of bars (TradingView, n.d.). Here both ema() functions compute on the smoothLen number of bars, which is the input variable that we gave a standard value of 5.

The value of the highestHigh variable is set by having ema() calculate on the values returned by highest(high, extremeLen). That highest() function requires a two arguments: a series of values (to return the highest price of) and an integer that specifies the lookback period (TradingView, n.d.). Here we set those arguments to the instrument’s high prices (high) and the extremeLen input variable, which has a default value of 20. With the highest() function placed inside the ema() function, TradingView first gets the 20-bar highest high and then computes its EMA. This way we smooth the highest highs.

The second ema() function call, which gives the lowestLow variable its value, is highly similar. Now we get the 20-bar lowest low (lowest(low, extremeLen)) and then this value is also smoothed with a 5-bar EMA.

With the indicator values calculated, we plot them on the chart:

plot(series=highestHigh, color=green, linewidth=2)
plot(series=lowestLow, color=red, linewidth=2)

Data is plotted on the chart with plot(), and this function’s series argument defines which values are displayed (TradingView, n.d.). Here, in the first plot() statement, we set that argument to the highestHigh variable. These smoothed highest high value are displayed in the green basic TradingView colour. The linewidth argument, which sets the plot’s size (TradingView, n.d.), is given a value of 2. That makes the plot a bit bigger than the default size.

In the second plot() statement we plot the lowest low value (series=lowestLow). This line – plot() makes a line by default (TradingView, n.d.) – has its colour set to red and the same width as the highest high line.

Plotting the smoothed highest high and lowest low in TradingView

When we add this programming example to a EuroStoxx 50 Index CFD chart, it looks like:

Example of TradingView script added to the chart

The indicator has these input options:

Example of input options in our TradingView script

Now when we set these inputs to a lookback period of 30 with a smoothing of 10, then the previous chart changes to:

Example of TradingView script's inputs changed

While we set the indicator’s values to 4 decimals with the precision argument of the study() function, TradingView ignored that and the indicator uses the instrument’s number of decimals. For more on this, see why has my indicator another precision than specified?. In the ‘Data Window`, however, the indicator does display with 4 figures after the floating point:

Example of the indicator's Data Window

To learn more about the study() function and its arguments, see specifying the precision of indicator values, overlaying an indicator on the chart’s instrument, and configuring an indicator’s price scale.

Summary

The study() function needs to be added to every indicator. Its required title argument sets the name of the indicator, which is also done by the shorttitle argument. The overlay argument makes the indicator display on the chart’s instrument (when set to true) or in its own sub panel (false). Setting the number of decimals is done with precision, although TradingView not always respects this argument’s value. We use the scale argument to define the price scale that the indicator attaches to. And with the max_bars_back argument we specify how many bars the indicator needs for its historical calculations.


References

Pine Script Language Tutorial (n.d.). Retrieved on February 24, 2016, from https://docs.google.com/document/d/1sCfC873xJEMV7MGzt1L70JTStTE9kcG2q-LDuWWkBeY/

TradingView (n.d.). Script Language Reference Manual. Retrieved on February 26, 2016, from https://www.tradingview.com/study-script-reference/