% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/conditional_effects.R
\name{conditional_effects}
\alias{conditional_effects}
\title{Conditional treatment effects}
\usage{
conditional_effects(
  object,
  newdata = NULL,
  effect = "all",
  summary = TRUE,
  probs = c(0.025, 0.5, 0.975)
)
}
\arguments{
\item{object}{An \code{mlumr_fit} object}

\item{newdata}{Data frame of covariate values at which to compute effects.
Each row defines one covariate profile. Column names must match the
covariates used in fitting. If \code{NULL} (default), uses the covariate means
from the IPD as a single reference profile.}

\item{effect}{Which effect measure. For binomial: \code{"all"}, \code{"link_effect"},
\code{"rd"}, or \code{"rr"}. For normal: \code{"all"} or \code{"md"}. For Poisson: \code{"all"}
or \code{"rr"}. The legacy value \code{"lor"} is accepted as an alias for
\code{"link_effect"} when the fitted link is logit.}

\item{summary}{Return summary statistics (\code{TRUE}) or full posterior draws
(\code{FALSE})}

\item{probs}{Quantiles for summary (default \code{c(0.025, 0.5, 0.975)})}
}
\value{
A data frame. If \code{summary = TRUE}, contains columns \code{profile},
\code{effect}, \code{mean}, \code{sd}, and quantile columns. If \code{summary = FALSE},
returns a single combined data frame of full posterior draws with a
\code{profile} column indicating which covariate profile each draw belongs
to.
}
\description{
Compute conditional (individual-level) treatment effects at specific
covariate values from a fitted ML-UMR model. Unlike \code{\link[=marginal_effects]{marginal_effects()}},
which averages over a population's covariate distribution, conditional
effects evaluate the treatment effect at a particular covariate profile.
}
\details{
For SPFA models, the conditional link-scale treatment effect is constant
across all covariate values because the shared beta cancels in the treatment
contrast on the fitted link scale. However, risk difference (RD) and risk
ratio (RR) still vary with covariates because they depend on absolute
probability levels. For relaxed models, all conditional effects vary with
covariate values because the index and comparator treatments have different
regression coefficients.

The conditional link-scale effect is computed directly as
\code{eta_index - eta_comparator}. This avoids numerical distortion from
transforming extreme response-scale probabilities back through the link
function.

\strong{Conditional vs marginal on non-identity links.} Conditional effects are
evaluated at a single covariate profile, so there is no averaging over a
population and no Jensen's-inequality gap between the conditional and
marginal response. Compare with \code{\link[=marginal_effects]{marginal_effects()}} and
\code{\link[=predict.mlumr_fit]{predict.mlumr_fit()}}, which average over either the IPD individuals
(index population) or the AgD integration points (comparator population)
and therefore return \code{E[g^{-1}(eta)]}, not \code{g^{-1}(E[eta])}.
}
\examples{
\dontrun{
# Conditional effects at IPD covariate means (default)
conditional_effects(fit)

# At specific covariate values
conditional_effects(fit, newdata = data.frame(age = 60, sex = 1))

# Multiple profiles
profiles <- data.frame(age = c(50, 60, 70), sex = c(0, 0, 1))
conditional_effects(fit, newdata = profiles)
}
}
\seealso{
\code{\link[=marginal_effects]{marginal_effects()}} for population-averaged treatment effects;
\code{\link[=conditional_predict]{conditional_predict()}} for absolute predictions at specific profiles;
\code{\link[=predict.mlumr_fit]{predict.mlumr_fit()}} for population-level predictions.
}
