bw-processing 1.5__tar.gz → 1.6__tar.gz

{bw_processing-1.5/src/bw_processing.egg-info → bw_processing-1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bw_processing
-Version: 1.5
+Version: 1.6
 Summary: Foo
 Author-email: Chris Mutel <cmutel@gmail.com>
 Maintainer-email: Chris Mutel <cmutel@gmail.com>
@@ -211,12 +211,12 @@ print(data_obj.url)
 
 ### Scale arrays
 
-Any resource group (persistent or dynamic, vector or array) can carry an optional `scale_array`: a one-dimensional float array of the same length as `indices_array`. Each element is a multiplicative factor applied to the corresponding data value before it is inserted into the matrix. The factor is applied to both static and stochastically-sampled values. A value of `1.0` leaves the data unchanged.
+Any resource group (persistent or dynamic, vector or array) can carry an optional `rescale_array`: a one-dimensional float array of the same length as `indices_array`. Each element is a multiplicative factor applied to the corresponding data value before it is inserted into the matrix. The factor is applied to both static and stochastically-sampled values. A value of `1.0` leaves the data unchanged.
 
 Typical use cases:
 
-* **Allocation factors** — when a process produces multiple products, the exchange amounts must be partitioned between them. Storing the allocation coefficients as a `scale_array` keeps them alongside the data they modify without requiring a separate processing step.
-* **Unit conversions** — when source data is expressed in a unit that differs from the matrix convention, a constant conversion factor can be stored as a `scale_array` rather than baked into every data value.
+* **Allocation factors** — when a process produces multiple products, the exchange amounts must be partitioned between them. Storing the allocation coefficients as a `rescale_array` keeps them alongside the data they modify without requiring a separate processing step.
+* **Unit conversions** — when source data is expressed in a unit that differs from the matrix convention, a constant conversion factor can be stored as a `rescale_array` rather than baked into every data value.
 
 ```python
 import numpy as np
@@ -226,18 +226,45 @@ from bw_processing.constants import INDICES_DTYPE
 dp = create_datapackage()
 indices_array = np.array([(1, 4), (2, 5), (3, 6)], dtype=INDICES_DTYPE)
 data_array = np.array([100.0, 200.0, 300.0])
-scale_array = np.array([0.6, 1.0, 0.4])  # e.g. allocation factors
+rescale_array = np.array([0.6, 1.0, 0.4])  # e.g. allocation factors
 
 dp.add_persistent_vector(
     matrix="technosphere",
     name="my-process",
     indices_array=indices_array,
     data_array=data_array,
-    scale_array=scale_array,
+    rescale_array=rescale_array,
 )
 ```
 
-The stored resource has `kind="scale"` and can be retrieved via `dp.get_resource("my-process.scale")`. The `scale_array` must be a float dtype (`float32` or `float64`); passing an integer array raises `WrongDatatype`.
+The stored resource has `kind="rescale"` and can be retrieved via `dp.get_resource("my-process.rescale")`. The `rescale_array` must be a float dtype (`float32` or `float64`); passing an integer array raises `WrongDatatype`.
+
+### Reference (production) exchanges
+
+Any resource group can also carry an optional `reference_array`: a one-dimensional boolean array of the same length as `indices_array`. Where an element is `True`, that exchange is the **reference (production) exchange** for its activity/column.
+
+The five structural heuristics in `bw_graph_tools` (matching ids, single non-flipped entry, single positive, single negative, unique product) cannot always identify the reference exchange — whenever an activity has more than one same-sign exchange and the products also appear in other columns, the choice is genuinely ambiguous. Only the modeller knows the answer. `reference_array` records it directly so downstream tools can read it instead of guessing.
+
+```python
+import numpy as np
+from bw_processing import create_datapackage
+from bw_processing.constants import INDICES_DTYPE
+
+dp = create_datapackage()
+indices_array = np.array([(1, 4), (2, 5), (3, 6)], dtype=INDICES_DTYPE)
+data_array = np.array([1.0, 0.5, 2.0])
+reference_array = np.array([True, False, False])  # first exchange is the reference
+
+dp.add_persistent_vector(
+    matrix="technosphere",
+    name="my-process",
+    indices_array=indices_array,
+    data_array=data_array,
+    reference_array=reference_array,
+)
+```
+
+The stored resource has `kind="reference"` and can be retrieved via `dp.get_resource("my-process.reference")`. It must be a boolean array; passing a non-boolean array raises `WrongDatatype`. To keep the common case cheap, the resource is written only when at least one entry is `True` — a group with no reference flags carries no `reference` resource. Using the high-level `MatrixEntry`/`ArrayEntry` API, set `reference=True` (or a boolean `reference` array) on the entries you want flagged.
 
 ### Parameter arrays for sensitivity analysis
 

{bw_processing-1.5 → bw_processing-1.6}/README.md

@@ -168,12 +168,12 @@ print(data_obj.url)
 
 ### Scale arrays
 
-Any resource group (persistent or dynamic, vector or array) can carry an optional `scale_array`: a one-dimensional float array of the same length as `indices_array`. Each element is a multiplicative factor applied to the corresponding data value before it is inserted into the matrix. The factor is applied to both static and stochastically-sampled values. A value of `1.0` leaves the data unchanged.
+Any resource group (persistent or dynamic, vector or array) can carry an optional `rescale_array`: a one-dimensional float array of the same length as `indices_array`. Each element is a multiplicative factor applied to the corresponding data value before it is inserted into the matrix. The factor is applied to both static and stochastically-sampled values. A value of `1.0` leaves the data unchanged.
 
 Typical use cases:
 
-* **Allocation factors** — when a process produces multiple products, the exchange amounts must be partitioned between them. Storing the allocation coefficients as a `scale_array` keeps them alongside the data they modify without requiring a separate processing step.
-* **Unit conversions** — when source data is expressed in a unit that differs from the matrix convention, a constant conversion factor can be stored as a `scale_array` rather than baked into every data value.
+* **Allocation factors** — when a process produces multiple products, the exchange amounts must be partitioned between them. Storing the allocation coefficients as a `rescale_array` keeps them alongside the data they modify without requiring a separate processing step.
+* **Unit conversions** — when source data is expressed in a unit that differs from the matrix convention, a constant conversion factor can be stored as a `rescale_array` rather than baked into every data value.
 
 ```python
 import numpy as np
@@ -183,18 +183,45 @@ from bw_processing.constants import INDICES_DTYPE
 dp = create_datapackage()
 indices_array = np.array([(1, 4), (2, 5), (3, 6)], dtype=INDICES_DTYPE)
 data_array = np.array([100.0, 200.0, 300.0])
-scale_array = np.array([0.6, 1.0, 0.4])  # e.g. allocation factors
+rescale_array = np.array([0.6, 1.0, 0.4])  # e.g. allocation factors
 
 dp.add_persistent_vector(
     matrix="technosphere",
     name="my-process",
     indices_array=indices_array,
     data_array=data_array,
-    scale_array=scale_array,
+    rescale_array=rescale_array,
 )
 ```
 
-The stored resource has `kind="scale"` and can be retrieved via `dp.get_resource("my-process.scale")`. The `scale_array` must be a float dtype (`float32` or `float64`); passing an integer array raises `WrongDatatype`.
+The stored resource has `kind="rescale"` and can be retrieved via `dp.get_resource("my-process.rescale")`. The `rescale_array` must be a float dtype (`float32` or `float64`); passing an integer array raises `WrongDatatype`.
+
+### Reference (production) exchanges
+
+Any resource group can also carry an optional `reference_array`: a one-dimensional boolean array of the same length as `indices_array`. Where an element is `True`, that exchange is the **reference (production) exchange** for its activity/column.
+
+The five structural heuristics in `bw_graph_tools` (matching ids, single non-flipped entry, single positive, single negative, unique product) cannot always identify the reference exchange — whenever an activity has more than one same-sign exchange and the products also appear in other columns, the choice is genuinely ambiguous. Only the modeller knows the answer. `reference_array` records it directly so downstream tools can read it instead of guessing.
+
+```python
+import numpy as np
+from bw_processing import create_datapackage
+from bw_processing.constants import INDICES_DTYPE
+
+dp = create_datapackage()
+indices_array = np.array([(1, 4), (2, 5), (3, 6)], dtype=INDICES_DTYPE)
+data_array = np.array([1.0, 0.5, 2.0])
+reference_array = np.array([True, False, False])  # first exchange is the reference
+
+dp.add_persistent_vector(
+    matrix="technosphere",
+    name="my-process",
+    indices_array=indices_array,
+    data_array=data_array,
+    reference_array=reference_array,
+)
+```
+
+The stored resource has `kind="reference"` and can be retrieved via `dp.get_resource("my-process.reference")`. It must be a boolean array; passing a non-boolean array raises `WrongDatatype`. To keep the common case cheap, the resource is written only when at least one entry is `True` — a group with no reference flags carries no `reference` resource. Using the high-level `MatrixEntry`/`ArrayEntry` API, set `reference=True` (or a boolean `reference` array) on the entries you want flagged.
 
 ### Parameter arrays for sensitivity analysis
 

{bw_processing-1.5 → bw_processing-1.6}/src/bw_processing/__init__.py

@@ -35,7 +35,7 @@ __all__ = (
     "UndefinedInterface",
 )
 
-__version__ = "1.5"
+__version__ = "1.6"
 
 
 from bw_processing.array_creation import create_array, create_structured_array

{bw_processing-1.5 → bw_processing-1.6}/src/bw_processing/datapackage.py

@@ -512,6 +512,7 @@ class Datapackage(DatapackageBase):
             distributions_array,
             flip_array,
             rescale_array,
+            reference_array,
         ) = resolve_dict_iterator(dict_iterator, nrows)
         self.add_persistent_vector(
             matrix=matrix,
@@ -522,6 +523,7 @@ class Datapackage(DatapackageBase):
             flip_array=flip_array,
             distributions_array=distributions_array,
             rescale_array=rescale_array,
+            reference_array=reference_array,
             matrix_serialize_format_type=matrix_serialize_format_type,
             **kwargs,
         )
