Struct CandlestickPlot 

pub struct CandlestickPlot {
    pub candles: Vec<CandleDataPoint>,
    pub candle_width: f64,
    pub wick_width: f64,
    pub color_up: String,
    pub color_down: String,
    pub color_doji: String,
    pub show_volume: bool,
    pub volume_ratio: f64,
    pub legend_label: Option<String>,
    pub show_tooltips: bool,
    pub tooltip_labels: Option<Vec<String>>,
}

Builder for a candlestick (OHLC) chart.

Each candle encodes four values — open, high, low, close — for a single period:

• The body spans from open to close. A bullish candle (close > open) is filled with color_up (default green). A bearish candle (close < open) is filled with color_down (default red). A doji (close == open) is drawn with color_doji (default gray).
• The wicks are thin vertical lines extending from the body to high (upper wick) and low (lower wick).

An optional volume panel can be shown below the price chart by attaching volumes with with_volume and enabling the panel with with_volume_panel.

Categorical vs numeric x-axis

Two input modes are available:

• Categorical (with_candle): candles are placed at evenly spaced integer positions and the labels are shown as x-axis category ticks.
• Numeric (with_candle_at): each candle is placed at an explicit f64 x position, enabling uneven spacing and a true numeric x-axis. Useful for quarterly or irregularly spaced data.

Example

use kuva::plot::CandlestickPlot;
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;

let plot = CandlestickPlot::new()
    .with_candle("Mon", 100.0, 106.5,  99.2, 105.8)
    .with_candle("Tue", 105.8, 108.0, 104.1, 104.5)
    .with_candle("Wed", 104.5, 109.2, 104.0, 108.0)
    .with_candle("Thu", 108.0, 111.5, 107.3, 110.9)
    .with_candle("Fri", 110.9, 111.0, 107.8, 108.5)
    .with_legend("ACME");

let plots = vec![Plot::Candlestick(plot)];
let layout = Layout::auto_from_plots(&plots)
    .with_title("Weekly OHLC")
    .with_x_label("Day")
    .with_y_label("Price (USD)");

let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("candlestick.svg", svg).unwrap();

Fields

candles: Vec<CandleDataPoint>

All candles in insertion order.

candle_width: f64

Candle body width as a fraction of the slot width between candles (default 0.7; range 0.0–1.0).

wick_width: f64

Wick stroke width in pixels (default 1.5).

color_up: String

Fill color for bullish candles (close > open). Default green.

color_down: String

Fill color for bearish candles (close < open). Default red.

color_doji: String

Fill color for doji candles (close == open). Default #888888.

show_volume: bool

Whether to render the volume bar panel below the price chart.

volume_ratio: f64

Fraction of the total chart height reserved for the volume panel (default 0.22).

legend_label: Option<String>

Optional legend entry label. When set a legend box is drawn inside the plot area.

show_tooltips: bool

tooltip_labels: Option<Vec<String>>

Implementations

impl CandlestickPlot

pub fn new() -> Self

Create a candlestick plot with default settings.

Defaults: candle width 0.7, wick width 1.5, green/red/gray colors, no volume panel, no legend.

pub fn with_candle<S: Into<String>>( self, label: S, open: impl Into<f64>, high: impl Into<f64>, low: impl Into<f64>, close: impl Into<f64>, ) -> Self

Append a candle in categorical mode.

The candle is placed at its insertion index and label is shown as an x-axis category tick. Use this when candles are evenly spaced (daily, weekly data).

let plot = CandlestickPlot::new()
    .with_candle("Mon", 100.0, 106.5,  99.2, 105.8)  // open, high, low, close
    .with_candle("Tue", 105.8, 108.0, 104.1, 104.5);

pub fn with_candle_at<S: Into<String>>( self, x: f64, label: S, open: impl Into<f64>, high: impl Into<f64>, low: impl Into<f64>, close: impl Into<f64>, ) -> Self

