Bars

Functionality

A classical indicator calculates one or multiple values using an existing data series.

Data series can be anything from closing prices to daily lows or values of an hourly period etc.

Every period (meaning all candles of one day, one hour etc.) is assigned one or more indicator values. The following example is based on an indicator value, such as with a moving average, for example. To calculate a smoothed moving average, AgenaTrader needs a data series. In this example we will use the closing prices. All closing prices of a bar (candle) that are represented in the chart will be saved in a list and indexed.

The current closing price, meaning the closing price of the bar that is on the right-hand side of the chart, will be assigned an index of 0. The bar to the left of that will have an index of 1 and so on. The oldest bar displayed will have an index value of 500.

Whenever a new bar is added within a session it will become the new index 0; the bar to the left of it, which previously had an index of 0, will become index 1 and so on. The oldest bar will become index 501. Within a script (a self-created program/algorithm) the Close will be representative for the array (list) of all closing prices. The last closing price is thus Close [0]; the closing price previous to this will become Close [1], the value before that will become Close [2] and the oldest bar will be Close [501]. The number within the squared brackets represents the index. AgenaTrader allows you to use the „bars ago" expression for this in general cases.

Obviously, every bar will not only have a closing value but also a High, Low, Open, Median, Typical, Weighted, Time and Volume. Thus, the high of the candle that occurred 10 days ago will be High [10], yesterday’s low Low [1]...

Important tip:

The previous examples all assume that the calculations will occur at the end of a period. The value of the currently running index is not being taken into consideration.

If you wish to use the values of the currently forming candle then you will need to set the value of

CalculateOnClosedBar to „false".

In this case the currently running bar will have the value 0, the bar next to the current bar will have the value 1 and so on. The oldest bar (as in the example above) would now have the value 502.

With close [0] you would receive the most recent value of the last price that your data provider transmitted to AgenaTrader. All values of the bar (high [0], low [0]…) may still change as long as the bar is not yet finished/closed and a new bar has not yet started. Only the open [0] value will not change.

Properties

Properties of Bars

"Bars" represents a list of all bars (candles) within a chart (see Functionality, Bars).

Bars (public IBars Bars) can be used directly in a script and equates to BarsArray [0] (see Bars.GetNextSessionTimeSpan for more information).

The list of bars itself has many properties that can be used in AgenaScript. Properties are always indicated by a dot before the objects (in this case bars, list of candles).

Bars.Count

Bars.CurrentSessionBeginTime

Bars.CurrentSessionEndTime

Bars.GetBar

Bars.GetBarIndex

Bars.GetBarsAgo

Bars.GetByIndex

Bars.GetClose

Bars.GetHigh

Bars.GetLow

Bars.GetNextSessionTimeSpan

Bars.GetOpen

Bars.GetSessionBegin

Bars.GetTime

Bars.GetVolume

Bars.Instrument

Bars.IsEod

Bars.IsFalling

Bars.IsFirstBarInSession

Bars.IsGrowing

Bars.IsIntraday

Bars.IsNtb

Bars.SessionBreak

Bars.LastBarCompleteness

Bars.NextSessionBeginTime

Bars.NextSessionEndTime

Bars.TailBottom

Bars.TailTop

Bars.TicksCountForLastBar

Bars.TicksCountInTotal

Bars.TimeFrame

BarsCountForSession

IsProcessingBarIndexLast

With the OnCalculate() method you can use any properties you want without having to test for a null reference. As soon as the function OnCalculate() is called up by AgenaScript, it is assumed that an object is also available. If you wish to use these properties outside of OnCalculate() then you should first perform a test for null references using if (Bars != null).

Bars.Count

Description

Bars.Count gives you the amount of bars in a data series.

See Properties for additional information.

Return Value

Type int Amount of Bars

Usage

Bars.Count

More Information

The value of ProcessingBarIndex can only be lesser than or equal to Bars.Count - 1

When you specify how many bars are to be loaded within AgenaTrader, then the value of Bars.Count is equal to this setting. In the following example, Bars.Count would give back a value of 500.

Example

Print ("There are a total of" + Bars.Count + "bars available.");

Bars.CurrentSessionBeginTime

Description

Bars.CurrentSessionBeginTime outputs the date and time for the beginning of the current trading session.