@@ -538,6 +540,8 @@ class Datapackage(DatapackageBase):
         High-level convenience method that does not require working directly
         with NumPy arrays. If any entry has a ``rescale`` value other than
         ``1.0``, the rescale values are stored as a ``rescale_array`` resource.
+        If any entry has ``reference=True``, the reference flags are stored as
+        a ``reference_array`` resource (``kind="reference"``).
 
         Args:
             matrix: Name of the target matrix (e.g. ``"technosphere"``).
@@ -562,6 +566,8 @@ class Datapackage(DatapackageBase):
         Each :class:`.ArrayEntry` becomes one persistent-array resource group.
         Resource group names are auto-generated. If an entry has a ``rescale``
         array it is stored as a ``rescale_array`` resource (``kind="rescale"``).
+        If an entry has a ``reference`` array with any ``True`` value it is
+        stored as a ``reference_array`` resource (``kind="reference"``).
 
         Args:
             matrix: Name of the target matrix (e.g. ``"technosphere"``).
@@ -577,6 +583,7 @@ class Datapackage(DatapackageBase):
                 data_array=entry.data,
                 flip_array=entry.flip,
                 rescale_array=entry.rescale,
+                reference_array=entry.reference,
             )
 
     def add_persistent_vector(
@@ -589,6 +596,7 @@ class Datapackage(DatapackageBase):
         flip_array: Optional[np.ndarray] = None,
         distributions_array: Optional[np.ndarray] = None,
         rescale_array: Optional[np.ndarray] = None,
+        reference_array: Optional[np.ndarray] = None,
         params_array: Optional[np.ndarray] = None,
         param_labels: Optional[list] = None,
         param_label_schema: Optional[AnyLabelSchema] = None,
@@ -605,6 +613,12 @@ class Datapackage(DatapackageBase):
         factors and unit conversions.  A value of ``1.0`` leaves the data
         unchanged.
 
+        ``reference_array`` is an optional 1-D boolean array of the same length
+        as ``indices_array``.  Where ``True``, that entry is the reference
+        (production) exchange for its column.  It is stored as a
+        ``reference_array`` resource (``kind="reference"``) only when at least
+        one entry is flagged.
+
         ``params_array`` is an optional 1-D float array recording the values of
         independent variables (e.g. model parameters) used to generate this
         resource group.  ``param_labels`` is an optional list of label objects
@@ -713,6 +727,15 @@ class Datapackage(DatapackageBase):
                 matrix_serialize_format_type=matrix_serialize_format_type,
                 **kwargs,
             )
