MTF Oscillator Framework [PineCoders]

2 Des 2020

This framework allows Pine coders to quickly build a complete multi-timeframe oscillator from any calculation producing values around a centerline, whether the values are bounded or not. Insert your calculation in the script and you have a ready-to-publish MTF Oscillator offering a plethora of presentation options and features.


█ HOW TO USE THE FRAMEWORK

1 — Insert your calculation in the `f_signal()` function at the top of the "Helper Functions" section of the script.
2 — Change the script's name in the `study()` declaration statement and the `alertcondition()` text in the last part of the "Plots" section.
3 — Adapt the default value used to initialize the CENTERLINE constant in the script's "Constants" section.
4 — If you want to publish the script, copy/paste the following description in your new publication's description and replace the "OVERVIEW" section with a description of your calculations.
5 — Voilà!


═════════════════════════════════════════════════════════════════════════


█ OVERVIEW

This oscillator calculates a directional value of True Range. When a bar is up, the positive value of True Range is used. A negative value is used when the bar is down. When there is no movement during the bar, a zero value is generated, even if True Range is different than zero. Because the unit of measure of True Range is price, the oscillator is unbounded (it does not have fixed upper/lower bounds).

True Range can be used as a metric for volatility, but by using a signed value, this oscillator will show the directional bias of progressively increasing/decreasing volatility, which can make it more useful than an always positive value of True Range.

The True Range calculation appeared for the first time in J. Welles Wilder's New Concepts in Technical Trading Systems book published in 1978. Wilder's objective was to provide a reliable measure of the effective movement—or range—between two bars, to measure volatility. True Range is also the building block used to calculate ATR (Average True Range), which calculates the average of True Range values over a given period using the `rma` averaging method—the same used in the calculation of another of Wilder's remarkable creations: RSI.


█ CONCEPTS

This oscillator's design stems from a few key concepts.

Relative Levels
Other than the centerline, relative rather than absolute levels are used to identify levels of interest. Accordingly, no fixed levels correspond to overbought/oversold conditions. Relative levels of interest are identified using:
 • A Donchian channel (historical highs/lows).
 • The oscillator's position relative to higher timeframe values.
 • Oscillator levels following points in time where a divergence is identified.

Higher timeframes
Two progressively higher timeframes are used to calculate larger-context values for the oscillator. The rationale underlying the use of timeframes higher than the chart's is that, while they change less frequently than the values calculated at the chart's resolution, they are more meaningful because more work (trader activity) is required to calculate them. Combining the immediacy of values calculated at the chart's resolution to higher timeframe values achieves a compromise between responsiveness and reliability.

Divergences as points of interest rather than directional clues
A very simple interpretation of what constitutes a divergence is used. A divergence is defined as a discrepancy between any bar's direction and the direction of the signal line on that same bar. No attempt is made to attribute a directional bias to divergences when they occur. Instead, the oscillator's level is saved and subsequent movement of the oscillator relative to the saved level is what determines the bullish/bearish state of the oscillator.

Conservative coloring scheme
Several additive coloring conditions allow the bull/bear coloring of the oscillator's main line to be restricted to specific areas meeting all the selected conditions. The concept is built on the premise that most of the time, an oscillator's value should be viewed as mere noise, and that somewhat like price, it only occasionally conveys actionable information.


█ FEATURES

Plots
 • Three lines can be plotted. They are named Main line, Line 2 and Line 3. You decide which calculation to use for each line:
   • The oscillator's value at the chart's resolution.
   • The oscillator's value at a medium timeframe higher than the chart's resolution.
   • The oscillator's value at the highest timeframe.
   • An aggregate line calculated using a weighed average of the three previous lines (see the Aggregate Weights section of Inputs to configure the weights).
 • The coloring conditions, divergence levels and the Hi/Lo channel always apply to the Main line, whichever calculation you decide to use for it.
 • The color of lines 2 and 3 are fixed but can be set in the "Colors" section of Inputs.
 • You can change the thickness of each line.
 • When the aggregate line is displayed, higher timeframe values are only used in its calculation when they become available in the chart's history,
  otherwise the aggregate line would appear much later on the chart. To indicate when each higher timeframe value becomes available,
  a small label appears near the centerline.
 • Divergences can be shown as small dots on the centerline.
 • Divergence levels can be shown. The level and fill are determined by the oscillator's position relative to the last saved divergence level.
 • Bull/bear markers can be displayed. They occur whenever a new bull/bear state is determined by the "Main Line Coloring Conditions".
 • The Hi/Lo (Donchian) channel can be displayed, and its period defined.
 • The background can display the state of any one of 11 different conditions.
 • The resolutions used for the higher timeframes can be displayed to the right of the last bar's value.
 • Four key values are always displayed in the Data Window (fourth icon down to the right of your chart):
  oscillator values for the chart, medium and highest timeframes, and the oscillator's instant value before it is averaged.

Main Line Coloring Conditions
 • Nine different conditions can be selected to determine the bull/bear coloring of the main line. All conditions set to "ON" must be met to determine the bull/bear state.
 • A volatility state can also be used to filter the conditions.
 • When the coloring conditions and the filter do not allow for a bull/bear state to be determined, the neutral color is used.

Signal
 • Seven different averages can be used to calculate the average of the oscillator's value.
 • The average's period can be set. A period of one will show the instant value of the oscillator,
  provided you don't use linear regression or the Hull MA as they do not work with a period of one.
 • An external signal can be used as the oscillator's instant value. If an already averaged external value is used, set the period to one in this indicator.
 • For the cases where an external signal is used, a centerline value can be set.

Higher Timeframes
 • The two higher timeframes are named Medium timeframe and Highest timeframe. They can be determined using one of three methods:
  • Auto-steps: the higher timeframes are determined using the chart's resolution. If the chart uses a seconds resolution, for example,
   the medium and highest resolutions will be 15 and 60 minutes.
  • Multiples: the timeframes are calculated using a multiple of the chart's resolution, which you can set.
  • Fixed: the set timeframes do not change with the chart's resolution.

Repainting
 • Repainting can be controlled separately for the chart's value and the higher timeframe values.
 • The default is a repainting chart value and non-repainting higher timeframe values. The Aggregate line will thus repaint by default,
  as it uses the chart's value along with the higher timeframes values.

Aggregate Weights
 • The weight of each component of the Aggregate line can be set.
 • The default is equal weights for the three components, meaning that the chart's value accounts for one third of the weight in the Aggregate.

High Volatility
 • This provides control over the volatility filter used in the Main line's coloring conditions and the background display.
 • Volatility is determined to be high when the short-term ATR is greater than the long-term ATR.

Colors
 • You can define your own colors for all of the oscillator's plots.
 • The default colors will perform well on both white and black chart backgrounds.

Alerts
 • An alert can be defined for the script. The alert will trigger whenever a bull/bear marker appears in the indicator's display.
  The particular combination of coloring conditions and the display of bull/bear markers when you create the alert will thus determine when the alert triggers.
  Once the alerts are created, subsequent changes to the conditions controlling the display of markers will not affect the existing alert(s).
 • You can create multiple alerts from this script, each triggering on different conditions.

Backtesting & Trading Engine Signal Line
 • An invisible plot named "BTE Signal" is provided. It can be used as an entry signal when connected to the PineCoders Backtesting & Trading Engine as an external input.
  It will generate an entry whenever a marker is displayed.



Look first. Then leap.

2 Des 2020

Catatan Rilis

Updated comments and the `security()` calls.

23 Des 2020

Catatan Rilis

Added the display of divergences on chart bars. Fine-tuned the detection of divergences.