Date and time for the beginning of the current trading session will be displayed correctly when the function is used on a bar that has occurred in the past.

Parameter

None

Return Value

Type DateTime

Usage

Bars.GetSessionBegin

More Information

The time for the returned value will equal the starting time defined in the Market Escort for the specified exchange. The value itself is set within the Instrument Escort and can be called up in AgenaScript using the function Instrument.Exchange .

Exchange:

Print("The currently running trading session started at " + Bars.CurrentSessionBeginTime );

Bars.CurrentSessionEndTime

Description

Bars.CurrentSessionEndTime outputs the time for the end of the currently running trading session. Date and time for the end of the current trading session will, in this case, also be outputted correctly when the function is used on a previous bar.

Parameter

None

Return Value

Type DateTime

Usage

Bars.GetSessionEnd

More Information

The time for the returned value will correlate with the end time of the trading session defined in the Market Escort for the exchange. The value itself can be set within the Instrument Escort and can be called up with AgenaScript using the Instrument.Exchange function.

Example

Print("The currently running trading session started at " + Bars.CurrentSessionBeginTime );

Bars.GetBar

Description

Bars.GetBar outputs the first bars (from oldest to newest) that correspond to the specified date/time.

See Bars.GetBarsAgo, Bars.GetByIndex, Bars.GetBarIndex.

Parameter

Type DateTime

Return Value

Type IBar Bar Object, for the bars corresponding to the timestamp

For a timestamp older than the oldest bar: 0 (null) For a timestamp younger than the newest bar: index of the last bar

Usage

Bars.GetBar(DateTime time)

More Information

For the indexing of bars please see Functionality, Bars

For more information about using DateTime see http://msdn.microsoft.com/de-de/library/system.datetime.aspx

Example

Print ("The closing price for 01.03.2012 at 18:00:00 was " + Bars.GetBar(new DateTime(2012, 01, 03, 18, 0, 0)).Close);

Bars.GetBarIndex

Description

Bars.GetBarIndex outputs the index of a bar – you can input either a bar object or a date-time object using this method.

See Bars.GetBar, Bars.GetBarsAgo, Bars.GetByIndex.

Parameter

Type IBar bar or Type DateTime

Return Value

Type int The bar index of the specified bar object or DateTime object

Usage

Bars.GetBarIndex (IBar bar)
Bars.GetBarIndex (DateTime dt)

More Information

For more information about indexing see Functionality, Bars

Example

int barsAgo = 5;
IBar bar = Bars.GetBar(Time[barsAgo]);
Print(barsAgo + " and " + Bars.GetBarIndex(bar) + " are equal in this example.");

Bars.GetBarsAgo

Description

Bars.GetBarsAgo outputs the index of the first bars (from oldest to newest) that correspond to the specified date/time.

See: Bars.GetBar, Bars.GetBarsAgo, Bars.GetByIndex.

Parameter

Type DateTime

Return Value

Type int Index of the bar that corresponds to the timestamp

With a timestamp older than the oldest bar: 0 (null) With a timestamp newer than the youngest bar: index of the last bar

Usage

Bars.GetBarsAgo(DateTime time)

More Information

For more information about indexing please see Functionality, Bars

For more information about using DateTime see http://msdn.microsoft.com/de-de/library/system.datetime.aspx

Example

Print("The bar for 01.03.2012 at 18:00:00 O’clock has an index of " + Bars.GetBarsAgo(new DateTime(2012, 01, 03, 18, 0, 0)));

Bars.GetByIndex

Description

Bars.GetByIndex outputs the index for the specified bar object

See Bars.GetBar, Bars.GetBarsAgo, Bars.GetByIndex.

Parameter

Type int Index

Return Value

Type IBar Bar object for the specified index

Usage

Bars.GetByIndex (int Index)

More Information

For indexing of bars see Functionality, Bars

Example

Print(Close[0] + " and " + Bars.GetByIndex(ProcessingBarIndex).Close + " are equal in this example.");

Bars.GetClose

Bars.GetClose(int index) – see Bars.GetOpen.

Bars.GetHigh

Bars.GetHigh(int index) – see Bars.GetOpen.

Bars.GetLow

Bars.GetLow(int index) – see Bars.GetOpen.

Bars.GetNextSessionTimeSpan

Description

Bars.GetNextSessionTimeSpan outputs the date and time for the beginning and end of a trading session.

