series(var Value, int Length): vars

Parameters:

Returns:

Usage:

ref(var Value, int Index): var

SeriesLength

SeriesBuffer

Remarks:

• Series correspond to serial variables in EasyLanguage™. The n-th element of a series is accessed by adding a [n] to the series name, where n is a positive integer number. For instance, myseries[0] is the most recent element, myseries[1] is the element of one time frame ago, and so on. n must be positive and smaller than the series length.
•  !!  The series function is responsible for allocating and shifting series. Therefore it must be called at any bar, either inside the run function or from a function that is called from the run function.
•  !!  An internal counter determines the pointer to be returned by a series() call. For keeping the counter in sync, all series() calls must be in the same order. Therefore they must not be skipped by if or other conditions that change from bar to bar (see example below). If the content of a series shall depend on if conditions, simply set its [0] element dependent on if. These restrictions also apply to all functions that internally create series, such as some indicator or signal processing functions. 
•  !!  Since the LookBack value is normally only known after the INITRUN, series are allocated in the FIRSTRUN. During the INITRUN they are set to a temporary pointer and filled with the initial value. This temporary content is overwritten by the series allocation in the FIRSTRUN. Series are only valid during the session and released after the EXITRUN.
• Dynamic series are normally shifted by the series call at the end of any bar or time frame when the NOSHIFT flag is not set. The [0] element is then moved to the [1] element, the [1] element to the [2] element and so on. The current Value becomes the new [0] element. Due to this mechanism, the series contains its elements in reverse chronological order with the most recent element at the start. For synchronizing series to external events or to longer time frames, either set the TimeFrame variable accordingly before the series() call, and set it back afterwards. Or use the NOSHIFT flag. The element [n] then corresponds to the nth event or time frame in the past.
• Static series (defined with a negative Length) are not automatically shifted, but can be shifted by script with the shift function. They can be used for storing arbitrary per-asset or per-algo variables, for excluding out-of-market time periods from indicators, or for shifting series by arriving price ticks in the tick function. Like any series, static series are allocated in the FIRSTRUN, so don't initialize them before as those values will be lost. Usage examples can be found in the SpecialBars script or in the SAR code in indicators.c.
• For offsetting a series into the past, add an offset +n. This creates a pointer onto the n-th element of the series. For instance, (MySeries+1) is MySeries at 1 bar offset into the past, excluding the last element MySeries[0]. This allows to access series elements in different ways: for instance, MySeries[3] is the same as (MySeries+2)[1] and the same as (MySeries+3)[0]. As the offset +n lets the series begin at the nth element, it reduces the available length of the series by n. When calling an indicator with a series with an offset, make sure that LookBack is always higher than the required lookback period of the function plus the unstable period plus the highest possible offset of the series.
• For adding or subtracting two series, create a series of the sum or difference of the recent elements, f.i. vars Sums = series(Data1[0] + Data2[0]);.
• Some functions expect a single value, other functions expect a series as parameter. When a function expects a single value from a series, use the last element (MySeries[0]). When the function expects a whole series, use MySeries or MySeries+n.
• If a series changes slowly, like an EMA, fill it initially with an average value. This prevents initialization effects when an accumulative indicator needs many bars to 'creep' from 0 to its first value.
• A value returned by a function can be converted to a series by using it as the first parameter to the series function. For instance, series(price()) is a series that contains the price value; series(SMA(series(priceClose()),30)) is a series containing the 30-bar Simple Moving Average of the Close value.
• The rev function reverses a series so that the [0] element is the earliest.
• The length parameter should not exceed the LookBack period, at least not when the series affects trading. Otherwise the script would trade differently in the fist time after starting..
• Every series requires memory and CPU resources. Therefore do not create more or longer series than needed. The longer a series, the more memory is required and the slower is script execution due to internal shifting the series on every time frame.
• If you need to create extremely many series and get an Error 041, increase TradesPerBar. This determines not only the maximum number of trades, but also the maximum number of series.
• For accessing the same series from several functions, declare a global vars, and set it with a series call in the run function.

Examples:

// create a series with the high-low price differences
vars PriceRanges = series(priceH()-priceL());
 
// compare the current range with the range from 3 bars ago
if(PriceRanges[0] > PriceRanges[3])
  ...
 
// calculate a 20-bar Simple Moving Average containing the price differences from 5 bars ago
var Average5 = SMA(PriceRange+5,20);


// wrong use of conditional series
if(priceClose() > Threshold) {
  vars X = series(priceClose()); // error message!
  vars Y = series(SMA(X,100)); // error message!
  ...
}

// correct use of conditional series
vars X = series(), Y = series();
if(priceClose() > Threshold) {
  X[0] = priceClose(); // ok!
  Y[0] = SMA(X,100);
  ...
}

// exclude out-of-market bars from a series
if(!market(EST,0)) set(NOSHIFT);
vars InMarketPrices = series(priceC());
set(NOSHIFT|OFF);

// use arrays of series
vars MySeriesArray[3]; // declare an array of series 
...
for(i=0; i<3; i++) 
  MySeriesArray[i] = series(); // fill the array with series 
...
(MySeriesArray[0])[0] = 123; // access the first element of the first series. Mind the parentheses!

See also: