With TradingView’s input options we can easily change values used by an indicator or trading strategy. But how do we make an input for specifying a time range?

In this article:

Setting a time range with a session input in TradingView Pine

When programming a TradingView script, we can create variables that hold the value of a manual option. That way a variable’s value can be changed by simply changing the option’s setting, and that saves us from having to edit the code to change a particular variable.

We make those user-definable inputs with the input() function. That function not only creates the input option itself, it also returns the input’s current value (Pine Script Language Tutorial, n.d.).

That means when we assign the value returned by input() to a variable, we can access the input’s current value by using that variable. This way changing the setting of an input also affects the value that’s used in the script, and that influences how our TradingView script behaves.

One input we can make with input() is a session option, and with this input option we can manually specify a time range. To create such an option we set the input() function’s type argument to session (Pine Script Language Tutorial, n.d.). That function then returns a string with the option’s current value, like "0900-1730" for the 9:00 to 17:30 time range.

Default syntax for creating a session input

The basic pattern for making a session input option looks like:

sessionString = input(title, type=session, defval, confirm)

When we create a session input with input(), the different arguments of that function work as follows (TradingView, n.d.):

Argument Description
title Optional string argument that specifies the title that’s placed before the input option (like title="RTH session").
type Required argument that, when set to session, lets the input() function create a time range option in the script’s input settings. With session, input() returns its current value as a string, which is then stored in the sessionString variable.
defval Required argument that sets the input’s default value. With a session input, defval needs to be set to a time string in 24-hour HHmm format like "0930-1600" (9:30 a.m. till 4 p.m.) or "2200-0800" (10 p.m. till 8 a.m.). With a default value the script can start calculating as soon as it is added to the chart.
confirm An optional argument that, when set to true, asks the user to confirm the input option(s) before the script starts calculating. This argument defaults to false, meaning that when confirm is missing the script settings don’t need to be confirmed. Only one of the script’s inputs needs to have this argument set too true before the inputs are displayed when we add the script to the chart.
Note: The input() function returns the current value of the input option. To use that value later on in the script, we have to assign that returned value to a variable. Without that, we cannot use the input’s value in the rest of the indicator or strategy.

These session input options made by input() look like:

Example of session inputs in TradingView
Note: Session specifications, like "0930-1600", are always in the time zone of the instrument’s exchange (Admin, 2015). This means for session inputs to work correctly, the chart’s time zone needs to be set to ‘Exchange’. To change that setting, we right-click on the chart, select ‘Properties’, and then move to the ‘Timezone/Sessions’ tab:
Changing the time zone settings of a TradingView chart

Example: a TradingView indicator with session inputs

Now let’s look at a practical example of a session input option. The indicator below has two session input options to specify two different time ranges. In the script we create a custom function to determine whether a price bar is inside the specified session. When it is, we shade the chart’s background in a particular colour.

The chart below shows the indicator’s appearance. After discussing the code we’ll look at the script’s input options and its effect on the chart.

Example TradingView chart with shaded background by a custom script
study(title="Time ranges", overlay=true)

// Create the inputs
euSession = input(title="EU session", type=session, 
    defval="0800-1530", confirm=true)

usSession = input(title="EU+US session", type=session,
    defval="1530-2200")
    
transparency = input(title="Transparency", type=integer,
    defval=50, minval=0, maxval=100)

// The BarInSession function returns true when
// the current bar is inside the session parameter
BarInSession(sess) => time(period, sess) != 0

// Set the colour variables for the ranges
euColour = #6495ED // Cornflower blue
usColour = #98FB98 // Pale green

// Determine the chart's background colour
chartColour = BarInSession(euSession) ? euColour : 
     BarInSession(usSession) ? usColour :
     na

// Set the background colour
bgcolor(color=chartColour, transp=transparency)

We first set the script’s properties with study(), a function that needs to be added to every indicator (TradingView, n.d.). We use it to specify the indicator’s title and, by setting overlay to true, make the indicator plot on the chart’s data series.

Then we make the script’s input options:

euSession = input(title="EU session", type=session, 
    defval="0800-1530", confirm=true)

usSession = input(title="EU+US session", type=session,
    defval="1530-2200")
    
transparency = input(title="Transparency", type=integer,
    defval=50, minval=0, maxval=100)

We create input options with input(), and that function also returns the option’s current setting (TradingView, n.d.). Here we assign those returned values to variables; that way we can access the input’s setting later on in the script.

The first input is named “EU session” and has its type argument to session. This session input has a default value (defval) of "0800-1530" (that is, 8 a.m. till 3:30 p.m). We store this input’s value in the euSession variable and use it to set a time range for when the European markets are open. Since we gave the confirm argument a value of true, the script’s input options pop-up whenever we add the script to the chart.

The second input (“EU+US session”) is also a session type input, and this one has a default value of "1530-2200". With it we define the US session, and we store this input’s current value in the usSession variable.

