VolatilityIndicators

Library "VolatilityIndicators"
This is a library of Volatility Indicators.
It aims to facilitate the grouping of this category of indicators, and also offer the customized supply of
the parameters and sources, not being restricted to just the closing price.

@Thanks and credits:
1. Dynamic Zones: Leo Zamansky, Ph.D., and David Stendahl
2. Deviation: Karl Pearson (code by TradingView)
3. Variance: Ronald Fisher (code by TradingView)
4. Z-score: Veronique Valcu (code by HPotter)
5. Standard deviation: Ronald Fisher (code by TradingView)
6. ATR (Average True Range): J. Welles Wilder (code by TradingView)
7. ATRP (Average True Range Percent): millerrh
8. Historical Volatility: HPotter
9. Min-Max Scale Normalization: gorx1
10. Mean Normalization: gorx1
11. Standardization: gorx1
12. Scaling to unit length: gorx1
13. LS Volatility Index: Alexandre Wolwacz (Stormer), Fabrício Lorenz, Fábio Figueiredo (Vlad) (code by me)
14. Bollinger Bands: John Bollinger (code by TradingView)
15. Bollinger Bands %: John Bollinger (code by TradingView)
16. Bollinger Bands Width: John Bollinger (code by TradingView)

dev(source, length, anotherSource)
  Deviation. Measure the difference between a source in relation to another source
  Parameters:
    source (float)
    length (simple int): (int) Sequential period to calculate the deviation
    anotherSource (float): (float) Source to compare
  Returns: (float) Bollinger Bands Width

variance(src, mean, length, biased, degreesOfFreedom)
  Variance. A statistical measurement of the spread between numbers in a data set. More specifically,
variance measures how far each number in the set is from the mean (average), and thus from every other number in the set.
Variance is often depicted by this symbol: σ2. It is used by both analysts and traders to determine volatility and market security.
  Parameters:
    src (float): (float) Source to calculate variance
    mean (float): (float) Mean (Moving average)
    length (simple int): (int) The sequential period to calcule the variance (number of values in data set)
    biased (simple bool): (bool) Defines the type of standard deviation. If true, uses biased sample variance (n),
    degreesOfFreedom (simple int): (int) Degrees of freedom. The number of values in the final calculation of a statistic that are free to vary.
Default value is n-1, where n here is length. Only applies when biased parameter is defined as true.
  Returns: (float) Standard deviation

stDev(src, length, mean, biased, degreesOfFreedom)
  Measure the Standard deviation from a source in relation to it's moving average.
In this implementation, you pass the average as a parameter, allowing a more personalized calculation.
  Parameters:
    src (float): (float) Source to calculate standard deviation
    length (simple int): (int) The sequential period to calcule the standard deviation
    mean (float): (float) Moving average.
    biased (simple bool): (bool) Defines the type of standard deviation. If true, uses biased sample variance (n),
else uses unbiased sample variance (n-1 or another value, as long as it is in the range between 1 and n-1), where n=length.
    degreesOfFreedom (simple int): (int) Degrees of freedom. The number of values in the final calculation of a statistic that are free to vary.
Default value is n-1, where n here is length.
  Returns: (float) Standard deviation

zscore(src, mean, length, biased, degreesOfFreedom)
  Z-Score. A z-score is a statistical measurement that indicates how many standard deviations a data point is from
the mean of a data set. It is also known as a standard score. The formula for calculating a z-score is (x - μ) / σ,
where x is the individual data point, μ is the mean of the data set, and σ is the standard deviation of the data set.
Z-scores are useful in identifying outliers or extreme values in a data set. A positive z-score indicates that the
data point is above the mean, while a negative z-score indicates that the data point is below the mean. A z-score of
0 indicates that the data point is equal to the mean.
Z-scores are often used in hypothesis testing and determining confidence intervals. They can also be used to compare
data sets with different units or scales, as the z-score standardizes the data. Overall, z-scores provide a way to
measure the relative position of a data point in a data
  Parameters:
    src (float): (float) Source to calculate z-score
    mean (float): (float) Moving average.
    length (simple int): (int) The sequential period to calcule the standard deviation
    biased (simple bool): (bool) Defines the type of standard deviation. If true, uses biased sample variance (n),
