% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/main_pool_arms.R
\name{pool_arms}
\alias{pool_arms}
\title{Pool or split arms in multi-arm trials}
\usage{
pool_arms(x, study_id, pool_side, method = c("pool", "split"), verbose = TRUE)
}
\arguments{
\item{x}{a data.frame in metaConvert wide format (as used by \code{\link{convert_df}}).}

\item{study_id}{character string: column name identifying which rows belong
to the same multi-arm trial.}

\item{pool_side}{character string: column name whose values indicate which
side to pool (\code{"exp"} or \code{"nexp"}) or \code{NA} for single-comparison rows
that should be left unchanged.}

\item{method}{either \code{"pool"} (Cochrane-recommended pooling of summary
statistics) or \code{"split"} (divide the shared arm's sample size).
See details.}

\item{verbose}{logical: whether to print warnings about columns set to NA
and non-identical shared-side values. Default is \code{TRUE}.}
}
\value{
A data.frame suitable for \code{\link{convert_df}}. The
\code{pool_side} column is removed from the output.
}
\description{
Pool or split arms in multi-arm trials
}
\details{
Multi-arm trials create dependency when multiple experimental arms share a
common control group (or vice versa). This function resolves the dependency
before effect size computation with \code{\link{convert_df}}.

With \code{method = "pool"} (recommended), the arms to be pooled are combined
into a single composite arm using Cochrane Handbook formulas (Table 23.3.a):
\itemize{
\item Sample sizes and event counts: summed
\item Means: weighted average by sample size
\item SDs: Cochrane pooling formula
\item SEs: recomputed from pooled SD and pooled n
\item CIs, medians, paired statistics: set to NA (cannot be pooled)
}
Returns one row per multi-arm group.

With \code{method = "split"}, the shared arm's sample size (and event counts)
is divided equally across comparisons. Each comparison retains its own arm
data unchanged, so the output has the same number of rows as the input but
with adjusted sample sizes on the shared side. Simpler but slightly
conservative.
}
\examples{
# Two experimental arms vs one shared control
dat <- data.frame(
  study_id = c("Study1", "Study1", "Study2"),
  pool_side = c("exp", "exp", NA),
  n_exp = c(30, 25, 40),
  n_nexp = c(28, 28, 35),
  mean_exp = c(12.5, 14.2, 10.0),
  mean_sd_exp = c(3.1, 2.8, 4.0),
  mean_nexp = c(10.1, 10.1, 9.5),
  mean_sd_nexp = c(3.0, 3.0, 3.8)
)

# Pool experimental arms into one composite arm
pooled <- pool_arms(dat, study_id = "study_id",
                    pool_side = "pool_side", method = "pool")

# Or split the shared control's sample size
split_dat <- pool_arms(dat, study_id = "study_id",
                       pool_side = "pool_side", method = "split")

}
\references{
Higgins JPT, Thomas J, Chandler J, Cumpston M, Li T, Page MJ, Welch VA
(editors). Cochrane Handbook for Systematic Reviews of Interventions.
Chapter 23, Table 23.3.a.
}
