CandlesGroup_Types

Library "CandlesGroup_Types"
CandlesGroup Type allows you to efficiently store and access properties of all the candles in your chart.

You can easily manipulate large datasets, work with multiple timeframes, or analyze multiple symbols simultaneously. By encapsulating the properties of each candle within a CandlesGroup object, you gain a convenient and organized way to handle complex candlestick patterns and data.

For usage instructions and detailed examples, please refer to the comments and examples provided in the source code.

method init(_self)
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup)

method init(_self, propertyNames)
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup)
    propertyNames (string)

method get(_self, key)
  get values array from a given property name
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property. Default is "index"
  Returns: values array

method size(_self)
  get size of values array. By default it equals to current bar_index
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
  Returns: size of values array

method push(_self, key, value)
  push single value to specific property
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property
    value (float): : property value
  Returns: CandlesGroup object

method push(_self, arr)
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup)
    arr (float)

method populate(_self, ohlc)
  populate ohlc to CandlesGroup
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    ohlc (float): : array of ohlc
  Returns: CandlesGroup object

method populate(_self, values, propertiesNames)
  populate values base on given properties Names
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    values (float): : array of property values
    propertiesNames (string): : an array stores property names. Use as keys to get values
  Returns: CandlesGroup object

method populate(_self)
  populate values (default setup)
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
  Returns: CandlesGroup object

method lookback(arr, bars_lookback)
  get property value on previous candles. For current candle, use *.lookback()
  Namespace types: float
  Parameters:
    arr (float): : array of selected property values
    bars_lookback (int): : number of candles lookback. 0 = current candle. Default is 0
  Returns: single property value

method highest_within_bars(_self, hiSource, start, end, useIndex)
  get the highest property value between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    hiSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns: the highest value within candles

method highest_within_bars(_self, returnWithIndex, hiSource, start, end, useIndex)
  get the highest property value and bar index between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    returnWithIndex (bool): : the function only applicable when it is true
    hiSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns:

method highest_point_within_bars(_self, hiSource, start, end, useIndex)
  get a Point object which contains highest property value between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    hiSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns: Point object contains highest property value

method lowest_within_bars(_self, loSource, start, end, useIndex)
  get the lowest property value between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    loSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns: the lowest value within candles

method lowest_within_bars(_self, returnWithIndex, loSource, start, end, useIndex)
  get the lowest property value and bar index between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    returnWithIndex (bool): : the function only applicable when it is true
    loSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns:

method lowest_point_within_bars(_self, loSource, start, end, useIndex)
  get a Point object which contains lowest property value between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    loSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns: Point object contains lowest property value

method time2bar(_self, t)
  Convert UNIX time to bar index of active chart
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    t (int): : UNIX time
  Returns: bar index

method time2bar(_self, timezone, YYYY, MMM, DD, hh, mm, ss)
  Convert timestamp to bar index of active chart. User defined timezone required
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    timezone (string): : User defined timezone
    YYYY (int): : Year
    MMM (int): : Month
    DD (int): : Day
    hh (int): : Hour. Default is 0
    mm (int): : Minute. Default is 0
    ss (int): : Second. Default is 0
  Returns: bar index

method time2bar(_self, YYYY, MMM, DD, hh, mm, ss)
  Convert timestamp to bar index of active chart
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    YYYY (int): : Year
    MMM (int): : Month
    DD (int): : Day
    hh (int): : Hour. Default is 0
    mm (int): : Minute. Default is 0
    ss (int): : Second. Default is 0
  Returns: bar index

method get_prop_from_time(_self, key, t)
  get single property value from UNIX time
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property
    t (int): : UNIX time
  Returns: single property value

method get_prop_from_time(_self, key, timezone, YYYY, MMM, DD, hh, mm, ss)
  get single property value from timestamp. User defined timezone required
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property
    timezone (string): : User defined timezone
    YYYY (int): : Year
    MMM (int): : Month
    DD (int): : Day
    hh (int): : Hour. Default is 0
    mm (int): : Minute. Default is 0
    ss (int): : Second. Default is 0
  Returns: single property value

method get_prop_from_time(_self, key, YYYY, MMM, DD, hh, mm, ss)
  get single property value from timestamp
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property
    YYYY (int): : Year
    MMM (int): : Month
    DD (int): : Day
    hh (int): : Hour. Default is 0
    mm (int): : Minute. Default is 0
    ss (int): : Second. Default is 0
  Returns: single property value

method bar2time(_self, index)
  Convert bar index of active chart to UNIX time
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    index (int): : bar index
  Returns: UNIX time

Point
  A point on chart
  Fields:
    price (series float): : price value
    bar (series int): : bar index
    bartime (series int): : time in UNIX format of bar

Property
  Property object which contains values of all candles
  Fields:
    name (series string): : name of property
    values (float): : an array stores values of all candles. Size of array = bar_index

