% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/updateCorrespondenceTable.R
\name{updateCorrespondenceTable}
\alias{updateCorrespondenceTable}
\title{Correspondence table creation}
\usage{
updateCorrespondenceTable(
  A,
  B,
  AStar,
  AB,
  AAStar,
  Reference = "none",
  MismatchToleranceB = 0.2,
  MismatchToleranceAStar = 0.2,
  Redundancy_trim = TRUE
)
}
\arguments{
\item{A}{A data frame containing the original classification A. The first column holds the codes;
optional subsequent columns may hold labels and supplementary info.}

\item{B}{A data frame containing the target classification B. Same structure expectations as \code{A}.}

\item{AStar}{A data frame containing the updated version A*. Same structure expectations as \code{A}.}

\item{AB}{A data frame containing the previous correspondence table A:B (at least two columns: A-codes, B-codes).}

\item{AAStar}{A data frame containing the concordance table A:A* (at least two columns: A-codes, A*-codes).}

\item{Reference}{The reference classification among A and B. Valid values: \code{"none"}, \code{"A"}, \code{"B"}.
If \code{"A"} or \code{"B"}, a "Review" flag column is included (see "Explanation of the flags").}

\item{MismatchToleranceB}{Maximum acceptable proportion of rows in the updated table with no code of B
among those that have a code for A and/or A*. Default \code{0.2}, range [0,1].}

\item{MismatchToleranceAStar}{Maximum acceptable proportion of rows in the updated table with no code of A*
among those that have a code for A and/or B. Default \code{0.2}, range [0,1].}

\item{Redundancy_trim}{Logical. If \code{TRUE} (default) trims correct redundant records by collapsing A-side fields to "Multiple"
when appropriate; if \code{FALSE}, keeps redundancies and adds a \code{Redundancy_keep} indicator.}
}
\value{
\code{updateCorrespondenceTable()} returns a list with two data frames:
\itemize{
  \item \code{updateCorrespondenceTable}: the updated correspondence A*:B with flags "CodeChange", "Review" (if applicable),
        "Redundancy", "NoMatchToAStar", "NoMatchToB", "NoMatchFromAStar", "NoMatchFromB", "LabelChange",
        plus any additional columns coming from \code{A}, \code{B}, \code{AStar}, \code{AB}, \code{AAStar}.
  \item \code{classificationNames}: the names of the classifications (A, B, A*) read from the first column headers.
}
}
\description{
Update the correspondence table between two classifications when one of them has been updated.
}
\details{
*Input data frame requirements*
\itemize{
  \item \code{A}, \code{B}, \code{AStar}: at least 1 column and at least 1 row. The first column contains the codes; the first row is the header.
  \item \code{AB}, \code{AAStar}: at least 2 columns and at least 1 row; the first two columns contain code pairs; the first row is the header.
  \item Codes in the first column of \code{A}, \code{B}, \code{AStar} must be unique (no duplicates).
  \item Pairs (first two columns) in \code{AB} and \code{AAStar} must be unique (no duplicate pairs).
  \item If additional columns are present in classification or correspondence tables, the second column is treated as a label.
  \item All columns are coerced to character.
}

*Minimum interdependencies*
\itemize{
  \item At least one code of A must appear in both \code{AAStar} and \code{AB}.
  \item At least one code of A* must appear in both \code{AStar} and \code{AAStar}.
  \item At least one code of B must appear in both \code{B} and \code{AB}.
}

*Mismatch tolerance*
\itemize{
  \item If the share of rows with \code{NoMatchToAStar == 1} exceeds \code{MismatchToleranceAStar}, the function stops with an error.
  \item If the share of rows with \code{NoMatchToB == 1} exceeds \code{MismatchToleranceB}, the function stops with an error.
}
}
\section{Explanation of the flags}{


\itemize{
    \item For each row of the updated correspondence table, the value of "CodeChange" is equal to \code{1} if the code of A (or A*)
     contained in this row maps -in this or any other row of the table- to a different code of A* (or A), otherwise the 
     "CodeChange" is equal to \code{0}. The value of "CodeChange" is empty if either the code of A, or the code of A*, or both are missing.
    \item The "Review" flag is produced only if argument \code{Reference} has been set equal to "\code{A}" or "\code{B}".
    For each row of the updated correspondence table, if \code{Reference} = "\code{A}" the value of "Review" is equal to
    \code{1} if the code of B maps to more than one code of A*, and \code{0} otherwise. If \code{Reference} = "\code{B}" the
    value of "Review" is equal to \code{1} if the code of A* maps to more than one code of B, and \code{0} otherwise. The value
    of the flag is empty if either the code of A*, or the code of B, or both are missing.
    \item For each row of the updated correspondence table, the value of "Redundancy" is equal to \code{1} if the row contains
    a combination of codes of A* and B that also appears in at least one other row of the updated correspondence table. The
    value of the flag is empty if both the code of A* and the code of B are missing.
    \item When "Redundancy_Trim" is equal to \code{FALSE} the "Redundancy_keep" flag is created to identify with value \code{1}
    the records that will be kept if trimming is performed.
    \item For each row of the updated correspondence table, the value of "NoMatchToAStar" is equal to \code{1} if there is a
    code for A,  for B, or for both, but no code for A*. The value of the flag is \code{0} if there are codes for both A and
    A* (regardless of whether there is a code for B or not). Finally, the value of "NoMatchToAStar" is empty if neither A nor B
    have a code in this row.
    \item For each row of the updated correspondence table, the value of "NoMatchToB" is equal to \code{1} if there is a code
    for A,  for A*, or for both, but no code for B. The value of the flag is \code{0} if there are codes for both A and B
    (regardless of whether there is a code for A* or not). Finally, the value of "NoMatchToB" is empty if neither A nor
    A* have a code in this row.
    \item For each row of the updated correspondence table, the value of "NoMatchFromAStar" is equal to \code{1} if the row
    contains a code of A* that appears in the table of classification A* but not in the concordance table A:A*. The value of
    the flag is \code{0} if the row contains a code of A* that appears in both the table of classification
    A* and the concordance table A:A*. Finally, the value of the flag is empty if the row contains no code of A* or if it
    contains a code of A* that appears in the concordance table A:A* but not in the table of classification A*.
    \item For each row of the updated correspondence table, the value of "NoMatchFromB" is equal to \code{1} if the row
    contains a code of B that appears in the table of classification B but not in the correspondence table A:B. The value of
    the flag is \code{0} if the row contains a code of B that appears in both the table of classification B and the
    correspondence table A:B. Finally, the value of the flag is empty if the row contains no code of B or if it contains a code
    of B that appears in the correspondence table A:B but not in the table of classification B.
    \item For each row of the updated correspondence table, the value of "LabelChange" is equal to \code{1} if the labels of
    the codes of A and A* are different, and \code{0} if they are the same. Finally, the value of "LabelChange" is empty if
    either of the labels, or both labels, are missing. Lower and upper case are considered the same, and punctuation characters
    are ignored when comparing code labels.
    \item The argument "Redundancy_trim" is used to delete all the redundancies which are mapping correctly. If the analysis 
   concludes that the A*code / Bcode mapping is correct for all cases involving redundancies, then an action is needed to remove 
   the redundancies. If the selected value is \code{TRUE}, all redundant records are removed and kept only one record for each unique 
   combination. For this record retained, the Acodes, the Alabel and the Asupp information is replaced with ‘multiple’. If the multiple 
   A records are the same, their value will not be replaced. If the selected value is \code{FALSE}, no trimming is executed so redundant 
   records are shown, together with the redundancy flag.
}
}

