Classification Quality Control

The main function classificationQC() performs structural and logical quality control on hierarchical classifications. It returns a list of data frames, including an enriched version of the classification (QC_output) and additional tables flagging potential issues such as orphan codes, duplicate labels, or sequencing problems.

The quality‑control checks identify several types of potential structural or logical issues commonly observed in official classifications:

• Missing hierarchy levels: codes for which no hierarchical level can be inferred from the provided structure (for example because their code length does not match any declared level). Such codes cannot be positioned reliably in the hierarchy.

• Orphan codes: codes that do not have a valid parent code at the immediately higher hierarchical level. This indicates a break in the hierarchical structure and usually reflects missing or inconsistent higher‑level codes.

• Childless codes: internal codes that do not have any descendants at the immediately lower hierarchical level. While expected at the lowest level, this may signal incomplete structures or unintended dead ends at higher levels.

• Duplicate labels: identical labels occurring more than once within the same hierarchical level. This does not invalidate the hierarchy, but may reduce interpretability and cause ambiguity when classifications are used in tabular or statistical contexts.

• Label‑hierarchy inconsistencies: situations in which the label of a child code does not reflect the label of its parent where such inheritance is expected (for example in single‑child situations), suggesting potential inconsistencies in naming conventions.

• Sequencing anomalies: gaps or breaks in expected code sequences among sibling codes under the same parent. In structured coding systems where code values are meaningful (for example numeric ranges), such gaps may indicate missing or omitted codes.

Main arguments

The main arguments of the function are:

• classification: A data frame containing the classification codes and labels.

• lengths: A data frame with one row per hierarchical level giving the initial and final positions of the segment of the code referring to that level. The number of rows implicitly defines the number of hierarchical levels (\(k\)). The column names should be charb and chare, if this is not the case, they will be automatically changed and a warning will appear.

• fullHierarchy: Logical. If FALSE, the function checks that all positions at levels greater than 1 have a parent at the level immediately above (no orphans). If TRUE, it additionally checks that positions at levels strictly lower than \(k\) have children in the next level (no childless nodes). More specifically, the function checks the completeness of the hierarchical structure by applying two rules:

  • Orphan check: A new field in the QC output, named orphan, takes the value 1 for positions at hierarchical level \(j > 1\) that lack a parent at the immediately higher level (\(j − 1\)), and 0 otherwise.
  • Childless check: A new field in the QC output, named childless, takes the value 1 for positions at hierarchical level \(j < k\) that lack a child at the immediately lower level (\(j + 1\)), and 0 otherwise.

• labelUniqueness: Logical. When TRUE, the function checks whether labels are unique, at each hierarchical level. Duplicates are listed in the QC_duplicatesLabel table.

• labelHierarchy:Logical. When TRUE, the function checks that single children share the same label as their parent and if a parent shares a label with one of its children, it must be a single-child parent. The possible values are:

  • 1: indicates a single child whose label does not match that of its parent;
  • 9: indicates a child whose label matches that of its parent without being a single child;
  • 0: indicates compliance.

• singleChildCode: an optional data frame defining admissible coding rules for single‑child and multiple‑child situations, with columns level, singleCode, and multipleCode. If these headers are missing or incorrect, they are automatically corrected with a warning.

• sequencing: an optional data frame defining admissible code‑range rules for multiple‑child situations, used to identify potential gaps in structured code sequences. The expected columns are level and multipleCode.

It is important to note that not all detected issues necessarily indicate errors. The quality‑control checks are diagnostic signals intended to support expert review of classification quality and consistency, and they do not impose constraints on the hierarchical structure itself. In particular:

• parent codes may legitimately have any number of children;
• sequencing checks are not about the order in which children appear;
• sequencing diagnostics are used to identify gaps in expected, structured code ranges where code values carry semantic meaning.

The validation procedures rely on a small set of auxiliary tables that define structural constraints, such as expected code lengths, single‑child rules, and sequencing between levels.

We load three auxiliary tables used for classification validation.

The following example applies classificationQC() to the NACE Rev.2 classification using additional parameters.

In this example, the user provides:

• a data frame containing the classification to be checked, and
• a data frame defining the hierarchical structure of the classification through the lengths argument.

This example demonstrates how different parameters of classificationQC() are used to perform structural and logical quality checks.

classification <- read.csv(
  system.file("extdata/test", "Nace2_long.csv", package = "correspondenceTables")
)

lengths <- data.frame(
  charb = c(1, 2, 3, 5),
  chare = c(1, 2, 4, 5)
)

We now apply the classificationQC() function using the previously defined classification and hierarchy structure. The function performs structural and logical quality checks on the NACE Rev.2 classification. For illustration purposes, the output is summarised by reporting the number of detected issues for selected quality checks.

output <- classificationQC(
  classification   = classification,
  lengths          = lengths,
  fullHierarchy    = TRUE,
  labelUniqueness  = TRUE,
  labelHierarchy   = TRUE,
  singleChildCode  = NULL,
  sequencing       = NULL
)

qc_summary <- data.frame(
  Check            = c("No levels", "Orphan codes", "Childless codes"),
  Number_of_issues = c(
    nrow(output$QC_noLevels),
    nrow(output$QC_orphan),
    nrow(output$QC_childless)
  )
)

knitr::kable(
  qc_summary,
  caption = "Summary of quality control checks",
  align = "c"
)

The following example illustrates the quality control of the NACE Rev.2 classification from CELLAR using additional parameters, including the singleChildCode argument.

singleChildCode <- read.csv(
  system.file("extdata/test", "SingleChild.csv", package = "correspondenceTables")
)
knitr::kable(
  singleChildCode,
  caption = "singleChildCode argument",
  align = "c"
)

output2 <- classificationQC(
  classification   = classification,
  lengths          = lengths,
  fullHierarchy    = TRUE,
  labelUniqueness  = TRUE,
  labelHierarchy   = TRUE,
  singleChildCode  = singleChildCode,
  sequencing       = NULL
)

This table lists orphan codes, i.e. codes that do not have a valid parent at the immediately higher hierarchical level.

QC_orphan

• Rows: 88
  
• Columns: 18

This table lists childless codes, i.e. codes that have no descendants at the immediately lower hierarchical level

QC_childless

• Rows: 21
  
• Columns: 19

In this final example, the sequencing parameter is used to detect potential gaps in structured sequences of sibling codes within the hierarchy.

Sequencing rules are applied at hierarchical levels 3 and 4, as specified in the sequencing input table. At these levels, the function identifies missing or inconsistent code values within predefined numeric or alphanumeric ranges, which may indicate incomplete or faulty classification structures.

singleChildCode <- read.csv(
  system.file("extdata/test", "SingleChild2.csv", package = "correspondenceTables")
)

sequencing <- read.csv(
  system.file("extdata/test", "Sequencing.csv",
              package = "correspondenceTables")
)

output3 <- classificationQC(
  classification   = classification, 
  lengths          = lengths,
  fullHierarchy    = TRUE,
  labelUniqueness  = TRUE,
  labelHierarchy   = TRUE,
  singleChildCode  = singleChildCode,
  sequencing       = sequencing
)

The QC_gapBefore argument identifies gaps in expected code sequences among sibling codes within the same parent.

QC_gapBefore

• Rows: 295
  
• Columns: 25

This table lists the last sibling codes within each group of children, used to assess sequence completeness.

QC_lastSibling

• Rows: 208
  
• Columns: 25

This table contains the full classification enriched with all quality‑control flags produced by the checks

QC_output

• Rows: 996
  
• Columns: 25