% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/main-interface.R
\name{icc_calc}
\alias{icc_calc}
\title{Calculate Intraclass Correlation Coefficient (ICC)}
\usage{
icc_calc(
  data,
  same_raters,
  rater_effect = NULL,
  rating_type,
  agreement_type = NULL,
  alpha = 0.05,
  rho0 = NULL,
  interaction = TRUE,
  na.rm = TRUE,
  verbose = TRUE
)
}
\arguments{
\item{data}{Data frame or matrix. Raw data where rows = subjects,
columns = raters/measurements.}

\item{same_raters}{Logical. Are all subjects measured by the same group
of raters?}

\item{rater_effect}{Character. "random" or "fixed". Ignored if
\code{same_raters = FALSE}.}

\item{rating_type}{Character. "single" (single rating) or "average"
(average of k ratings).}

\item{agreement_type}{Character. "absolute" (absolute agreement) or
"consistency" (consistency). Ignored if \code{same_raters = FALSE}.}

\item{alpha}{Numeric. Significance level for confidence interval,
default 0.05.}

\item{rho0}{Numeric. Optional null hypothesis value for non-zero test,
default NULL.}

\item{interaction}{Logical. Whether to include interaction term in
two-way models, default TRUE.}

\item{na.rm}{Logical. Whether to automatically remove rows with missing
values, default TRUE.}

\item{verbose}{Logical. Whether to emit warnings and tips, default TRUE.}
}
\value{
A named list containing:
\describe{
  \item{data_summary}{List. Data preprocessing summary.}
  \item{icc_result}{List. Full ICC calculation results.}
  \item{evaluation}{List. Reliability evaluation results.}
  \item{report}{Character. Standardized report text.}
  \item{warning_msg}{Character or NULL. Warning message.}
  \item{tip_msg}{Character or NULL. Tip message.}
}
}
\description{
Top-level main function for complete ICC analysis. Users only need to
provide raw data and answer 4 design questions. The function automatically
handles data preprocessing, parameter validation, ICC type mapping,
core calculation, reliability evaluation, and report generation.
}
\examples{
# Example 0: Use built-in example dataset
data(icc_data)
result <- icc_calc(icc_data, same_raters = TRUE, rater_effect = "random",
                   rating_type = "single", agreement_type = "absolute")
# Example 1: One-way random effects, single rating (ICC(1,1))
data <- matrix(rnorm(100), nrow = 20, ncol = 5)
result <- icc_calc(data, same_raters = FALSE, rating_type = "single")

# Example 2: Two-way random effects, average rating, absolute agreement (ICC(2,k))
result <- icc_calc(data, same_raters = TRUE, rater_effect = "random",
                   rating_type = "average", agreement_type = "absolute")

# Example 3: Two-way mixed effects, single rating, consistency (ICC(3,1))
result <- icc_calc(data, same_raters = TRUE, rater_effect = "fixed",
                   rating_type = "single", agreement_type = "consistency")

# Example 4: Special scenario - automatic mapping with tip
# Random effects + consistency (automatically mapped to ICC(3,1))
result <- icc_calc(data, same_raters = TRUE, rater_effect = "random",
                   rating_type = "single", agreement_type = "consistency")

# Example 5: Special scenario - not recommended combination with warning
# Fixed effects + absolute agreement (NOT RECOMMENDED)
result <- icc_calc(data, same_raters = TRUE, rater_effect = "fixed",
                   rating_type = "average", agreement_type = "absolute")

# Example 6: Advanced parameters - custom alpha and non-zero test
result <- icc_calc(data, same_raters = TRUE, rater_effect = "random",
                   rating_type = "single", agreement_type = "absolute",
                   alpha = 0.1, rho0 = 0.6, verbose = FALSE)

# Example 7: Extract specific results
result$icc_result$point_est  # ICC point estimate
result$evaluation$rating_en  # Reliability rating
result$report               # Full text report
}
\references{
McGraw, K. O., & Wong, S. P. (1996). Forming inferences about some
intraclass correlation coefficients. Psychological Methods, 1(1), 30-46.

Koo, T. K., & Li, M. Y. (2016). A guideline of selecting and reporting
intraclass correlation coefficients for reliability research. Journal of
Chiropractic Medicine, 15(2), 155-163.
}
