In this article we look at the most important points of specifying indicator settings programmatically in TradingView Pine. Follow the links to the full articles for more information and examples.

In this article:

Configuring TradingView indicator settings with code

Configuring indicator properties programmatically, like its name and how the indicator’s values should display on the chart, is done with the study() function (Pine Script Language Tutorial, n.d.). We need to add this function to the code of every indicator, and its title argument (which sets the indicator’s name) always needs to be given a value (TradingView, n.d.).

The study() function configures several indicator settings, and by specifying these in the code our indicator is always added to the chart with the correct settings. We can, however, still configure indicator settings by hand. That way we can set different instances of the same indicator to different settings.

study() 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: Whenever we change, add, or remove an argument from the study() function with the indicator added to the chart, we often (depending on the argument) need to remove the script from the chart and re-add it before the updated code is visible.

The study() function has a couple of requirements (e.g., TradingView, n.d.):

  • Every indicator needs to use this function. Whenever study() is missing from the code or improperly formatted, TradingView generates the ‘the script must have one study() or strategy() function call’ error message.
  • The study() function should be added once to the code. If not, the ‘the script must have one study() or strategy() function call’ error message appears.
  • The title argument of the study() function always needs to be set. Otherwise, the ‘cannot call ‘study’ with arguments’ error message appears.
  • The study() function can only be used with the title, shorttitle, overlay, precision, scale, and max_bars_back arguments. If we mistype these or use an unrecognised argument, TradingView generates an ‘unknown argument’ error message.

Using code to set the name of a TradingView indicator

The study() function has one required argument: title, which specifies the indicator’s name programmatically (TradingView, n.d.). That name displays in the indicator legend that’s shown on the chart, in the ‘Data Window’, and in the ‘Create Alert’ window.

An example of setting an indicator’s name with title is:

study(title="My example script")
Note: The indicator name (which we set with title) differs from the filename under which the script is saved in the Pine Editor. That filename is, however, used in the list of indicators when we search for a specific script. Because of that, it’s easier to find a script when it’s chart name (set by title) matches or resembles the name in the indicator list.

Besides title, we can also specify the indicator’s name with shorttitle. Both arguments have the following features:

  • The indicator name defined by title and shorttitle cannot be set manually: using these arguments of the study() function is the only way to set an indicator’s name.
  • title and shorttitle only accept a literal string (like title="My script"). They cannot be set to a built-in variable or user-defined string variable, and nor do they accept a concatenated TradingView string.

Placing an indicator on the chart’s instrument programmatically

overlay is another argument of the study() function, and this argument makes the indicator display on the instrument (when set to true) or shows the indicator in a separate chart panel (when false) (TradingView, n.d.). The default value of this optional argument is false, and so indicators are plotted in a subchart when the overlay argument is missing from the study() function.

We can use the overlay argument like this:

study(title="My example script", overlay=false)
Tip: When we add the indicator to the chart before we use or change the overlay argument, the indicator needs to be removed and re-added to the chart to see the effect of the updated code.

The overlay argument has a few noteworthy features:

  • overlay only accepts literal Boolean values (like overlay=true). We cannot set this argument to a built-in or user-defined bool variable, and nor can the overlay argument work with a Boolean input variable.
  • Each indicator, regardless of its range of values, can be overlaid on the chart’s instrument. When an indicator’s values are different than the scale used by the instrument itself, we can specify the indicator’s price scale programmatically to prevent distorting the instrument’s scale.
  • It’s not possible to programmatically define in which subchart an indicator should display when overlay is false. This can only be done manually with the ‘move up’ ( ) and ‘move down’ ( ) icons displayed in the top right of the indicator’s chart panel.
  • The overlay argument affects most, but not all, TradingView functions. For example, barcolor() always colours the instrument’s price bars regardless of whether the overlay argument is set to true or false.

Setting the precision of a TradingView indicator with code

Another argument of the study() function is precision, which sets the number of decimals used by the indicator. This argument accepts a non-negative integer that specifies how many digits are displayed after the floating point of the indicator’s values (TradingView, n.d.). This optional argument defaults to 4, and we can use it like this:

study(title="My example script", precision=3)

