mario.Database.calc_trades#

db.calc_trades(...) aggregates one sector or commodity into a region-by-region trade matrix.

When item is omitted, MARIO aggregates all sectors or commodities together, but only when they share one common unit of measure. Hybrid or otherwise heterogeneous unit layouts still require an explicit item.

For IOT tables it uses Z for intermediate trade and Y for final demand. For SUT tables it uses U for intermediate trade and Yc for final demand when the table follows the Isard format.

For Chenery-Moses SUT tables, commodity trade is aggregated from S instead. Because that trade is stored as one supply-side flow matrix, MARIO currently supports only the aggregate case with intermediate=True, final=True and aggregate=True.

When both intermediate=True and final=True, the default is aggregate=True, so the returned dataframe is the sum of intermediate and final trade. Use aggregate=False to keep the two components separate under a column MultiIndex.

Use total=True to add row and column totals.

Use clusters=... to aggregate the Region dimension before totals and plotting. This accepts Region aggregation presets such as 'continent' and explicit mappings such as {'EU': ['FR', 'DE', 'IT']}.

Use clusters_direction='origin' to aggregate only the origin Regions, 'destination' to aggregate only the destination Regions, or 'both' to aggregate both axes. The default is 'both'.

Use scenario='all' to calculate the same trade matrix for every available scenario on the database. In that case db.calc_trades(...) returns a dictionary {scenario: dataframe} instead of a single dataframe.

Use show_plot=True to also build and display a region-by-region heatmap while still returning the trade matrix.

Use exclude_domestic_from_plot=True to hide same-label origin-destination pairs from that heatmap without changing the returned trade matrix.

When more than one scenario is plotted together, MARIO builds one animated heatmap with a scenario slider.

Use save_plot=... to write that heatmap to an HTML file. The older path=... argument is still accepted as a backward-compatible alias. When save_plot is provided, MARIO saves the plot without displaying it. When the path ends in .html or .htm, MARIO writes HTML; for image extensions such as .png or .svg, it uses Plotly image export.

Use title=... to override the heatmap title. The heatmap colorbar uses the unit of the selected item instead of the generic sum of Value label.

Database.calc_trades(item=None, scenario='baseline', clusters=None, clusters_direction='both', intermediate=True, final=True, aggregate=True, total=False, show_plot=False, exclude_domestic_from_plot=False, save_plot=None, path=False, auto_open=False, title=None)#

Calculate region-by-region trade matrices for one item.

Parameters:

  • item – Sector or commodity label to aggregate by region. When omitted, MARIO aggregates all sectors or commodities only if they share one common unit of measure.

  • scenario – Scenario to analyse.

  • clusters – Optional Region aggregation preset or mapping applied before totals and plotting. This accepts the same Region aggregation payloads used by MARIO’s region aggregation helpers, including preset strings such as "continent" and explicit {"Group": [regions...]} mappings.

  • clusters_direction – Select which axis should receive Region aggregation when clusters is provided. Use "origin" to aggregate only rows, "destination" to aggregate only columns, or "both" for the default square aggregation.

  • intermediate – When True, include intermediate transactions. This uses Z for IOT tables and U for SUT tables.

  • final – When True, include final-demand transactions. This uses Y for IOT tables and Yc for SUT tables.

  • aggregate – When True and both intermediate and final are enabled, return their sum as one trade matrix. Use aggregate=False to keep the two components separate.

  • total – When True, add a Total row and a Total column.

  • show_plot – When True, build and display a region-by-region heatmap for the calculated trades.

  • exclude_domestic_from_plot – When True, omit same-label origin-destination pairs from the heatmap only. The returned trade matrix is not modified.

  • save_plot – Optional HTML output path for the heatmap. When provided, MARIO writes the plot to this path.

  • path – Backward-compatible alias for save_plot. Ignored when neither show_plot nor save_plot are requested. Pass False to skip HTML export.

  • auto_open – When True, automatically open the saved heatmap HTML.

  • title – Optional title for the heatmap. When omitted, MARIO uses "Trades for {item}".

Returns:

Region-by-region trade matrix for one scenario, or a dictionary {scenario: matrix} when more than one scenario is requested. When both intermediate and final are requested, the default is to return their aggregate sum. Use aggregate=False to get a dataframe with column MultiIndex top-level labels Intermediate and Final. When more than one scenario is plotted together, MARIO builds one animated heatmap with a scenario slider.

Return type:

pandas.DataFrame | dict

On this page