+        if reference_array is not None:
+            self._add_reference_array_resource(
+                reference_array=reference_array,
+                indices_array=indices_array,
+                name=name,
+                keep_proxy=keep_proxy,
+                matrix_serialize_format_type=matrix_serialize_format_type,
+                **kwargs,
+            )
         if params_array is not None:
             params_array = load_bytes(params_array)
             if params_array.ndim != 1:
@@ -751,6 +774,7 @@ class Datapackage(DatapackageBase):
         name: Optional[str] = None,
         flip_array: Optional[np.ndarray] = None,
         rescale_array: Optional[np.ndarray] = None,
+        reference_array: Optional[np.ndarray] = None,
         params_array: Optional[np.ndarray] = None,
         param_labels: Optional[list] = None,
         param_label_schema: Optional[AnyLabelSchema] = None,
@@ -767,6 +791,12 @@ class Datapackage(DatapackageBase):
         factors and unit conversions.  A value of ``1.0`` leaves the data
         unchanged.
 
+        ``reference_array`` is an optional 1-D boolean array of the same length
+        as ``indices_array``.  Where ``True``, that entry is the reference
+        (production) exchange for its column.  It is stored as a
+        ``reference_array`` resource (``kind="reference"``) only when at least
+        one entry is flagged.
+
         ``params_array`` is an optional 2-D float array of shape
         ``(n_params, n_scenarios)`` where ``n_scenarios`` must equal
         ``data_array.shape[1]``.  It records the independent variable values
@@ -850,6 +880,15 @@ class Datapackage(DatapackageBase):
                 matrix_serialize_format_type=matrix_serialize_format_type,
                 **kwargs,
             )
+        if reference_array is not None:
+            self._add_reference_array_resource(
+                reference_array=reference_array,
+                indices_array=indices_array,
+                name=name,
+                keep_proxy=keep_proxy,
+                matrix_serialize_format_type=matrix_serialize_format_type,
+                **kwargs,
+            )
         if params_array is not None:
             params_array = load_bytes(params_array)
             if params_array.ndim != 2:
@@ -912,7 +951,7 @@ class Datapackage(DatapackageBase):
                     if kind == "indices":
                         meta_object = "vector"
                         meta_type = "indices"
-                    elif kind in ("flip", "rescale", "params"):
+                    elif kind in ("flip", "rescale", "reference", "params"):
                         meta_object = "vector"
                         meta_type = "generic"
                     elif kind == "distributions":
@@ -986,6 +1025,41 @@ class Datapackage(DatapackageBase):
             **kwargs,
         )
 
