Firetron's XTR

--  ============================================================================
--    Firetron's XTR
--
--    Finds the average, maximum, median, or minimum true range
--    or percent true range.
--    Supports specifying a fraction of the range to use.
--    Supports any period there is price data for, not capped at 200.
--    Supports true percent range.
--
--    Custom Command Dependencies:
--    Firetron's FractionGrab
--    Firetron's Median
--
--    Discord: @FiretronP75
--  ============================================================================

--  ========================================================
--    Variables
--  ========================================================

--  ------------------------------------
--    Definition
--  ------------------------------------

local dDefault
local dDescription
local dName
local dOutput
local dRequired
local dSuggestions
local dType

--  ------------------------------------
--    Enumeration
--  ------------------------------------

local Type = {
  average = 'average',
  maximum = 'maximum',
  median  = 'median',
  minimum = 'minimum',
}

--  ------------------------------------
--    Function
--  ------------------------------------

local GetXTR

--  ------------------------------------
--    Parameter
--  ------------------------------------

local pFullCandles
local pHlcStyle
local pIndex
local pInterval
local pIsPercent
local pMarket
local pPeriod
local pTotal
local pType

--  ========================================================
--    Command Definition
--  ========================================================

dName        = 'XTR'
dDescription = 'Finds the average, maximum, median, or minimum true range or percent true range. '
             ..'Supports specifying a fraction of the range to use. '
             ..'Supports any period there is price data for, not capped at 200. '
             ..'Supports true percent range.'
DefineCommand(dName, dDescription)

--  ========================================================
--    Parameter Definitions
--  ========================================================

dType        = StringType
dName        = 'type'
dDescription = '"average" for average true range, "maximum" for maximum true range, "median" for median true range, "minimum" for minimum true range.'
dRequired    = false
dDefault     = Type.average
dSuggestions = 'Input'
pType = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = NumberType
dName        = 'period'
dDescription = 'How many intervals to go back. '
             ..'Set to -1 to use the maximum available history. '
             ..'True range calculation requires one extra candle because it compares across two candles. '
             ..'For your convenience, your period will automatically be increased by one so you do not need to remember to.'
dRequired    = false
dDefault     = -1
dSuggestions = 'Input'
pPeriod = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = NumberType
dName        = 'interval'
dDescription = 'Time of each candle in minutes.'
dRequired    = false
dDefault     = 60
dSuggestions = 'InputInterval'
pInterval = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = BooleanType
dName        = 'fullCandles'
dDescription = 'If false, the currently open candle will not be included.'
dRequired    = false
dDefault     = true
dSuggestions = 'Input'
pFullCandles = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = StringType
dName        = 'market'
dDescription = 'Which market to look at.'
dRequired    = false
dDefault     = PriceMarket()
dSuggestions = 'InputAccountMarket, InputMarket, PriceMarket'
pMarket = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = BooleanType
dName        = 'hlcStyle'
dDescription = 'When enabled, the data returned will be adjusted for HLC instead of OHLC. Meaning that the OHL data can change.'
dRequired    = false
dDefault     = false
dSuggestions = 'Input'
pHlcStyle = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = NumberType
dName        = 'index'
dDescription = 'Which part to grab. '
             ..'Unlike a fraction numerator, previous parts are not included. '
             ..'In a fraction, 2 would mean 1st and 2nd parts combined. '
             ..'But here, 2 would mean the 2nd part without the 1st.'
dRequired    = false
dDefault     = 1
dSuggestions = 'Input'
pIndex = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = NumberType
dName        = 'total'
dDescription = 'How many parts to divide into. '
             ..'This is just like a fraction denominator.'
dRequired    = false
dDefault     = 1
dSuggestions = 'Input'
pTotal = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

dType        = BooleanType
dName        = 'isPercent'
dDescription = 'If true, the true percent range will be used.'
dRequired    = false
dDefault     = false
dSuggestions = 'Input'
pIsPercent = DefineParameter(dType, dName, dDescription, dRequired, dDefault, dSuggestions)

--  ========================================================
--    Parameter Validation
--  ========================================================

local isValidType =
  pType == Type.average or
  pType == Type.maximum or
  pType == Type.median  or
  pType == Type.minimum

if not isValidType then

  LogError('CC_XTR:  Type "'..pType..'" is not a valid type parameter.')

end

pPeriod = pPeriod + 1

--  ========================================================
--    Function
--  ========================================================

GetXTR = function ()

  local highList  = HighPrices( pInterval, pFullCandles, pMarket, pHlcStyle)
  local lowList   = LowPrices(  pInterval, pFullCandles, pMarket, pHlcStyle)
  local closeList = ClosePrices(pInterval, pFullCandles, pMarket, pHlcStyle)

  if #closeList == 0 then return -1 end -- This only happens on save/compile.

  local period = pPeriod

  if pPeriod == 0
  or pPeriod > #closeList then

    period = #closeList

  end

  local highPeriodList  = Grab(highList,  0, period)
  local lowPeriodList   = Grab(lowList,   0, period)
  local closePeriodList = Grab(closeList, 0, period)

  local trueRangeList = TRANGE(highPeriodList, lowPeriodList, closePeriodList)

  if pIsPercent then

    local previousCloseList = Grab(closePeriodList, 1, period - 1)

    trueRangeList = trueRangeList / previousCloseList

  end

  local willSort = pTotal ~= 1

  local list = CC_FractionGrab(trueRangeList, pIndex, pTotal, willSort)

  if pType == Type.average then

    return Average(list)

  elseif pType == Type.maximum then

    return Max(list)

  elseif pType == Type.median then

    return CC_Median(list, willSort)

  elseif pType == Type.minimum then

    return Min(list)

  end

end

--  ========================================================
--    Output Definition
--  ========================================================

DefineIntervalOptimization(pInterval)

dType        = NumberType
dOutput      = GetXTR()
dDescription = 'The average, maximum, median, or minimum true range or true percent range.'
dSuggestions = 'Add, Div, Mul, Mult, Sub'
DefineOutput(dType, dOutput, dDescription, dSuggestions)