Formatting & helpers

Number formatting

format_number applies WBG rules: automatic scale suffix (K/M/B), auto decimal places based on magnitude, and optional currency/percent/unit handling.

import attaviz
print(attaviz.format_number(1234567))              # 1.2M
print(attaviz.format_number(0.456, percent=True))  # 45.6%
print(attaviz.format_number(50000, currency=True)) # $50.0K
print(attaviz.format_number(1234567890, unit="bytes"))  # 1.2GB

1.2M
45.6%
$50.0K
1.2GB

Key parameters:

decimals — integer or "auto" (default). Auto uses 2 decimals for values under 1, 1 decimal for 1–100, 0 above.
scale — "K", "M", "B", "G", or "auto".
currency — prefix with $.
percent — multiply by 100 and suffix with %.
unit — when set to a technical unit (W, byte, bit, ton, …), uses G instead of B for billions.

D3 number format strings

For Altair axes/tooltips, which expect a D3 format string rather than a Python-formatted value:

print(attaviz.d3_number_format())                  # ',.1f'
print(attaviz.d3_number_format(decimals=0))        # ',.0f'
print(attaviz.d3_number_format(currency=True))     # '$,.1f'
print(attaviz.d3_number_format(percent=True))      # '.1%'

,.1f
,.0f
$,.1f
.1%

D3 format strings don’t support custom suffixes, so for K/M/B either pre-scale the data or indicate the scale in the axis title (“GDP (millions)”).

Auto-scaled Altair axis labels

vega_scale_labelExpr() returns a Vega expression that applies Attaviz K/M/B scaling to raw values in an Altair axis:

import altair as alt

axis = alt.Axis(labelExpr=attaviz.vega_scale_labelExpr())

attaviz.vega_scale_labelExpr(
    *,
    currency=False,
    unit=None,
    decimals="auto",
)

Set currency=True for a dollar prefix, unit for a unit suffix, or decimals to an integer for fixed precision. This function returns an expression, not a D3 format string; pass it to labelExpr, not format.

Date formatting

from datetime import date
import attaviz
d = date(2023, 1, 15)
print(attaviz.format_date(d, style="month_year"))               # Jan-23
print(attaviz.format_date(d, style="month_year", short=False))  # January 2023
print(attaviz.format_date(d, style="quarter"))                  # 23Q1
print(attaviz.format_date(d, style="fiscal_year"))              # FY23

Jan-23
January 2023
23Q1
FY23

Supported style values: "day", "month", "month_year", "quarter", "year", "fiscal_year". The WBG fiscal year runs July–June (July 2023 is FY24; January 2023 is FY23).

D3 date format strings

print(attaviz.d3_date_format("month_year"))               # %b-%y
print(attaviz.d3_date_format("month_year", short=False))  # %B %Y
print(attaviz.d3_date_format("year"))                     # %y

%b-%y
%B %Y
%y

"quarter" and "fiscal_year" cannot be represented as D3 time-format strings. For those, pre-compute values with format_date and pass them to Altair as strings, or use a Vega expression in the axis encoding.

Captions

Attach a styled caption below a chart.

attaviz.add_caption(
    chart,
    "Source: World Bank Development Indicators, 2023",
    *,
    align="left",
)

align — "left" (default, on-spec), "center", or "right".
Embed a newline (\n) in the text for multi-line captions.

add_caption() remains available for compatibility. Prefer frame() for new publication charts because it also requires an accessibility description and supports notes, sources, and a byline.