Database.plot(
matrix=None,
data=None,
scenarios='baseline',
base_scenario=None,
difference='absolute',
preset='overview',
kind=None,
x=None,
y='Value',
color=None,
size=None,
facet_row=None,
facet_col=None,
animation_frame=None,
hover_name=None,
hover_data=None,
line_group=None,
text=None,
path_columns=None,
filters=None,
item=None,
agg='sum',
top_n=None,
path=None,
auto_open=True,
layout=None,
barmode='relative',
log_x=False,
log_y=False,
title=None,
return_data=False,
*,
log_color=False,
color_clip=None,
show_totals=False,
totals_format='.3s',
**kwargs,
)#

Build one interactive plot from a matrix or a prepared dataframe.

Parameters:

  • matrix – Matrix name to resolve, flatten and plot. Canonical names and their configured aliases are both accepted.

  • data – Optional already-flat dataframe. Use this for custom derived views.

  • scenarios – Scenario name or iterable of scenario names. Used only with matrix=....

  • base_scenario – Optional reference scenario used to plot scenario differences.

  • difference – Difference mode used with base_scenario. Accepted values are "absolute" and "relative".

  • preset – Convenience preset for the non-expert workflow. Accepted values are "overview", "composition", "trend", "heatmap", "treemap" and "sunburst". With "heatmap" and no x, a matrix is drawn as it is stored: one row per matrix row, one column per matrix column, in the original order. Pass x and heatmap_y to pivot on other columns.

  • kind – Plotly Express chart type. When omitted, MARIO infers a sensible default from preset.

  • mappings – Standard Plotly Express mappings used in the advanced workflow. This includes x, y, color, size, facet_row, facet_col, animation_frame, hover_name, hover_data, line_group and text.

  • path_columns – Hierarchy columns for treemap and sunburst plots.

  • filters – Column filters applied after flattening. Example: {"Region_from": ["IT"], "Sector_to": ["Food"]}.

  • item – Optional shorthand filter applied on Level_from and Level_to when the selected matrix carries activity/commodity or sector semantics.

  • agg – Aggregation applied before plotting.

  • top_n – Optional cap on the number of x categories kept in the plot.

  • path – Output HTML path. Pass False to skip HTML export.

  • auto_open – When True, open the generated HTML plot automatically.

  • layout – Optional Plotly layout overrides.

  • barmode – Bar stacking mode used for bar plots.

  • show_totals – Show only one total label per stacked bar, summing the displayed segments after filtering and aggregation. Supported for bar plots with barmode='relative' or 'stack', without animation. Signed segments produce a net total label at the stack’s outer edge. Segment labels from text or text_auto are suppressed.

  • totals_format – Plotly/D3 number format for total labels, for example '.3s' (compact, the default) or ',.0f' (whole numbers).

  • log_x – Whether to use logarithmic scaling.

  • log_y – Whether to use logarithmic scaling.

  • log_color – Heatmaps only. When True, color cells by log10 of their value so that a few very large entries, such as the diagonal of Z, do not flatten the rest of the matrix. Zero cells are left blank and negative values raise an error.

  • color_clip – Heatmaps only. Optional pair of quantiles, for example (0.05, 0.995). Color values outside this range are clipped to it, which softens outliers. Applied after log_color.

  • title – Optional plot title.

  • return_data – When True, return (figure, plotted_dataframe).

  • **kwargs – Additional keyword arguments forwarded to Plotly Express.

Returns:

The generated figure, or (figure, plotted_dataframe) when return_data=True.

Return type:

plotly.graph_objects.Figure | tuple

Totals on stacked bars#

Use show_totals=True to display one total above each stacked column, without labels on its individual segments. Totals use the segments displayed after filtering, aggregation and top_n selection:

fig = database.plot(
    matrix="E", x="Item_to", color="Region",
    filters={"Item_from": ["GHG AR6 GWP-100"]},
    category_orders={"Item_to": database.sectors},
    show_totals=True, totals_format=".3s",
    title="E | direct GHG emissions",
    path="results/E_totals.html", auto_open=False,
)

totals_format accepts Plotly/D3 number formats: ".3s" gives compact labels and ",.0f" shows whole numbers. If text or text_auto is also provided, only total labels are shown. Faceted bar plots are supported; animated plots and grouped/overlaid bars are not. With signed segments, labels report the net total and sit outside the stack.