# `Tucan.Finance`
[🔗](https://github.com/pnezis/tucan/blob/v0.7.0/lib/tucan/finance.ex#L1)

Financial plots.

This module provides specialized financial plots like `candlestick/7`.

# `candlestick`

```elixir
@spec candlestick(
  plotdata :: Tucan.plotdata(),
  timestamp :: String.t(),
  open :: String.t(),
  high :: String.t(),
  low :: String.t(),
  close :: String.t(),
  opts :: keyword()
) :: VegaLite.t()
```

Plots a candlestick chart from OHLC data.

`timestamp` is expected to correspond to the beginning of the chart's period.

## Options

* `:volume` (`t:String.t/0`) - A field with the traded volume of each period. If set the volume is drawn as a
  bar chart below the prices, colored by the direction of the price.

### Data Options

* `:only` - A subset of fields to pick from the data. Applicable only if tabular data
  are provided.

### Styling Options

* `:clip` (`t:boolean/0`) - Whether a mark will be clipped to the enclosing group’s width and height.
* `:fill_opacity` (`t:number/0`) - The fill opacity of the plotted elements. The default value is `1`.
* `:height` (`t:pos_integer/0` or `:container`) - Height of the plot. Can either be the height in pixels or `:container` to indicate that
  the height of the plot should be the same as its surrounding container.
* `:title` (`t:String.t/0`) - The title of the graph
* `:volume_height` (`t:pos_integer/0`) - The height of the volume chart in pixels, if `:volume` is set. The default value is `60`.
* `:width` (`t:pos_integer/0` or `:container`) - Width of the plot. Can either be the width in pixels or `:container` to indicate that
  the width of the plot should be the same as its surrounding container.

### Interactivity Options

* `:tooltip` (`boolean() | :data | :encoding`) - The tooltip text string to show upon mouse hover or an object defining which fields
  should the tooltip be derived from. Can be one of the following:

  * `:encoding` - all fields from encoding are used
  * `:data` - all fields of the highlighted data point are used
  * `true` - same as `:encoding`
  * `false`, `nil` - no tooltip is used
* `:zoomable` (`t:boolean/0`) - Whether the plot will be zoomable or not. If set to `true` you will be able to pan and
  zoom the plot with your mouse. You can reset to the original view with a double click. The default value is `false`.

## Examples

```tucan
Tucan.Finance.candlestick(:ohlc, "date", "open", "high", "low", "close",
  width: 400,
  tooltip: true
)
|> Tucan.Axes.set_y_title("Price")
```

With the traded volume below the prices, here for generated data:

```tucan
:rand.seed(:exsss, {1, 2, 3})

{data, _close} =
  Enum.map_reduce(Date.range(~D[2024-03-01], ~D[2024-05-31]), 100.0, fn date, previous ->
    open = previous + :rand.normal()
    close = open + 2 * :rand.normal()
    high = max(open, close) + abs(:rand.normal())
    low = min(open, close) - abs(:rand.normal())
    volume = round(1_000_000 * (1 + abs(close - open)) * (0.5 + :rand.uniform()))

    {%{date: date, open: open, high: high, low: low, close: close, volume: volume}, close}
  end)

Tucan.Finance.candlestick(data, "date", "open", "high", "low", "close",
  volume: "volume",
  width: 450,
  height: 200
)
```

With `:volume` set the plot is a vertical concatenation of the prices and the
volume, sharing the time axis. The price axis is titled `"Price"`, and functions
that expect a single or layered view, e.g. `Tucan.Axes.set_y_title/2`, cannot be
applied to it.

---

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