JK_Traders_Reality_Lib

Library "JK_Traders_Reality_Lib"
This library contains common elements used in Traders Reality scripts

calcPvsra(pvsraVolume, pvsraHigh, pvsraLow, pvsraClose, pvsraOpen, redVectorColor, greenVectorColor, violetVectorColor, blueVectorColor, darkGreyCandleColor, lightGrayCandleColor)
  calculate the pvsra candle color and return the color as well as an alert if a vector candle has apperared.
Situation "Climax"
Bars with volume >= 200% of the average volume of the 10 previous chart TFs, or bars
where the product of candle spread x candle volume is >= the highest for the 10 previous
chart time TFs.
Default Colors: Bull bars are green and bear bars are red.
Situation "Volume Rising Above Average"
Bars with volume >= 150% of the average volume of the 10 previous chart TFs.
Default Colors: Bull bars are blue and bear are violet.
  Parameters:
    pvsraVolume (float): the instrument volume series (obtained from request.sequrity)
    pvsraHigh (float): the instrument high series (obtained from request.sequrity)
    pvsraLow (float): the instrument low series (obtained from request.sequrity)
    pvsraClose (float): the instrument close series (obtained from request.sequrity)
    pvsraOpen (float): the instrument open series (obtained from request.sequrity)
    redVectorColor (simple color): red vector candle color
    greenVectorColor (simple color): green vector candle color
    violetVectorColor (simple color): violet/pink vector candle color
    blueVectorColor (simple color): blue vector candle color
    darkGreyCandleColor (simple color): regular volume candle down candle color - not a vector
    lightGrayCandleColor (simple color): regular volume candle up candle color - not a vector
return [pvsraColor, alertFlag, averageVolume, volumeSpread, highestVolumeSpread]

adr(length, barsBack)
  Parameters:
    length (simple int): how many elements of the series to calculate on
    barsBack (simple int): starting possition for the length calculation - current bar or some other value eg last bar
return adr the adr for the specified lenght

adrHigh(adr, fromDo)
  Calculate the ADR high given an ADR
  Parameters:
    adr (float): the adr
    fromDo (simple bool): boolean flag, if false calculate traditional adr from high low of today, if true calcualte from exchange midnight
return adrHigh the position of the adr high in price

adrLow(adr, fromDo)
  Parameters:
    adr (float): the adr
    fromDo (simple bool): boolean flag, if false calculate traditional adr from high low of today, if true calcualte from exchange midnight
return adrLow the position of the adr low in price

splitSessionString(sessXTime)
  given a session in the format 0000-0100:23456 split out the hours and minutes
  Parameters:
    sessXTime (simple string): the session time string usually in the format 0000-0100:23456
return [startHour, startMin, endHour, endMin]

calcSessionStartEnd(sessXTime, gmt)
  calculate the start and end timestamps of the session
  Parameters:
    sessXTime (simple string): the session time string usually in the format 0000-0100:23456
    gmt (simple string): the gmt offset string usually in the format GMT+1 or GMT+2 etc
return [targetstartTimeX,targetendTimeX]

drawOpenRange(sessXTime, sessXcol, showOrX, gmt)
  draw open range for a session
  Parameters:
    sessXTime (simple string): session string in the format 0000-0100:23456
    sessXcol (simple color): the color to be used for the opening range box shading
    showOrX (simple bool): boolean flag to toggle displaying the opening range
    gmt (simple string): the gmt offset string usually in the format GMT+1 or GMT+2 etc
return void

drawSessionHiLo(sessXTime, showRectangleX, showLabelX, sessXcolLabel, sessXLabel, gmt, sessionLineStyle)
  Parameters:
    sessXTime (simple string): session string in the format 0000-0100:23456
    showRectangleX (simple bool)
    showLabelX (simple bool)
    sessXcolLabel (simple color): the color to be used for the hi/low lines and label
    sessXLabel (simple string): the session label text
    gmt (simple string): the gmt offset string usually in the format GMT+1 or GMT+2 etc
    sessionLineStyle (simple string): the line stile for the session high low lines
return void

calcDst()
  calculate market session dst on/off flags
return [nyDST, ukDST, sydDST] indicating if DST is on or off for a particular region

timestampPreviousDayOfWeek(previousDayOfWeek, hourOfDay, gmtOffset, oneWeekMillis)
  Timestamp any of the 6 previous days in the week (such as last Wednesday at 21 hours GMT)
  Parameters:
    previousDayOfWeek (simple string): Monday or Satruday
    hourOfDay (simple int): the hour of the day when psy calc is to start
    gmtOffset (simple string): the gmt offset string usually in the format GMT+1 or GMT+2 etc
    oneWeekMillis (simple int): the amount if time for a week in milliseconds
return the timestamp of the psy level calculation start time

getdayOpen()
  get the daily open - basically exchange midnight
