---
title: "Analyse Correspondence Table"
output:
  rmarkdown::html_vignette:  
    toc: TRUE
description: "This vignette explains how to use the `analyseCorrespondenceTable()` function to explore and diagnose correspondence tables."
vignette: >
  %\VignetteIndexEntry{Analyse Correspondence Table}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


```{r include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

<div style="text-align: justify;">
## Overview  
 
This vignette demonstrates how to extract key diagnostic information from correspondence tables using the `analyseCorrespondenceTable()` function, including:

- the inventory of codes involved on both sides of the correspondence;
- the presence of one‑to‑one, one‑to‑many, or many‑to‑many relationships;
- potential structural issues that may affect downstream use (aggregation, updates, or quality checks).
</div>

```{r}
library(correspondenceTables)  
```

```{r, echo=FALSE, results="asis"}
cat("
<style>
table {
  width: 100% !important;
}
table caption {
  text-align: center;
}
</style>
")
```

## Application of `analyseCorrespondenceTable`

### Example 1: Basic analysis of a correspondence table
In this first example, only a correspondence table is provided.
No explicit source or target classification tables are supplied.


```{r}
# Load example correspondence table
AB <- read.csv(
  system.file("extdata/test", "ExempleAnnexe.csv", package = "correspondenceTables"),
  stringsAsFactors = FALSE
)

```


The analysis is then performed using default settings:


```{r}
# Perform analysis
result <- analyseCorrespondenceTable(
  AB = AB,
  A  = NULL,
  B  = NULL,
  longestAcodeOnly = FALSE,
  longestBcodeOnly = FALSE
)
```

 
The function returns a list containing multiple outputs.
Two key components are displayed below.

The tables below illustrate the first rows of the outputs returned by the function:


```{r}
# Display results

knitr::kable(
  head(result$Inventory),
  caption = "Inventory results: Basic analysis of a correspondence table",
  align = "c"
)


knitr::kable(
  head(result$Analysis),
  caption = "Analysis results: Basic analysis of a correspondence table",
  align = "c"
)

```

 <div style="text-align: justify;">
**Interpretation of the results**

The `analyseCorrespondenceTable()` function returns a list of outputs that
summarise the structure of the correspondence table from complementary
perspectives. In this example, two components are displayed:
**Inventory** and **Analysis**.

**Inventory table**

The `Inventory` table provides descriptive information about the codes
appearing on each side of the correspondence. Typical columns include:

- the identifiers of codes on side *A* and side *B*;
- the number of times each code appears in the correspondence;
- summary indicators describing how codes are connected.

This table is useful for identifying which codes are involved in the
correspondence and for detecting duplicates or unexpected patterns.

**Analysis table**

The `Analysis` table summarises the relationship structure between the
two classifications. In particular, it classifies the relationships between codes as:

- **1:1 (one‑to‑one)**: each code on side *A* corresponds to exactly one
  code on side *B*;
- **1:M (one‑to‑many)**: one code on side *A* corresponds to multiple
  codes on side *B*;
- **M:1 (many‑to‑one)**: multiple codes on side *A* correspond to one
  code on side *B*;
- **M:M (many‑to‑many)**: multiple codes on side *A* correspond to
  multiple codes on side *B*.

Many‑to‑many (M:M) relationships are typically the most complex and may require
special attention, as they can introduce ambiguity in aggregation,
conversion, or validation processes.


Together, the inventory and analysis outputs provide an overview of both
the content and the structural properties of the correspondence
table.
</div>

### Example 2: Full analysis with source and target classifications
In this second example, all main parameters of the function are used.

- `AB`: correspondence table between NACE Rev.2 and NACE Rev.2.1
- `A`: source classification (NACE Rev.2)  
- `B`: target classification (NACE Rev.2.1)

The analysis is restricted to the lowest‑level codes on both sides of the
correspondence.


```{r}
# Load correspondence table (NACE Rev.2 -> NACE Rev.2.1)
AB <- read.csv(
  system.file("extdata/test", "ab_data.csv", package = "correspondenceTables"),
  stringsAsFactors = FALSE
)

# Load source classification (NACE Rev.2)
A <- read.csv(
  system.file("extdata/test", "a_data.csv", package = "correspondenceTables"),
  stringsAsFactors = FALSE
)

# Load target classification (NACE Rev.2.1)
B <- read.csv(
  system.file("extdata/test", "b_data.csv", package = "correspondenceTables"),
  stringsAsFactors = FALSE
)

```


```{r warning = FALSE}
# Perform analysis using all function parameters
result2 <- analyseCorrespondenceTable(
  AB = AB,
  A  = A,
  B  = B,
  longestAcodeOnly = TRUE,
  longestBcodeOnly = TRUE
)

```


The tables illustrate the first rows of the outputs returned by the function:
The resulting inventory and analysis summary are shown below: 


```{r}
# Display results

knitr::kable(
  head(result2$Inventory),
  caption = "Inventory results: Full analysis with source and target classifications",
  align = "c"
) 


knitr::kable(
  head(result2$Analysis[, 1:5]),
  caption = "Analysis results: Full analysis with source and target classifications",
  align = "c"
)


```

Restricting the analysis to the lowest‑level codes can be useful when the
correspondence table is intended for aggregation or conversion at the most
granular classification level.

 <div style="text-align: justify;">
## Notes

If `A` and `B` are provided, the function performs additional consistency checks against the source and target classification domains.

The `longestAcodeOnly` and `longestBcodeOnly` arguments allow users to restrict the analysis to the most detailed codes, which is often desirable in practical statistical workflows.

This functionality supports the validation and interpretation of correspondence tables, particularly when preparing data for aggregation, transformation, or integration tasks.

</div>