Position

Library "Position"
Allows for simulating trades within an indicator.

newTrade(size, price, timestamp)
  Creates a new trade object.
  Parameters:
    size: The size of the trade (number of shares or contracts).
    price: The price at which the trade took place.
    timestamp: The timestamp of the trade. Defaults to the current time.
  Returns: A new trade object.

start(size, price, timestamp)
  Starts a new position.
  Parameters:
    size: The size of the position (number of shares or contracts).
    price: The price at which the position was started.
    timestamp: The timestamp of the start of the position. Defaults to the current time.
  Returns: A new position object.

trade(pos, size, price, timestamp)
  Modifies an existing position.
  Parameters:
    pos: The position to be modified.
    size: The size of the trade (number of shares or contracts).
    price: The price at which the trade took place.
    timestamp: The timestamp of the trade. Defaults to the current time.
  Returns: The modified position object.

exit(pos, price, timestamp)
  Closes a position by trading the entire position size at a given price and timestamp.
  Parameters:
    pos: The position being closed.
    price: The price at which the position is being closed.
    timestamp: The timestamp of the trade, defaults to the current time.
  Returns: The updated position after the trade.

unrealized(pos, price)
  Calculates the unrealized gain or loss for a given position and price.
  Parameters:
    pos: The position for which to calculate unrealized gain/loss.
    price: The current market price.
  Returns: The calculated unrealized gain or loss.

Trade
  Represents a single trade.
  Fields:
    size: Size of the trade in units.
    price: Price of the trade in currency.
    value: Total value of the trade in currency units.
    time: Timestamp of the trade.

Position
  Represents a single position.
  Fields:
    size: Size of the position in units.
    price: Average price of the position in currency.
    value: Total value of the position in currency units.
    start: Timestamp of the first trade that opened the position.
    net: Realized gains and losses of the position in currency units.
    history: Array of trades that make up the position.

Release Notes:

v2 Updated thumbnail.

Release Notes:

v3

Added:
size(pos)
  Returns the number of shares held by a position.
  Parameters:
    pos: The position for which to read the size. A value of NA will return zero.

isActive(pos)
  Returns true if the position has shares.
  Parameters:
    pos: The position for which to read the size. A value of NA will return false.

Release Notes:

v4 Position State

Added:
state(pos)
  Returns the current state of the position.
  Parameters:
    pos: The position to read the state from.

DirectionState
  The state of a position in one direction
  Fields:
    change: The change in shares
    holding: Indicates whether a position is currently being held
    increased: Indicates whether the position has increased
    decreased: Indicates whether the position has decreased

State
  The bi-directional state of a position
  Fields:
    holding: Indicates whether a position is currently being held
    change
    long: The state of the long position
    short: The state of the short position

Release Notes:

v5 Handle NA values.

Updated:
state(pos)
  Returns the current state of the position.
  Parameters:
    pos: The position to read the size from.

Release Notes:

v6 Added a default labeling system. The label format can be changed the label is generated.

Added:
addLabel(pos, ts)
  Creates a lablel if a trade was made.
  Parameters:
    pos: The position.
    ts: The state of the position or result of the trade to generate a label from.
  Returns: The label that was generated or na if none.

Updated:
start()
  Starts a new (blank) position with no trades.
  Returns: A new position object.

trade(pos, size, price, timestamp)
  Modifies an existing position.
  Parameters:
    pos: The position to be modified.
    size: The size of the trade (number of shares or contracts).
    price: The price at which the trade took place.
    timestamp: The timestamp of the trade. Defaults to the current time.
  Returns: The result of the trade. (The state of the position.)

Position
  Represents a single position.
  Fields:
    size: The size of the position.
    price: Average price of the position in currency.
    value: Total value of the position in currency units.
    start: Timestamp of the first trade that opened the position.
    net: Realized gains and losses of the position in currency units.
    history: Array of trades that make up the position.

DirectionState
  The state of a position in one direction
  Fields:
    size: The size of the position
    change: The change in size
    holding: Indicates whether a position is currently being held
    increased: Indicates whether the position has increased
    decreased: Indicates whether the position has decreased

State
  The bi-directional state of a position
  Fields:
    size
    change
    holding: Indicates whether a position is currently being held
    long: The state of the long position
    short: The state of the short position
    price

Release Notes:

v7 Allow for appending details to tooltip.

Release Notes:

v8 Fix unmatched brace.

Release Notes:

v9 Moved details to bottom.

Release Notes:

v10 Leverage new PineScript extension features. Improve concatenation of strings using array.join.

Release Notes:

v11