+    def _add_reference_array_resource(
+        self,
+        *,
+        reference_array: np.ndarray,
+        indices_array: np.ndarray,
+        name: str,
+        keep_proxy: bool,
+        matrix_serialize_format_type: Optional[MatrixSerializeFormat],
+        **kwargs,
+    ) -> None:
+        reference_array = load_bytes(reference_array)
+        if reference_array.dtype != bool:
+            raise WrongDatatype(
+                "`reference_array` dtype is {}, but must be `bool`".format(reference_array.dtype)
+            )
+        if reference_array.shape != indices_array.shape:
+            raise ShapeMismatch(
+                "`reference_array` shape ({}) doesn't match `indices_array` ({}).".format(
+                    reference_array.shape, indices_array.shape
+                )
+            )
+        # If no references flagged, don't need to store it
+        if reference_array.sum():
+            self._add_numpy_array_resource(
+                array=reference_array,
+                group=name,
+                name=name + ".reference",
+                kind="reference",
+                keep_proxy=keep_proxy,
+                matrix_serialize_format_type=matrix_serialize_format_type,
+                meta_object="vector",
+                meta_type="generic",
+                **kwargs,
+            )
+
     @staticmethod
     def _check_params_args(
         params_array: Optional[np.ndarray],
@@ -1133,6 +1207,7 @@ class Datapackage(DatapackageBase):
         name: Optional[str] = None,
         flip_array: Optional[np.ndarray] = None,  # Not interface
         rescale_array: Optional[np.ndarray] = None,  # Not interface
+        reference_array: Optional[np.ndarray] = None,  # Not interface
         params_array: Optional[np.ndarray] = None,  # Not interface
         param_labels: Optional[list] = None,
         param_label_schema: Optional[AnyLabelSchema] = None,
@@ -1147,7 +1222,7 @@ class Datapackage(DatapackageBase):
         1-D numpy array of length ``len(indices_array)`` each time it is called.
 
         The ``indices_array``, optional ``flip_array``, optional ``rescale_array``,
-        and optional ``params_array`` are static and are stored as normal numpy
+        optional ``reference_array``, and optional ``params_array`` are static and are stored as normal numpy
         resources.  See ``add_persistent_vector`` for documentation of the
         ``params_array``, ``param_labels``, and ``param_label_schema`` arguments.
 
@@ -1162,6 +1237,8 @@ class Datapackage(DatapackageBase):
                 multiplied by ``-1`` before insertion.
             rescale_array: Optional 1-D float array of multiplicative factors
                 applied before matrix insertion.
+            reference_array: Optional 1-D boolean array; where ``True`` the
+                entry is the reference (production) exchange for its column.
             keep_proxy: If ``True``, store a proxy rather than the raw array
                 for on-disk resources.
             matrix_serialize_format_type: Override the instance-level
@@ -1219,6 +1296,15 @@ class Datapackage(DatapackageBase):
                 matrix_serialize_format_type=matrix_serialize_format_type,
                 **kwargs,
             )
+        if reference_array is not None:
+            self._add_reference_array_resource(
+                reference_array=reference_array,
+                indices_array=indices_array,
+                name=name,
+                keep_proxy=keep_proxy,
+                matrix_serialize_format_type=matrix_serialize_format_type,
+                **kwargs,
+            )
         if params_array is not None:
             params_array = load_bytes(params_array)
             if params_array.ndim != 1:
@@ -1267,6 +1353,7 @@ class Datapackage(DatapackageBase):
         name: Optional[str] = None,
         flip_array: Optional[np.ndarray] = None,
         rescale_array: Optional[np.ndarray] = None,  # Not interface
+        reference_array: Optional[np.ndarray] = None,  # Not interface
         params_array: Optional[np.ndarray] = None,  # Not interface
         param_labels: Optional[list] = None,
         param_label_schema: Optional[AnyLabelSchema] = None,
@@ -1283,7 +1370,7 @@ class Datapackage(DatapackageBase):
         interface.
 
         The ``indices_array``, optional ``flip_array``, optional ``rescale_array``,
-        and optional ``params_array`` are static and are stored as normal numpy
+        optional ``reference_array``, and optional ``params_array`` are static and are stored as normal numpy
         resources.  For dynamic arrays the column count of ``params_array`` is
         not validated against the interface (whose column count may be unknown at
         write time).  See ``add_persistent_vector`` for documentation of the
@@ -1300,6 +1387,8 @@ class Datapackage(DatapackageBase):
                 multiplied by ``-1`` before insertion.
             rescale_array: Optional 1-D float array of multiplicative factors
                 applied before matrix insertion.
+            reference_array: Optional 1-D boolean array; where ``True`` the
+                entry is the reference (production) exchange for its column.
             keep_proxy: If ``True``, store a proxy rather than the raw array
                 for on-disk resources.
             matrix_serialize_format_type: Override the instance-level
@@ -1365,6 +1454,15 @@ class Datapackage(DatapackageBase):
                 matrix_serialize_format_type=matrix_serialize_format_type,
                 **kwargs,
             )
+        if reference_array is not None:
+            self._add_reference_array_resource(
+                reference_array=reference_array,
+                indices_array=indices_array,
+                name=name,
+                keep_proxy=keep_proxy,
+                matrix_serialize_format_type=matrix_serialize_format_type,
+                **kwargs,
+            )
         if params_array is not None:
             params_array = load_bytes(params_array)
             if params_array.ndim != 2:

{bw_processing-1.5 → bw_processing-1.6}/src/bw_processing/matrix_entry.py

@@ -63,6 +63,12 @@ class MatrixEntry:
             Stored as a ``rescale_array`` resource (``kind="rescale"``). Note
             that the Python ``float`` value is downcast to ``numpy.float32``
             when written to the structured array.