See Bars.CurrentSessionBeginTime, Bars.CurrentSessionEndTime, Bars.NextSessionBeginTime, Bars.NextSessionEndTime.

Parameter

DateTime	time	Date or time for which the data of the following trading session will be scanned/searched.
iBars	bars	Bar object for which the data will be scanned/searched.
int	barsago	Number of days in the past for which the data will be searched/scanned.

Return Value

DateTime session begin DateTime session end

Note: The date for the beginning and the end of a trading session are connected components. If the specified date corresponds to the end date of the current trading session then the returned value for the beginning of a trading session may already be in the past. In this case the date for the following trading session cannot be returned.

Usage

Bars.GetNextSessionTimeSpan(Bars bars, int barsAgo, out DateTime sessionBegin, out DateTime sessionEnd)
Bars.GetNextSessionTimeSpan(DateTime time, out DateTime sessionBegin, out DateTime sessionEnd)

More Information

The two signatures will not necessarily output the same result. When using the bar signature, the supplied bar will be inspected for its session template association. The beginning and end of the next session will be taken from this template.

When using the time signature, the date and time of the supplied bar will be used to calculate the data for the current and the following sessions.

When using the time signature, a timestamp is transmitted that corresponds exactly to the beginning or the end time of a session.

More information can be found here http://msdn.microsoft.com/de-de/library/system.datetime.aspx

Example

DateTime sessionBegin;
DateTime sessionEnd;
protected override void OnCalculate()
{
Bars.GetNextSessionTimeSpan(Bars, 0, out sessionBegin, out sessionEnd);
Print("Session Start: " + sessionBegin + " Session End: " + sessionEnd);
}

Bars.GetOpen

Description

For reasons of compatibility, the following methods are available.

• Bars.GetOpen(int index) outputs the open for the bars referenced with <index>.

• Bars.GetHigh(int index) outputs the high for the bars referenced with <index>.

• Bars.GetLow(int index) outputs the low for the bars referenced with <index>.

• Bars.GetClose(int index) outputs the close for the bars referenced with <index>.

• Bars.GetTime(int index) outputs the timestamp for the bars referenced with <index>.

• Bars.GetVolume(int index) outputs the volume for the bars referenced with <index>.

Caution: The indexing will deviate from the Indexing, Bars normally used. Here, the indexing will begin with 0 for the oldest bar (on the left of the chart) and end with the newest bar on the right of the chart (=Bars.Count-1).

The indexing can easily be recalculated:

private int Convert(int idx)
{
return Math.Max(0,Bars.Count-idx-1-(CalculateOnClosedBar?1:0));
}

Parameter

int index (0 .. Bars.Count-1)

Return Value

Type double for GetOpen, GetHigh, GetLow, GetClose and GetVolume

Type DateTime for GetTime

Bars.GetSessionBegin

Description

Bars.GetSessionBegin provides the date and time of the particular session start. The date and time for the start of the current trading session are also correctly indicated when the function is called from a bar in the past. See also other Properties of bars.

Parameter

None

Return value

Type DateTime

Usage

Bars.GetSessionBegin(DateTime dt)

Further Information

The time of the returned value corresponds to the start time of the trading session. The relevant trading center which is specified in the MarketEscort. The trading place used for the value is set in the Instrumet Escort and can be determined in AgenaSript with the Instrument.Exchange function.

Example

Print("Die Handelssitzung am 25.03.2015 hat um "+ Bars.GetSessionBegin(new DateTime(2015, 03, 25)) + " begonnen.");
}

Bars.GetTime

Bars.GetTime(int index) – see Bars.GetOpen.

Bars.GetVolume

Bars.GetVolume(int index) – see Bars.GetOpen.

Bars.Instrument

Description

Bars.Instrument outputs an instrument object for the trading instrument displayed within the chart.

See Properties for more information.

Parameter

None

Return Value

Type Instrument

Usage

Bars.Instrument

More Information

For more information regarding the trading instruments please see Instruments.

Example

// both outputs will provide the same result
Print("The currently displayed trading instrument has the symbol: " + Bars.Instrument);
Instrument i = Bars.Instrument;
Print("The currently displayed trading instrument has the symbol " + i.Symbol);

Bars.IsEod

Description

Bars.IsEod can be used to check whether they are end-of-day bars.