return the daily open value which is float price

newBar(res)
  new_bar: check if we're on a new bar within the session in a given resolution
  Parameters:
    res (simple string): the desired resolution
return true/false is a new bar for the session has started

toPips(val)
  to_pips Convert value to pips
  Parameters:
    val (float): the value to convert to pips
return the value in pips

rLabel(ry, rtext, rstyle, rcolor, valid, labelXOffset)
  a function that draws a right aligned lable for a series during the current bar
  Parameters:
    ry (float): series float the y coordinate of the lable
    rtext (simple string): the text of the label
    rstyle (simple string): the style for the lable
    rcolor (simple color): the color for the label
    valid (simple bool): a boolean flag that allows for turning on or off a lable
    labelXOffset (int): how much to offset the label from the current position

rLabelOffset(ry, rtext, rstyle, rcolor, valid, labelOffset)
  a function that draws a right aligned lable for a series during the current bar
  Parameters:
    ry (float): series float the y coordinate of the lable
    rtext (string): the text of the label
    rstyle (simple string): the style for the lable
    rcolor (simple color): the color for the label
    valid (simple bool): a boolean flag that allows for turning on or off a lable
    labelOffset (int)

rLabelLastBar(ry, rtext, rstyle, rcolor, valid, labelXOffset)
  a function that draws a right aligned lable for a series only on the last bar
  Parameters:
    ry (float): series float the y coordinate of the lable
    rtext (string): the text of the label
    rstyle (simple string): the style for the lable
    rcolor (simple color): the color for the label
    valid (simple bool): a boolean flag that allows for turning on or off a lable
    labelXOffset (int): how much to offset the label from the current position

drawLine(xSeries, res, tag, xColor, xStyle, xWidth, xExtend, isLabelValid, xLabelOffset, validTimeFrame)
  a function that draws a line and a label for a series
  Parameters:
    xSeries (float): series float the y coordinate of the line/label
    res (simple string): the desired resolution controlling when a new line will start
    tag (simple string): the text for the lable
    xColor (simple color): the color for the label
    xStyle (simple string): the style for the line
    xWidth (simple int): the width of the line
    xExtend (simple string): extend the line
    isLabelValid (simple bool): a boolean flag that allows for turning on or off a label
    xLabelOffset (int)
    validTimeFrame (simple bool): a boolean flag that allows for turning on or off a line drawn

drawLineDO(xSeries, res, tag, xColor, xStyle, xWidth, xExtend, isLabelValid, xLabelOffset, validTimeFrame)
  a function that draws a line and a label for the daily open series
  Parameters:
    xSeries (float): series float the y coordinate of the line/label
    res (simple string): the desired resolution controlling when a new line will start
    tag (simple string): the text for the lable
    xColor (simple color): the color for the label
    xStyle (simple string): the style for the line
    xWidth (simple int): the width of the line
    xExtend (simple string): extend the line
    isLabelValid (simple bool): a boolean flag that allows for turning on or off a label
    xLabelOffset (int)
    validTimeFrame (simple bool): a boolean flag that allows for turning on or off a line drawn

drawPivot(pivotLevel, res, tag, pivotColor, pivotLabelColor, pivotStyle, pivotWidth, pivotExtend, isLabelValid, validTimeFrame, levelStart, pivotLabelXOffset)
  draw a pivot line - the line starts one day into the past
  Parameters:
    pivotLevel (float): series of the pivot point
    res (simple string): the desired resolution
    tag (simple string): the text to appear
    pivotColor (simple color): the color of the line
    pivotLabelColor (simple color): the color of the label
    pivotStyle (simple string): the line style
    pivotWidth (simple int): the line width
    pivotExtend (simple string): extend the line
    isLabelValid (simple bool): boolean param allows to turn label on and off
    validTimeFrame (simple bool): only draw the line and label at a valid timeframe
    levelStart (int): basically when to start drawing the levels
    pivotLabelXOffset (int): how much to offset the label from its current postion
return the pivot line series

getPvsraFlagByColor(pvsraColor, redVectorColor, greenVectorColor, violetVectorColor, blueVectorColor, lightGrayCandleColor)
  convert the pvsra color to an internal code
  Parameters:
    pvsraColor (color): the calculated pvsra color
    redVectorColor (simple color): the user defined red vector color
    greenVectorColor (simple color): the user defined green vector color
    violetVectorColor (simple color): the user defined violet vector color
    blueVectorColor (simple color): the user defined blue vector color
    lightGrayCandleColor (simple color): the user defined regular up candle color
return pvsra internal code