+        reference: If True, this exchange is the reference (production) exchange
+            for its activity/column. Consumers such as bw_graph_tools use this
+            to identify production exchanges directly instead of guessing from
+            matrix structure. Stored as a ``reference_array`` resource
+            (``kind="reference"``) only when at least one entry is flagged;
+            defaults to False.
     """
 
     row: int
@@ -77,6 +83,7 @@ class MatrixEntry:
     maximum: float = math.nan
     negative: bool = False
     rescale: float = 1.0
+    reference: bool = False
 
     def __post_init__(self):
         if self.uncertainty_type in _NO_UNCERTAINTY_IDS:
@@ -109,6 +116,10 @@ class ArrayEntry:
         rescale: Optional 1-D float array of per-entry multiplicative factors
             (one per row). ``1.0`` leaves the value unchanged. Stored as a
             ``rescale_array`` resource (``kind="rescale"``).
+        reference: Optional 1-D boolean sequence of length ``n_entries``.
+            Where True, that entry is the reference (production) exchange for
+            its column. Stored as a ``reference_array`` resource
+            (``kind="reference"``) only when at least one entry is flagged.
     """
 
     rows: np.ndarray
@@ -116,6 +127,7 @@ class ArrayEntry:
     data: np.ndarray
     flip: Optional[np.ndarray] = None
     rescale: Optional[np.ndarray] = None
+    reference: Optional[np.ndarray] = None
 
     def __post_init__(self):
         self.rows = np.asarray(self.rows)
@@ -150,6 +162,12 @@ class ArrayEntry:
                 raise ValueError(
                     f"`rescale` shape {self.rescale.shape} doesn't match `rows` shape {self.rows.shape}"
                 )
+        if self.reference is not None:
+            self.reference = np.asarray(self.reference, dtype=bool)
+            if self.reference.shape != self.rows.shape:
+                raise ValueError(
+                    f"`reference` shape {self.reference.shape} doesn't match `rows` shape {self.rows.shape}"
+                )
 
 
 def create_datapackage_from_entries(

{bw_processing-1.5 → bw_processing-1.6}/src/bw_processing/merging.py

@@ -53,7 +53,7 @@ def add_resource_suffix(metadata: dict, suffix: str) -> dict:
     last = metadata["name"].split(".")[-1]
     rest = metadata["name"][: -len(last) - 1]
 
-    if last not in {"indices", "data", "distributions", "flip"}:
+    if last not in {"indices", "data", "distributions", "flip", "rescale", "reference"}:
         raise ValueError("Can't understand resource name suffix")
 
     rest = metadata["name"][: -len(last) - 1]

{bw_processing-1.5 → bw_processing-1.6}/src/bw_processing/utils.py

@@ -65,6 +65,7 @@ def dictionary_formatter(row: dict) -> tuple:
         row.get("negative", False),
         row.get("flip", False),
         row.get("rescale", 1.0),
+        row.get("reference", False),
     )
 
 
@@ -74,13 +75,18 @@ def resolve_dict_iterator(iterator: Any, nrows: int = None) -> tuple:
     data = (dictionary_formatter(row) for row in iterator)
     array = create_structured_array(
         data,
-        INDICES_DTYPE + [("amount", np.float32)] + UNCERTAINTY_DTYPE + [("flip", bool), ("rescale", np.float32)],
+        INDICES_DTYPE
+        + [("amount", np.float32)]
+        + UNCERTAINTY_DTYPE
+        + [("flip", bool), ("rescale", np.float32), ("reference", bool)],
         nrows=nrows,
         sort=True,
         sort_fields=sort_fields,
     )
     rescale = array["rescale"]
     rescale_array = rescale if (rescale != 1.0).any() else None
+    reference = array["reference"]
+    reference_array = reference if reference.any() else None
     return (
         array["amount"],
         # Not repacking fields would cause this multi-field index to return a view
@@ -102,6 +108,7 @@ def resolve_dict_iterator(iterator: Any, nrows: int = None) -> tuple:
         ),
         array["flip"],
         rescale_array,
+        reference_array,
     )
 
 

