Plotto.CandlestickChart (plotto v0.2.0)

A candlestick chart: renders open-high-low-close (OHLC) financial and price data intervals as candlesticks with wicks and colored bodies.

Use a candlestick chart to visualize asset prices, stock movements, and trading volatility over time intervals (minutes, hours, days, months).

Example

data = [
  %{label: "09:00", open: 100.0, high: 105.0, low: 98.0, close: 104.0},
  %{label: "09:05", open: 104.0, high: 106.0, low: 101.0, close: 102.0}
]

chart = Plotto.CandlestickChart.new!(data, title: "AAPL - 5m")
svg = Plotto.to_svg!(chart)
png = Plotto.to_png!(chart)

Summary

Types

ohlc_item()

One OHLC data point: interval :label, numeric :open, :high, :low, :close, and optional :attrs attribute map.

options()

Chart options, after defaults have been applied. Stored in this resolved map form on the chart struct (t/0's :opts field).

series()

One candlestick series: optional :name and its list of ohlc_item/0 points.

t()

The candlestick chart struct.

Functions

new(data, opts \\ [])

Builds a candlestick chart. Returns {:ok, chart} or {:error, reason}.

new!(data, opts \\ [])

Same as new/2, but returns the t/0 struct directly and raises ArgumentError if validation fails.

Types

ohlc_item()

@type ohlc_item() :: %{
  :label => String.t(),
  :open => number(),
  :high => number(),
  :low => number(),
  :close => number(),
  optional(:attrs) => %{optional(String.t()) => String.t()}
}

One OHLC data point: interval :label, numeric :open, :high, :low, :close, and optional :attrs attribute map.

options()

@type options() :: %{
  width: pos_integer(),
  height: pos_integer(),
  title: String.t() | nil,
  colors: [String.t()],
  legend: :top_left | :top_right | :bottom_left | :bottom_right | nil,
  bullish_color: String.t(),
  bearish_color: String.t()
}

Chart options, after defaults have been applied. Stored in this resolved map form on the chart struct (t/0's :opts field).

series()

@type series() :: %{name: String.t() | nil, data: [ohlc_item()]}

One candlestick series: optional :name and its list of ohlc_item/0 points.

t()

@type t() :: %Plotto.CandlestickChart{data: [series()], opts: options()}

The candlestick chart struct.

Functions

new(data, opts \\ [])

@spec new(
  [ohlc_item()] | [series()],
  keyword()
) :: {:ok, t()} | {:error, String.t()}

Builds a candlestick chart. Returns {:ok, chart} or {:error, reason}.

data can be either a flat list of ohlc_item/0 maps or a list of series/0 maps containing OHLC points.

Options

:width - chart width in pixels. Defaults to 600.
:height - chart height in pixels. Defaults to 400.
:title - optional chart title centered above the plot. Defaults to nil.
:bullish_color - hex color for bullish candles (close >= open). Defaults to "#26A69A".
:bearish_color - hex color for bearish candles (close < open). Defaults to "#EF5350".
:legend - optional legend position: :top_left, :top_right, :bottom_left, or :bottom_right. Defaults to nil.

new!(data, opts \\ [])

@spec new!(
  [ohlc_item()] | [series()],
  keyword()
) :: t()

Same as new/2, but returns the t/0 struct directly and raises ArgumentError if validation fails.