Single score

An impact assessment answers with one number per category: so much climate change, so much land use, so much water. A single score combines them into one figure, by normalizing each category against a reference and weighting what is left.

VoLCA does not have a single score built in. You describe the one you want in the method collection that carries the categories, and the engine computes it alongside them. That is what [[methods.scoring]] is for. [[methods.patches]], further down, is the other half of the same problem: correcting individual characterization factors when the published method and the one you are asked to reproduce differ.

Both live under a [[methods]] entry in your configuration file.

A worked example

This is the Environmental Cost single score (ECS), as it is actually configured, shortened to four categories so the shape is visible. The real one runs to fifteen.

[[methods]]
name = "EF3.1"
path = "/data/EF-v3.1.zip"

  [[methods.scoring]]
  name = "ECS"
  unit = "Pts"
  displayMultiplier = 1e6

    # A short name for each impact category this score uses. The value on the
    # right has to be the category's name in the method, spelled exactly.
    [methods.scoring.variables]
    cch = "Climate change"
    ldu = "Land use"
    etfo = "Ecotoxicity, freshwater_organics"
    etfi = "Ecotoxicity, freshwater_inorganics"

    # Quantities the method does not carry, built from the ones it does.
    [methods.scoring.computed]
    etf = "2 * etfo + etfi"

    # What a computed quantity is called when it is shown.
    [methods.scoring.labels]
    etf = "Ecotoxicity, freshwater"

    # Divide each quantity by a reference: one person's annual share.
    [methods.scoring.normalization]
    cch = 7553.08
    ldu = 819498.0
    etf = 98120.0

    # Then weight what is left. These sum to 1 across the full score.
    [methods.scoring.weighting]
    cch = 0.2106
    ldu = 0.0629
    etf = 0.2106

    # The score itself: normalized, weighted quantities added up.
    [methods.scoring.scores]
    total = "cch + ldu + etf"

Read the arithmetic in that order. Each variable names a category. computed builds quantities the method does not publish on its own, here doubling organic freshwater ecotoxicity before adding the inorganic half. normalization divides by a reference so the categories become comparable, weighting decides how much each one counts, and scores says which of them go into the answer.

[[methods.scoring]]

Field	Description
name	What this score is called, in results and in the interface
unit	The unit its number carries: "Pts", "µPts PEF"
displayMultiplier	Every value this set returns is multiplied by it, in the API response as well as on screen. Normalized and weighted scores land around 10⁻⁶, so 1e6 puts them where a reader can compare them. A client reading total is reading a number already multiplied
variables	Short name to category name. The right-hand side has to match the method exactly, and it is where a single score most often goes wrong: a method exported by a different tool spells the same category differently
computed	Quantities built from other quantities, as formulas over the names above. Evaluated before normalization
labels	What a computed quantity is called when shown. Every key must be a variable or a computed quantity, or the configuration is refused
normalization	Divisor per quantity
weighting	Weight per quantity, applied after normalization
scores	The scores this set produces, each a formula over the normalized and weighted quantities. total is the conventional name

A method collection may carry several scoring sets. The EF 3.1 collection carries two, ECS and PEF, which differ in how they treat freshwater ecotoxicity and in their weights.

Formulas in computed and scores take +, -, *, /, ^, parentheses, numbers, the functions abs, sqrt, log, ln, exp, min and max, and the variable names you defined.

Correcting factors: [[methods.patches]]

Sometimes the method as published is not the method you are asked to reproduce. A patch changes matching characterization factors as the collection loads, so what you compute against is the corrected table and nothing downstream has to know.

[[methods]]
name = "EF3.1-adapted"
path = "/data/EF-adapted.csv"

  [[methods.patches]]
  description = "uraniumFRU: -40% on Uranium factors in Resource use, fossils"
  match = { category = "Resource use, fossils", flow-name-prefix = "Uranium" }
  scale = 0.6

  [[methods.patches]]
  description = "Long-term emissions are excluded from this variant"
  match = { subcompartment-contains = "long-term" }
  set-value = 0.0

Field	Description
description	Why this patch exists. The engine names the patch by it when the patch matches no factor at all, so a selector that stops matching is reported in your words rather than as a rendered selector
match	Which factors it applies to. At least one selector is required: a patch matching everything is refused
scale	Multiply the matched factors by this
set-value	Replace the matched factors with this

Exactly one of scale and set-value must be given. Both, or neither, is refused at startup rather than resolved silently.

Selectors

Every selector given must match, so several narrow one patch down together.

Selector	Matches on
category	The impact category’s name, exactly
flow-name	The flow’s name, exactly
flow-name-prefix	The start of the flow’s name, which is how a family of substances is caught at once
cas	The flow’s CAS registry number
subcompartment-contains	Any part of the subcompartment, which is how “long-term” is caught wherever it appears

When a score comes out wrong

Four failures account for most of it, and only the first leaves a trace:

• A category name that does not match. variables maps a short name to a category spelled exactly as the method spells it. One name that does not match does not cost you one contribution: the quantity is missing from the environment, the total formula then fails on an unknown variable, and the whole scoring set is dropped from the answer. The only trace is a warning in the server log. A method exported by another tool renames categories, so a set written against one export loses everything against another. Compare against what volca methods lists.
• A quantity missing from weighting. Only labels keys are checked against the variables you declared. A typo in normalization or weighting is accepted, and a quantity with no weight is weighted zero: the score still computes, still answers, and is quietly short by that category’s share.
• No energy densities. A factor written per MJ or per m³ cannot meet a flow measured in kilograms without a density to bridge them, and those categories score zero. Declare [[energy-densities]]; see Configuration.
• No geography hierarchy. A regionalized factor is found by walking from a location up to its parents. Without geographies, that walk has nowhere to go and regional factors are missed.