{bw_processing-1.5 → bw_processing-1.6/src/bw_processing.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bw_processing
-Version: 1.5
+Version: 1.6
 Summary: Foo
 Author-email: Chris Mutel <cmutel@gmail.com>
 Maintainer-email: Chris Mutel <cmutel@gmail.com>
@@ -211,12 +211,12 @@ print(data_obj.url)
 
 ### Scale arrays
 
-Any resource group (persistent or dynamic, vector or array) can carry an optional `scale_array`: a one-dimensional float array of the same length as `indices_array`. Each element is a multiplicative factor applied to the corresponding data value before it is inserted into the matrix. The factor is applied to both static and stochastically-sampled values. A value of `1.0` leaves the data unchanged.
+Any resource group (persistent or dynamic, vector or array) can carry an optional `rescale_array`: a one-dimensional float array of the same length as `indices_array`. Each element is a multiplicative factor applied to the corresponding data value before it is inserted into the matrix. The factor is applied to both static and stochastically-sampled values. A value of `1.0` leaves the data unchanged.
 
 Typical use cases:
 
-* **Allocation factors** — when a process produces multiple products, the exchange amounts must be partitioned between them. Storing the allocation coefficients as a `scale_array` keeps them alongside the data they modify without requiring a separate processing step.
-* **Unit conversions** — when source data is expressed in a unit that differs from the matrix convention, a constant conversion factor can be stored as a `scale_array` rather than baked into every data value.
+* **Allocation factors** — when a process produces multiple products, the exchange amounts must be partitioned between them. Storing the allocation coefficients as a `rescale_array` keeps them alongside the data they modify without requiring a separate processing step.
+* **Unit conversions** — when source data is expressed in a unit that differs from the matrix convention, a constant conversion factor can be stored as a `rescale_array` rather than baked into every data value.
 
 ```python
 import numpy as np
@@ -226,18 +226,45 @@ from bw_processing.constants import INDICES_DTYPE
 dp = create_datapackage()
 indices_array = np.array([(1, 4), (2, 5), (3, 6)], dtype=INDICES_DTYPE)
 data_array = np.array([100.0, 200.0, 300.0])
-scale_array = np.array([0.6, 1.0, 0.4])  # e.g. allocation factors
+rescale_array = np.array([0.6, 1.0, 0.4])  # e.g. allocation factors
 
 dp.add_persistent_vector(
     matrix="technosphere",
     name="my-process",
     indices_array=indices_array,
     data_array=data_array,
-    scale_array=scale_array,
+    rescale_array=rescale_array,
 )
 ```
 
-The stored resource has `kind="scale"` and can be retrieved via `dp.get_resource("my-process.scale")`. The `scale_array` must be a float dtype (`float32` or `float64`); passing an integer array raises `WrongDatatype`.
+The stored resource has `kind="rescale"` and can be retrieved via `dp.get_resource("my-process.rescale")`. The `rescale_array` must be a float dtype (`float32` or `float64`); passing an integer array raises `WrongDatatype`.
+
+### Reference (production) exchanges
+
+Any resource group can also carry an optional `reference_array`: a one-dimensional boolean array of the same length as `indices_array`. Where an element is `True`, that exchange is the **reference (production) exchange** for its activity/column.
+
+The five structural heuristics in `bw_graph_tools` (matching ids, single non-flipped entry, single positive, single negative, unique product) cannot always identify the reference exchange — whenever an activity has more than one same-sign exchange and the products also appear in other columns, the choice is genuinely ambiguous. Only the modeller knows the answer. `reference_array` records it directly so downstream tools can read it instead of guessing.
+
+```python
+import numpy as np
+from bw_processing import create_datapackage
+from bw_processing.constants import INDICES_DTYPE
+
+dp = create_datapackage()
+indices_array = np.array([(1, 4), (2, 5), (3, 6)], dtype=INDICES_DTYPE)
+data_array = np.array([1.0, 0.5, 2.0])
+reference_array = np.array([True, False, False])  # first exchange is the reference
+
+dp.add_persistent_vector(
+    matrix="technosphere",
+    name="my-process",
+    indices_array=indices_array,
+    data_array=data_array,
+    reference_array=reference_array,
+)
+```
+
+The stored resource has `kind="reference"` and can be retrieved via `dp.get_resource("my-process.reference")`. It must be a boolean array; passing a non-boolean array raises `WrongDatatype`. To keep the common case cheap, the resource is written only when at least one entry is `True` — a group with no reference flags carries no `reference` resource. Using the high-level `MatrixEntry`/`ArrayEntry` API, set `reference=True` (or a boolean `reference` array) on the entries you want flagged.
 
 ### Parameter arrays for sensitivity analysis
 

{bw_processing-1.5 → bw_processing-1.6}/tests/test_datapackage.py

@@ -947,3 +947,101 @@ def test_zipfile_compressed_roundtrip(tmp_path):
     dp = load_datapackage(ZipFileSystem(str(zip_path)))
     data, _ = dp.get_resource("sa-data-vector.data")
     assert np.allclose(data, [2, 7, 12])
+
+
+REFERENCE_INDICES = np.array([(1, 4), (2, 5), (3, 6)], dtype=INDICES_DTYPE)
+
+
+def test_reference_array_stored():
+    dp = create_datapackage()
+    dp.add_persistent_vector(
+        matrix="sa_matrix",
+        data_array=np.array([2, 7, 12]),
+        name="sa-ref",
+        indices_array=REFERENCE_INDICES,
+        reference_array=np.array([True, False, False], dtype=bool),
+    )
+    data, _ = dp.get_resource("sa-ref.reference")
+    assert data.dtype == bool
+    assert list(data) == [True, False, False]
+
+
+def test_reference_array_not_stored_when_all_false():
+    dp = create_datapackage()
+    dp.add_persistent_vector(
+        matrix="sa_matrix",
+        data_array=np.array([2, 7, 12]),
+        name="sa-ref",
+        indices_array=REFERENCE_INDICES,
+        reference_array=np.array([False, False, False], dtype=bool),
+    )
+    assert "sa-ref.reference" not in [r["name"] for r in dp.resources]
+
+
+def test_reference_array_wrong_dtype():
+    dp = create_datapackage()
+    with pytest.raises(WrongDatatype):
+        dp.add_persistent_vector(
+            matrix="sa_matrix",
+            data_array=np.array([2, 7, 12]),
+            name="sa-ref",
+            indices_array=REFERENCE_INDICES,
+            reference_array=np.array([1, 0, 0], dtype=int),
+        )
+
+
+def test_reference_array_shape_mismatch():
+    dp = create_datapackage()
+    with pytest.raises(ShapeMismatch):
+        dp.add_persistent_vector(
+            matrix="sa_matrix",
+            data_array=np.array([2, 7, 12]),
+            name="sa-ref",
+            indices_array=REFERENCE_INDICES,
+            reference_array=np.array([True, False], dtype=bool),
+        )
+
+
+def test_reference_array_persistent_array():
+    dp = create_datapackage()
+    dp.add_persistent_array(
+        matrix="sa_matrix",
+        data_array=np.arange(12).reshape((3, 4)),
+        name="sa-ref-arr",
+        indices_array=REFERENCE_INDICES,
+        reference_array=np.array([False, True, False], dtype=bool),
+    )
+    data, _ = dp.get_resource("sa-ref-arr.reference")
+    assert list(data) == [False, True, False]
+
+
+def test_reference_array_dynamic_vector():
+    dp = create_datapackage()
+    dp.add_dynamic_vector(
+        interface=Dummy(),
+        matrix="sa_matrix",
+        name="sa-ref-dyn",
+        indices_array=REFERENCE_INDICES,
+        reference_array=np.array([False, False, True], dtype=bool),
+    )
+    data, _ = dp.get_resource("sa-ref-dyn.reference")
+    assert list(data) == [False, False, True]
+
+
+def test_reference_array_roundtrip(tmp_path):
+    fs = generic_zipfile_filesystem(dirpath=tmp_path, filename="ref.zip")
+    dp = create_datapackage(fs=fs, name="test-reference")
+    dp.add_persistent_vector(
+        matrix="sa_matrix",
+        data_array=np.array([2, 7, 12]),
+        name="sa-ref",
+        indices_array=REFERENCE_INDICES,
+        reference_array=np.array([True, False, True], dtype=bool),
+    )
+    dp.finalize_serialization()
+
+    loaded = load_datapackage(ZipFileSystem(str(tmp_path / "ref.zip")))
+    data, resource = loaded.get_resource("sa-ref.reference")
+    assert resource["kind"] == "reference"
+    assert data.dtype == bool
+    assert list(data) == [True, False, True]

{bw_processing-1.5 → bw_processing-1.6}/tests/test_matrix_entry.py

@@ -59,6 +59,18 @@ class TestMatrixEntry:
         e = MatrixEntry(row=1, col=2, amount=3.0, rescale=2.0)
         assert e.as_dict()["rescale"] == pytest.approx(2.0)
 
+    def test_reference_default_is_false(self):
+        e = MatrixEntry(row=1, col=2, amount=3.0)
+        assert e.reference is False
+
+    def test_reference_custom_value(self):
+        e = MatrixEntry(row=1, col=2, amount=3.0, reference=True)
+        assert e.reference is True
+
+    def test_reference_in_as_dict(self):
+        e = MatrixEntry(row=1, col=2, amount=3.0, reference=True)
+        assert e.as_dict()["reference"] is True
+
     def test_loc_set_to_amount_for_no_uncertainty(self):
         e = MatrixEntry(row=1, col=2, amount=5.0)
         assert e.loc == pytest.approx(5.0)
@@ -90,7 +102,7 @@ class TestMatrixEntry:
         assert set(d.keys()) == {
             "row", "col", "amount", "flip", "uncertainty_type",
             "loc", "scale", "shape", "minimum", "maximum", "negative",
-            "rescale",
+            "rescale", "reference",
         }
 
     def test_as_dict_values(self):
@@ -251,6 +263,19 @@ class TestArrayEntry:
         with pytest.raises(ValueError, match="rescale.*rows"):
             ArrayEntry(rows=[0, 1], cols=[2, 3], data=np.ones((2, 4)), rescale=[1.0, 2.0, 3.0])
 
+    def test_reference_default_is_none(self):
+        e = ArrayEntry(rows=[0, 1], cols=[2, 3], data=np.ones((2, 4)))
+        assert e.reference is None
+
+    def test_reference_coerced_to_bool(self):
+        e = ArrayEntry(rows=[0, 1], cols=[2, 3], data=np.ones((2, 4)), reference=[1, 0])
+        assert e.reference.dtype == bool
+        assert list(e.reference) == [True, False]
+
+    def test_reference_shape_mismatch(self):
+        with pytest.raises(ValueError, match="reference.*rows"):
+            ArrayEntry(rows=[0, 1], cols=[2, 3], data=np.ones((2, 4)), reference=[True, False, True])
+
 
 class TestAddArrayEntries:
     def test_single_entry(self):
@@ -325,6 +350,32 @@ class TestAddArrayEntries:
         stored = dp.data[dp.resources.index(rescale_resource)]
         np.testing.assert_array_almost_equal(stored, [2.0, 0.5])
 
+    def test_reference_stored_correctly(self):
+        dp = create_datapackage()
+        entry = ArrayEntry(rows=[0, 1], cols=[2, 3], data=np.ones((2, 3)), reference=[True, False])
+        dp.add_array_entries(matrix="technosphere_matrix", entries=[entry])
+        group = next(iter(dp.groups.values()))
+        reference_resource = next(r for r in group.resources if r["kind"] == "reference")
+        stored = dp.data[dp.resources.index(reference_resource)]
+        assert stored.dtype == bool
+        assert list(stored) == [True, False]
+
+    def test_no_reference_resource_when_reference_is_none(self):
+        dp = create_datapackage()
+        entry = ArrayEntry(rows=[0, 1], cols=[2, 3], data=np.ones((2, 3)))
+        dp.add_array_entries(matrix="technosphere_matrix", entries=[entry])
+        group = next(iter(dp.groups.values()))
+        kinds = [r["kind"] for r in group.resources]
+        assert "reference" not in kinds
+
+    def test_no_reference_resource_when_all_false(self):
+        dp = create_datapackage()
+        entry = ArrayEntry(rows=[0, 1], cols=[2, 3], data=np.ones((2, 3)), reference=[False, False])
+        dp.add_array_entries(matrix="technosphere_matrix", entries=[entry])
+        group = next(iter(dp.groups.values()))
+        kinds = [r["kind"] for r in group.resources]
+        assert "reference" not in kinds
+
 
 class TestAddEntries:
     def test_no_rescale_resource_when_all_rescale_one(self):
@@ -388,6 +439,49 @@ class TestAddEntries:
             else:
                 assert rescales[i] == pytest.approx(2.0)
 
+    def test_no_reference_resource_when_no_references(self):
+        dp = create_datapackage()
+        entries = [
+            MatrixEntry(row=1, col=2, amount=1.0),
+            MatrixEntry(row=3, col=4, amount=2.0),
+        ]
+        dp.add_entries(matrix="technosphere_matrix", entries=entries)
+        group = next(iter(dp.groups.values()))
+        kinds = [r["kind"] for r in group.resources]
+        assert "reference" not in kinds
+
+    def test_reference_resource_stored_when_set(self):
+        dp = create_datapackage()
+        entries = [
+            MatrixEntry(row=1, col=2, amount=1.0, reference=True),
+            MatrixEntry(row=3, col=4, amount=2.0, reference=True),
+        ]
+        dp.add_entries(matrix="technosphere_matrix", entries=entries)
+        group = next(iter(dp.groups.values()))
+        reference_resource = next(r for r in group.resources if r["kind"] == "reference")
+        stored = dp.data[dp.resources.index(reference_resource)]
+        assert stored.dtype == bool
+        assert list(stored) == [True, True]
+
+    def test_reference_aligned_with_data_when_sorted(self):
+        # add_entries sorts by (row, col); reference flags must follow the same order
+        dp = create_datapackage()
+        entries = [
+            MatrixEntry(row=3, col=4, amount=2.0, reference=False),
+            MatrixEntry(row=1, col=2, amount=1.0, reference=True),
+        ]
+        dp.add_entries(matrix="technosphere_matrix", entries=entries)
+        group = next(iter(dp.groups.values()))
+        idx_resource = next(r for r in group.resources if r["kind"] == "indices")
+        reference_resource = next(r for r in group.resources if r["kind"] == "reference")
+        indices = dp.data[dp.resources.index(idx_resource)]
+        references = dp.data[dp.resources.index(reference_resource)]
+        for i, idx in enumerate(indices):
+            if idx["row"] == 1:
+                assert references[i] == np.bool_(True)
+            else:
+                assert references[i] == np.bool_(False)
+
 
 class TestSimpleGraphDeprecation:
     def test_deprecation_warning(self):

{bw_processing-1.5 → bw_processing-1.6}/tests/test_utils.py

@@ -37,7 +37,7 @@ def test_dictionary_formatter_sparse():
     result = dictionary_formatter(given)
     assert result[:5] == (1, 1, 4, 0, 4)
     assert all(np.isnan(x) for x in result[5:9])
-    assert result[9:] == (False, False, 1.0)
+    assert result[9:] == (False, False, 1.0, False)
 
 
 def test_dictionary_formatter_uncertainty_type():
@@ -68,7 +68,7 @@ def test_dictionary_formatter_complete():
         "negative": True,
         "flip": False,
     }
