Nomenclature and Custom LCIA Method Format

Users can create and load their own LCIA methods into edges using a JSON file format. This format defines characterization factors (CFs) between suppliers (flows) and consumers (activities), supporting regionalized, parameterized, and dynamic impact assessments.

File Structure

A custom LCIA method JSON file is structured as follows:

{
  "name": "Method name",
  "version": "1.0",
  "unit": "unit of the impact score",
  "description": "optional text",
  "exchanges": [ ... list of CFs ... ]
}

Each exchange defines a characterization factor applied to a flow from a supplier (typically a biosphere flow or technosphere process) to a consumer (typically a technosphere process).

Exchange Structure

Each item in the exchanges list is a dictionary with:

  • supplier: Criteria to match the source flow

  • consumer: Criteria to match the target activity

  • value: The CF value (numeric or expression)

  • weight: Optional numeric weight (used in regional aggregation)

Supplier Fields

The supplier block may contain:

  • name (str): Name of the flow or activity (can use matching operators)

  • reference product (str): For technosphere flows, specifies the product output

  • categories (list): List of categories for biosphere flows

  • location (str): ISO country code or region

  • matrix (str): Required; either biosphere or technosphere

  • operator (str): Optional; one of:

    • equals (default)

    • startswith

    • contains

  • excludes (list of str): Optional; substrings that disqualify a match

Consumer Fields

The consumer block may include:

  • location (str): ISO code or region name

  • classifications (dict): Classification codes, e.g., CPC sector codes:

    "classifications": {
    "CPC": ["01", "011"]
}

  • type (str): Optional type hint for matching, e.g., process

  • matrix (str): Required; should be technosphere

Value Field

The value field can be:

  • A numeric value (float or int):

    "value": 1.3204

  • A string expression using parameters:

    "value": "28 * (1 + 0.001 * (co2ppm - 410))"

  • A function call (if supported by the runtime):

    "value": "GWP('CH4', H, C_CH4)"

    These can refer to dynamic variables or scenario-dependent parameters defined in the LCIA model context. Function calls must use a bare function name that is explicitly available to the evaluator, for example through allowed_functions.

String expressions are intentionally limited to arithmetic, parameter names, literal numbers/strings/lists/tuples, and bare allowlisted function calls. Object attribute access, subscripting, comprehensions, lambdas, imports, and method calls are rejected. Python callables passed through allowed_functions are trusted code; the expression sandbox restricts the method expression, not the implementation of those callables.

Weight Field

The optional weight field is used when multiple CFs are available for a supplier-consumer pair (e.g., in regionalized methods). Weights are normalized and used to compute a weighted average.

Matching Logic

Matching is performed between exchange definitions and actual flows/activities in the LCI database. Matching criteria include:

  • Exact or pattern-based name/reference matching (equals, startswith, contains)

  • Location matching with fallback to broader regions (e.g., from IT to RER to GLO)

  • Classification matching (e.g., CPC sectors)

  • Optional excludes for disqualifying candidates

Advanced Features

Parameterized Values

Values can include parameters such as co2ppm, year, or scenario-specific variables. These are evaluated at runtime using the current parameter values.

"value": "265 * (1 + 0.0005 * (co2ppm - 410))"

Classification Matching

Classifications are matched hierarchically. For example, if the CF uses:

"classifications": {
    "CPC": ["01"]
}

Then it will match any activity whose CPC classification starts with 01, such as 0111.

Geographic Disaggregation

If location-specific CFs are provided, the method supports regionalized impact assessment. Missing regions can fall back to broader aggregates:

  • IT → RER → GLO

Multiple CFs with overlapping geographic scopes can be combined using their weight field.

Examples

Minimal Example

{
  "name": "My LCIA Method",
  "version": "1.0",
  "unit": "kg CO2e",
  "exchanges": [
    {
      "supplier": {
        "name": "Carbon dioxide",
        "matrix": "biosphere"
      },
      "consumer": {
        "matrix": "technosphere"
      },
      "value": 1.0
    }
  ]
}

Region-Specific Example

{
  "supplier": {
    "name": "Carbon dioxide",
    "matrix": "biosphere"
  },
  "consumer": {
    "location": "FR",
    "matrix": "technosphere"
  },
  "value": 2.0
}

Dynamic Expression Example

{
  "supplier": {
    "name": "Methane, fossil",
    "operator": "contains",
    "matrix": "biosphere"
  },
  "consumer": {
    "matrix": "technosphere"
  },
  "value": "28 * (1 + 0.001 * (co2ppm - 410))"
}

Country Pair Example

{
  "supplier": {
    "name": "aluminium production, primary",
    "reference product": "aluminium, primary",
    "location": "AL",
    "matrix": "technosphere",
    "operator": "startswith",
    "excludes": ["alloy", "market"]
  },
  "consumer": {
    "location": "GB",
    "matrix": "technosphere"
  },
  "value": 5.66e-08,
  "weight": 0.0038
}

Saving and Loading

Save your custom LCIA method as a JSON file (e.g., my_method.json), then load it into edges using:

from edges import EdgeLCIA
lcia = EdgeLCIA.from_file("my_method.json")

Make sure all required fields (name, unit, version, exchanges) are present and correctly formatted.

—

This page can grow with more examples, including tips for debugging mismatches or visualizing the CF structure. Let me know if you’d like to include YAML support or template generators.