Price Formats

Price formatters control how numeric values appear on price-axis tick labels, crosshair labels, and last-value labels. TVL provides five typed surfaces: PriceFormat (per-series), and four chart-level named-preset enums (PriceFormatter, TickmarksPriceFormatter, PercentageFormatter, TickmarksPercentageFormatter). They cover the common currency, percent, volume, and scientific notation cases.

Reach for PriceFormat when you need precision-level control on one series; reach for the chart-level named presets when you want every label across the chart to share a single format.

What are price formats useful for?

Matching market conventions: USD equities want two decimals, JPY pairs want zero, FX wants four. Pick the right preset and the crosshair label matches the venue you trade on.
Volume formatting: Render volume axes as 1.2M instead of 1,234,567 by using type="volume" on the histogram series.
Percent overlays: A percentage-mode price scale needs a percent formatter; pair it with price_scale=tvl.price_scale(mode="percentage") for relative-return overlays.
Tick density and label width: A compact formatter ("compact") keeps long-number axes from pushing the plot area narrow.

Examples

Set per-series price format with `PriceFormat`

PriceFormat is built with tvl.price_format(...) and passed to the price_format= parameter of any series factory. type selects the kind ("price", "volume", "percent"), precision is the number of decimal places, and min_move is the smallest representable step.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.line(
    values,
    timestamp="Timestamp",
    value="Value",
    price_format=tvl.price_format(precision=4, min_move=0.0001),
)

Use this when your data is denominated in a unit that doesn’t match the chart-level locale or formatter.

Format volume with `PriceFormat`

For volume axes (and any large-number axis), type="volume" tells lightweight-charts to render large values in a human-readable form. Combine it with the histogram chart for the canonical price + volume pane stack.

import deephaven.plot.tradingview_lightweight as tvl

volume = tvl.data.volume()

chart = tvl.histogram(
    volume,
    timestamp="Timestamp",
    value="Volume",
    price_format=tvl.price_format(type="volume", precision=0),
)

Set precision=0 for whole-share volume; use precision=2 if you’re plotting dollar volume.

Format a percent series with `PriceFormat`

type="percent" renders raw percentage values (e.g. 42.5 as 42.5%) on the price axis. Use this for return overlays where the underlying series already holds percentages.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()
returns = values.update_view(["Value = (Value - 100.0) / 100.0 * 100.0"])

chart = tvl.line(
    returns,
    timestamp="Timestamp",
    value="Value",
    price_format=tvl.price_format(type="percent", precision=2),
)

If you actually want the price scale to be in percent mode (not just the labels), pair this with price_scale=tvl.price_scale(mode="percentage") on the series; see price-scale.

Pick a named price formatter for crosshair labels

PriceFormatter is the chart-level named preset for the crosshair price label and last-value label. Set price_formatter="currency_usd" and every numeric label gets the $1,234.56 shape. Pair it with locale="en-US" to lock down thousands separators and decimal punctuation.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    price_formatter="currency_usd",
    locale="en-US",
)

The PriceFormatter enum values are "currency_usd", "currency_eur", "currency_gbp", "currency_jpy", "percent", "compact", and "scientific".

Switch between USD, EUR, GBP, and JPY presets

The PriceFormatter and TickmarksPriceFormatter aliases both accept the same four currency presets plus "percent", "compact", and "scientific". Pick whichever matches your data and locale.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

usd = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    price_formatter="currency_usd",
    tickmarks_price_formatter="currency_usd",
    locale="en-US",
)
eur = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    price_formatter="currency_eur",
    tickmarks_price_formatter="currency_eur",
    locale="de-DE",
)
gbp = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    price_formatter="currency_gbp",
    tickmarks_price_formatter="currency_gbp",
    locale="en-GB",
)

Each currency preset wraps numbers in the right symbol; the locale kwarg controls the thousands separator and decimal mark.

Use the JPY currency preset

"currency_jpy" is the only preset that defaults to zero decimal places, matching how yen pairs are conventionally quoted. Pair it with locale="ja-JP" for fully-localized thousands separators.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(values, timestamp="Timestamp", value="Value"),
    price_formatter="currency_jpy",
    locale="ja-JP",
)

If you need a different decimal count, drop down to PriceFormat and set precision explicitly.

