Skip to content

Add optional reference (production) exchange column to datapackage schema - #108

Merged
cmutel merged 1 commit into
mainfrom
add-reference-column
Jul 10, 2026
Merged

cmutel merged 1 commit into
mainfrom
add-reference-column

Conversation

@cmutel

@cmutel cmutel commented Jul 10, 2026

Copy link
Copy Markdown
Member

Summary

Adds an optional per-exchange reference boolean column to the datapackage schema, stored as its own side-resource (kind="reference") exactly like flip/rescale: additive, backward compatible, and written only when at least one entry is flagged.

Modellers can now record which technosphere exchange is the reference (production) exchange for an activity, so consumers such as bw_graph_tools can read it directly instead of relying on structural heuristics. Those heuristics cannot disambiguate co-production columns — an activity with more than one same-sign exchange whose products also appear in other columns (e.g. process A co-produces product Y and waste Z, process B treats Z while consuming Y). In that case no sign/flip/uniqueness rule can recover the modeller's intent, and guess_production_exchanges raises UnclearProductionExchange. See cauldron/brightway-api#739 for the full problem write-up.

Design

A separate optional resource rather than a new field in INDICES_DTYPE, because the indices dtype is format-pinned (strictly asserted in the Parquet path, hand-built field-by-field) and mandatory/universal; a separate resource is non-breaking and zero-cost when unused.

Changes

  • MatrixEntry.reference: bool = False; ArrayEntry.reference: Optional[np.ndarray] (bool coercion + shape validation).
  • reference_array kwarg on add_persistent_vector, add_persistent_array, add_dynamic_vector, add_dynamic_array; threaded from add_entries/add_array_entries; new _add_reference_array_resource helper.
  • Threaded through dictionary_formatter / resolve_dict_iterator.
  • "reference" added to the Parquet kind mapping and to the merging resource-suffix whitelist (also adds the previously-missing rescale there).
  • README section, CHANGES.md entry, version bump 1.5 → 1.6.

Tests

Dataclass defaults/validation, formatter/resolver, low-level validation (wrong dtype, shape mismatch), skip-when-empty, and a write→reload round-trip. Full suite: 273 passed, 1 skipped.

Follow-ups (separate PRs, not in this change)

  • matrix_utils: expose has_reference/reference on ResourceGroup.
  • bw_graph_tools: an authoritative "heuristic zero" that reads group.reference first in guess_production_exchanges.

Refs cauldron/brightway-api#739

…hema

Adds an optional per-exchange `reference` boolean column, stored as its own
side-resource (`kind="reference"`) exactly like `flip`/`rescale`: additive,
backward compatible, and written only when at least one entry is flagged.

Modellers can now record which technosphere exchange is the reference
(production) exchange, so consumers such as bw_graph_tools can read it
directly instead of relying on structural heuristics, which cannot
disambiguate co-production columns (an activity with multiple same-sign
outputs whose products also appear in other columns).

- MatrixEntry.reference / ArrayEntry.reference
- reference_array kwarg on all add_* methods + _add_reference_array_resource
- threaded through dictionary_formatter / resolve_dict_iterator
- "reference" added to Parquet kind mapping and merging suffix whitelist
- README section, CHANGES entry, version bump 1.5 -> 1.6
- tests: dataclass defaults/validation, low-level validation, skip-when-empty,
  write->reload round-trip

Refs cauldron/brightway-api#739
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant