% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mlumr.R
\name{mlumr}
\alias{mlumr}
\title{Fit ML-UMR Model}
\usage{
mlumr(
  data,
  model = c("spfa", "relaxed"),
  link = NULL,
  prior_intercept = default_prior_intercept(),
  prior_beta = default_prior_beta(),
  prior_sigma = default_prior_sigma(),
  chains = 4,
  iter = 2000,
  warmup = 1000,
  seed = NULL,
  adapt_delta = 0.95,
  max_treedepth = 15,
  refresh = 200,
  engine = NULL,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{data}{An \code{mlumr_data} object with integration points (from
\code{\link[=add_integration]{add_integration()}})}

\item{model}{Model type: \code{"spfa"} (shared prognostic factor assumption) or
\code{"relaxed"} (treatment-specific coefficients). Default \code{"spfa"}.}

\item{link}{Link function. For binomial: \code{"logit"} (default), \code{"probit"},
or \code{"cloglog"}. For normal: \code{"identity"} (default) or \code{"log"}. For
poisson: \code{"log"} (default, only option). If \code{NULL}, uses the canonical
default for the family.}

\item{prior_intercept}{Prior for treatment intercepts. Default from
\code{\link[=default_prior_intercept]{default_prior_intercept()}} (\code{prior_normal(0, 10)}, weakly informative
on the linear-predictor scale). See \code{\link[=prior_normal]{prior_normal()}} for guidance.}

\item{prior_beta}{Prior for regression coefficients. May be a single
prior broadcast to all covariates, or a \code{list} of priors of length
\code{n_cov} for per-coefficient specification. All per-coefficient priors
must share the same family and (for Student-t) df. Default from
\code{\link[=default_prior_beta]{default_prior_beta()}} (\code{prior_normal(0, 2.5)}; Gelman et al. 2008;
Stan community prior-choice wiki). Set \code{autoscale = TRUE} on the
prior to divide the scale by each covariate's empirical SD — useful
when predictors are on very different scales.}

\item{prior_sigma}{Prior for residual SD (normal family only). Default
from \code{\link[=default_prior_sigma]{default_prior_sigma()}} (\code{prior_normal(0, 2.5)}, half-normal via
the Stan \verb{<lower=0>} constraint). \code{\link[=prior_exponential]{prior_exponential()}} is also
supported for sigma.}

\item{chains}{Number of MCMC chains (default 4)}

\item{iter}{Total iterations per chain (default 2000)}

\item{warmup}{Number of warmup iterations (default 1000)}

\item{seed}{Random seed for reproducibility}

\item{adapt_delta}{Target acceptance rate (default 0.95)}

\item{max_treedepth}{Maximum tree depth for NUTS (default 15)}

\item{refresh}{How often to print progress (0 = silent, default 200)}

\item{engine}{Stan backend: \code{"rstan"} (default) or \code{"cmdstanr"}. If \code{NULL},
uses the engine set by \code{\link[=mlumr_engine]{mlumr_engine()}}. See \code{\link[=mlumr_engine]{mlumr_engine()}} for setup.}

\item{verbose}{Logical; if \code{FALSE}, suppresses mlumr progress messages.
Stan sampler progress is still controlled by \code{refresh}.}

\item{...}{Additional arguments passed to the Stan sampling function
(\code{\link[rstan:sampling]{rstan::sampling()}} or cmdstanr's \verb{$sample()} method)}
}
\value{
An object of class \code{mlumr_fit}
}
\description{
Fit a Bayesian multilevel unanchored meta-regression model using individual
patient data (IPD) and aggregate data (AgD). Supports binary, continuous,
and count outcomes.
}
\details{
The model assumes that all AgD rows come from the same comparator treatment
and that, conditional on covariates, there is no between-study heterogeneity.
If AgD rows come from multiple studies with different designs or unmeasured
confounders, this assumption may not hold. No random effects for study-level
heterogeneity are included.

\strong{AgD scale assumptions (family = \code{"normal"}).} The AgD likelihood is
\code{y_agd ~ normal(E[exp(eta)], se_agd)} under \code{link = "log"} and
\code{y_agd ~ normal(E[eta], se_agd)} under \code{link = "identity"}. In both
cases \code{set_agd()} expects \code{outcome_mean} and \code{outcome_se} on the
\strong{arithmetic (original, untransformed) scale}, not log-scale or
geometric. Passing log-scale summaries silently misspecifies the
likelihood. See \code{\link[=set_agd]{set_agd()}} for details.

\strong{Comparator-population weighting is family-dependent.} Integrated
marginal predictions in the comparator population (\verb{*_comparator}
generated quantities) are weighted by:
\itemize{
\item \strong{binomial}: \code{n_agd[k]} (AgD sample size), so larger
AgD rows contribute more to the marginal mean.
\item \strong{normal}: equal weights across AgD rows (\verb{/ n_agd_rows}),
reflecting the normal likelihood's treatment of each row as a
single summary statistic.
\item \strong{poisson}: \code{E_agd[k]} (AgD exposure), matching the
rate-based likelihood.
}
Each weighting is natural for the corresponding likelihood; users
comparing marginal effects across families should be aware they are
not identically weighted.

\strong{Weakly-identified coefficients in the relaxed model} —
\code{beta_comparator} is identified only through AgD, so the relaxed
model needs informative priors (or many AgD rows) to estimate
effect modification reliably. \code{\link[=prior_sensitivity]{prior_sensitivity()}} is the
recommended diagnostic.
}
\examples{
\dontrun{
# Binary SPFA model
fit_spfa <- mlumr(dat, model = "spfa")

# Relaxed SPFA (allows effect modification)
fit_relaxed <- mlumr(dat, model = "relaxed")
}
}
\seealso{
\code{\link[=prior_sensitivity]{prior_sensitivity()}} for sensitivity of the posterior
to \code{prior_beta}; \code{\link[=set_agd]{set_agd()}} for AgD scale requirements;
\code{\link[=prior_summary]{prior_summary()}} for introspection of the priors actually used.
}