\examples{
\dontrun{

  # Read CSVs outside, pass data frames in:
  
  A_df      <- utils::read.csv(system.file("extdata/test", "NAICS2017.csv",
  package = "correspondenceTables"),
  sep = ",", header = TRUE, check.names = FALSE, 
  colClasses = "character", encoding = "UTF-8")
                               
  AStar_df  <- utils::read.csv(system.file("extdata/test", "NAICS2022.csv",
  package = "correspondenceTables"),
  sep = ",", header = TRUE, check.names = FALSE,
  colClasses = "character", encoding = "UTF-8")
                               
  B_df      <- utils::read.csv(system.file("extdata/test", "NACE.csv",
  package = "correspondenceTables"),
  sep = ",", header = TRUE, check.names = FALSE,
  colClasses = "character", encoding = "UTF-8")
  
  AB_df     <- utils::read.csv(system.file("extdata/test", "NAICS2017_NACE.csv",
  package = "correspondenceTables"),
  sep = ",", header = TRUE, check.names = FALSE,
  colClasses = "character", encoding = "UTF-8")
                               
  AAStar_df <- utils::read.csv(system.file("extdata/test", "NAICS2017_NAICS2022.csv",
  package = "correspondenceTables"),
  sep = ",", header = TRUE, check.names = FALSE,
  colClasses = "character", encoding = "UTF-8")

  UPC <- updateCorrespondenceTable(
    A = A_df, B = B_df, AStar = AStar_df, AB = AB_df, AAStar = AAStar_df,
    Reference = "none", MismatchToleranceB = 0.5, MismatchToleranceAStar = 0.3,
    Redundancy_trim = FALSE
  )

  summary(UPC)
  head(UPC$updateCorrespondenceTable)
  UPC$classificationNames
}

}
