Understanding contextualization quality

Contextualization quality is how completely and correctly sources link to the industrial knowledge graph. Time series reach the functional location (asset) they belong to. P&ID tags resolve to CogniteAsset nodes. Equipment sits under the right parent in the hierarchy. Quality is a property of the graph and the links you created, not of a single algorithm run. A strong entity matching model still scores poorly when target assets are missing, aliases are empty, or scope spans two plants with the same tag string.

​

Why contextualization quality matters

Without measurement, teams tune machine learning while the real problem is graph preparation. You might lower an approval threshold when the issue is voided tags on old drawings, or retrain a model when P-101 exists at two sites in the same candidate set. Measuring quality helps you:

• Separate missing targets from bad matching logic.
• Prioritize alias work, rules, and scoped reruns instead of blanket reprocessing.
• Show progress to subject matter experts (SMEs) and data owners after each contextualization wave.

Read About contextualization for prerequisites, then Prepare aliases and match fields and Operate matching and annotation before you treat a dashboard score as a model-tuning task.

​

How to read contextualization metrics

The sections below cover in-scope denominators, time series and diagram metrics, human review patterns, and how to turn scores into fixes.

​

Count only data that should link

The most common quality mistake is measuring the whole project when only a subset was in scope for a wave. Before you interpret coverage or orphan rates:

• Define the in-scope population. Example: time series from PI for unit 100 that represent online instruments, not every raw point in the historian.
• Exclude by design. Spare equipment, future phases, and lab-only tags may never get a link in this wave. Do not count them as failures.
• Match the scope you used in the pipeline. If entity matching ran on one data set or instance space, score the same boundary. See Operate matching and annotation.

​

Entity matching and time series coverage

For time series and similar sources, two headline ideas drive most reviews. The table below summarizes what each metric means and what it usually indicates. Low coverage often means enterprise targets are missing from the graph, not that the matching model is weak. If contextualization_bad rows in the CDF Entity Matching deployment pack show no candidate overlap, return to Prepare aliases and match fields before you change thresholds.

​

Confidence is not one thing

Entity matching produces model scores. Manual mappings and regex rules do not. When you review a mixed pipeline:

• Treat rule and manual links as deterministic. They do not belong in the same distribution as machine learning confidence.
• Use auto-approval thresholds to separate accepted links from review queues. Changing the threshold without fixing aliases shifts noise, not quality. See Runtime parameters.
• Compare distributions within the same method (all ML suggestions, all rule hits) rather than across methods.

​

Human review as a diagnostic

Human-in-the-loop (HITL) acceptance in Cognite Data Fusion (CDF), confirming, rejecting, or correcting suggested matches, is a quality signal, not just cleanup. SME time is expensive. Use review queues to find systematic gaps (a unit, a tag prefix, a source system), then fix aliases or rules for that slice instead of reviewing row by row forever.

​

Diagram and file annotation quality

For P&IDs and engineering files, think in layers:

• File coverage: share of in-scope drawings that received at least one annotation.
• Tag recall: share of tag strings on the drawing that resolved to a target (misses often mean missing name / aliases, not bad OCR).
• Match rate: share of detected tags that matched an enterprise node in scope.
• Density: annotations per drawing; very low density can mean wrong file type in scope or a symbol library mismatch.

The File Annotation deployment pack separates approved and suggested annotations with thresholds. Confidence on diagram annotations reflects parser and matcher behavior for that file type, not entity matching scores on time series. Do not merge the two when you report quality to stakeholders.

​

Turn metrics into action

Use a simple loop after each contextualization wave:

1. Measure in-scope coverage and orphans using the Contextualization Quality Dashboard deployment pack or your pipeline review queues.
2. Classify failures: missing target, alias gap, scope error, or true matcher ambiguity.
3. Fix with the cheapest tool: transformation join, manual mapping, regex rule, then alias enrichment.
4. Rerun incrementally on the affected scope. See Operate matching and annotation.

Repeat until in-scope coverage meets the bar your use case needs, not until every metric is perfect across the whole tenant.

​

Next steps

• Deploy and run the Contextualization Quality Dashboard deployment pack for scored metrics across hierarchy, time series, file annotation, and related dimensions.
• Fix root causes with Prepare aliases and match fields and Operate matching and annotation.
• Return to About contextualization if you need to revisit tool choice or enterprise prerequisites.