Transformation and statistics functions

A library of general functions for evaluating statistical and other mathematical properties of data series (not necessarily prices).

Correlation(vars Data1, vars Data2, int TimePeriod): var

Pearson's correlation coefficient between two data series over the given TimePeriod, in the range between -1..+1. A coefficient of +1.0, a "perfect positive correlation," means that changes in Data2 cause identical changes in Data1 (e.g., a change in the indicator will result in an identical change in the asset price). A coefficient of -1.0, a "perfect negative correlation," means that changes in Data2 cause identical changes in Data1, but in the opposite direction. A coefficient of zero means there is no relationship between the two series and that a change in Data2 will have no effect on Data1. This function can be also used to get the autocorrelation of a series by calculating the correlation coefficient between the original series and the same series lagged by one or two bars (series+1 or series+2).

Covariance(vars Data1, vars Data2, int TimePeriod): var

Covariance between two data series. Can be used to generate a covariance matrix f.i. for the markowitz efficient frontier calculation.

Fisher(vars Data): var

Fisher Transform; transforms a normalized Data series to a normal distributed range. The return value has no theoretical limit, but most values are between -1 .. +1. All Data values must be in the -1 .. +1 range, f.i. by normalizing with the AGC, Normalize, or cdf function. The minimum Data length is 1. Source available in indicators.c.

FisherInv(vars Data): var

Inverse Fisher Transform; compresses the Data series to be between -1 and +1. The minimum length of the Data series is 1. Source available in indicators.c.

FisherN(vars Data, int TimePeriod): var

Fisher Transform with normalizing; normalizes the Data series with the given TimePeriod and then transforms it to a normal distributed range. Similar to a Normalize filter (see below), but more selective due to the normal distribution of the output. The return value has no theoretical limit, but most values are in the -1.5 .. +1.5 range. The minimum length of the Data series is equal to TimePeriod. The function internally creates series and thus must be called in a fixed order in the script. Source available in indicators.c.

FractalDimension(vars Data, int TimePeriod): var

Fractal dimension of the Data series; normally 1..2. Smaller values mean more 'jaggies'. Can be used to detect the current market regime or to adapt moving averages to the fluctuations of a price series. Requires a lookback period of twice the TimePeriod. Source available in indicators.c.

Gauss(vars Data, int TimePeriod): var

Gauss Filter, returns a weighted average of the data within the given time period, with the weight curve equal to the Gauss Normal Distribution. Useful for removing noise by smoothing raw data. The minimum length of the Data series is equal to TimePeriod, the lag is half the TimePeriod.

HTDcPeriod(vars Data): var

Hilbert Transform - Dominant Cycle Period, developed by John Ehlers. Hilbert transform algorithms are explained in Ehler's book "Rocket Science for Traders" (see book list). This function is equivalent, but less accurate than the DominantPeriod function.

HTDcPhase(vars Data): var

Hilbert Transform - Dominant Cycle Phase.

HTPhasor(vars Data): var

Hilbert Transform - Phasor Components. Result in rInPhase, rQuadrature.

HTSine(vars Data): var

Hilbert Transform - SineWave. Result in rSine, rLeadSine.

HTTrendline(vars Data): var

Hilbert Transform - Instantaneous Trendline.

HTTrendMode(vars Data): int

Hilbert Transform trend indicator - returns 1 for Trend Mode, 0 for Cycle Mode.

Hurst (vars Data, int TimePeriod): var

Hurst exponent of the Data series; between 0..1. The Hurst exponent measures the 'memory' of a series. It quantifies the autocorrelation, i.e. the tendency either to revert to the mean (Hurst < 0.5) or to continue trending in a direction (Hurst > 0.5). This way the Hurst exponent can detect if the market is in a trending state. The TimePeriod window (minimum 20) must have sufficient length to catch the long-term trend. The function internally creates a series and thus must be called in a fixed order in the script. Source available in indicators.c.

LinearReg(vars Data, int TimePeriod): var

Linear Regression, also known as the "least squares method" or "best fit". Linear Regression attempts to fit a straight trendline between several data points in such a way that the distance between each data point and the trendline is minimized. For each point, the straight line over the specified previous bar period is determined in terms of y = b + m*x. The LinearReg function returns b+m*(TimePeriod-1).
LinearReg is a TA-LIB function. For higher order regression, use the polyfit / polynom functions. For pre-trained logistic regression with multiple variables, use the advise(PERCEPTRON,...) function.