-    expected = (1, 2, 3, 4, 5, 6, 7, 8, 9, True, False, 1.0)
+    expected = (1, 2, 3, 4, 5, 6, 7, 8, 9, True, False, 1.0, False)
     assert dictionary_formatter(given) == expected
 
 
@@ -85,20 +85,32 @@ def test_dictionary_formatter_one_dimensional():
         "negative": True,
         "flip": False,
     }
-    expected = (1, 1, 3, 4, 5, 6, 7, 8, 9, True, False, 1.0)
+    expected = (1, 1, 3, 4, 5, 6, 7, 8, 9, True, False, 1.0, False)
     assert dictionary_formatter(given) == expected
 
 
 def test_dictionary_formatter_rescale():
     given = {"row": 1, "col": 2, "amount": 3.0, "rescale": 0.5}
     result = dictionary_formatter(given)
-    assert result[-1] == 0.5
+    assert result[-2] == 0.5
 
 
 def test_dictionary_formatter_rescale_default():
     given = {"row": 1, "amount": 4}
     result = dictionary_formatter(given)
-    assert result[-1] == 1.0
+    assert result[-2] == 1.0
+
+
+def test_dictionary_formatter_reference():
+    given = {"row": 1, "col": 2, "amount": 3.0, "reference": True}
+    result = dictionary_formatter(given)
+    assert result[-1] is True
+
+
+def test_dictionary_formatter_reference_default():
+    given = {"row": 1, "amount": 4}
+    result = dictionary_formatter(given)
+    assert result[-1] is False
 
 
 def test_check_suffix():