Append a candle at an explicit numeric x position.

The candle body is centred at x on a continuous numeric x-axis. Use this when candles are unevenly spaced — for example quarterly data where x is a fractional year — or when the x position carries meaning beyond a simple sequence index.

When using this method, call with_candle_width to set an appropriate body width in data units (e.g. 0.15 for quarterly data spaced 0.25 units apart).

let plot = CandlestickPlot::new()
    // x = fractional year; candles spaced 0.25 apart
    .with_candle_at(2023.00, "Q1", 110.0, 118.0, 108.0, 116.0)
    .with_candle_at(2023.25, "Q2", 116.0, 122.0, 114.0, 121.0)
    .with_candle_at(2023.50, "Q3", 121.0, 126.0, 118.5, 119.5)
    .with_candle_width(0.15);

pub fn with_volume<T, I>(self, volumes: I) -> Self

where T: Into<f64>, I: IntoIterator<Item = T>,

Attach volume values to existing candles.

Values are matched to candles in insertion order. If there are fewer volume values than candles, the remaining candles receive no volume. The volume data is not rendered until with_volume_panel is also called.

let plot = CandlestickPlot::new()
    .with_candle("Mon", 100.0, 106.0, 99.0, 105.0)
    .with_candle("Tue", 105.0, 108.0, 104.0, 104.5)
    .with_volume([1_250_000.0, 980_000.0])
    .with_volume_panel();

pub fn with_volume_panel(self) -> Self

Enable the volume bar panel below the price chart.

The panel occupies the bottom portion of the chart area (default 22 %). Requires volume data attached via with_volume. Volume bars are colored to match their candle (green = up, red = down).

pub fn with_volume_ratio(self, ratio: f64) -> Self

Set the fraction of the total chart height used by the volume panel (default 0.22).

For example 0.30 gives the volume panel 30 % of the chart height and leaves 70 % for the price chart. Has no effect unless with_volume_panel is also called.

pub fn with_candle_width(self, width: f64) -> Self

Set the candle body width as a fraction of the slot between candles (default 0.7).

In categorical mode the slot width is 1.0 (one index unit), so 0.7 gives a body that fills 70 % of the available space. In numeric mode (with_candle_at) this value is in data units — set it to be smaller than the spacing between candles.

Complement of with_gap: width = 1.0 - gap.

pub fn with_gap(self, gap: f64) -> Self

Set the gap between candles as a fraction of the slot (default 0.3).

Only meaningful in categorical mode. Complement of with_candle_width: gap = 1.0 - width.

pub fn with_wick_width(self, width: f64) -> Self

Set the wick stroke width in pixels (default 1.5).

pub fn with_color_up<S: Into<String>>(self, color: S) -> Self

Set the fill color for bullish candles where close > open (default "rgb(68,170,68)" — green).

Accepts any CSS color string.

pub fn with_color_down<S: Into<String>>(self, color: S) -> Self

Set the fill color for bearish candles where close < open (default "rgb(204,68,68)" — red).

Accepts any CSS color string.

pub fn with_color_doji<S: Into<String>>(self, color: S) -> Self

Set the fill color for doji candles where close == open (default "#888888" — gray).

A doji typically signals indecision in the market. Accepts any CSS color string.

pub fn with_legend<S: Into<String>>(self, label: S) -> Self

Add a legend label, causing a legend box to appear inside the plot area.

let plot = CandlestickPlot::new()
    .with_candle("Jan", 100.0, 108.0, 98.0, 106.0)
    .with_legend("ACME Corp");

pub fn with_tooltips(self) -> Self

pub fn with_tooltip_labels( self, labels: impl IntoIterator<Item = impl Into<String>>, ) -> Self

Trait Implementations

impl Default for CandlestickPlot

fn default() -> Self

Returns the “default value” for a type.

impl From<CandlestickPlot> for Plot

fn from(p: CandlestickPlot) -> Self

Converts to this type from the input type.