Area Chart

An area chart is a line chart with a vertical gradient fill underneath. The fill shows the magnitude of the value as well as its trajectory. Use it for single-series time series where you want to emphasize how much, such as equity curves, cumulative volume, or account balance, rather than the shape of small fluctuations.

The fill is a vertical gradient between top_color (just below the line) and bottom_color (at the chart bottom).

What are area charts useful for?

Emphasizing magnitude: The shaded region under the line shows how big the value is, in addition to where it’s going.
Single-series time series: When there is only one quantity to plot, an area chart carries more visual weight than a bare line and still reads as a trend at a glance.
Cumulative quantities: Volume traded, P&L, balance, headcount, and anything else that accumulates suits an area chart.
Dashboard tiles: A filled area stays legible on small chart tiles where the line alone would be too thin to register.

Examples

A basic area chart

Pass a table with a timestamp column and a value column. With tvl.data.values() (columns Timestamp and Value) the defaults already match, but they are shown here explicitly for clarity.

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

area = tvl.area(data, timestamp="Timestamp", value="Value")

The line traces the value; the area below it fades from the top color to the bottom color.

Customize the gradient

top_color is the gradient stop at the line; bottom_color is the stop at the bottom of the chart. Both accept a Deephaven theme color (e.g. "orange-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.

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

area = tvl.area(
    data,
    timestamp="Timestamp",
    value="Value",
    top_color="orange-800",
    bottom_color="transparent",
)

The gradient runs from a deep amber at the line down to fully transparent at the chart bottom.

Line width

line_width sets the outline thickness as an integer 1-4 (the LWC default is 3). Wider outlines stand out on dashboards; thinner outlines disappear into the gradient on detail charts.

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

area = tvl.area(data, timestamp="Timestamp", value="Value", line_width=1)

The outline is now one pixel wide.

One area per group with `by`

Set by to a partition column and the chart draws one area per unique value, each with its own auto-assigned color from the user’s theme palette. This is useful for comparisons, but note that the areas overlay rather than stack arithmetically.

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

area = tvl.area(
    data,
    timestamp="Timestamp",
    value="Price",
    by="Sym",
)

Each symbol gets its own translucent area, automatically colored.

Invert the filled area

invert_filled_area=True flips the gradient so the area is drawn above the line instead of below it. This is the typical layout for “deficit” or “below-baseline” views, where the value of interest is the gap between the line and the top of the chart.

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

area = tvl.area(
    data,
    timestamp="Timestamp",
    value="Value",
    invert_filled_area=True,
)

The shaded region now extends from the line up to the top of the chart rather than down to the bottom.

Line color and a relative gradient

line_color sets the outline color independently of the fill. relative_gradient=True anchors the gradient stops to the series’ value range rather than the visible pane, so the fill keeps consistent colors as the chart scrolls.

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

area = tvl.area(
    data,
    timestamp="Timestamp",
    value="Value",
    line_color="accent-500",
    relative_gradient=True,
)

Per-point colors from columns

line_color_column, top_color_column, and bottom_color_column drive the line and the two gradient stops from per-row table columns of color strings.

import deephaven.plot.tradingview_lightweight as tvl
data = tvl.data.values().update_view(
    [
        "LineCol = Value >= 100 ? `#26a69a` : `#ef5350`",
        "TopCol = Value >= 100 ? `rgba(38,166,154,0.4)` : `rgba(239,83,80,0.4)`",
        "BotCol = `rgba(0,0,0,0)`",
    ]
)

area = tvl.area(
    data,
    timestamp="Timestamp",
    value="Value",
    line_color_column="LineCol",
    top_color_column="TopCol",
    bottom_color_column="BotCol",
)

API Reference

Renders a filled area between the value line and the bottom of the chart, using a vertical gradient between top_color and bottom_color.

Returns: TvlChart A chart wrapping a single area series (or one per partition when by is set).

Parameters	Type	Default	Description
table	Any		Deephaven table with the data.
timestamp	str		Column name for the time axis.
value	str		Column name for the y-axis.
line_color	Optional[Color]	None	Line color at the top of the filled area.
top_color	Optional[Color]	None	Gradient fill color at the top.
bottom_color	Optional[Color]	None	Gradient fill color at the bottom (typically transparent).
relative_gradient	Optional[bool]	None	If True, the gradient is measured relative to the series values rather than the chart bounds.
invert_filled_area	Optional[bool]	None	If True, fill above the line instead of below.
line_width	Optional[LineWidth]	None	Stroke width 1–4 px.
line_style	Optional[LineStyle]	None	Dash pattern; see LineStyle.
line_type	Optional[LineType]	None	Geometry between data points; see LineType.
line_visible	Optional[bool]	None	Show the line.
point_markers_visible	Optional[bool]	None	Show point markers at every data point.
point_markers_radius	Optional[float]	None	Point marker radius.
crosshair_marker	Optional[CrosshairMarker]	None	Styling for the crosshair marker dot; build with crosshair_marker().
last_price_animation	Optional[LastPriceAnimationMode]	None	Last-price dot animation.
last_value_visible	Optional[bool]	None	Show the last-value badge.
title	Optional[str]	None	Title.
visible	Optional[bool]	None	Series visibility.
price_scale_id	Optional[str]	None	Price-scale ID.
price_format	Optional[PriceFormat]	None	Per-series 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; build with base_line().
price_scale	Optional[PriceScale]	None	Options for the price scale this series binds to; build with price_scale().
line_color_column	Optional[str]	None	Per-row line color column.
top_color_column	Optional[str]	None	Per-row top-color column.
bottom_color_column	Optional[str]	None	Per-row bottom-color column.
pane	Optional[int]	None	Pane index.
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.
continuous	bool	True	True (default) = time-proportional chart axis; False opts the whole chart back to the plain ordinal layout. See line_series().
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.