OHLC (ohlc v1.1.6)

Library for generating OHLC candles from trades.

OHLC takes ordered list of trade events as input and outputs OHLC candles list.

Library includes few options for appending candles to existing candles lists and more.

This library could be useful if you want to create your own charting engine or trading bot.

Documentation can be found here: https://hexdocs.pm/ohlc/1.0.0/OHLC.html

Installation

The package can be installed by adding ohlc to your list of dependencies in mix.exs:

def deps do
  [
    {:ohlc, "~> 1.1"}
  ]
end

Example usage

defmodule Example do
  def calculate_ohlc() do
    trades = [
      [price: 12.21, volume: 0.98, time: 1616439921],
      [price: 12.54, volume: 12.1, time: 1616439931],
      [price: 12.56, volume: 18.3, time: 1616439952],
      [price: 18.9, volume: 12, time: 1616440004],
      [price: 11, volume: 43.1, time: 1616440025],
      [price: 18.322, volume: 43.1, time: 1616440028]
    ]

    case OHLC.create_candles(trades, :minute) do
      {:ok, data} -> IO.inspect data
      {:error, msg} -> IO.puts msg
    end
  end
end

Example output

%{
  candles: [
    %{
      close: 12.56,
      etime: 1616439959,
      high: 12.56,
      low: 12.21,
      open: 12.21,
      processed: true,
      stime: 1616439900,
      trades: 3,
      type: :bullish,
      volume: 31.38
    },
    %{
      close: 18.9,
      etime: 1616440019,
      high: 18.9,
      low: 18.9,
      open: 18.9,
      processed: true,
      stime: 1616439960,
      trades: 1,
      type: :bearish,
      volume: 12.0
    },
    %{
      close: 18.322,
      etime: 1616440079,
      high: 18.322,
      low: 11.0,
      open: 11.0,
      processed: true,
      stime: 1616440020,
      trades: 2,
      type: :bullish,
      volume: 86.2
    }
  ],
  pair: nil,
  timeframe: :minute
}

Link to this section Summary

Types

Single candle generated.

A list of candles.

Available options for create_candles/3

Available timeframes for create_candles/3

Single trade.

A list of trades.

Functions

Coverts candles to new timeframe.

Function for generating candles from trades and timeframe provided.

Merges candle into another candle.

Link to this section Types

Specs

candle() :: %{
  :open => float(),
  :high => float(),
  :low => float(),
  :close => float(),
  :volume => float(),
  :trades => integer(),
  :stime => integer() | float(),
  :etime => integer() | float(),
  :type => :bullish | :bearish | nil,
  optional(:processed) => boolean()
}

Single candle generated.

Specs

candles() :: [candle()]

A list of candles.

Specs

opts() :: [
  forward_fill: boolean(),
  validate_trades: boolean(),
  previous_candle: candle(),
  pair: atom() | binary()
]

Available options for create_candles/3

  • :forward_fill - When set true copies the previous candles closing price to the next candle if no trades happend to be in between. Useful when you don't want to get empty time gap between the generated candles.
  • :validate_trades - When set true all trades are being validated before generating the candles to avoid errors and misinformation.
  • :previous_candle - Trades are appended to the previous candle if possible before generating the new candles.
  • :pair - Adds the pair name to the returned outputs metadata.

Specs

timeframe() :: :minute | :hour | :day | :week

Available timeframes for create_candles/3

Specs

trade() :: [price: number(), volume: number(), time: number()]

Single trade.

Specs

trades() :: [trade()]

A list of trades.

Link to this section Functions

Link to this function

convert_timeframe(candles, timeframe)

Specs

convert_timeframe(candles(), timeframe()) :: {:ok, candles()}

Coverts candles to new timeframe.

Parameters:

candles - A list of candles. timeframe- Must be higher then the existing candles timeframe. For example if candles were previously created using :hour timeframe then the provided timeframe cannot be :minute.

Returns a tuple containing the list of candles with converted timeframe.

Link to this function

create_candles(trades, timeframe, opts \\ [])

Specs

create_candles(trades(), timeframe(), opts() | nil) ::
  {:ok, %{pair: binary() | atom(), timeframe: timeframe(), candles: candles()}}
  | {:error, atom()}

Function for generating candles from trades and timeframe provided.

Parameters:

  • trades - A list containing all the trades. Trades must be chronologically arranged(ASC) by the timestamp field.
  • timeframe - Timeframe for the candles.
  • opts - Option values for the data proccessing.

Returns a tuple containing the metadata for the candles and a list of generated candles.

Link to this function

merge_child(main_candle, merge_candle)

Specs

merge_child(candle(), candle()) :: {:ok, candle()} | {:error, atom()}

Merges candle into another candle.

If main candles :stime is 0 then fallback to the merge_child :stime.

Parameters:

  • main_candle - Candle which will be merged into.
  • merge_candle - Candle which will be merged. It is important to have etime less than first candle. Meaning both candles should stay in the same timeframe.