else uses unbiased sample variance (n-1 or another value, as long as it is in the range between 1 and n-1), where n=length.
    degreesOfFreedom (simple int): (int) Degrees of freedom. The number of values in the final calculation of a statistic that are free to vary.
Default value is n-1, where n here is length.
  Returns: (float) Z-score

atr(source, length)
  ATR: Average True Range. Customized version with source parameter.
  Parameters:
    source (float): (float) Source
    length (simple int): (int) Length (number of bars back)
  Returns: (float) ATR

atrp(length, sourceP)
  ATRP (Average True Range Percent)
  Parameters:
    length (simple int): (int) Length (number of bars back) for ATR
    sourceP (float): (float) Source for calculating percentage relativity
  Returns: (float) ATRP

atrp(source, length, sourceP)
  ATRP (Average True Range Percent). Customized version with source parameter.
  Parameters:
    source (float): (float) Source for ATR
    length (simple int): (int) Length (number of bars back) for ATR
    sourceP (float): (float) Source for calculating percentage relativity
  Returns: (float) ATRP

historicalVolatility(lengthATR, lengthHist)
  Historical Volatility
  Parameters:
    lengthATR (simple int): (int) Length (number of bars back) for ATR
    lengthHist (simple int): (int) Length (number of bars back) for Historical Volatility
  Returns: (float) Historical Volatility

historicalVolatility(source, lengthATR, lengthHist)
  Historical Volatility
  Parameters:
    source (float): (float) Source for ATR
    lengthATR (simple int): (int) Length (number of bars back) for ATR
    lengthHist (simple int): (int) Length (number of bars back) for Historical Volatility
  Returns: (float) Historical Volatility

minMaxNormalization(src, numbars)
  Min-Max Scale Normalization. Maximum and minimum values are taken from the sequential range of
numbars bars back, where numbars is a number defined by the user.
  Parameters:
    src (float): (float) Source to normalize
    numbars (simple int): (int) Numbers of sequential bars back to seek for lowest and hightest values.
  Returns: (float) Normalized value

minMaxNormalization(src, numbars, minimumLimit, maximumLimit)
  Min-Max Scale Normalization. Maximum and minimum values are taken from the sequential range of
numbars bars back, where numbars is a number defined by the user.
In this implementation, the user explicitly provides the desired minimum (min) and maximum (max) values for the scale,
rather than using the minimum and maximum values from the data.
  Parameters:
    src (float): (float) Source to normalize
    numbars (simple int): (int) Numbers of sequential bars back to seek for lowest and hightest values.
    minimumLimit (simple float): (float) Minimum value to scale
    maximumLimit (simple float): (float) Maximum value to scale
  Returns: (float) Normalized value

meanNormalization(src, numbars, mean)
  Mean Normalization
  Parameters:
    src (float): (float) Source to normalize
    numbars (simple int): (int) Numbers of sequential bars back to seek for lowest and hightest values.
    mean (float): (float) Mean of source
  Returns: (float) Normalized value

standardization(src, mean, stDev)
  Standardization (Z-score Normalization). How "outside the mean" values relate to the standard deviation (ratio between first and second)
  Parameters:
    src (float): (float) Source to normalize
    mean (float): (float) Mean of source
    stDev (float): (float) Standard Deviation
  Returns: (float) Normalized value

scalingToUnitLength(src, numbars)
  Scaling to unit length
  Parameters:
    src (float): (float) Source to normalize
    numbars (simple int): (int) Numbers of sequential bars back to seek for lowest and hightest values.
  Returns: (float) Normalized value

lsVolatilityIndex(movingAverage, sourceHvol, lengthATR, lengthHist, lenNormal, lowerLimit, upperLimit)
  LS Volatility Index. Measures the volatility of price in relation to an average.
  Parameters:
    movingAverage (float): (float) A moving average
    sourceHvol (float): (float) Source for calculating the historical volatility
    lengthATR (simple int): (float) Length for calculating the ATR (Average True Range)
    lengthHist (simple int): (float) Length for calculating the historical volatility
    lenNormal (simple int): (float) Length for normalization
    lowerLimit (simple int)
    upperLimit (simple int)
  Returns: (float) LS Volatility Index