See Properties for more information.

Parameter

None

Return Value

Type bool

Usage

Bars.IsEod

More Information

Within OnCalculate(), this property can be used without having to test for null reference. As soon as the method OnCalculate () is called by AgenaScript, there is always a bar object.

If this property used outside of OnCalculate (), then a corresponding test should be set to zero reference, e.g. With if (bars! = Null).

Example

Print("The bars are EOD: " + Bars.IsEod);

Bars.IsFalling

Description

Bar properties used when Bar is falling down.

Parameter

None

Return Value

None

Usage

Bars[0].IsFalling;

Bars.IsFirstBarInSession

Description

With Bars.IsFirstBarInSession you can determine whether the current bar is the first bar of the trading session.

See Properties of bars for more information.

Return Value

Type bool

true: The bar is the first bar of the current trading session false: The bar is not the first bar of the current trading session

Usage

Bars.IsFirstBarInSession

More Information

With OnCalculate() this property can be used without having to test for a null reference. As soon as the OnCalculate() method is called up, an object will become available. If this property is called up outside of OnCalculate() you should test for a null reference using if (Bars != null).

Example

if (Bars.IsFirstBarInSession)
Print ("The current trading session started at" + Time [0]);

Bars.isGrowing

Description

Bar properties used when Bar is growing up.

Parameter

None

Return Value

None

Usage

Bars[0].isGrowing;

Bars.IsIntraday

Description

Bars.IsIntraday returns a boolean which indicates if the TimeFrame is intra-day.

Return Value

bool

It returns "true" if TimeFrame is intra-day (e.g. 1 min, 15 min, 1 hour, etc.) and "false" in other cases.

Usage

Bars.IsIntraday

Example

if(Bars.IsIntraday) {
    Print("TimeFrame is Intraday.");
} else {
    Print("TimeFrame is not Intraday.");
}

Bars.IsNtb

Description

With Bars.IsNtb it can be checked whether it is not-time-based bars. For example Ntb bars are Point & Figure or Renko Charts.

See Properties for more information.

Parameter

None

Return Value

Type bool

Usage

Bars.IsNtb

More Information

OnCalculate() property can be used without having to test for null reference first. As soon as the method OnCalculate() is called by AgenaScript, there is always a bar object. If this property is used outside of OnCalculate(), then a corresponding test should be set to zero reference, e.g. With if (bars! = Null).

Example

Print("The bars are Ntb: " + Bars.IsNtb);

Bars.IsSessionBreak

Description

Bars.IsSessionBreak can be used to determine whether the bars are within the commercial trading session in the commercial breaks defined in the marketplace escort.

See Properties for more information.

Parameter

None

Return Value

Type bool

Usage

Bars.IsSessionBreak

More Information

Example

if (Bars.IsSessionBreak)
{
    Print("The stock exchange Xetra has just a trade pause.");
}

Bars.LastBarCompleteness

Description

Bars.LastBarCompleteness outputs the value that displays what percentage a bar has already completed. A bar with a period of 10 minutes has completed 50% after 5 minutes.

For non-time-based charts (Kagi, LineBreak, Renko, Range, P&F etc.) this will output 0 during backtesting.

Return Value

double

A percentage value; 30% will be outputted as 0.3

Usage

Bars.LastBarCompleteness

More Information

With OnCalculate() this property can be used without having to test for a null reference. As soon as the OnCalculate() method is called up by AgenaScript, the object will become available.

If this property is used outside of OnCalculate() you should test for a null reference before executing it. You can test using if (Bars != null)

Example

// A 60 minute chart is looked at from an intraday perspective
// every 5 minutes before the current bar closes
// an acoustic signal shall be played
// 55 min. equals 92%
bool remind = false;
protected override void OnCalculate()
{
if (FirstTickOfBar) remind = true;
    if (remind && Bars.LastBarCompleteness >= 0.92)
    {
    remind = false;
    PlaySound("Alert1");
    }
}

Bars.NextSessionBeginTime

Description

Bars.NextSessionBeginTime outputs the date and time for the start of the next trading session. Date and time for the next session will be correctly outputted when the function is used on a bar in the past.

Parameter

None

Return Value

Type DateTime

Usage

Bars.GetSessionNextBegin

More Information

The time for the returned value will correlate to the value displayed in the MarketEscort. The value can be set within the Instrument Escort and can be called up using the Instrument.Exchange function.

