Labels & Text

Every strategy accepts three universal text parameters and a set of variable-specific label parameters. All are optional strings that default to None; when None, each strategy computes a meaningful default from its configured variables.

Universal parameters

Parameter	Description
title	Figure title. Defaults to a generated description of the chart.
subtitle	Figure subtitle rendered below the title (Plotly 5.15+).
caption	Caption intended for <figcaption> in an HTML <figure> wrapper. Not applied to the Plotly figure — returned in FigureView.caption.
description	Free multiline text explaining how to interpret the figure. Not applied to the Plotly figure — returned in FigureView.description.
storytelling_context	Narrative context for the figure — its goal, target audience, and analytical angle. Not applied to the Plotly figure — returned in FigureView.storytelling_context.

Variable-specific parameters

Parameter	Applies to
category_label	bar, grouped bar, pie, boxplot
value_label	bar, grouped bar, line, categorical line, pie, sunburst, heatmap, boxplot, grouped boxplot, choropleth map
group_label	grouped bar, grouped boxplot
country_label	choropleth map
date_label	line
category_label	line (legend title for the category dimension when category_variable is set)
x_label	categorical line, heatmap
series_label	categorical line (when series_variable is set)
y_label	heatmap
path_label	sunburst (reserved for future use)

Example

from orama.strategies.bar import BarChartStrategy
from orama.variables import Aggregation

strategy = BarChartStrategy(
    fields_metadata=fields_metadata,
    category_variables=["region"],
    aggregation=Aggregation(name="total_revenue", function="sum", field="revenue"),
    # Universal labels
    title="Revenue by Region",
    subtitle="All regions · Q1 2025",
    caption="Source: Internal sales data. Figures in EUR.",
    description="Revenue is computed as the sum of invoiced amounts net of VAT.\nOnly regions with at least one transaction are shown.",
    # Variable-specific labels
    category_label="Region",
    value_label="Total Revenue (€)",
)

view = strategy.plot(dfs={"main": df}, tr=NullTranslations(), theme=theme)

# Render with caption and/or description
html = view.figure.to_html(full_html=False)
if view.caption:
    html = f"<figure>{html}<figcaption>{view.caption}</figcaption></figure>"
# view.description is available for custom rendering (e.g., a tooltip or popover)

Unit annotations

All strategies recognise FieldMetadata.extra["unit"] and automatically append the unit to the auto-generated default value label. When no explicit value_label is provided, the label becomes "<default label> (<unit>)" — for example "Sum of revenue (EUR)".

The unit is not appended when the caller provides an explicit value_label.

from fields_metadata import MetadataExtractor

metadata = MetadataExtractor().extract(MyModel)

# Annotate numeric fields with their units after extraction
metadata["revenue"].extra["unit"] = "EUR"
metadata["tax_rate"].extra["unit"] = "%"

# value axis label → "Sum of revenue (EUR)"
strategy = BarChartStrategy(
    fields_metadata=metadata,
    category_variables=["region"],
    aggregation=Aggregation(name="total_revenue", function="sum", field="revenue"),
)

Storytelling context

storytelling_context captures the why behind a figure: who the audience is, what question it answers, and what conclusion the analyst wants to convey. It is not rendered inside the Plotly figure itself — it is returned in FigureView.storytelling_context for use by the caller (e.g. rendered as an aside, fed to an LLM, logged, or displayed as an annotation outside the chart).

strategy = BarChartStrategy(
    ...,
    storytelling_context=(
        "Audience: regional sales managers. "
        "Goal: identify which regions are underperforming relative to Q1 targets."
    ),
)
view = strategy.build(dfs={"main": df}, tr=tr, theme=theme)
print(view.storytelling_context)

A pre-build callback can populate or overwrite storytelling_context dynamically — for example by querying an LLM with the chart data before rendering (see Callbacks).