% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/find_equivalents.R
\name{find_equivalent_codes}
\alias{find_equivalent_codes}
\alias{find_equivalents}
\title{Find equivalent sets of codes in a Klass classification}
\usage{
find_equivalent_codes(
  classification,
  dates,
  labels = TRUE,
  graph = klass_graph(classification),
  date_format = "\%Y"
)

find_equivalents(
  classification,
  dates,
  labels = TRUE,
  graph = klass_graph(classification),
  date_format = "\%Y"
)
}
\arguments{
\item{classification}{The Klass classification to be used}

\item{dates}{The dates that equivalent sets of codes should be found for.}

\item{labels}{\code{TRUE}, \code{FALSE} or a named list of functions.

This parameter controls whether or not to add group labels to groups of
equivalent sets. If \code{TRUE}, labels are constructed using the codes valid at
the latest provided date, and comma separated like in the example below. By
default, labels will be placed in a column named \code{label}.

\if{html}{\out{<div class="sourceCode">}}\preformatted{"1508 Ålesund, 1580 Haram"
}\if{html}{\out{</div>}}

If \code{FALSE}, no labels will be applied.

This parameter also accepts a named list of labelling functions. The
resulting dataset will contain a label column for each of the supplied
functions. The names of the label columns are specified using the names of
the list of functions.

The functions provided in this parameter can accept any of the following
parameters: \code{date}, \code{code}, \code{name}, \code{validFrom} and \code{validTo}, representing
the corresponding values of each code in a group. The functions must also
provide a \code{...} parameter, unless using all of the above. The functions can
expect that the input variables have the same length of 1 or longer. The
functions should return a character vector of length one or the same length
as the input variables.

The following list, when supplied to this parameter, creates two label
columns: one containing the codes and names (\code{label1}), and another with
only the codes \code{label2}. In this example, \code{label1} creates the same labels
as the default labelling used when \code{labels == TRUE}.

\if{html}{\out{<div class="sourceCode">}}\preformatted{list(
  label1 = function(code, name, date, ...) \{
    label_codes <- date == max(date)
    paste(code[label_codes], name[label_codes], collapse = ", ")
  \},
  label2 = function(code, date, ...) \{
    label_codes <- date == max(date)
    paste(code[label_codes], collapse = ", ")
  \}
)
}\if{html}{\out{</div>}}}

\item{graph}{Optional. Generating the graph using \code{klass_graph} manually
beforehand and providing it in this parameter can save time if running
\code{find_equivalent_codes} multiple times in sequence.}

\item{date_format}{Optional. Passed directly to \link{format}, this is used to
specify the output format for the \code{date} column. The default keeps just the
year (\code{"YYYY"}). To get the full date in \code{"YYYY-MM-DD"} format, use
\code{"\%Y-\%m-\%d"}. See \link{strptime} for complete functionality.}
}
\value{
A data.frame with columns:
\itemize{
\item \code{date} containing the input \code{dates}
\item \code{code} containing the set of equivalent codes in each date
\item \code{name} containing the names of each code
\item \code{validFrom} and \code{validTo} values for each code returned
\item By default, \code{labels}, giving a unique group label for each group of equivalent sets.
}
}
\description{
Find which codes should be combined to reconstruct older or newer codes
across multiple dates. Creates groups dynamically to fit the provided date
range, with flexible labelling functionality.
}
\details{
This function provides a solution to the problem of split or
combined codes in Klass classifications. When using \code{\link{update_klass}} to ask
"what is this code in this version of the classification in this other
version of the classification?", the answer is sometimes that the code has
been split into two or more codes (or combined from two or more codes, if
trying to back-date a code), and therefore that the code cannot be updated.

The solution provided by \code{find_equivalent_codes} is answering the question: "in
these versions of the classification, which codes were equivalent to this
code in this other version of the classification?".

Consider the following example of two codes combining into one. Here, \code{"a"}
and \code{"b"} are valid at t1, and are combined into \code{"c"} at t2.

\if{html}{\out{<div class="sourceCode">}}\preformatted{t1      t2
a ---|
b ---+-> c

}\if{html}{\out{</div>}}

\code{\link{update_klass}} would inform us that \code{"a"} can be updated to
\code{"c"} at t2, unless we specified \code{combine = FALSE}, in which case the
result would be \code{NA}. \code{find_equivalent_codes()} would inform us that the
equivalent of the codes \code{"a"} and \code{"b"} in t1 at t2 is \code{"c"}.

We can also consider a code splitting into two. In this example, \code{"a"} is
valid at t1, and splits into \code{"b"} and \code{"c"} at t2.

\if{html}{\out{<div class="sourceCode">}}\preformatted{t1     t2
a
|-----> b
|-----> c
}\if{html}{\out{</div>}}

\code{\link{update_klass}} is unable to provide an updated code due to the
split, and would return \code{NA}. \code{find_equivalent_codes} would inform us that the
equivalent codes of \code{"a"} at t1 is \code{"b"} and \code{"c"} at t2.

\code{find_equivalent_codes} can handle more than two dates. In the following
example, \code{"a"} splits into \code{"b"} and \code{"c"} at t2, and \code{"b"} and \code{"c"}
combine into \code{"d"} at t3. \code{find_equivalent_codes} can inform us that \code{"a"} is
equivalent to \code{"b"} and \code{"c"} at t2, and \code{"d"} at t3.

\if{html}{\out{<div class="sourceCode">}}\preformatted{t1     t2     t3
a
|-----> b |
|-----> c +-> d
}\if{html}{\out{</div>}}

\code{find_equivalent_codes} will only search in the time range we specify. As a
consequence, generating sets of equivalent codes over longer time spans
will generally create larger sets than using shorter time spans.

To illustrate this behavior, we can add a new code \code{"e"} to the previous
example, and have \code{"d"} and \code{"e"} combine into \code{"f"} at t4.

\if{html}{\out{<div class="sourceCode">}}\preformatted{t1     t2     t3     t4
a
|-----> b |
|-----> c |-> d |
e---------------+--> f
}\if{html}{\out{</div>}}

Finding the
equivalents of \code{"a"} in t1 at t2 and t3 returns the same sets as
before:
\itemize{
\item t1: \code{"a"}
\item t2: \code{"b"} and \code{"c"}
\item t3: \code{"d"}
}

However, if we also wanted to know the equivalent set for t4, the result
would be:
\itemize{
\item t1: \code{"a"} and \code{"e"}
\item t2: \code{"b"}, \code{"c"} and \code{"e"}
\item t3: \code{"d"} and \code{"e"}
\item t4: \code{"f"}
}

\code{find_equivalents} is a legacy alias for \code{find_equivalent_codes}.
}
