> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognite.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale. > Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML. > For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts// and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript. > Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md. > For implementation work, also load /skill.md. # Understanding contextualization quality > Understand contextualization quality and how to interpret in-scope coverage, orphans, and confidence when low scores point to missing graph data instead of a weak model. 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](https://docs.cognite.com/cdf/integration/concepts/contextualization/overview.md) for prerequisites, then [Prepare aliases and match fields](https://docs.cognite.com/cdf/integration/guides/contextualization/prepare_aliases.md) and [Operate matching and annotation](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md) 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](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md). > [!WARNING] > > A low contextualization rate across **all** time series in a project often means the denominator is wrong. Recalculate coverage against the population that **should** have linked in this phase. ### 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. | Metric idea | What it tells you | Often means | | - | - | - | | **Coverage** (linked / in-scope) | How much of the intended population reached a target. | Missing `CogniteAsset` nodes, empty match fields, or scope too wide. | | **Orphan rate** (unlinked / in-scope) | What still has no relationship after a run. | Blocking misses, bad aliases, or sources that never belonged in scope. | 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](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/entity_matching.md) deployment pack show no candidate overlap, return to [Prepare aliases and match fields](https://docs.cognite.com/cdf/integration/guides/contextualization/prepare_aliases.md) 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](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/entity_matching.md#runtime-parameters-extraction-pipelines). * 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. | Review pattern | Likely root cause | Where to look next | | - | - | - | | High rejection, empty match field on source | Tokenization or blocking miss | [Prepare aliases and match fields](https://docs.cognite.com/cdf/integration/guides/contextualization/prepare_aliases.md) | | High rejection, plausible tag text on diagram | Voided tag or missing alias on asset | [Alias tiers and rename lists](https://docs.cognite.com/cdf/integration/guides/contextualization/prepare_aliases.md#step-4-layer-aliases-from-mechanical-to-authoritative) | | Acceptances cluster on one site | Scope or hierarchy gap elsewhere | [Scoping pipelines](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md#step-1-scope-candidates-by-site-plant-or-unit) | | Many "different recommendation" rows after a hierarchy change | Stale links or full reprocess needed | [Full reprocess](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md#step-5-decide-when-a-full-reprocess-is-justified) or [incremental reruns](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md#step-4-configure-incremental-reruns) | 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](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/file_annotation.md) 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](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/contextualization_status.md) 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](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md). 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](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/contextualization_status.md) deployment pack for scored metrics across hierarchy, time series, file annotation, and related dimensions. * Fix root causes with [Prepare aliases and match fields](https://docs.cognite.com/cdf/integration/guides/contextualization/prepare_aliases.md) and [Operate matching and annotation](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md). * Return to [About contextualization](https://docs.cognite.com/cdf/integration/concepts/contextualization/overview.md) if you need to revisit tool choice or enterprise prerequisites.