Candlestick Chart

A candlestick chart shows the open, high, low, and close (OHLC) of a price series as a stack of rectangular bodies with thin “wick” lines, giving a compact view of where price ranged within each interval. Use it when you have time-bucketed OHLC bars and need to read direction and range at a glance.

In a bullish (up) candle the close sits above the open and the body is typically rendered green; in a bearish (down) candle the close sits below the open and the body is typically red. The wick (or “shadow”) extends from the body to the period’s high and low, so wick length communicates intra-bar volatility.

What are candlestick charts useful for?

Reading short-term price action: Bodies and wicks make direction and intra-bar range readable at a glance, which is why candlesticks are common on technical-analysis screens.
Spotting reversal and continuation patterns: Many classical patterns (engulfings, hammers, dojis) rely on the relative size of body and wicks, and candlesticks are the only chart type that surfaces both.
Comparing volatility regimes: Long wicks with small bodies signal indecision; tall bodies with short wicks signal momentum. Switching between regimes is easy to see.
Confirming aggregations: Because TVL aggregates OHLC server-side when the table is large, a candlestick chart is also a quick check that your binning matches what you expected.

Examples

A basic candlestick chart

Hand the chart a Deephaven table that already contains OHLC columns and the rest is automatic. The defaults (timestamp="Timestamp", open="Open", high="High", low="Low", close="Close") match the columns produced by tvl.data.ohlc(), so for the demo dataset you only need the table itself.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(data)

Each candle covers one row in data; green bodies are up days and red bodies are down days. tvl.candlestick() doesn’t carry the last-price pulse animation that line / area / baseline series do. See line and styling for the LastPriceAnimationMode examples.

When up_color / down_color are not provided, the chart adapts to the active theme automatically. Light and dark themes both render correctly without code changes.

Map non-default OHLC column names

If your table uses different column names, for example lowercase columns coming from a feed or a different timestamp column, pass them explicitly. Every column kwarg is just a string column name.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc().rename_columns(["Ts=Timestamp", "O=Open", "H=High", "L=Low", "C=Close"])

candlestick = tvl.candlestick(
    data,
    timestamp="Ts",
    open="O",
    high="H",
    low="L",
    close="C",
)

Customize up and down colors

Override the default green/red palette with up_color and down_color. Use this to match a brand palette, build a color-blind-friendly variant, or to dim the candles before overlaying markers and price lines.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(
    data,
    up_color="seafoam-800",
    down_color="magenta-600",
)

All color kwargs (up_color, down_color, border_*_color, wick_*_color) accept a Deephaven theme color (e.g. "seafoam-800", "accent-300"), a hex code ("#1f8a70"), a named CSS color ("crimson"), or an rgb()/rgba() string for transparency. Theme colors adapt automatically when the user switches themes; hardcoded values do not. Leaving the up/down colors unset inherits the active theme’s OHLC palette.

Outline-only candles via border colors

border_up_color and border_down_color set the outline color of each candle independently of the body fill. Setting a border to "transparent" removes that border entirely, leaving only the body fill. Combine this with a neutral body fill and a single visible up border to get a “pavement” two-tone candle.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(
    data,
    up_color="gray-500",
    down_color="gray-500",
    border_up_color="gray-500",
    border_down_color="transparent",
)

Up candles use a neutral grey throughout; down candles drop their border so only the grey body remains.

Recolor the wicks

wick_up_color and wick_down_color set the wick color separately from the body. Use this to dim the wicks while keeping bright bodies (for marker visibility), or to brighten the wicks on a dark background.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(
    data,
    wick_up_color="gray-500",
    wick_down_color="gray-500",
)

Both wicks are now grey; the bodies keep their defaults.

Set the chart title

title is the legend label for the series. It appears on hover and in the chart toolbar. Use it whenever you have more than one series on a chart, or when the chart will be embedded somewhere a column name (Open/Close) is too generic.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(data, title="AAPL daily OHLC")

The legend now reads “AAPL daily OHLC” instead of the default series name.

Server-side autobinning

Hand the chart a large OHLC table and TVL automatically aggregates it server-side into a viewport-friendly number of buckets, picking a “nice” bin width and computing first(Open) / max(High) / min(Low) / last(Close) per bin. Override the bucket count or width via bin_count / bin_width, or set auto_bin=False to bypass it entirely for small tables.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(data, auto_bin=True, bin_width="P7D")

See autobin for the full autobin surface: ISO-8601 duration grammar, when each auto_bin value is the right pick, and how the path interacts with the downsampler.

Single border / wick colors and toggles

