% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bPET.R
\name{bPET}
\alias{bPET}
\title{Bayesian Precision-Effect Test (PET) Model}
\usage{
bPET(
  yi,
  vi,
  sei,
  weights,
  ni,
  mods,
  scale,
  cluster,
  data,
  slab,
  subset,
  measure,
  prior_effect,
  prior_heterogeneity,
  prior_mods,
  prior_scale,
  prior_heterogeneity_allocation,
  prior_bias,
  standardize_continuous_predictors = TRUE,
  set_contrast_factor_predictors = "treatment",
  prior_unit_information_sd,
  rescale_priors = 1,
  prior_informed_field,
  prior_informed_subfield,
  effect_direction = "detect",
  sample = 5000,
  burnin = 2000,
  adapt = 500,
  chains = 3,
  thin = 1,
  parallel = FALSE,
  autofit = FALSE,
  autofit_control = set_autofit_control(),
  convergence_checks = set_convergence_checks(),
  seed = NULL,
  silent,
  ...
)
}
\arguments{
\item{yi}{a vector of effect sizes, or a formula with the effect size on the
left-hand side and location moderators on the right-hand side (for example
\code{yi ~ x1 + x2}). If a formula is supplied, \code{mods} must not be specified.}

\item{vi}{a vector of sampling variances. Either \code{vi} or \code{sei} must be
supplied for normal models.}

\item{sei}{a vector of standard errors. Either \code{vi} or \code{sei} must be
supplied for normal models.}

\item{weights}{an optional vector of positive likelihood weights. For
normal/effect-size models, each weight powers the estimate likelihood. For
constructors with GLMM raw-count input, each weight powers the paired
two-arm likelihood for one study.}

\item{ni}{an optional vector of sample sizes. Used for \code{measure = "GEN"}
or when estimating \code{"UISD"}).}

\item{mods}{an optional matrix, data.frame, or formula specifying
location moderators (meta-regressors). Formula input is evaluated in \code{data}.}

\item{scale}{an optional matrix, data.frame, or formula specifying
scale predictors for location-scale models. Formula input is evaluated in
\code{data}.}

\item{cluster}{an optional vector of cluster identifiers for multilevel
meta-analysis.}

\item{data}{an optional data frame containing the variables.}

\item{slab}{an optional vector of study labels.}

\item{subset}{an optional logical or numeric vector specifying a subset of
data to be used.}

\item{measure}{a character string specifying the effect size measure.
Normal/effect-size constructors require an explicit value and support
\code{"SMD"}, \code{"ZCOR"}, \code{"RR"}, \code{"OR"}, \code{"HR"}, \code{"RD"}, \code{"IRR"}, and \code{"GEN"}.
Use \code{"GEN"} only for general effect sizes without a known unit information
standard deviation. GLMM raw-count constructors support only \code{"OR"} and
\code{"IRR"} and default to \code{"OR"}.}

\item{prior_effect}{prior distribution for the effect size (\eqn{\mu}) parameter
(the intercept). If omitted, a default prior is constructed. In single-model
functions, explicit \code{NULL} or \code{FALSE} sets a spike at zero.}

\item{prior_heterogeneity}{prior distribution for the heterogeneity (\eqn{\tau})
parameter. If omitted, a default prior is constructed. In single-model
functions, explicit \code{NULL} or \code{FALSE} sets a spike at zero.}

\item{prior_mods}{prior distribution for the moderators (\eqn{\beta}) parameters.
A single prior applies to all terms; a named list can specify term-specific
priors. If omitted or \code{NULL}, default priors are used.}

\item{prior_scale}{prior distribution for the scale (\eqn{\delta}) parameters.
A single prior applies to all terms; a named list can specify term-specific
priors. If omitted or \code{NULL}, default priors are used.}

\item{prior_heterogeneity_allocation}{prior distribution for the fraction of
heterogeneity allocated to the cluster-level component in multilevel models
(\eqn{\rho}). If omitted or \code{NULL}, defaults to \code{Beta(1, 1)}.}