CandlesGroup
  Candles Group object which contains properties of all candles
  Fields:
    propertyNames (string): : an array stores property names. Use as keys to get values
    properties (Property): : array of Property objects

Versionsinformation:

v2
typo fixed

Versionsinformation:

v3
Example of CandlesGroup with other timeframe data fixed

Versionsinformation:

v4

Added:
method bar2arrID(_self, index)
  Get array index of CandlesGroup from bar index
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    index (int): : bar index
  Returns: array index

method time2arrID(_self, t)
  Get array index of CandlesGroup from UNIX time
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    t (int): : UNIX time
  Returns: array index

Versionsinformation:

v5

Added:
method sma(_self, key, length)
  The sma function returns the moving average
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property
    length (int): : number of bars
  Returns: float value

method ema(_self, key, length)
  The ema function returns the exponentially weighted moving average.
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property
    length (int): : number of bars
  Returns: float value

method rma(_self, key, length)
  Relative Moving Average. Rounds to 4 s.f.
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    key (string): : key name of selected property
    length (int): : number of bars
  Returns: float value

method tr(_self, offset)
  True range
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    offset (int): : history bar offset. Default is 0
  Returns: float value

method atr(_self, length)
  Average true range returns the RMA of true range. Rounds to 4 s.f.
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    length (int): : number of bars
  Returns: float value

Versionsinformation:

v6
1. bar calculation on other timeframe fixed
2. examples for handling other timeframe data added

Added:
method lastIndex(_self)
  get last index of values array
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
  Returns: last index of values array

Updated:
method highest_within_bars(_self, returnWithIndex, hiSource, start, end, useIndex)
  get the highest property value and array index between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    returnWithIndex (bool): : the function only applicable when it is true
    hiSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns:

method lowest_within_bars(_self, returnWithIndex, loSource, start, end, useIndex)
  get the lowest property value and array index between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    returnWithIndex (bool): : the function only applicable when it is true
    loSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns:

Versionsinformation:

v7
Usage and Examples updated

Versionsinformation:

v8
method get_prop_from_time() bug fixed. Now it accepts higher timeframe Candles Group.

Versionsinformation:

v9

Updated:
CandlesGroup
  Candles Group object which contains properties of all candles
  Fields:
    increment (series bool): : if true, size of value array increased at that candle. Default is false
    propertyNames (string): : an array stores property names. Use as keys to get values
    properties (Property): : array of Property objects

Versionsinformation:

v10

Updated:
CandlesGroup
  Candles Group object which contains properties of all candles
  Fields:
    tf (series string): : timeframe
    is_size_increased (series bool): : if true, size of value array increased at that candle. Default is false
    propertyNames (string): : an array stores property names. Use as keys to get values
    properties (Property): : array of Property objects

Versionsinformation:

v11

1. A new field `detail` is added to CandlesGroup Type. Possible values: "full", "normal", "lite", "custom".
2. populate() function is based on the new `detail` field to populate the number of properties.
3. time2bar() function is updated. Now it will return future bar_index based on bar duration of chart timeframe. Or return NaN if it is earlier than the 1st bar of the chart.
4. A new debug table is added to the comment section as an example.

Updated:
CandlesGroup
  Candles Group object which contains properties of all candles
  Fields:
    tf (series string): : timeframe
    detail (series string): : variety of candle properties. Possible value: "full", "normal", "lite", "custom"
    is_size_increased (series bool): : if true, size of value array increased at that candle. Default is false
    propertyNames (string): : an array stores property names. Use as keys to get values
    properties (Property): : array of Property objects

Versionsinformation:

v12

1. Updated all UDT Point Type to bulit-in chart.point type.
2. Refactored those usage examples to built-in chart.point type.
3. UDT Point Type is removed from this library.

Updated:
method highest_point_within_bars(_self, hiSource, start, end, useIndex)
  get a chart.point object which contains highest property value between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    hiSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns: chart.point object contains highest property value

method lowest_point_within_bars(_self, loSource, start, end, useIndex)
  get a chart.point object which contains lowest property value between specific candles
  Namespace types: CandlesGroup
  Parameters:
    _self (CandlesGroup): : CandlesGroup object
    loSource (string): : key name of selected property
    start (int): : start bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true
    end (int): : end bar for calculation. Default is candles lookback value from current candle. 'index' value is used if 'useIndex' = true. Default is 0
    useIndex (bool): : use index instead of lookback value. Default = false
  Returns: chart.point object contains lowest property value

Removed:
Point
  A point on chart

Versionsinformation:

v13

methods refactored

- methods time2bar(), bar2arrID(), time2arrID() refactored. Now they can returns nearest bar/arrID even though parameters are inside bar.
- usages and examples for the above methods updated.
- Debug Tables refactored.