In this tutorial, we’ll be examining the input.timeframe function in Pine Script. This versatile function provides significant customization options for users of your script. Let’s delve into the intricacies of this function and learn how to use it effectively.
What is input.timeframe?
The input.timeframe function provides a way to add an input to the Inputs tab of your script’s Settings. It essentially allows you to offer configuration options to users of your script by adding a dropdown menu that enables users to select a specific timeframe.
The function uses a timeframe selector and returns the selected timeframe as a string. The selector includes any custom timeframes that a user may have added via the chart’s Timeframe dropdown.
Syntax of input.timeframe
The syntax for input.timeframe is as follows:
input.timeframe(defval, title, options, tooltip, inline, group, confirm) → input string
Arguments
Let’s break down what each argument stands for:
- defval (const string): Determines the default value of the input variable. This is the initial value proposed in the script’s “Settings/Inputs” tab. If
optionsparameter is used with a list of values, the value must be one of them. - title (const string): Title of the input. If not specified, the script will default to using the variable name as the title.
- options (tuple of const string values): A list of options to choose from. Each option represents a timeframe choice.
- tooltip (const string): The string that will be shown to the user when hovering over the tooltip icon.
- inline (const string): This argument is used to group all the input calls in one line.
- group (const string): Creates a header above all inputs using the same group argument string.
- confirm (const bool): If set to true, the user will be asked to confirm the input value before the indicator is added to the chart. By default, this value is false.
Use Case Example
Now, let’s see input.timeframe in action. We will create an indicator that allows us to select a timeframe and visualize Apple’s (AAPL) closing prices according to the chosen timeframe.
//@version=5
indicator("input.timeframe Example", overlay=true)
i_res = input.timeframe('D', "Resolution", options=['D', 'W', 'M'])
s = request.security(syminfo.tickerid, i_res, close)
plot(s)
//@version=5: This line indicates the version of Pine Script that the script is intended to run on. In this case, it specifies that the script is written in Pine Script version 5, which is currently the latest version of the language as of my knowledge cutoff in September 2021.indicator("input.timeframe Example", overlay=true): This line is creating a new indicator with the title “input.timeframe Example”. Theoverlayargument being set totrueindicates that this indicator is intended to be drawn directly on the price chart.i_res = input.timeframe('D', "Resolution", options=['D', 'W', 'M']): This line is creating an input using theinput.timeframefunction. It is initializing a new variablei_reswith a default value of ‘D’ (daily resolution). The user will have the options to select from ‘D’ (daily), ‘W’ (weekly), and ‘M’ (monthly) timeframes.s = request.security(syminfo.tickerid, i_res, close): Here, the script is requesting security data. It’s fetching the closing price (close) for the current symbol (retrieved usingsyminfo.tickerid) at the timeframe chosen by the user (retrieved fromi_res).plot(s): Finally, this line is plotting the fetched data on the chart.
This is a relatively simple example, but it demonstrates the flexibility and user-friendliness that input.timeframe brings to Pine Script.
Key Takeaway
The input.timeframe function is a powerful tool in Pine Script for adding user configuration options. Understanding how to properly use this function allows script creators to build more dynamic, flexible, and user-friendly scripts. It promotes interactive user involvement by letting them specify their preferred timeframe, enhancing their experience.
Conclusion
Mastering Pine Script’s input.timeframe function helps you provide users with customization options, making your scripts more flexible and interactive. By understanding its arguments and syntax, you can easily incorporate it into your own scripts, enhancing their utility and functionality. As demonstrated, even a simple implementation can significantly improve your script’s user experience. Practice using input.timeframe in different scenarios to take full advantage of its capabilities.