Skip to content

Flow Rule-Based Mapping

Overview

Write rules that find flows across the dataset and replace them with other flows. Each mapping has a name, notes and one or more rules that say how to match source flows and which target flows replace them.

The editor contains two tabs, listed at the bottom of the editor:

  • General Information: set the mapping name, notes and rules.
  • Mappings: review the results of the rules, and apply them.

To open the editor, select a mapping in the Flow Rule-Based Mapping folder of the Data Processing navigation panel, or select the + button of that folder to create a new one.

Note

You write the rules of a rule-based mapping. To let an AI-assisted service propose the replacements instead, see Flow AI-Assisted Mapping.


Workflow

  1. Select the + button of the Flow Rule-Based Mapping folder. A new mapping opens with a default name.
  2. Enter a Name and Notes in the General Information tab.
  3. Expand the Rules section and select its + button to add each rule. Fill in the columns of every rule.
  4. Select Save.
  5. Select the green Map button in the Rules header. PyGREET switches to the Mappings tab and lists every replacement the rules would make.
  6. Remove any row you do not want to apply.
  7. Select the green Apply Mapping button to apply the remaining rows to the dataset.
  8. Save the dataset with the Save button at the bottom of the navigation panel to keep the result. See Save or Discard Changes.

General Information

The General Information tab of the Flow Rule-Based Mapping editor with two rules
Figure 1: The General Information tab of the Flow Rule-Based Mapping editor with two rules

Name and Notes

  • Name: a label for the rule set. You need a name to save the mapping.
  • Notes: free text for the purpose or context of the mapping. Detailed notes are recommended.

Info

The Has been applied? checkbox shows whether the rule set has been applied to the dataset. It is read-only. PyGREET selects it after you apply the mapping. An applied mapping contains only the matches found when you applied it. It does not search for matches added to the dataset afterward.

Important

You cannot save an applied mapping again: the Save button is disabled. To reuse its rules, edit them and select Save as New, which creates a new mapping that has not been applied.


Rules

The Rules section holds the matching rules of the mapping. You need at least one rule to save the mapping. The section is collapsed for a new mapping, so select its header to expand it.

  • Select the + button next to the section title to add a rule. New rules appear at the top of the table.
  • Select the x next to a rule's Criteria to delete that rule.
  • Hover over the i icon in the section header to read how to enter synonyms (see Synonyms).

Each rule consists of the following columns:

Criteria

Criteria sets how PyGREET identifies the source flow. The options are:

Criteria Description
Flow Matches one flow that you select from the dataset in a list
Exact Match Matches flows whose name is exactly equal to the source text
Partial Match Matches flows whose name contains the source text as a substring

Note

Exact Match and Partial Match do not distinguish between uppercase and lowercase letters.

Source Flow / Matching Text

The value used to identify flows to be replaced:

  • When Criteria is Flow, this field is a list where you select one dataset flow.
  • When Criteria is Exact Match or Partial Match, this is a free-text field for the text to search for.
  • Until you select a criteria, the field shows Select criteria first.
Synonyms

When Exact Match or Partial Match is selected, several texts can be entered in the same field, separated by |. A flow matches the rule if it matches any of them. For example:

carbon dioxide | dioxide, carbon | carbon dioxide; at plant

Scope

Scope sets how much of the dataset PyGREET searches:

Scope Description
General Applies the rule across the entire dataset
Specific Import Restricts the rule to a particular external import

External Import

Select the external import to restrict the rule to. This field is enabled only when Scope is Specific Import.

Note

This field is disabled (shown as N/A) when Scope is General.

Level

Level restricts matching to one section of an editor. The options are:

Level Description
General Applies across all levels
Main Outputs Targets the main outputs section of a Stationary Process
Coproducts Targets the coproducts section of a Stationary Process
Inputs Targets the inputs section of a Stationary Process
Non-Combustion Emissions & Wastes Targets the non-combustion emissions and wastes section of a Stationary Process
Impact Factors Targets impact factors defined in the Impact Categories Editor

Target Flow

The dataset flow that replaces every matched source flow. Select it from a list, and start typing to filter the list.

Note

When Criteria is Flow, the flow selected as the source is not offered in the Target Flow list.


Saving the Mapping

The Save as New and Save buttons, and the tabs of the editor
Figure 2: The Save as New and Save buttons, and the tabs of the editor

  • Save keeps the mapping in the working copy of the dataset. It is enabled after an edit, and disabled if the mapping has been applied.
  • Save as New keeps the current content as a new mapping, with Has been applied? cleared. It is enabled after an edit.
  • An orange dot on the tab of the mapping marks unsaved changes. When you close the tab, this window opens:

The unsaved changes window
Figure 3: The unsaved changes window

Important

While a mapping has unsaved edits, the Map button and the Mappings tab are disabled. Save the mapping first. Selecting Map on a mapping that has never been saved shows the message Please save the flow mapping before executing mappings.


Mappings

The Mappings tab lists the results of the rules: every match found and the replacement that PyGREET will apply (or has applied). It fills when you select the green Map button in the Rules header, and its title shows the number of results in parentheses, as in Mapping Results.

Before you run a mapping, the tab shows only the message No Mapping Results Yet.

The results appear in a table with these columns:

Column Description
Source Flow The flow found in the dataset that matched a rule
Target Flow The flow that replaces the matched source flow
Source Unit The unit of the source flow
Target Unit The unit of the target flow
Conversion Factor The factor used to convert from the source unit to the target unit
Type The level where the match was found (for example, Non-Combustion Emission & Wastes, Product, Input)
Parent The entity in the library that contains the matched flow (for example, the process or technology name)
Source The library or dataset that the parent entity belongs to (for example, GREET, U.S. Federal LCA Commons)

The Mappings tab with 20 results that replace Carbon Dioxide with CO2, each with source and target unit and a conversion factor of 1
Figure 4: The Mappings tab with 20 results that replace Carbon Dioxide with CO2, each with source and target unit and a conversion factor of 1

Note

A unit or factor that does not apply is displayed as -.

Working with the table:

  • Select a column title to sort by it.
  • The Source Flow, Target Flow and Parent names are links. Select one to open that flow, process or impact category in the Library.
  • The table is paginated. The number of rows per page can be 10, 15, 20, 30, 40 or 50, and defaults to 20.
  • Select the x button at the right of a row to exclude that match from the mapping. PyGREET does not keep the removal: when you open the tab again, it lists all matches again.

Note

Apply Mapping skips the rows you removed from the table. It applies only the remaining rows.

Guardrails

When the table has results, select the i icon above the table to see the guardrails PyGREET applies when it replaces flows:

  • Matches you removed are not applied.
  • Inputs from wells are not replaced with non-elementary flows.
  • Emissions and wastes are not replaced with non-elementary flows.
  • Flow ID and Exact Match rules keep the source unit with a conversion factor of 1.
  • Partial Match rules convert to the target flow's preferred unit.
  • Substitutions where no unit conversion can be established between source and target are excluded.

Applying the Mapping

Select the green Apply Mapping button above the table to replace the listed flows in the dataset. When the replacement finishes, PyGREET reloads the library elements and shows the message Mapping applied and library elements reloaded successfully.

After a mapping is applied:

  • Has been applied? is checked in the General Information tab.
  • Apply Mapping is disabled and the x buttons disappear from the table.
  • The dataset has unsaved changes. Select Save at the bottom of the navigation panel to keep them, or Discard to return to the last saved dataset.

Important

Applying a mapping rewrites flows in the working copy of the dataset. Review the results before you apply, and see Save or Discard Changes to understand how to keep or undo the change.