The last input is a numerical integer input. 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 this input “Transparency” and give it a default value of 50, with an allowed range of 0 (minval=0) to 100 (maxval=100). Its current value is assigned to the transparency variable that we use later on to change the background’s transparency.

After making the inputs we create a custom function:

BarInSession(sess) => time(period, sess) != 0

We use the function declaration operator (=>) to create a single-line function. For this we specify the function’s name followed by any argument(s) that it requires. Then after the => operator we place the expression that the function should return (Pine Script Language Tutorial, n.d.).

Here we name our function BarInSession() and specify one argument between its parentheses: sess. We use that value to specify a session and will use it inside the function when we check whether the current bar falls inside that session.

In our custom function we use the time() function. That function requires two arguments: the resolution and a session (TradingView, n.d.). Now when a bar with the specified resolution falls inside that session, then time() returns that bar’s time. When the bar isn’t in that session, it returns NaN (Pine Script Language Tutorial, n.d.).

The values that we use time() with are period (a variable that returns the chart’s current resolution; TradingView, n.d.) and the sess variable that we specified whenever we call our BarInSession() function. Now to see if the value that’s returned by time() indicates whether the bar is in the session or not, we check whether that returned value is unequal to (!=) 0.

Now when the bar is inside the session, then time() returns the bar’s time and the time expressed as a numerical value is indeed unequal to 0. In that case our BarInSession() function returns true. Now when the bar is outside the session, time() returns a value that’s the equivalent of 0 and BarInSession() returns false.

This way we can use our custom BarInSession() function to check whether the current bar is inside the specified time range or not.

Next we create two colour variables and determine the chart’s background colour:

euColour = #6495ED // Cornflower blue
usColour = #98FB98 // Pale green

chartColour = BarInSession(euSession) ? euColour : 
     BarInSession(usSession) ? usColour :
     na

We create two colour variables here: euColor and usColour. The first is assigned the hexadecimal colour value of cornflower blue while the value of usColour is set to pale green.

Then we use those variables when we set the value of the chartColour variable with the conditional (ternary) operator (?:). This operator works on three values. The first is a true/false expression that, when true, makes the operator return its second value. And when false, the conditional operator returns its third and last value (Pine Script Language Tutorial, n.d.). This makes it work like an if/else statement: ‘if this is true, return A; otherwise, return B’.

Since we use the conditional operator twice here, we also evaluate two true/false expressions. The first is the BarInSession() function with the euSession input variable. That input has a default value of 8:00 till 15:30, and our custom BarInSession() function returns true when the script’s current bar falls inside that session. In that case, the first conditional operator returns the euColour variable. Now when the bar isn’t in that session, TradingView processes the second conditional operator.

That one evaluates BarInSession(usSession), and here our custom function will return true when the bar’s time is between 15:30 and 22:00. When the bar is in that range, the second conditional operator returns usColour and that pale green colour is then assigned to the chartColour variable.

When the true/false expression of this second conditional operator is also false, it returns na. That built-in variable returns a so-called “not a number” value (TradingView, n.d.) that, when used as a colour, gives a transparency effect (Pine Script Language Tutorial, n.d.). In our case, that means the background wouldn’t be coloured and remains the same.

After setting the chartColour variable to cornflower blue, pale green, or ‘transparency’, we perform the actual background colouring:

bgcolor(color=chartColour, transp=transparency)

The bgcolor() function colours the chart’s background from top to bottom (Pine Script Language Tutorial, n.d.). We set its colour argument to the chartColour variable we’ve just made for a blue, green, or default background.

The transp argument, which specifies the background colour’s transparency from 0 (not transparent) to 100 (fully transparent) (TradingView, n.d.), is set to the transparency input variable. That way we can use the numerical input option to easily change the background’s transparency by hand.

Charts: adding a session input option to a TradingView script

Now when we add the above example indicator to the chart, it first brings up the script’s ‘Inputs’ tab to have us configure or verify the input options:

Example of the TradingView indicators's inputs

When we click ‘OK’ the indicator is added with its default values to the chart. On a EUR/USD chart, that looks like:

Example chart with shaded background

Now when we adjust the script’s settings to the following:

Changing the input settings of a TradingView script

Then the chart changes accordingly:

Example of a TradingView script added to a chart

Summary

We add input options to a script with the input() function, and this function also returns the input’s current value. By assigning that value to a variable, we can access the input’s value later on in the script. One of the input types that we can make with input() are session inputs. These allow us to specify a time range and are created by setting the type argument of input() to session. We specify the default value of an input option with the defval argument. In the case of session inputs, that argument has to be set to a string that specifies the time range like "0800-1530" (8 a.m. to 3:30 p.m) or "2200-1100" (10 p.m. till 11 a.m.). Once we’ve defined a session, we can use the time() function to see if a price bar falls inside that time range.

Learn more:


References

Admin (October 5, 2015). time() only works with exchange time chart? Discussion topic. Retrieved on October 8, 2015, from https://getsatisfaction.com/tradingview/topics/-time-only-works-with-exchange-time-chart

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

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