Example

Print("The next trading session starts at " + Bars.NextSessionBeginTime);

Bars.NextSessionEndTime

Description

Bars.NextSessionEndTime outputs the date and time for the end of the next session. See Properties for more information.

Parameter

None

Return Value

Type DateTime

Usage

Bars.GetSessionNextEnd

More Information

The time for the returned value will correlate with the value specified within the MarketEscort. The value itself can be set within the Instrument Escort and can be called up with AgenaScript using the Instrument.Exchange function.

Example

Print("The next trading session ends at " + Bars.NextSessionEndTime);

Bars.TailBottom

Description

With this property you are able to get the height of the bottom candle tail.

Parameter

None

Return Value

None

Usage

Bars[0].TailBottom;

Example

Print("The height of the bottom candle tail is: " + Bars.TailBottom);

Bars.TailTop

Description

With this property you are able to get the height of the top candle tail.

Parameter

None

Return Value

None

Usage

Bars[0].TailTop;

Example

Print("The height of the top candle tail is: " + Bars.TailTop);

Bars.TicksCountForLastBar

Description

Bars.TicksCountForLastBar outputs the total numbers of ticks contained within a bar.

More information can be found in Properties of bars.

Parameter

None

Return Value

Type int

Usage

Bars.TicksCountForLastBar

More Information

With OnCalculate() this property can be used without having to test for a null reference. As soon as the OnCalculate() method is called up by AgenaScript, the object will become available.

If this property is used outside of OnCalculate(), you should test for a null reference before executing it. You can test using if (Bars != null)

Example

Print("The current bar consists of " + Bars.TicksCountForLastBar + " Ticks.");

Bars.TicksCountInTotal

Description

Bars.TicksCountInTotal outputs the total number of ticks from the moment the function is called up.

More information can be found here: Properties.

Parameter

None

Return Value

Type int

Usage

Bars.TicksCountInTotal

More Information

The data type int has a positive value range of 2147483647. When you assume 10 ticks per second, there will be no overlaps within 2 trading months with a daily runtime of 24 hours.

With OnCalculate() this property can be used without having to test for a null reference. As soon as the OnCalculate() method is called up by AgenaScript, the object will become available.

If this property is used outside of OnCalculate(), you should test for a null reference before executing it. You can test using if (Bars != null)

Example

Print("The total amount of ticks is " + Bars.TicksCountInTotal);

Bars.TimeFrame

Description

Bars.TimeFrame outputs the timeframe object containing information regarding the currently used timeframe.

More information can be found here: Properties

Parameter

None

Return Value

Type ITimeFrame

Usage

Bars.TimeFrame

More Information

For more information about timeframe objects please see TimeFrame.

With OnCalculate() this property can be used without having to test for a null reference. As soon as the OnCalculate() method is called up by AgenaScript, the object will become available.

If this property is used outside of OnCalculate(),you should test for a null reference before executing it. You can test using if (Bars != null)

Example

//Usage within a 30 minute chart
TimeFrame tf = (TimeFrame) Bars.TimeFrame;
Print(Bars.TimeFrame); // outputs "30 Min"
Print(tf.Periodicity); // outputs "Minute"
Print(tf.PeriodicityValue); // outputs "30"

BarsCountForSession

Description

Bars.BarsCountForSession outputs the amount of bars that have occurred since the beginning of the current trading session.

See further Properties of bars.

Return Value

Type int Amount of Bars

A value of -1 indicates a problem with referencing the correct session beginning.

Usage

Bars.BarsCountForSession

Further Information

Within OnCalculate() this property can be used without having to test for a null reference. As soon as the OnCalculate() method is called up by AgenaScript, the object will become available.

If this property is used outside of OnCalculate() then you should test for a null reference before executing it. You can test using if (Bars!= null) .

Example

Print("Since the start of the last trading session there have been" + Bars.BarsCountForSession + "bars.");

ProcessingBarIndexLast

Description

Indicates if current bar is last in calculation.

Parameter

none

Return value

Type bool

Usage

ProcessingBarIndexLast

More Information

used for complicated calculation on a last bar

Example

protected override void OnCalculate()
        {
            base.OnCalculate();
            if (!IsProcessingBarIndexLast)
                return;
            bool isUpdated;
}