lsVolatilityIndex(sourcePrice, movingAverage, sourceHvol, lengthATR, lengthHist, lenNormal, lowerLimit, upperLimit)
  LS Volatility Index. Measures the volatility of price in relation to an average.
  Parameters:
    sourcePrice (float): (float) Source for measure the distance
    movingAverage (float): (float) A moving average
    sourceHvol (float): (float) Source for calculating the historical volatility
    lengthATR (simple int): (float) Length for calculating the ATR (Average True Range)
    lengthHist (simple int): (float) Length for calculating the historical volatility
    lenNormal (simple int)
    lowerLimit (simple int)
    upperLimit (simple int)
  Returns: (float) LS Volatility Index

bollingerBands(src, length, mult, basis)
  Bollinger Bands. A Bollinger Band is a technical analysis tool defined by a set of lines plotted
two standard deviations (positively and negatively) away from a simple moving average (SMA) of the security's price,
but can be adjusted to user preferences. In this version you can pass a customized basis (moving average), not only SMA.
  Parameters:
    src (float): (float) Source to calculate standard deviation used in Bollinger Bands
    length (simple int): (int) The time period to be used in calculating the standard deviation
    mult (simple float): (float) Multiplier used in standard deviation. Basically, the upper/lower bands are standard deviation multiplied by this.
    basis (float): (float) Basis of Bollinger Bands (a moving average)
  Returns: (float) A tuple of Bollinger Bands, where index 1=basis; 2=basis+dev; 3=basis-dev; and dev=multiplier*stdev

bollingerBands(src, length, aMult, basis)
  Bollinger Bands. A Bollinger Band is a technical analysis tool defined by a set of lines plotted
two standard deviations (positively and negatively) away from a simple moving average (SMA) of the security's price,
but can be adjusted to user preferences. In this version you can pass a customized basis (moving average), not only SMA.
Also, various multipliers can be passed, thus getting more bands (instead of just 2).
  Parameters:
    src (float): (float) Source to calculate standard deviation used in Bollinger Bands
    length (simple int): (int) The time period to be used in calculating the standard deviation
    aMult (float): (float) An array of multiplies used in standard deviation. Basically, the upper/lower bands are standard deviation multiplied by this.
This array of multipliers permit the use of various bands, not only 2.
    basis (float): (float) Basis of Bollinger Bands (a moving average)
  Returns: (float) An array of Bollinger Bands, where:
index 1=basis; 2=basis+dev1; 3=basis-dev1; 4=basis+dev2, 5=basis-dev2, 6=basis+dev2, 7=basis-dev2, Nup=basis+devN, Nlow=basis-devN
and dev1, dev2, devN are ```multiplier N * stdev```

bollingerBandsB(src, length, mult, basis)
  Bollinger Bands %B - or Percent Bandwidth (%B).
Quantify or display where price (or another source) is in relation to the bands.
%B can be useful in identifying trends and trading signals.
Calculation:
%B = (Current Price - Lower Band) / (Upper Band - Lower Band)
  Parameters:
    src (float): (float) Source to calculate standard deviation used in Bollinger Bands
    length (simple int): (int) The time period to be used in calculating the standard deviation
    mult (simple float): (float) Multiplier used in standard deviation
    basis (float): (float) Basis of Bollinger Bands (a moving average)
  Returns: (float) Bollinger Bands %B

bollingerBandsB(src, length, aMult, basis)
  Bollinger Bands %B - or Percent Bandwidth (%B).
Quantify or display where price (or another source) is in relation to the bands.
%B can be useful in identifying trends and trading signals.
Calculation
%B = (Current Price - Lower Band) / (Upper Band - Lower Band)
  Parameters:
    src (float): (float) Source to calculate standard deviation used in Bollinger Bands
    length (simple int): (int) The time period to be used in calculating the standard deviation
    aMult (float): (float) Array of multiplier used in standard deviation. Basically, the upper/lower bands are standard deviation multiplied by this.
This array of multipliers permit the use of various bands, not only 2.
    basis (float): (float) Basis of Bollinger Bands (a moving average)
  Returns: (float) An array of Bollinger Bands %B. The number of results in this array is equal the numbers of multipliers passed via parameter.

bollingerBandsW(src, length, mult, basis)
  Bollinger Bands Width. Serve as a way to quantitatively measure the width between the Upper and Lower Bands
