% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/predict.R
\name{predict.brma}
\alias{predict.brma}
\title{Predict From brma Object}
\usage{
\method{predict}{brma}(
  object,
  newdata = NULL,
  type = "terms",
  as_measure = TRUE,
  output_measure = NULL,
  transform = NULL,
  probs = c(0.025, 0.975),
  bias_adjusted = FALSE,
  quiet = FALSE,
  conditional = FALSE,
  ...
)
}
\arguments{
\item{object}{a fitted brma object}

\item{newdata}{specification for prediction data. Defaults to \code{NULL} which
corresponds to prediction for the observed data. Alternatives are:
\itemize{
\item{\code{TRUE} returns a single aggregated prediction (either the scalar
parameter for models without moderators/scale, or the average across the
model matrix for regression models). Not available for \code{type = "response"}
since observation-level sampling variance is required.}
\item{A data.frame (for meta-regression) or a named list with effect size
measure and variability metrics (for meta-analysis) for new studies. The input
must contain the variables used by the requested prediction type. Outcome
columns are optional for \code{type = "terms"} unless PET/PEESE bias terms
are included via \code{bias_adjusted = FALSE}.}
}}

\item{type}{type of prediction to be performed. Options are:
\itemize{
\item{\code{"terms"} (alias: \code{"marginal"}): Fixed-effect parameters only (mu).
Produces the mean effect size estimate at the given predictor levels,
not accounting for random effects.}
\item{\code{"cluster"}: Fixed effects plus cluster-level random effects (mu + gamma).
Only available for multilevel (3-level) models.}
\item{\code{"estimate"} (aliases: \code{"effect"}, \code{"blup"}): True
effects (mu + gamma + theta). For existing normal data, returns posterior
draws of conditional BLUP means, not simulated latent-effect draws. For
new data, samples estimate-level random effects.}
\item{\code{"response"} (alias: \code{"outcome"}): Predicted observed values (yi).
Incorporates both heterogeneity and sampling variability.}
\item{\code{"terms.scale"}: Scale parameter (tau), incorporating scale
regression if present.}
}}

\item{as_measure}{logical; whether to convert GLMM response predictions from
simulated counts to continuity-corrected effect-size estimators (logOR for
binomial, logIRR for Poisson). Defaults to \code{TRUE}. Only relevant for
GLMM models with \code{type = "response"}. When \code{FALSE}, returns raw
frequency data (counts). Use \code{type = "estimate"} for latent logOR/logIRR
predictions.}

\item{output_measure}{effect-size measure for location/effect predictions.
Defaults to the fitted measure. Supported conversions are among \code{"SMD"},
\code{"COR"}, \code{"ZCOR"}, and \code{"OR"}; \code{"RR"}, \code{"HR"},
\code{"IRR"}, \code{"RD"}, and \code{"GEN"} can only be returned on their
fitted measure. Use \code{transform = "EXP"} for ratio-scale output from
log-scale measures.}

\item{transform}{optional display transformation. Currently \code{"EXP"}
exponentiates log-scale measures \code{"OR"}, \code{"RR"}, \code{"HR"},
and \code{"IRR"}.}

\item{probs}{quantiles of the posterior samples to be displayed when the
returned \code{brma_samples} object is printed. Defaults to \code{c(.025, .975)}.}

\item{bias_adjusted}{whether predictions should adjust for publication bias.
Defaults to \code{FALSE}. When \code{TRUE}:
\itemize{
\item{PET/PEESE terms are NOT added to the mean parameter (mu), returning
the bias-corrected effect estimate.}
\item{For \code{type = "response"} with selection models, samples from
the ordinary normal predictive distribution instead of the selected-normal
distribution, simulating what would be observed without publication bias.}
}
When \code{FALSE}:
\itemize{
\item{PET/PEESE terms ARE added to mu, returning predictions that include
the expected bias (i.e., what we expect to observe given publication bias).}
\item{For \code{type = "response"} with selection models, samples from
the selected-normal distribution reflecting the selective publishing
process.}
}}

\item{quiet}{logical; whether to suppress informational messages about
prediction scale and bias adjustment.}

\item{conditional}{whether to return conditional posterior predictions for
RoBMA product-space objects. For location predictions, samples are conditioned
on the effect component; for \code{type = "terms.scale"}, samples are
conditioned on the heterogeneity component. Conditional samples are flattened
to one chain after subsetting posterior rows.}

\item{...}{additional arguments}
}
\value{
A \code{brma_samples} object containing posterior samples. When printed,
displays a summary table via \code{BayesTools::ensemble_estimates_table}. The
underlying samples matrix can be accessed directly (the object inherits from matrix)
or via \code{summary()} to obtain the summary table. The samples can also be converted
to \pkg{posterior} draws formats using \code{as_draws()} and related functions.
}
\description{
\code{predict.brma} predicts values
}
\details{
\strong{Type hierarchy:}
\itemize{
\item{\code{"terms"}: mu (fixed effects only)}
\item{\code{"cluster"}: mu + gamma (adds cluster-level random effect)}
\item{\code{"estimate"}: mu + gamma + theta (adds estimate-level random effect)}
\item{\code{"response"}: mu + gamma + theta + epsilon (adds sampling error)}
}
For existing normal observations, \code{type = "estimate"} reports the
conditional BLUP mean \eqn{E(\theta_i \mid y_i, \mu_i, \tau_i)} for each
posterior draw. It is therefore an empirical-Bayes summary, not a draw from
the full latent-effect posterior \eqn{\theta_i \mid y_i}. For new data,
estimate-level random effects are sampled from their model distribution.

For RoBMA product-space objects, conditional posterior predictions subset
posterior rows according to model indicators. This removes the original
chain structure, so returned \code{brma_samples} objects are intentionally
stored as one flattened chain.

Note that in contrast to \link[metafor]{predict}, the \code{type = "response"} produces
predictions for the new effect size estimates. To obtain results corresponding to
metafor's predict function, use \code{type = "terms"} for the mean effect size
and \code{type = "estimate"} for true effects (prediction interval).

\strong{Likelihood weights:} If the model was fitted with \code{weights},
the weights affect the posterior fit, log-likelihood, LOO/WAIC, and
existing-data conditional diagnostics such as BLUP shrinkage and leverage.
They do not change the observation-level sampling error used by
\code{type = "response"} for normal models: response predictions simulate
raw future effect-size estimates with the supplied \code{sei}, not
\code{sei / sqrt(weight)}.
}
\examples{
\dontrun{
if (requireNamespace("metadat", quietly = TRUE) &&
    requireNamespace("metafor", quietly = TRUE)) {
  data(dat.bcg, package = "metadat")
  dat <- metafor::escalc(
    measure = "RR",
    ai      = tpos,
    bi      = tneg,
    ci      = cpos,
    di      = cneg,
    data    = dat.bcg
  )

  fit <- brma(
    yi      = yi,
    vi      = vi,
    mods    = ~ ablat + year,
    data    = dat,
    measure = "RR",
    seed    = 1,
    silent  = TRUE
  )

  predict(fit, type = "terms")
  predict(fit, newdata = TRUE, type = "terms")
  predict(fit, type = "estimate")
}
}

}
\seealso{
\code{\link[=pooled_effect]{pooled_effect()}}, \code{\link[=pooled_heterogeneity]{pooled_heterogeneity()}}, \code{\link[=blup]{blup()}}
}
