% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/calculate_pvc.R
\name{calculate_pvc}
\alias{calculate_pvc}
\title{Calculate Proportional Change in Between-Stratum Variance (PVC)}
\usage{
calculate_pvc(
  model1,
  model2,
  bootstrap = FALSE,
  n_boot = 1000,
  conf_level = 0.95
)
}
\arguments{
\item{model1}{A maihda_model object from \code{fit_maihda()}. This is the
reference model (typically a simpler or baseline model).}

\item{model2}{A maihda_model object from \code{fit_maihda()}. This is the
comparison model (typically a more complex model with additional predictors).}

\item{bootstrap}{Logical indicating whether to compute bootstrap confidence
intervals for PVC. Default is FALSE.}

\item{n_boot}{Number of bootstrap samples if bootstrap = TRUE. Default is 1000.}

\item{conf_level}{Confidence level for bootstrap intervals. Default is 0.95.}
}
\value{
A list containing:
  \item{pvc}{The estimated proportional change in variance}
  \item{var_model1}{Between-stratum variance from model1}
  \item{var_model2}{Between-stratum variance from model2}
  \item{ci_lower}{Lower bound of confidence interval (if bootstrap = TRUE)}
  \item{ci_upper}{Upper bound of confidence interval (if bootstrap = TRUE)}
  \item{bootstrap}{Logical indicating if bootstrap was used}
}
\description{
Calculates the proportional change in between-stratum variance (PVC) between
two MAIHDA models. The PVC measures how much the between-stratum variance
changes when moving from one model to another, and is calculated as:
PVC = (Var_model1 - Var_model2) / Var_model1
}
\details{
The PVC is interpreted as the proportional reduction (or increase if negative)
in between-stratum variance when moving from model1 to model2. A positive PVC
indicates that model2 explains some of the between-stratum variance present in
model1, while a negative PVC suggests that model2 has more unexplained
between-stratum variance.

When bootstrap = TRUE, the function uses a parametric bootstrap: it simulates
new responses from model2 and refits both models with \code{lme4::refit()} for
each simulated response to obtain confidence intervals for the PVC estimate.
}
\examples{
\donttest{
# Create strata and fit two models
strata_result <- make_strata(maihda_sim_data, c("gender", "race"))
model1 <- fit_maihda(health_outcome ~ age + (1 | stratum), data = strata_result$data)
model2 <- fit_maihda(health_outcome ~ age + gender + (1 | stratum), data = strata_result$data)

# Calculate PVC without bootstrap
pvc_result <- calculate_pvc(model1, model2)
print(pvc_result$pvc)

# Calculate PVC with bootstrap CI
# pvc_boot <- calculate_pvc(model1, model2, bootstrap = TRUE, n_boot = 500)
# print(pvc_boot)
}

}
