Database.pool_trade(
commodities,
*,
supply_suffix: str = ' - supply',
need_suffix: str = ' - need',
inplace: bool = True,
)#

Pool the trade of selected commodities behind one pass-through layer.

For each selected commodity c MARIO adds, per region, one "{c}{supply_suffix}" activity and one "{c}{need_suffix}" commodity. The pass-through activity consumes the whole domestic output of c; every buyer (intermediate use and final demand) is rewired onto the domestic need commodity, keeping its total input; and the supply block routes each destination market to the origin pass-through activities with the bilateral trade flows observed on the Isard use side. The rest of the table keeps its Isard layout.

After the pooling, the technology mix of c and its trade mix live in two separate market-share columns of s and can be updated independently with update_supply_mix() and update_trade_mix() (the latter with items="{c}{supply_suffix}" and commodities="{c}{need_suffix}").

Parameters:

  • commodities – One commodity label or an iterable of labels to pool.

  • supply_suffix – Suffix appended to the commodity label to name the pass-through activity.

  • need_suffix – Suffix appended to the commodity label to name the pooled market commodity.

  • inplace – When True, mutate the current database. When False, return a transformed copy.

Returns:

Transformed database when inplace=False, otherwise None.

Return type:

Database | None

Notes

Activity, Commodity and Consumption category labels must be the same in every region. Nonuniform regional classifications raise NotImplementable before copying the database or querying matrices, including when inplace=False.

The pooling is a representation change, not a data change at the destination level: bilateral trade totals per destination region are preserved exactly, and the initial market shares written in s equal the observed origin shares of each destination’s total use. What is averaged away is the buyer-specific sourcing heterogeneity inside each destination region — the Chenery-Moses hypothesis, applied only to the selected commodities. For grid-like commodities such as electricity this is typically more realistic than the Isard buyer-specific sourcing.

The transformation is structural: it rebuilds the baseline and drops any other scenario (with one warning), like the other structural transforms. The pooled pairs are recorded on meta.pooled_trade_map.