Calculation:
Bollinger Bands Width = (Upper Band - Lower Band) / Middle Band
  Parameters:
    src (float): (float) Source to calculate standard deviation used in Bollinger Bands
    length (simple int): (int) Sequential period to calculate the standard deviation
    mult (simple float): (float) Multiplier used in standard deviation
    basis (float): (float) Basis of Bollinger Bands (a moving average)
  Returns: (float) Bollinger Bands Width

bollingerBandsW(src, length, aMult, basis)
  Bollinger Bands Width. Serve as a way to quantitatively measure the width between the Upper and Lower Bands
Calculation
Bollinger Bands Width = (Upper Band - Lower Band) / Middle Band
  Parameters:
    src (float): (float) Source to calculate standard deviation used in Bollinger Bands
    length (simple int): (int) Sequential period to calculate the standard deviation
    aMult (float): (float) Array of multiplier used in standard deviation. Basically, the upper/lower bands are standard deviation multiplied by this.
This array of multipliers permit the use of various bands, not only 2.
    basis (float): (float) Basis of Bollinger Bands (a moving average)
  Returns: (float) An array of Bollinger Bands Width. The number of results in this array is equal the numbers of multipliers passed via parameter.

dinamicZone(source, sampleLength, pcntAbove, pcntBelow)
  Get Dynamic Zones
  Parameters:
    source (float): (float) Source
    sampleLength (simple int): (int) Sample Length
    pcntAbove (simple float): (float) Calculates the top of the dynamic zone, considering that the maximum values are above x% of the sample
    pcntBelow (simple float): (float) Calculates the bottom of the dynamic zone, considering that the minimum values are below x% of the sample
  Returns: A tuple with 3 series of values: (1) Upper Line of Dynamic Zone;
(2) Lower Line of Dynamic Zone; (3) Center of Dynamic Zone (x = 50%)

Examples:

Phát hành các Ghi chú:

v2
:
- Renamed "Dinamic Zones" to "Dynamic Zones";
- Added examples on main chart.

Phát hành các Ghi chú:

v3
Added Standard Error

Phát hành các Ghi chú:

v4

Added:
1. Keltner Channels.
2. Keltner Channels B% (or Percent Bandwidth): same as Bollinger Bands %B, but instead of Bollinger Bands, the logic of Keltner Channels is used to obtain the Percent Bandwidth (%B).
3. Keltner Channels W (Keltner Channels Width): same as Bollinger Bands Width, but instead of Bollinger Bands, the logic of Keltner Channels is used to obtain the Width.
4. Moving Average Envelopes.
5. Donchian Channels.

Examples:
Keltner Channels

Keltner Channels with custom source

Keltner Channels with multiple bands

Keltner Channels %B - or Percent Bandwidth (%B)

With normalization

Keltner Channels %B with multiple bands

Keltner Channels Width

Keltner Channels Width with multiple bands

Moving Average Envelopes

Moving Average Envelopes with multiple bands

Donchian Channels with custom source for high and low

Donchian Channels with multiple bands

Phát hành các Ghi chú:

v5
Minor fix in ta.highest/ta.lowest to function with hl2 sources.

Phát hành các Ghi chú:

v6

Fixed functions without export keyword.

Phát hành các Ghi chú:

v7

- Added t-score function. A t-score is a statistical measurement that indicates how many standard errors a data point is from
the mean of a data set. It is also known as a standard score. When to use t-score instead of z-score? When the sample size is small (n < 30).

- Now there are two ways to calculate historical volatility: Accumulated ATR Version and Returns version. Both forms of volatility calculation have their specific utilities and applications. Therefore, it is worthwhile to have both approaches available, and one should not necessarily replace the other. Each method has its advantages and may be more appropriate in different contexts.

The first approach, using the accumulated ATR, can be useful when you want to take into account the implied volatility of prices over time, reflecting broader price movements and higher impact events. It can be especially relevant in scenarios where unexpected events can drastically affect prices.

The second approach, using the standard deviation of returns, is more common and traditionally used to measure historical volatility. It considers the variability of prices relative to their average, providing a more general measure of market volatility.

Therefore, both forms of calculation have their merits and can be useful depending on the context and specific analysis needs. Having both options available gives users flexibility in choosing the most appropriate volatility measure for the situation at hand.

- The LS Volatility Index indicator has been updated to use one of these two strands.

- Minor fix in descriptions.

Phát hành các Ghi chú:

v8

Improvements to LS Volatility Index parameters.