Aggregate one or more sets through a workbook, an in-memory mapping, or a Region preset produced by region_aggregation.

Typical patterns are:

  • aggregate multiple sets from a filled Excel workbook;

  • aggregate only Region directly, without creating a workbook first;

  • combine a prefilled Region mapping with other workbook-based aggregations.

  • apply a NACE or CPA mapping prepared by get_aggregation(), as shown in Aggregating by classification.

aggregated_db = db.aggregate(
        io=None,
        levels="Region",
        region_aggregation="continent",
        inplace=False,
)

When both io and region_aggregation are provided, MARIO injects the generated Region mapping only if the workbook or mapping does not already contain an explicit Region sheet.

Note

For regional classifications, item mappings use the original region and item as their source key, even when regions are aggregated in the same operation. Only existing nodes are aggregated, and unit compatibility checks still apply.

Regions can be merged only when their complete label sets match across all regional classifications. This also applies to Region presets and in-memory inputs. Comparisons use literal labels; MARIO does not infer equivalence between different labels. See mario.Database.get_aggregation_excel for the corresponding workbook layout.

Database.aggregate(
io,
drop=['unused'],
levels='all',
calc_all=False,
ignore_nan=False,
zero_output_epsilon: float | None = 1e-30,
inplace=True,
region_aggregation=None,
)#

Aggregate one or more classification levels in the database.

Parameters:

  • io – Aggregation definition, either as workbook path or as an in-memory mapping shaped like get_aggregation_excel(...) output.

  • drop – Labels to drop after aggregation. The historical default ["unused"] removes placeholder groups created during workbook editing.

  • levels – One classification level, an iterable of levels, or "all".

  • calc_all – When True, recompute the standard dependent matrices after aggregation.

  • ignore_nan – When True, missing aggregation targets are treated as no-aggregation identity mappings.

  • zero_output_epsilon – Positive fallback used to preserve non-zero coefficients for zero-output columns during aggregation. Pass None to disable the fallback.

  • inplace – When True, mutate the current database. When False, return an aggregated copy.

  • region_aggregation – Optional Region aggregation preset or explicit mapping applied even when io is None. When a workbook or dict is also provided, MARIO uses the explicit Region sheet if present and otherwise injects the generated Region mapping.

Returns:

Aggregated database when inplace=False, otherwise None.

Return type:

Database | None