LinearRegAngle(vars Data, int TimePeriod): var

Linear Regression Angle. Returns m converted to degrees. Due to the different x and y units of a price chart, the angle is normally of little use.

LinearRegIntercept(vars Data, int TimePeriod): var

Linear Regression Intercept. Returns b.

LinearRegSlope(vars Data, int TimePeriod): var

Linear Regression Slope. Returns m as data difference per bar.

MaxVal(vars Data, int TimePeriod): var

Highest value over a specified period.

MaxIndex(vars Data, int TimePeriod): int

Index of highest value over a specified period. 0 = highest value is at current bar, 1 = at one bar ago, and so on. If the series was shifted (+N), add the offset N to the returned index for getting the index of the series.

Median(vars Data, int TimePeriod): var

Median Filter; sorts the elements of the Data series and returns their middle value within the given time period. Useful for removing noise spikes by eliminating extreme values. The minimum length of the Data series is equal to TimePeriod, the lag is half the TimePeriod. See also Percentile.

MinVal(vars Data, int TimePeriod): var

Lowest value over a specified period.

MinIndex(vars Data, int TimePeriod): int

Index of lowest value over a specified period. 0 = lowest value is at current bar, 1 = at one bar ago, and so on. If the series was shifted (+N), add the offset N to the returned index for getting the index of the series.

MinMax(vars Data, int TimePeriod): var

Lowest and highest values over a specified period. Result in rMin, rMax.

MinMaxIndex(vars Data, int TimePeriod): int

Indexes of lowest and highest values over a specified period. Result in rMinIdx, rMaxIdx. 0 = current bar, 1 = one bar ago, and so on.

Mode(vars Data, int TimePeriod, int Steps): var

Most frequent Data value within TimePeriod. For this the Data range is divided into Steps separate ranges, and the number of values that fall into a range is counted. The function returns the value with the highest count.

Moment(vars Data, int TimePeriod, int N): var

The statistical moment N (1..4) of the Data series section given by TimePeriod. The first moment is the mean, the second is the variance, third is skewness, and fourth ist kurtosis. The standard deviation is the square root of the second moment. Source available in indicators.c.

Normalize(vars Data, int TimePeriod): var

Transforms the Data series to the -1...+1 range within the given TimePeriod. Similar to the AGC function, but does not differentiate between attack and decay. The minimum length of the Data series is equal to TimePeriod. Source available in indicators.c. See also scale.

NumInRange(vars Low, vars High, var Min, var Max, int Length): var

Number of data ranges, given by their Low and High values, that lie completely inside the interval from Min to Max within the given Length. Can be used to calculate the distribution of prices or candles. Low and High can be set to the same value for counting all values in the interval, or swapped for counting all candles that touch the interval. Returns a value of 1..TimePeriod. Source available in indicators.c. See also PercentRank.

NumRiseFall(vars Data, int TimePeriod): var

Length of the last streak of rising or falling values in the Data series, back to the given TimePeriod. For a rising sequence its length is returned, for a falling sequence the negative length (f.i. -3 when Data[3] < Data[2] > Data[1] > Data[0]). Range: 1..TimePeriod-1. See the RandomWalk script for an example. Source available in indicators.c.

NumUp(vars Data, int TimePeriod, var Theshold): var

NumDn(vars Data, int TimePeriod, var Theshold): var

Number of upwards or downwards Data changes by more than the given Threshold within the TimePeriod, from 0 to TimePeriod-1. See also SumUp, SumDn. Source code in indicators.c.

Percentile(vars Data, int Length, var Percent): var

Returns the given percentile of the Data series with given Length; f.i. Percent = 95 returns the Data value that is above 95% of all other values. Percent = 50 returns the Median of the Data series.

PercentRank(vars Data, int Length, var Value): var

The opposite of Percentile: Returns the percentage of Data values within the given Length that are smaller or equal than the given Value; returns 100 when Value is the greatest in the data range. Can transform any series to a range of 0..100. See also NumInRange.

R2(vars Data, int Length): var

Coefficient of determination (+1...-1); similarity of the Data series with a straight line through its end points. At 1 the data series is equivalent to a straight line, at 0 or below even the mean of the data is a better fit to the straight line than the real data series.

ShannonGain(vars Data, int TimePeriod): var

