Plotto.CandlestickChart (plotto v0.6.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_center
    | :top_right
    | :left_top
    | :left_middle
    | :left_bottom
    | :right_top
    | :right_middle
    | :right_bottom
    | :bottom_left
    | :bottom_center
    | :bottom_right
    | :top
    | :bottom
    | nil,
  legend_orientation: :vertical | :horizontal,
  bullish_color: String.t(),
  bearish_color: String.t(),
  tooltip: :data | :native | :title | false | nil | function(),
  y_max: number() | nil,
  y_min: number() | nil,
  y_max_soft: boolean(),
  y_min_soft: boolean(),
  y_max_guide: false | {:solid | :dashed | :dotted, String.t()},
  y_min_guide: false | {:solid | :dashed | :dotted, String.t()},
  value_prefix: String.t() | nil,
  value_suffix: String.t() | nil,
  x_guidelines: false | {:solid | :dashed | :dotted, String.t()},
  y_guidelines: false | {:solid | :dashed | :dotted, 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_center, :top_right, :left_top, :left_middle, :left_bottom, :right_top, :right_middle, :right_bottom, :bottom_left, :bottom_center, or :bottom_right. Defaults to nil.
:legend_orientation - optional legend layout orientation: :vertical or :horizontal. Applies when :legend is a top or bottom position. Defaults to :vertical.
:y_max - optional maximum target or upper bound for the Y axis. Defaults to nil.
:y_min - optional minimum target or lower bound for the Y axis. Defaults to nil.
:y_max_soft - boolean indicating if :y_max can be exceeded if data values are greater. Defaults to true.
:y_min_soft - boolean indicating if :y_min can be exceeded if data values are smaller. Defaults to false.
:y_max_guide - optional horizontal guide line drawn at y_max: false, true, or {:solid | :dashed | :dotted, color}. Defaults to false.
:y_min_guide - optional horizontal guide line drawn at y_min: false, true, or {:solid | :dashed | :dotted, color}. Defaults to false.
:value_prefix - optional string prefix prepended to numeric values (e.g. "$", "€"). Can also be passed as :prefix. Defaults to nil.
:value_suffix - optional string suffix appended to numeric values (e.g. "%"). Can also be passed as :suffix. Defaults to nil.
:x_guidelines - optional vertical guidelines drawn at each category: false, true, or {:solid | :dashed | :dotted, color}. Defaults to false.
:y_guidelines - optional horizontal guidelines drawn at each Y-axis tick: false, true, or {:solid | :dashed | :dotted, color}. Defaults to false.

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.