Use the compact preset for high-volume axes

"compact" renders 1234 as 1.23K, 12,345,678 as 12.35M, and so on. Useful for axes that span many orders of magnitude.

import deephaven.plot.tradingview_lightweight as tvl

volume = tvl.data.volume()
big_volume = volume.update_view(["Volume = Volume * 1_000_000"])

chart = tvl.chart(
    tvl.histogram(big_volume, timestamp="Timestamp", value="Volume"),
    price_formatter="compact",
)

This is the simplest answer to “I want my axis to show K/M/B suffixes.”

Scientific notation for wide-range axes

"scientific" renders values as 1.23e+5. Reach for it when the axis spans many orders of magnitude (latency in nanoseconds vs seconds, etc.) and you want exponents instead of compact suffixes.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()
scientific_values = values.update_view(["Value = Value * 1e-9"])

chart = tvl.chart(
    tvl.line(scientific_values, timestamp="Timestamp", value="Value"),
    price_formatter="scientific",
)

Format axis tick labels separately

TickmarksPriceFormatter controls the tick label on the price axis, while PriceFormatter controls the crosshair label. The enum values are identical but the two parameters are independent: you can render $1,234.56 on the crosshair while showing a compact 1.2K on the axis ticks.

import deephaven.plot.tradingview_lightweight as tvl

volume = tvl.data.volume().update_view(["Volume = Volume * 1_000_000"])

chart = tvl.chart(
    tvl.histogram(volume, timestamp="Timestamp", value="Volume"),
    price_formatter="currency_usd",
    tickmarks_price_formatter="compact",
)

This split keeps detailed values in the crosshair without blowing out the axis width.

Format percentages with `PercentageFormatter`

PercentageFormatter is the named-preset enum for the crosshair percentage label, used when a price scale is in percentage mode. Its four values trade precision for compactness: "percent" shows two decimals, "percent_1dp" one, "percent_0dp" zero, and "decimal" falls back to the raw ratio.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(
        values,
        timestamp="Timestamp",
        value="Value",
        price_scale=tvl.price_scale(mode="percentage"),
    ),
    percentage_formatter="percent_1dp",
)

# Use the raw-ratio fall-back when your audience reads `0.42` instead of `42%`.
decimal = tvl.chart(
    tvl.line(
        values,
        timestamp="Timestamp",
        value="Value",
        price_scale=tvl.price_scale(mode="percentage"),
    ),
    percentage_formatter="decimal",
    tickmarks_percentage_formatter="decimal",
)

Switch to "percent_0dp" for a tighter dashboard layout or to "decimal" if your audience reads raw ratios.

Format percentage tick marks

TickmarksPercentageFormatter mirrors PercentageFormatter but controls the axis ticks themselves. Use it together with a percentage price scale to render ticks like 42% while the crosshair shows 42.5%.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()

chart = tvl.chart(
    tvl.line(
        values,
        timestamp="Timestamp",
        value="Value",
        price_scale=tvl.price_scale(mode="percentage"),
    ),
    percentage_formatter="percent",
    tickmarks_percentage_formatter="percent_0dp",
)

The four TickmarksPercentageFormatter values match PercentageFormatter: "percent", "percent_1dp", "percent_0dp", "decimal".

Custom precision for tiny-tick instruments

For instruments quoted in tiny increments (FX 4-pip, low-priced crypto), build a PriceFormat with the right precision and minMove rather than reaching for a preset. The chart formatter respects the precision exactly.

import deephaven.plot.tradingview_lightweight as tvl

values = tvl.data.values()
fx = values.update_view(["Value = Value * 0.0001"])

chart = tvl.line(
    fx,
    timestamp="Timestamp",
    value="Value",
    price_format=tvl.price_format(precision=5, min_move=0.00001),
)

Stick with the built-in "price", "volume", and "percent" types, or use the chart-level named presets.

API Reference

Create a PriceFormat for a series' price_format= argument.

Returns: PriceFormat A number-format config for price_format=.

Parameters	Type	Default	Description
type	Literal['price', 'volume', 'percent']	'price'	Value kind — "price", "volume", or "percent".
precision	int \| None	None	Number of decimal places.
min_move	float \| None	None	Smallest representable step (e.g. 0.01 for cents).

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