Meaningful characteristics of precision are:

  • Setting precision to 0 displays numbers with special formatting (Pine Script Language Tutorial, n.d.): thousands are then displayed with the ‘K’ suffix and millions with the ’M’ suffix. This prevents large numbers from distorting the indicator’s price scale.
  • The precision argument can only be set to a literal integer (like precision=2). This argument doesn’t accept built-in and user-defined variables nor does precision accept a numerical input variable.
  • precision affects all indicator values; different plots from the same indicator cannot display with a different number of decimals.
  • When the indicator is overlaid on the chart’s instrument, the precision of the instrument determines how many decimals the indicator uses. In that case the precision argument is ignored. For more, including a workaround, see why an indicator displays with different precision than specified.

Setting a TradingView indicator’s price scale programmatically

scale is another argument of the study() function. This one specifies which price scale an indicator uses (TradingView, n.d.). This is an optional argument; when not set, the indicator attaches to the right price scale.

An example of scale is:

study(title="My example script", scale=scale.left)

We can set the scale argument to the following values (TradingView, n.d.):

Value Meaning
scale.right Sets the indicator to use the chart’s right price scale. This is also the standard setting: when the scale argument isn’t specified, it defaults to scale.right.
scale.left Makes the indicator use the left price scale. This is helpful when plotting more than one indicator in the same chart panel, or when overlaying the indicator on the chart’s instrument.
scale.none Doesn’t attach the indicator to any of the chart’s price scales. Since that makes the indicator’s values not show up on the left or right price axis, the indicator displays on the full chart area. This also means that the indicator’s values cannot be read from the price scale and that sometimes part of the indicator isn’t visible.

Features of the scale argument include the following:

  • With scale=scale.none, the indicator needs to be overlaid on the chart (that is, overlay=true) (TradingView, n.d.). Otherwise, the ‘cannot use ‘scale=scale.none’ in combination with ‘overlay=false’ settings’ error message is generated.
  • When the value of the scale argument is changed when the indicator is already added to the chart, the script needs to be removed and re-added to the chart to see the effect of the updated code.
  • To prevent an overlaid indicator from using the same amount of decimals as the chart’s instrument uses, we need to set scale to scale.left. That way the script uses its own price scale with its own decimal precision.

Setting the max bars back of an indicator in TradingView

The last argument of the study() function is max_bars_back. This argument sets the maximum number of price bars that are available for the indicator to reference (TradingView, n.d.). What this means is that max_bars_back specifies how many historical price bars the indicator uses in its calculations.

This amount of bars depends on the indicator’s code. For instance, an indicator that plots a 25-bar EMA (Exponential Moving Average) and a 30-bar SMA (Simple Moving Average) needs at least 30 price bars to calculate both moving average. And so max_bars_back would need to be at least 30. As long as there aren’t 30 price bars available, then the indicator ‘waits’ before calculating.

We set the number of bars an indicator needs for its operations like this:

study(title="Example of Max bars back", max_bars_back=20)

TradingView automatically determines the ‘max bars back’ value – in rare cases (like when we have complex code), we need to use max_bars_back to set this value ourselves.

Some observations and suggestions of this argument are:

  • The value set to max_bars_back is only used by TradingView when it cannot automatically determine the indicator’s number of historical bars referenced. Also, when the max_bars_back value is too low for the indicator to calculate successfully, then TradingView discards the argument’s value (TradingView, n.d.).
  • The ‘out of depth at index’ error message is triggered when TradingView cannot automatically figure out how many historical bars an indicator needs for its calculations.
  • When we set max_bars_back to a value that’s too high (like, higher than the number of bars on the chart), then the indicator generates the ‘Too large lookback’ error message.
  • Manually setting max_bars_back involves a trade off. On the one hand, this argument needs to be high enough so that the indicator can calculate successfully, even when its input options change. On the other hand, a very high value means the indicator will ‘wait’ a long time before calculating, ‘missing out’ on a lot of historical data in the process.
  • As a rule of thumb, set max_bars_back to 50 for short-term indicators, 100 when it’s a medium-term indicator, and 200 or more for (very) long-term indicators.
  • There’s no manual option for configuring the number of historical price bars used by an indicator; we can only set this programmatically with max_bars_back.

This ends our overview of the different ways to programmatically configure an indicator. See all TradingView Pine programming articles to learn more about other topics.


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 March 20, 2016, from https://www.tradingview.com/study-script-reference/