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.
Reading a finding
Section titled “Reading a finding”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.
Structural checks
Section titled “Structural checks”| Check | What it reports | Severity |
|---|---|---|
| Reference product | Entries without exactly one reference exchange: none leaves nothing to normalise against, several make the entry ambiguous. | danger |
| Allocation sums | Coproducts 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 range | A single allocation percentage below 0 or above 100, even when the block still sums to 100. | warning |
| Unallocated | Entries 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 activities | The same name, location and reference product more than once: one of them is stale. | warning |
| Duplicate products | Two 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 amounts | Amounts that are not finite, and reference amounts of zero, which normalisation would divide by. | danger |
| Unmeasurable amounts | Amounts 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 metadata | Datasets with no description or classification (info), no location, or exchanges whose unit the unit registry does not define (warning). | info, warning |
| Undeclared geography | Geographies the source never declared: read from the dataset name (SimaPro often leaves whole databases at “Unspecified”) or filled in by the loader. | info |
| Formula consistency | Stored 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 collisions | Distinct names sharing their first 80 characters. SimaPro cuts process names there, so an export would merge them. | warning |
| Missing pedigree | Data lines without pedigree scores, in a database that otherwise carries them. | info |
| Unconsumed products | Reference products nothing in this database takes in: expected for a final product, a dangling intermediate in a background database. | info |
| Unsupplied inputs | Inputs 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 inputs | Inputs whose only producer is a dataset the source filed as obsolete. It still computes, but the number is the superseded one. | warning |
| Land transformation balance | Within an activity, the area transformed “to” a use differs from the area transformed “from” another by more than 1 %. | warning |
| Oxygen demand order | BOD5 greater than COD, or DOC greater than TOC, in one activity: the first is always a fraction of the second. | warning |
| Invalid CAS numbers | CAS numbers whose check digit does not confirm the rest. A corrupt CAS silently breaks the matching of flows across databases. | warning |
| Water balance | An 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 |
Computed checks
Section titled “Computed checks”| Check | What it reports | Severity |
|---|---|---|
| Score outliers | Category 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 scores | Entries whose every category score is zero: the inventory is empty, or nothing in it is characterised. | warning |
| Negative scores | Category scores below zero. Legitimate where avoided production or waste treatment dominates, worth confirming elsewhere. | info |
| No answer | Entries 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.
Running the report
Section titled “Running the report”In the web interface
Section titled “In the web interface”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.
From the command line
Section titled “From the command line”volca --config volca.toml --db agribalyse quality-reportvolca --config volca.toml --db agribalyse quality-report --limit 20 --format csv > quality.csvvolca --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.
Over HTTP
Section titled “Over HTTP”GET /api/v1/db/{db}/quality-report?limit=NGET /api/v1/db/{db}/quality-report.csvGET /api/v1/db/{db}/computed-quality-report?collection=NAME&limit=NGET /api/v1/db/{db}/computed-quality-report.csv?collection=NAMEThe CSV is the file the web interface offers, byte for byte.
From Python
Section titled “From Python”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.
From an AI assistant
Section titled “From an AI assistant”The MCP tools get_quality_report and get_computed_quality_report return
the same reports. See MCP tools.