For input files and an import example, see the BONSAI guide.

mario.parse_bonsai(
path: str | Path,
*,
table: str = 'SUT',
year: int | None = None,
extensions: bool = True,
unmatched_extensions: str = 'warn',
unmatched_final_demand: str = 'warn',
chunksize: int = 100000,
model: str = 'Database',
name: str | None = None,
calc_all: bool = False,
**kwargs,
) → object#

Parse BONSAI Balanced HSUT or the native, already modelled b2 HIOT.

Parameters:

  • path (str or pathlib.Path) – Complete ZIP archive or directory containing one Balanced HSUT or b2 HIOT release. A single nested release directory is detected automatically.

  • table (str, optional) – SUT for Balanced HSUT (default), or IOT for the b2 HIOT.

  • year (int, optional) – Reference year. For HSUT, an explicit value must match classification.csv. For HIOT, it is read from nonempty elementary-flow time values when available; otherwise provide it explicitly. Release dates are not years.

  • extensions (bool, optional) – Load recalculated elementary flows: all_elementary_flows_AB_and_BB.csv for HSUT, total_elementary_flow_w_iLUC.csv for HIOT. Defaults to True; False loads only economics with zero satellite placeholders.

  • unmatched_extensions ({"warn", "raise"}, optional) – Report and omit elementary-flow rows without a classified process, or reject the import. Full omitted rows are retained in the import report.

  • unmatched_final_demand ({"warn", "raise"}, optional) – For HIOT, report and omit demand for products absent from the native matrix, or reject the import. Full omitted rows remain in the report.

  • chunksize (int, optional) – Number of CSV rows per read; economic matrices stay sparse.

  • model ({"Database", "ModelState"}, optional) – Type of the returned MARIO object.

  • name (str, optional) – Dataset name stored in metadata.

  • calc_all (bool, optional) – Calculate derived matrices after import. Defaults to False. Large Balanced tables should be inspected or aggregated before computing full inverse matrices.

Notes

HSUT requires classification.csv, hybrid_supply_w_characteristic_unit.csv and hybrid_use_w_characteristic_unit.csv. The reference year comes from the classification, not the release directory. Native commodity codes, regional flows and hybrid units are preserved. No value-added accounts are inferred from mixed physical units: Va and Vc contain a zero placeholder.

HIOT requires extended_size_hiot.b2.pkl and final_demand.b2.csv from the same source snapshot. A release directory can be updated in place; its name and file modification dates do not establish input consistency. The native matrix already includes Stone, iLUC and capital. Only load trusted BONSAI pickle exports. Native product codes identify IOT Sectors; original activity/reference-product pairs are retained in the import report. For the native net-supply matrix T, X is its diagonal and Z = diag(X)-T. This retains the exact BONSAI system and substitution credits even when source production and demand do not balance. Gross reference production and self consumption cannot be recovered separately. V/VY are zero placeholders. The parser does not convert Balanced HSUTs or read precomputed Leontief inverses or footprints.

IOT multipliers satisfy f = e (I-z)^-1 = E T^-1. calc_ghg() applies the MARIO GHG profile, not the export’s LCIA workbook. Comparing saved BONSAI footprints requires matching source snapshots, LCIA factors, regional product identities and native units. Characterize the required accounts before keep_extensions to limit the number of environmental solve rows.

Import diagnostics and satellite identities are stored in Database.info["bonsai"] or ModelState.metadata.extra["bonsai"]. No archive extraction or automatic download is performed; HSUT uses only CSVs. Satellite labels use name | compartment. Native UUIDs are appended only to disambiguate homonyms, and units only if the same identity has multiple units. Original identities remain in the import report and units in Database.units["Satellite account"].

A successful import sets session compute defaults to compute_method='solve', linear_solver='umfpack' when installed (otherwise 'scipy'), linear_strategy='direct' and singular_policy='partial', including when calc_all=True. These defaults also affect other databases in the same Python process; they can be changed afterwards with the compute settings functions. Other settings and the saved user profile are unchanged. UMFPACK requires scikit-umfpack and SuiteSparse (conda install -c conda-forge scikit-umfpack). The optional mariopy[umfpack] extra installs the Python wrapper; pip users must install SuiteSparse first. Missing optional dependencies select SciPy; numerical failures are not retried with another solver. Failed imports restore prior settings. Partial solves warn and return NaN at coefficients affected by singular components, without changing source data. Defaults are defined in mario.settings.parser_profiles.PARSER_COMPUTE_PROFILES["bonsai"].

Native b2 HIOT#

Use table="IOT" to read BONSAI’s final hybrid input-output model:

db = mario.parse_bonsai("/path/to/HIOT/20260615", table="IOT")
db.get_index("Sector", region="IT")
db.units["Sector"].head()
db.info["bonsai"]

The same call accepts a ZIP with one nested release directory. The input bundle must contain:

  • extended_size_hiot.b2.pkl: the native sparse net-supply matrix,

  • final_demand.b2.csv: final consumption,

  • total_elementary_flow_w_iLUC.csv: absolute direct elementary flows, unless extensions=False.

Use a trusted BONSAI export for the native pickle. No precomputed inverse, terminated inventory or footprint is loaded. The parser does not rebuild Stone markets or convert the Balanced HSUT. The b2 system already includes iLUC and capital modelling. Intermediate supply/use CSV exports are not needed.

The reference year comes from nonempty time values in the elementary flows, independently of the release directory date. If that metadata is unavailable, provide it explicitly, for example year=2016. An explicit year must agree with source time values when present.

Representation and source coverage#

Product codes identify Sectors. Activity/product reference pairs, native units and nonuniform regional classifications remain in db.info["bonsai"] and the matrix axes. No Cartesian expansion of regions and products is performed.

For the native net-supply matrix T, MARIO stores X = diag(T) and Z = diag(X) - T. Thus diag(X) - Z exactly preserves the original model, including substitution credits. Direct coefficients use this supplied net reference production rather than demand-based row totals. Gross reference supply and self consumption are not separately recoverable from T. Value-added accounts are zero placeholders; they are not inferred by summing flows in different physical units.

The final-demand export can refer to products absent from the final HIOT. unmatched_final_demand="warn" reports and omits those rows, retaining their full contents in db.info["bonsai"]["unmatched_final_demand"]. Choose unmatched_final_demand="raise" to reject incomplete coverage. The analogous unmatched_extensions option applies to elementary-flow activities absent from the imported model. Source production imbalance is recorded under product_balance without modifying the model.

An IOT exposes per-unit satellite multipliers as f; the native HSUT exposes commodity multipliers as fc. The default table="SUT" and its CSV-based Balanced import remain unchanged.

Further calculations#

With Q = diag(X), the imported blocks satisfy

\[T = Q - Z = (I-z)Q, \qquad e = EQ^{-1}, \qquad f = e(I-z)^{-1} = ET^{-1}.\]

MARIO’s usual multiplier formula therefore represents the native system. The configured solve obtains the requested multipliers without materializing a full inverse. Units follow the elementary-flow and product units in the source. Keep calc_all=False and request only the matrices needed for an analysis. See Resolvable Matrices and Blocks for available calculations and mario.Database.calc_ghg for greenhouse-gas characterization.

The directory name 20260615 identifies the source folder, not a frozen snapshot or the reference year. Individual files can be updated within it. Archive inputs together and record their checksums for reproducible analyses.