\item{prior_bias}{PET regression-coefficient prior created by
\code{prior_PET()}. If omitted or \code{NULL}, the default is a Cauchy prior
centered at 0, truncated to positive values, with scale from
\code{RoBMA.get_option("default_bias_PET.scale")}.}

\item{standardize_continuous_predictors}{logical. Whether to standardize continuous predictors.
Defaults to \code{TRUE}.}

\item{set_contrast_factor_predictors}{character. How to set contrast for factor predictors.
Defaults are constructor-specific and shown in each function usage; single-model
constructors use \code{"treatment"}, while model-averaging constructors use \code{"meandif"}.}

\item{prior_unit_information_sd}{numeric. The unit information standard deviation (\eqn{\sigma_{unit}}).
Cannot be used together with \code{prior_informed_field}.}

\item{rescale_priors}{numeric. A scaling factor for supported prior distributions.
Point and none priors are unchanged. For constructors with publication-bias
prior distributions, \code{rescale_priors} does not rescale them except for the
default PEESE prior's UISD adjustment. Defaults to 1.}

\item{prior_informed_field}{character. The field of the informed prior distributions.
Omit to use the standard default prior specification; explicit \code{NULL} is invalid.}

\item{prior_informed_subfield}{character. The subfield of the informed prior distributions.
Omit to use the field-specific default, such as \code{"Cochrane"} for
\code{prior_informed_field = "medicine"}; explicit \code{NULL} is invalid.}

\item{effect_direction}{direction used by publication-bias adjustments.
\code{"positive"} assumes statistically significant positive estimates are more
likely to be selected; \code{"negative"} mirrors the selection direction;
\code{"detect"} infers the direction from the fitted data.}

\item{sample}{numeric. Number of MCMC samples to save. Defaults to \code{5000}.}

\item{burnin}{numeric. Number of burn-in iterations. Defaults to \code{2000}.}

\item{adapt}{numeric. Number of adaptation iterations. Defaults to \code{500}.}

\item{chains}{numeric. Number of MCMC chains. Defaults to \code{3}.}

\item{thin}{numeric. Thinning interval. Defaults to \code{1}.}

\item{parallel}{logical. Whether to run MCMC chains in parallel. Defaults to \code{FALSE}.}

\item{autofit}{logical. Whether to automatically extend the MCMC chains if convergence is not met.
Defaults to \code{FALSE}.}

\item{autofit_control}{list of autofit control settings. See \code{\link[=set_autofit_control]{set_autofit_control()}} for details.}

\item{convergence_checks}{list of convergence check settings. See \code{\link[=set_convergence_checks]{set_convergence_checks()}} for details.}

\item{seed}{numeric. Random seed for reproducibility. Defaults to \code{NULL}.}

\item{silent}{logical. Whether to suppress output. Constructors with no
explicit default use \code{RoBMA.get_option("silent")} when \code{silent} is omitted.
Model-averaging wrappers default to \code{TRUE} unless explicitly changed.}

\item{...}{additional advanced arguments. Fitting functions reject unused
arguments; currently recognized internal arguments include \code{only_data},
\code{only_priors}, \code{is_JASP}, and \code{is_JASP_prefix}.}
}
\value{
A fitted object of class \code{c("bPET", "brma")} containing a single
PET publication-bias model fit.
}
\description{
Function for fitting random-effects, meta-regression, multilevel,
and location-scale meta-analytic PET models.
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")

  fit <- bPET(
    yi      = yi,
    vi      = vi,
    data    = dat.lehmann2018,
    measure = "SMD",
    seed    = 1,
    silent  = TRUE
  )

  summary(fit)
  funnel(fit)
}
}

}
\seealso{
\link{publication_bias_prior_specification}, \code{\link[=RoBMA]{RoBMA()}}, \code{\link[=bPEESE]{bPEESE()}},
\code{\link[=bselmodel]{bselmodel()}}, \code{\link[=summary.brma]{summary.brma()}}, \code{\link[=funnel.brma]{funnel.brma()}}
}