updateZones(pvsra, direction, boxArr, maxlevels, pvsraHigh, pvsraLow, pvsraOpen, pvsraClose, transperancy, zoneupdatetype, zonecolor, zonetype, borderwidth, coloroverride, redVectorColor, greenVectorColor, violetVectorColor, blueVectorColor)
  a function that draws the unrecovered vector candle zones
  Parameters:
    pvsra (int): internal code
    direction (simple int): above or below the current pa
    boxArr (array<box>): the array containing the boxes that need to be updated
    maxlevels (simple int): the maximum number of boxes to draw
    pvsraHigh (float): the pvsra high value series
    pvsraLow (float): the pvsra low value series
    pvsraOpen (float): the pvsra open value series
    pvsraClose (float): the pvsra close value series
    transperancy (simple int): the transparencfy of the vecor candle zones
    zoneupdatetype (simple string): the zone update type
    zonecolor (simple color): the zone color if overriden
    zonetype (simple string): the zone type
    borderwidth (simple int): the width of the border
    coloroverride (simple bool): if the color overriden
    redVectorColor (simple color): the user defined red vector color
    greenVectorColor (simple color): the user defined green vector color
    violetVectorColor (simple color): the user defined violet vector color
    blueVectorColor (simple color): the user defined blue vector color

cleanarr(arr)
  clean an array from na values
  Parameters:
    arr (array<box>): the array to clean
return if the array was cleaned

calcPsyLevels(oneWeekMillis, showPsylevels, psyType, sydDST)
  calculate the psy levels
4 hour res based on how mt4 does it
mt4 code
int Li_4 = iBarShift(NULL, PERIOD_H4, iTime(NULL, PERIOD_W1, Li_0)) - 2 - Offset;
ObjectCreate("PsychHi", OBJ_TREND, 0, Time[0], iHigh(NULL, PERIOD_H4, iHighest(NULL, PERIOD_H4, MODE_HIGH, 2, Li_4)), iTime(NULL, PERIOD_W1, 0), iHigh(NULL, PERIOD_H4,
iHighest(NULL, PERIOD_H4, MODE_HIGH, 2, Li_4)));
so basically because the session is 8 hours and we are looking at a 4 hour resolution we only need to take the highest high an lowest low of 2 bars
we use the gmt offset to adjust the 0000-0800 session to Sydney open which is at 2100 during dst and at 2200 otherwize. (dst - spring foward, fall back)
keep in mind sydney is in the souther hemisphere so dst is oposite of when london and new york go into dst
  Parameters:
    oneWeekMillis (simple int): a constant value
    showPsylevels (simple bool): should psy levels be calculated
    psyType (simple string): the type of Psylevels - crypto or forex
    sydDST (bool): is Sydney in DST
return [psyHi, psyLo, psyHiLabel, psyLoLabel, psySessionStartTime]

adrHiLo(length, barsBack, fromDO)
  Parameters:
    length (simple int): how many elements of the series to calculate on
    barsBack (simple int): starting possition for the length calculation - current bar or some other value eg last bar
    fromDO (simple bool): boolean flag, if false calculate traditional adr from high low of today, if true calcualte from exchange midnight
return adr, adrLow and adrHigh - the adr, the position of the adr High and adr Low with respect to price

drawSessionHiloLite(sessXTime, showRectangleX, showLabelX, sessXcolLabel, sessXLabel, gmt, sessionLineStyle, sessXcol)
  Parameters:
    sessXTime (simple string): session string in the format 0000-0100:23456
    showRectangleX (simple bool)
    showLabelX (simple bool)
    sessXcolLabel (simple color): the color to be used for the hi/low lines and label
    sessXLabel (simple string): the session label text
    gmt (simple string): the gmt offset string usually in the format GMT+1 or GMT+2 etc
    sessionLineStyle (simple string): the line stile for the session high low lines
    sessXcol (simple color): - the color for the box color that will color the session
return void

msToHmsString(ms)
  converts milliseconds into an hh:mm string. For example, 61000 ms to '0:01:01'
  Parameters:
    ms (int): - the milliseconds to convert to hh:mm
return string - the converted hh:mm string

countdownString(openToday, closeToday, showMarketsWeekends, oneDay)
  that calculates how much time is left until the next session taking the session start and end times into account. Note this function does not work on intraday sessions.
  Parameters:
    openToday (int): - timestamps of when the session opens in general - note its a series because the timestamp was created using the dst flag which is a series itself thus producing a timestamp series
    closeToday (int): - timestamp of when the session closes in general - note its a series because the timestamp was created using the dst flag which is a series itself thus producing a timestamp series
return a countdown of when next the session opens or 'Open' if the session is open now
    showMarketsWeekends (simple bool)
    oneDay (simple int)

countdownStringSyd(sydOpenToday, sydCloseToday, showMarketsWeekends, oneDay)
  that calculates how much time is left until the next session taking the session start and end times into account. special case of intraday sessions like sydney
  Parameters:
    sydOpenToday (int)
    sydCloseToday (int)
    showMarketsWeekends (simple bool)
    oneDay (simple int)