Expected logarithmic gain rate of the Data series in the range of about +/-0.0005. The gain rate is derived from the Shannon probability P = (1 + Mean(Gain) / RootMeanSquare(Gain)) / 2, which is the likeliness of a rise or fall of a high entropy data series in the next bar period. A positive gain rate indicates that the series is more likely to rise, a negative gain rate indicates that it is more likely to fall. The zero crossover could be used for a trade signal. Algorithm by John Conover. Source available in indicators.c.

ShannonEntropy(vars Data, int Length, int PatternSize): var

Entropy of patterns in the Data series, in bit; can be used to determine the 'randomness' of the data. PatternSize (2..8) determines the partitioning of the data into patterns of up to 8 bit. Each Data value is either higher than the previous value, or it is not; this is a binary information and constitutes one bit of the pattern. The more random the patterns are distributed, the higher is the Shannon entropy. Totally random data has a Shannon entropy identical to the pattern size. Algorithm explained on the Financial Hacker blog; source available in indicators.c.

Spearman(vars Data, int TimePeriod): var

Spearman's rank correlation coefficient; correlation between the original Data series and the same series sorted in ascending order within TimePeriod (1..256). Returns the similarity to a steadily rising series and can be used to determine trend intensity and turning points. Range = -1..+1, lag = TimePeriod/2. For usage and details, see Stocks & Commodities magazine 2/2011. Source available in indicators.c.

StdDev(vars Data, int TimePeriod): var

Standard Deviation of the Data series in the time period, from the ta-lib; accuracy = 0.0001. Use instead the square root of the second Moment when high accuracy or long time periods are required.

Sum(vars Data, int TimePeriod): var

Sum of all Data elements in the time period.

SumUp(vars Data, int TimePeriod): var

SumDn(vars Data, int TimePeriod): var

Sum of all upwards or downwards Data changes within the TimePeriod. See also NumUp, NumDn. Source code in indicators.c.

TSF(vars Data, int TimePeriod): var

Time Series Forecast. Returns b + m*(TimePeriod), the Linear Regression forecast for the next bar.

Variance(vars Data, int TimePeriod): var

Variance of the Data series in the time period, from the ta-lib; accuracy = 0.0001. Use instead the second Moment when high accuracy or long time periods are required.

Standard parameters:

TimePeriod	The number of bars for the time period of the function, if any; or 0 for using a default period.
Length	The length of the Data series.
Data	A data series, often directly derived from the price functions price(), priceClose() etc.. Alternatively a user created series or any other double float array with the given minimum length can be used. If not mentioned otherwise, the minimum length of the Data series is TimePeriod. Some functions require a second data array Data2.

Usage example:

Volatility(Prices,20) calculates the standard volatility of a daily price series over the last 20 days.

Remarks:

The TA-Lib function prototypes are defined in include\functions.h. Information about the usage and the indicator algorithms can be found online at www.tadoc.org. The C source code of all included TA-Lib indicators is contained in Source\ta_lib.zip and can be studied for examining the algorithms. Some TA-Lib indicators that originally didn't work properly - such as Correlation or SAR - have been replaced by working versions. The C source code of most additional indicators that are not part the the TA-Lib is contained in Source\indicators.c.
All TA functions are applied on series and do normally not accept other data arrays. In the INITRUN, all TA functions return 0, and LookBack is automatically increased to the largest required lookback time by a TA function.
TimeFrame affects subsequent data series and thus also affects all indicators that use the data series as input. The TimePeriod is then not in Bar units, but in time frame units. TimeFrame has no effect on indicators that do not use data series.

Examples:

// plot some indicators
function run()
{
  set(PLOTNOW);
  var* Price = series(price());
	
// plot Bollinger bands
  BBands(Price,30,2,2,MAType_SMA);
  plot("Bollinger1",rRealUpperBand,BAND1,0x00CC00);
  plot("Bollinger2",rRealLowerBand,BAND2,0xCC00FF00);
  plot("SAR",SAR(0.02,0.02,0.2),DOT,RED);
  ZigZag(Price,20*PIP,5,BLUE);
	
// plot some other indicators	
  plot("ATR (PIP)",ATR(20)/PIP,NEW,RED);
  plot("Doji",CDLDoji(),NEW+BARS,BLUE);
  plot("FractalDim",FractalDimension(Price,30),NEW,RED);
  plot("ShannonGain",ShannonGain(Price,40),NEW,RED);
}