Titles, Legends, and Watermarks

TVL doesn’t have a “title” widget. Instead, a chart title is added through a watermark, and per-series titles drive the in-chart legend that appears in the top-left corner. This page covers titles and legends and gives a brief tour of the watermark options; for the full watermark treatment (multi-line, image watermarks, alignment) see watermark.

What are titles and legends useful for?

Identifying a chart in a dashboard: A watermark title tells viewers what they’re looking at: symbol, instrument, or scenario.
Per-series labels: Each series can carry a title=, which appears in the chart’s legend overlay along with the live last-value readout.
Brand and context: Watermarks can include disclaimers, environment names (“staging”), or “as of” timestamps without taking up screen space.
Selective legend: Hide the last-value badge on noisy overlay series with last_value_visible=False while keeping the title.

Examples

Add a chart title via watermark

The simplest title is a single-line watermark. tvl.watermark(text=...) sets the text; visible=True enables it; color and font_size style it.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    watermark=tvl.watermark(
        visible=True,
        text="Reference Index",
        color="rgba(150, 150, 150, 0.6)",
        font_size=24,
    ),
)

The watermark sits centered behind the data by default. See watermark for alignment options.

Position the watermark in a corner

horz_align ("left" / "center" / "right") and vert_align ("top" / "center" / "bottom") on tvl.watermark(...) place the watermark in any of nine positions. Use a corner placement when the watermark serves as a chart title rather than a centered background label.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    watermark=tvl.watermark(
        visible=True,
        text="USD / EUR",
        horz_align="left",
        vert_align="top",
        font_size=18,
        color="rgba(150, 150, 150, 0.7)",
    ),
)

For a “title bar” effect, anchor top-left and increase the color opacity.

Show series titles in the legend

Each series factory accepts a title= parameter, and the value appears in the legend overlay in the top-left of the chart. Setting title on multiple series gives each a labeled badge.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()
shifted = values.update_view(["Value = Value + 10"])

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value", title="Index", color="#2563eb"),
    tvl.line(shifted, timestamp="Timestamp", value="Value", title="Index +10", color="#dc2626"),
)

Without title, the series shows a colored marker with the live value but no name. That’s fine for single-series charts, but awkward when you have several overlays.

Hide the last-value badge on noisy series

last_value_visible=False hides the price-axis pill that follows each series. Use this for noisy reference overlays where the live value isn’t useful (e.g. a moving-average line above a candlestick).

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()
shifted = values.update_view(["Value = Value + 10"])

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value", title="Main", color="#2563eb"),
    tvl.line(
        shifted,
        timestamp="Timestamp",
        value="Value",
        title="Reference",
        color="#94a3b8",
        last_value_visible=False,
    ),
)

The series remains in the legend overlay; only the right-edge price label disappears.

Toggle series visibility from the start

visible=False starts the series hidden. Useful for “click to enable” legend interactions handled outside Python, or for setting up a chart where most series are off by default.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value", title="Primary"),
    tvl.line(
        values.update_view(["Value = Value + 5"]),
        timestamp="Timestamp",
        value="Value",
        title="Optional overlay",
        visible=False,
    ),
)

The legend entry still shows; the line doesn’t render until something toggles visible back on.

Multi-line watermark for richer titles

For a two-line title (instrument + tagline, “as of” timestamps, etc.) pass a list of WatermarkLine dataclasses to tvl.watermark(lines=[...]). Each line can carry its own color, font size, line height, and font style. See watermark for details.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    watermark=tvl.watermark(
        visible=True,
        horz_align="center",
        vert_align="center",
        lines=[
            tvl.WatermarkLine(
                text="USD / EUR",
                color="rgba(150, 150, 150, 0.65)",
                font_size=32,
            ),
            tvl.WatermarkLine(
                text="Daily close, 2024",
                color="rgba(150, 150, 150, 0.55)",
                font_size=14,
                font_style="italic",
            ),
        ],
    ),
)

Single-line shortcuts (tvl.watermark(text=...)) and tvl.watermark(lines=...) are mutually exclusive, so pick one path.

Image watermark as a “brand mark”

tvl.watermark_image(url=...) is the third watermark path, rendering a logo or seal in the chart. Combine with alpha for a subtle background mark.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    watermark_image=tvl.watermark_image(
        visible=True,
        url="https://example.com/brand.png",
        max_width=120,
        max_height=120,
        padding=16,
        alpha=0.15,
    ),
)

See watermark for the full image-watermark surface.

Compact dashboard-tile titles

For dense small-multiples layouts, use a small corner-anchored watermark as a tile label. Pair with font_size on the chart so the axis labels stay legible in a tile.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    font_size=10,
    watermark=tvl.watermark(
        visible=True,
        text="AAA",
        horz_align="left",
        vert_align="top",
        font_size=12,
        color="rgba(150, 150, 150, 0.7)",
    ),
)

This works well for tiled overview screens: title in the corner, data filling the rest.

API Reference

For the full tvl.chart signature, see the Chart container page.