% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calculate_overlap.R
\name{calculate_overlap}
\alias{calculate_overlap}
\title{Calculate Inter-Rater Agreement Across Multiple Datasets}
\usage{
calculate_overlap(datasets, alpha = FALSE, key_cols = NULL)
}
\arguments{
\item{datasets}{List. A list of data frames to compare. Each data frame should
have the same column structure with variable columns (Var1, Var2, etc.).}

\item{alpha}{Logical. If TRUE, also compute Krippendorff's Alpha (nominal)
for each variable across the provided datasets. Defaults to FALSE.}

\item{key_cols}{Character vector or NULL. Column name(s) used to match rows
across datasets. Use this when datasets have different row counts due to a
compound row identity (e.g. \code{key_cols = c("Var1", "Var3")}). Rows with
NA in any key column are dropped before matching. When NULL (default), rows
are matched on the first column only, which is the standard behaviour for
single-response output from \code{parallel_execute()}.}
}
\value{
Matrix. If alpha = FALSE: one-row matrix with average percentage
agreement for each variable (columns), rounded to 2 decimals.
If alpha = TRUE: two-row matrix with row "Overlap" (percent agreement)
and row "Alpha" (Krippendorff's Alpha for nominal data), rounded
to 3 decimals for Alpha.
}
\description{
This function calculates the percentage overlap (agreement) between multiple
datasets containing the same variables. It's designed to assess reliability
and consistency when the same data is processed multiple times or by different
systems/raters.
}
\details{
The function performs comprehensive overlap analysis:
\itemize{
\item Finds common rows across all datasets based on \code{key_cols}
\item Aligns and sorts datasets by the key before comparing
\item Calculates pairwise agreement for all possible dataset combinations
\item Computes variable-wise agreement percentages
\item Returns average agreement across all dataset pairs
}

Agreement is calculated as the percentage of cases where values match exactly.
The number of rows used in the comparison is printed as a message (\code{N = ...}).
}
\examples{
\dontrun{
# Standard use: compare two processing runs (single-response output)
run1 <- parallel_execute(my_data, slicing_n = 100, cores = 4)
run2 <- parallel_execute(my_data, slicing_n = 100, cores = 4)
calculate_overlap(list(run1, run2))

# Multi-response output: datasets may differ in row count;
# match on compound key (e.g. speech ID + paragraph number)
calculate_overlap(list(run1, run2), key_cols = c("Var1", "Var3"))
}

}
\seealso{
\code{\link[=parallel_execute]{parallel_execute()}}
}
