SAM API

SAM API#

Utilities for reading, validating, and converting a Social Accounting Matrix into model-ready CGE-Core data.

Build CGE-Core datasets from a single social accounting matrix.

The bundled examples read a directory of four CSVs: param-sam-.csv plus set-i-.csv (goods), set-h-.csv (factors), and set-u-.csv (all SAM accounts). For a real-country SAM – e.g. a Philippine SAM with its own sector list – writing the set files by hand is error-prone. This module derives them from the SAM itself: the user names the factor accounts and the institutional accounts, and every remaining account is a good.

Combined with the accounts= mapping on the model-definition classes (which relabels the institutional accounts the equations read, e.g. HOH -> HH), this lets a balanced SAM with the standard-model account structure – activities, factors, one household, government, an indirect-tax row, a tariff row, investment, and rest-of-world – be loaded without editing model code. The benchmark flows used in ratios, CES/CET powers, and Cobb-Douglas calibration must also satisfy the reference model’s nonzero/positivity assumptions.

Example:

from cge_core import CGE, sam
from cge_core.models import StdCGE

accounts = dict(hoh='HH', gov='GOVT', inv='SAV-INV',
                ext='ROW', idt='ITAX', trf='TARIFF')
sam.build_dataset('ph_sam.csv', 'ph_data_dir',
                       factors=['CAP', 'LAB'],
                       institutions=accounts.values())
model = CGE(model=StdCGE(accounts=accounts), data='ph_data_dir')

Provenance: new in CGE-Core v0.3.0; developed through an AI-assisted workflow directed and reviewed by James Matthew Miraflor (2026), project lead and maintainer. Not part of the original NIST PyCGE.

cge_core.sam.build_dataset(sam_path, out_dir, factors, institutions)#

Turn a single SAM CSV into a directory loadable by model_data.

Writes set-i-.csv (goods), set-h-.csv (factors), set-u-.csv (all accounts) and copies the SAM to param-sam-.csv in out_dir.

Parameters:

  • sam_path (str or Path) – path to the SAM CSV.

  • out_dir (str or Path) – destination directory (created if missing).

  • factors (sequence of str) – factor account labels.

  • institutions (iterable of str) – institutional account labels; for the standard model, pass the six values of the accounts mapping given to StdCGE (household, government, investment, external, indirect tax, tariff).

Returns:

the populated directory.

Return type:

out_dir (Path)

Raises:

DataValidationError – from derive_sets() / SAM validation.

cge_core.sam.derive_sets(path, factors, institutions)#

Split a SAM’s accounts into goods, factors, and institutions.

Every account that is neither a factor nor an institution is a good (an activity/commodity in the standard model’s one-to-one mapping).

Parameters:

  • path (str or Path) – path to the SAM CSV.

  • factors (sequence of str) – labels of the factor accounts (e.g. ['CAP', 'LAB']).

  • institutions (iterable of str) – labels of the institutional accounts – for the standard model, the household, government, investment, external, indirect-tax, and tariff accounts.

Returns:

goods in SAM order, and the

factor list in SAM order.

Return type:

(goods, factors) (tuple of list)

Raises:

DataValidationError – if any named factor or institution is missing from the SAM, or no goods remain.

cge_core.sam.read_sam(path)#

Read and validate a SAM CSV.

The file is validated with the same structural checks the engine applies (square, unique labels, finite numeric cells, balanced row and column totals), then parsed.

Parameters:

path (str or Path) – path to a SAM CSV whose first row and first column carry the account labels.

Returns:

labels is the account list in file

order; cells maps (row_label, column_label) to the numeric value.

Return type:

(labels, cells) (tuple)

Raises:

DataValidationError – if the file fails structural validation.