# `Plotto.CandlestickChart`
[🔗](https://github.com/altenwald/plotto/blob/v0.6.0/lib/plotto/candlestick_chart.ex#L1)

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)

# `ohlc_item`

```elixir
@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`

```elixir
@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:t/0`'s `:opts` field).

# `series`

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

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

# `t`

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

The candlestick chart struct.

# `new`

```elixir
@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 `t:ohlc_item/0` maps or a list of `t: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!`

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

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*