Database.update_supply_mix(
shares_by_region,
*,
scenario: str = 'baseline',
clone_from: str | None = None,
rescale: bool = False,
year: int | None = None,
ember_path: str | PathLike[str] | None = None,
api_key=None,
region_aggregation=None,
aggregate_as_ember: bool = False,
column_regions=None,
column_sectors=None,
column_categories=None,
level: str | None = None,
commodities=None,
aggregate_commodity=None,
) → None#

Update one regional supply mix in the selected scenario.

For IOT databases the mix redistributes the combined coefficient rows of one regional sector bundle across z and Y.

For SUT databases the behaviour depends on the classification the share labels belong to:

  • Commodity mix — the bundle rows are redistributed across the use block u and the final-demand block Yc, exactly like the IOT case with commodities playing the sector role.

  • Activity mix (market shares) — the bundle rows are redistributed inside the supply block s, restricted to the commodity columns selected by commodities=.... This rewrites the market shares of the selected activities in producing those commodities. The shares are rescaled onto the combined share currently held by the selected activities, so producers outside the bundle (e.g. by-product suppliers of the same commodity) keep their share untouched.

Parameters:

  • shares_by_region –

    Either one explicit mapping region -> {label: share} or the special string "electricity". Example:

    db.update_supply_mix({"IT": {"wind": 0.6, "solar": 0.4}})

    moves the weight currently held by wind and solar in Italy to a 60/40 split between them, leaving every other technology and the region’s total electricity input per buyer unchanged.

    The listed labels form one bundle whose combined column total is preserved; rows outside it keep their coefficients, so a subset rewrites only the split among its members. A label is a Sector (IOT) or a Commodity/Activity (SUT, see level); all labels of one region share the same classification. Shares are relative weights expected to sum to one (±0.01); pass rescale=True for arbitrary positive totals.

    When "electricity" is used, MARIO derives one generation mix from EMBER electricity-generation data for the requested year. The EMBER taxonomy is more aggregated than the disaggregated electricity classification exposed by EXIOBASE and EMERGING-E, so the database electricity bundle is first aggregated to the compatible EMBER fuel groups before the update is applied. The resulting group totals are then redistributed back to the original database labels using the current internal composition of each aggregated group.

    On IOT databases the update targets the generation sectors across z and Y. On SUT databases MARIO first aggregates the disaggregated electricity commodities into one shared commodity (see aggregate_commodity) and then rewrites the market shares of the generation activities in s. Transmission and distribution labels are left unchanged in both cases.

  • scenario – Scenario to update in place. When it does not exist yet, provide clone_from=... to create it first.

  • clone_from – Optional existing source scenario to clone when scenario does not exist yet.

  • rescale – When True, rescale each region-level vector to sum to one even when the provided values are totals or otherwise do not already form a near-unit mix.

  • year – EMBER year to use when shares_by_region="electricity". When omitted, MARIO uses the latest year available in the selected EMBER snapshot. When one covered region has no exact observation for the requested year, MARIO falls back to the nearest available year for that region and emits one warning.

  • ember_path – Optional path to one EMBER CSV snapshot. When omitted (and no api_key), MARIO uses the packaged reduced EMBER electricity-generation snapshot. The upstream EMBER yearly full release is published at https://files.ember-energy.org/public-downloads/yearly_full_release_long_format.csv

  • api_key –

    shares_by_region="electricity" only: a one-entry mapping naming a live data provider, {"ember": "<key>"} – MARIO fetches generation-by-fuel for year from the Ember API (the path for users without a snapshot; register a key at https://ember-energy.org/data/api/). Pass just "ember" to use a key configured globally via mario.set_api_keys(), the EMBER_API_KEY env var, or mario/settings/api_keys.yaml. {"nxbase": "<key>"} is reserved for the hosted nxbase (not available yet). Mutually exclusive with ember_path; requires an explicit year. Same api_key interface as update_trade_mix() ({"entsoe": ...} there).

    The generation (supply) mix uses Ember, not ENTSO-E, because Ember covers every country worldwide, whereas ENTSO-E is limited to the European synchronous area. The trade mix is the mirror image (update_trade_mix() uses ENTSO-E: it is the one with bilateral cross-border flows, which matter only inside that area).

  • region_aggregation –

    Optional Region aggregation metadata used only when shares_by_region="electricity". This can be one Region sheet workbook path, one pandas Series/DataFrame, one mapping shaped like an aggregation workbook Region sheet, or one explicit aggregated_region -> [original_region, ...] mapping.

    When omitted, MARIO automatically reuses db.meta.region_aggregation_map if the database was aggregated earlier through aggregate().

  • aggregate_as_ember – When True and shares_by_region="electricity" on one IOT database, aggregate the database Sector classification to the coarser EMBER fuel-group names after applying the updated mix. The aggregation is structural and therefore affects the whole database, not only the selected scenario.

  • column_regions – Restrict the redistribution to buyer/demand columns of these regions only. Accepts one region or an iterable of regions. When None (default) the mix is applied across all columns. The operation stays matricial: the selected columns are extracted and rewritten, the others are left untouched.

  • column_sectors – Restrict the redistribution to buyer columns of these labels only. On IOT databases these are the buyer sectors of z; on SUT commodity mixes they are the buyer activities of u. Final-demand blocks have no such columns and are filtered by column_regions and column_categories. Not accepted for Activity-level mixes, whose rewritten columns are selected by commodities=... instead.

  • column_categories – Restrict the final-demand redistribution to these consumption categories only (the Y block on IOT, Yc on SUT commodity mixes). None (default) means all categories. Not accepted for Activity-level mixes, which rewrite no final-demand block.

  • level – Classification of the share labels. Optional on SUT databases when the labels resolve unambiguously to Activities or Commodities; required ('Activity' or 'Commodity') when one label exists in both classifications. IOT databases always operate on Sectors.

  • commodities – SUT Activity-level mixes only: the commodity (or commodities) whose market shares should be rewritten in s. Defaults to the targets of aggregate_commodity when that argument is provided.

  • aggregate_commodity – SUT only. Optional {'new commodity': [existing commodities]} mapping structurally aggregated (through aggregate()) before the mix update, so that several activities compete on one shared commodity market. The aggregation affects the whole database, not only the selected scenario. With shares_by_region="electricity" the mapping defaults to the packaged electricity profile, so it can be omitted for EXIOBASE-style layouts.

Returns:

The selected scenario is updated in place.

Return type:

None

Notes

The method rewrites coefficient-side blocks preserving the original column totals of each selected regional bundle: z/Y for IOT, u/Yc for SUT commodity mixes and s for SUT activity mixes.

With regional classifications, every supplied label must exist in its specified region. Level inference checks these regional memberships. Column selectors filter actual columns by label and region; they do not create missing region-item pairs. Sparse inputs retain sparse storage, and rows outside each selected bundle remain unchanged. Explicit aggregate_commodity mappings apply to existing regional occurrences of their member codes only.

The target scenario is reset to coefficient-side storage internally before applying the redistribution, so callers do not need an extra reset_to_coefficients(...) around this operation.

Regions that are not covered by EMBER are left unchanged and generate one warning when shares_by_region="electricity".

Warning

On Chenery-Moses SUTs (see to_chenery_moses()) the supply block entangles technology and trade: one region’s technology mix is replicated, scaled by its trade shares, inside the s columns of every destination market it exports to. Updating a technology mix there requires rewriting the region’s rows in all destination columns — which is what the default column_regions=None does, preserving each destination’s trade share. Restricting column_regions to the domestic market only would leave the exported production on the old mix: the same fleet would carry two different technology mixes depending on the buyer. Layouts that separate the two informations (Isard tables, or pooled tables built with pool_trade()) are immune by construction.