Skip to content

Data Quality Report

A score tells you that a database computes. It does not tell you that the datasets behind it are well formed: an allocation that sums to 200 %, a release written in litres where the file says cubic metres, two activities claiming the same product. The quality report looks for those defects, for the people who build, repair or release databases.

It comes in two parts:

  • The structural report reads what the database stores. It needs no method and no matrix, so it runs on a database that is only staged (parsed, not built) as well as on a loaded one: you can read it before paying for a build.
  • The computed report judges what the database computes. It scores every activity against one method collection, then looks for scores out of line with the rest. It needs a loaded database and a loaded collection.

Each check returns a list of findings, worst first. A finding names the entry it was found on (activity, location, and the product when the check knows which one), and says what is wrong in one sentence, for example:

allocation sums to 69.90% across 3 coproduct(s)

Every finding carries a severity:

  • danger: the entry cannot compute correctly as it stands (no reference exchange, a non-finite amount, an allocation that does not sum to 100 %).
  • warning: something is very likely wrong and worth fixing (a duplicate, an out-of-range percentage, a water release ten times the intake).
  • info: a place to look, often expected (a final product nothing consumes, a geography read from the dataset name).

A check with nothing to judge is reported as not applicable, which is not the same as passing. A database without any allocation percentage is not judged on its allocation sums; a database whose format never carries pedigree scores is not accused of missing them.

CheckWhat it reportsSeverity
Reference productEntries without exactly one reference exchange: none leaves nothing to normalise against, several make the entry ambiguous.danger
Allocation sumsCoproducts of one block whose percentages do not sum to 100 % (half a point of rounding is tolerated), or a block where only some coproducts carry a percentage.danger, warning
Allocation out of rangeA single allocation percentage below 0 or above 100, even when the block still sums to 100.warning
UnallocatedEntries the engine refuses to score, with the reason and what would repair it. They load and can be read; any request to score them is refused with the same words.danger
Duplicate activitiesThe same name, location and reference product more than once: one of them is stale.warning
Duplicate productsTwo activities declaring the same product at the same location. An input naming that product is answered by one of them, the other supplies nothing.warning
Suspicious amountsAmounts that are not finite, and reference amounts of zero, which normalisation would divide by.danger
Unmeasurable amountsAmounts below 1e-27 in any unit, smaller than one atom weighs: a residue of computation that reads as data. On a reference exchange, every other amount is divided by it.danger on a reference, warning otherwise
Missing metadataDatasets with no description or classification (info), no location, or exchanges whose unit the unit registry does not define (warning).info, warning
Undeclared geographyGeographies the source never declared: read from the dataset name (SimaPro often leaves whole databases at “Unspecified”) or filled in by the loader.info
Formula consistencyStored amounts that disagree with the formulas documenting them, and formulas the engine could not evaluate. Disagreement is expected in allocated system-model exports, whose formulas still describe the unallocated parent.info
Truncated name collisionsDistinct names sharing their first 80 characters. SimaPro cuts process names there, so an export would merge them.warning
Missing pedigreeData lines without pedigree scores, in a database that otherwise carries them.info
Unconsumed productsReference products nothing in this database takes in: expected for a final product, a dangling intermediate in a background database.info
Unsupplied inputsInputs naming a product no activity of this database supplies: normal in a foreground database drawing on another one, a hole in one meant to stand alone.info
Obsolete inputsInputs whose only producer is a dataset the source filed as obsolete. It still computes, but the number is the superseded one.warning
Land transformation balanceWithin an activity, the area transformed “to” a use differs from the area transformed “from” another by more than 1 %.warning
Oxygen demand orderBOD5 greater than COD, or DOC greater than TOC, in one activity: the first is always a fraction of the second.warning
Invalid CAS numbersCAS numbers whose check digit does not confirm the rest. A corrupt CAS silently breaks the matching of flows across databases.warning
Water balanceAn activity releasing to water and soil more than ten times the water it withdraws or buys (releases under one litre are ignored). Almost always a unit slip, and water-use methods count a release as a credit, so the slip can turn a score negative.warning
CheckWhat it reportsSeverity
Score outliersCategory scores far from the norm of the entries that share the same reference unit (kg with kg, kWh with kWh), on a log scale: more than 3.5 robust standard deviations from the median. A milligram read as a kilogram lands three orders of magnitude out. Groups of fewer than 20 entries are not judged. The wildest deviation comes first.warning
Zero scoresEntries whose every category score is zero: the inventory is empty, or nothing in it is characterised.warning
Negative scoresCategory scores below zero. Legitimate where avoided production or waste treatment dominates, worth confirming elsewhere.info
No answerEntries the engine has no answer for, so they have no score at all. Most often their supply chain reaches processes no amount can satisfy, such as two that each take all of what the other makes; an input amount that is not a finite number, or a demand on another database in a unit that does not convert, does the same. The sentence names the process in the way.danger

The computed report scores every activity of the database at once. An engine may cap how many activities one such request covers (max_batch_activities, see Configuration), and the shared public engine refuses it altogether: run it on an engine of your own.

Open the database, then the Data quality tab. The structural checks run as soon as the tab opens; each card shows the worst findings of its check, and each finding links to the activity it names. The computed checks start with Run computed checks, against the method collection chosen beside the button when more than one is loaded.

Compare with holds the structural report against another version of the same database: instead of every finding, the tab lists the structural findings this version added and those it fixed. That is the view to read before releasing a new version. The computed report has no such comparison.

Both reports download as CSV for a spreadsheet, which holds every finding rather than the first rows the cards show.

Terminal window
volca --config volca.toml --db agribalyse quality-report
volca --config volca.toml --db agribalyse quality-report --limit 20 --format csv > quality.csv
volca --config volca.toml --db agribalyse computed-quality-report --collection EF3.1

--limit N keeps the N worst findings of each check. --collection can be left out when only one method collection is loaded.

GET /api/v1/db/{db}/quality-report?limit=N
GET /api/v1/db/{db}/quality-report.csv
GET /api/v1/db/{db}/computed-quality-report?collection=NAME&limit=N
GET /api/v1/db/{db}/computed-quality-report.csv?collection=NAME

The CSV is the file the web interface offers, byte for byte.

report = client.quality_report("agribalyse", limit=20)
computed = client.computed_quality_report("agribalyse", collection="EF3.1")

quality_report_csv and computed_quality_report_csv return the CSV. See the Python reference.

The MCP tools get_quality_report and get_computed_quality_report return the same reports. See MCP tools.