border_color and wick_color set one color for both up and down candles, shorthand for setting the *_up_color / *_down_color pair to the same value. border_visible and wick_visible toggle the outline and wick rendering entirely.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(
    data,
    border_visible=True,
    border_color="gray-500",
    wick_visible=True,
    wick_color="gray-500",
)

Time-proportional layout with `continuous`

By default (continuous=True) candles are laid out proportionally in time. Unlike the histogram, candle bodies are not drawn end-to-end — they keep the classic proportions, with a small gap between adjacent candles — but sections of data separated by a time hole (a market close, a halted feed, missing rows) are separated by a proportional open gap. On data with no holes, continuous=True and continuous=False look the same. Set continuous=False to restore the plain ordinal layout, which collapses any time hole to a single candle-width step.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc()

candlestick = tvl.candlestick(data, continuous=False)

Per-bar colors from a column

Drive each candle’s color from a table column with color_column (body), border_color_column (outline), and wick_color_column (wick). Each names a column holding a CSS/theme color string per row. Here we color each bar by whether it closed up or down.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.ohlc().update_view(
    ["BarColor = Close >= Open ? `#26a69a` : `#ef5350`"]
)

candlestick = tvl.candlestick(
    data,
    color_column="BarColor",
    border_color_column="BarColor",
    wick_color_column="BarColor",
)

API Reference

A candlestick series renders four channels (open, high, low, close) per time bucket as a filled body with wicks. When the source table is large, auto-binning aggregates OHLC values server-side before the data is shipped to the browser.

Returns: TvlChart A chart wrapping a single candlestick series. chart().

Parameters	Type	Default	Description
table	Any		The Deephaven table containing OHLC data.
timestamp	str	'Timestamp'	Column name for the time axis.
open	str	'Open'	Column name for the opening price.
high	str	'High'	Column name for the bar high.
low	str	'Low'	Column name for the bar low.
close	str	'Close'	Column name for the closing price.
up_color	Optional[Color]	None	Body color for up-bars.
down_color	Optional[Color]	None	Body color for down-bars.
border_visible	Optional[bool]	None	Show the body border.
border_color	Optional[Color]	None	Border color for both directions.
border_up_color	Optional[Color]	None	Border color for up-bars (overrides border_color for up).
border_down_color	Optional[Color]	None	Border color for down-bars.
wick_visible	Optional[bool]	None	Show wicks.
wick_color	Optional[Color]	None	Wick color for both directions.
wick_up_color	Optional[Color]	None	Wick color for up-bars.
wick_down_color	Optional[Color]	None	Wick color for down-bars.
title	Optional[str]	None	Title shown in the series tooltip / legend.
visible	Optional[bool]	None	Whether the series is visible.
last_value_visible	Optional[bool]	None	Show the last-value badge on the price scale.
price_scale_id	Optional[str]	None	ID of the price scale this series uses ("left", "right", or a custom overlay ID).
price_format	Optional[PriceFormat]	None	Per-series number format; build with price_format().
last_price_line	Optional[LastPriceLine]	None	Styling for the auto last-price horizontal rule; build with last_price_line().
base_line	Optional[BaseLine]	None	Styling for the zero/index base line (percentage / indexed_to_100 price modes); build with base_line().
price_scale	Optional[PriceScale]	None	Options for the price scale this series binds to; build with price_scale().
color_column	Optional[str]	None	Column name supplying per-row body color (overrides up_color / down_color).
border_color_column	Optional[str]	None	Column name supplying per-row border color.
wick_color_column	Optional[str]	None	Column name supplying per-row wick color.
pane	Optional[int]	None	Pane index (default 0).
markers	Optional[list[Marker]]	None	Static markers.
price_lines	Optional[list[PriceLine]]	None	Horizontal price lines.
marker_spec	Optional[MarkerSpec]	None	Table-driven marker spec.
auto_bin	Optional[bool]	None	Tri-state. None (default) auto-bins when the table exceeds the auto-bin threshold (5000 rows); True forces aggregation even for small tables; False ships the raw table.
bin_width	Optional[str]	None	ISO 8601 duration override (e.g. "PT1S", "PT5M").
bin_count	Optional[int]	None	Target number of bins (default 5000).
continuous	bool	True	True (default) renders candle bodies spanning their full time bin (end-to-end); False uses the built-in fixed pixel-width renderer.
by	Optional[str]	None	Column name to partition the table by. When set, one runtime series is created per unique value; new partition keys discovered at runtime (ticking tables) add new series automatically.
on_press	Optional[PressEventCallable]	None	Server-side callback invoked when the user presses (clicks) on the chart. Receives a TvlPressEvent dict, or no argument.
on_double_press	Optional[PressEventCallable]	None	Server-side callback invoked when the user double-presses on the chart.