% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hazard_api.R
\name{predict.hazard}
\alias{predict.hazard}
\title{Predict from a hazard model object}
\usage{
\method{predict}{hazard}(
  object,
  newdata = NULL,
  type = c("hazard", "linear_predictor", "survival", "cumulative_hazard"),
  decompose = FALSE,
  se.fit = FALSE,
  level = 0.95,
  conf.type = c("log-log", "logit"),
  ...
)
}
\arguments{
\item{object}{A \code{hazard} object.}

\item{newdata}{Optional matrix or data frame of predictors. For types requiring
time (e.g., "survival", "cumulative_hazard"), newdata should include a \code{time}
column, or time will be taken from the fitted object's data.}

\item{type}{Prediction type:
\itemize{
\item \code{"linear_predictor"}: Linear predictor eta = x*beta (not available for multiphase)
\item \code{"hazard"}: Instantaneous hazard. Single-distribution models return the
hazard scale exp(eta); multiphase models return the additive hazard
h(t|x) = sum_j mu_j(x) phi_j'(t) and so require time values (like
\code{"survival"}/\code{"cumulative_hazard"}). \code{decompose} is not supported for
\code{"hazard"}.
\item \code{"survival"}: Survival probability S(t|x) = exp(-H(t|x))
\item \code{"cumulative_hazard"}: Cumulative hazard H(t|x) at event times
}}

\item{decompose}{Logical; if \code{TRUE} and the model is multiphase, return a
data frame with per-phase cumulative hazard contributions alongside the
total.  Ignored for single-distribution models.  Default \code{FALSE}.}

\item{se.fit}{Logical; if \code{TRUE}, compute delta-method standard errors and
confidence limits for each prediction.  The return value becomes a data
frame with columns \code{fit}, \code{se.fit}, \code{lower}, \code{upper}.  Default \code{FALSE}.
CLs are computed on the log-hazard / log-cumhaz scale and on the
log(-log(survival)) scale so lower/upper stay inside the valid range
of each prediction type; \code{linear_predictor} uses symmetric natural-scale
CLs.
For multiphase models, \code{se.fit = TRUE} combines with \code{decompose = TRUE}
when \code{type = "cumulative_hazard"}: the result is a long data frame with one
row per prediction time and component (\code{component} in \code{"total"} plus each
phase name) and columns \code{fit}, \code{se.fit}, \code{lower}, \code{upper}. Per-phase CLs
use only that phase's parameters, so they do not sum to the total CL.
The combination is not available for \code{type = "survival"} (per-phase
survival is not additive).}

\item{level}{Numeric confidence level in \verb{(0, 1)}; default \code{0.95}.
Only used when \code{se.fit = TRUE}.}

\item{conf.type}{Transform for \code{type = "survival"} confidence limits when
\code{se.fit = TRUE}: \code{"log-log"} (default) builds them on \verb{log(-log S)} (the
\code{survival::survfit} standard); \code{"logit"} builds them on \code{logit(1 - S)},
reproducing SAS HAZARD's \code{HAZPRED} survival limits. Other types are
unaffected (hazard/cumulative-hazard use a log scale that already matches
HAZPRED). Only used when \code{se.fit = TRUE}.}

\item{...}{Unused; included for S3 compatibility.}
}
\value{
When \code{se.fit = FALSE} (default), a numeric vector of predictions.
When \code{se.fit = TRUE}, a data frame with columns \code{fit}, \code{se.fit}, \code{lower},
\code{upper} (delta-method point estimate, standard error, and confidence
limits at \code{level}). For multiphase \code{type = "cumulative_hazard"} with
\code{decompose = TRUE}, a long data frame (\code{time}, \code{component}, \code{fit},
\code{se.fit}, \code{lower}, \code{upper}); with \code{decompose = TRUE} and \code{se.fit = FALSE},
a wide data frame of per-phase contributions.
}
\description{
Produces prediction outputs from a \code{hazard} object. Supports multiple prediction
types including linear predictor, hazard, survival probability, and cumulative hazard.
}
\details{
For Weibull models with survival or cumulative_hazard predictions:
\itemize{
\item Cumulative hazard: H(t|x) = (mu*t)^nu * exp(eta)
\item Survival: S(t|x) = exp(-H(t|x))
}

Time values must be positive and finite. If newdata contains a \code{time} column,
it will be used; otherwise, the time vector from the fitted object is used.
For models fit with \code{time_windows}, predictions for \code{type = "linear_predictor"}
or \code{"hazard"} also require time values (via \code{newdata$time} or fitted-time fallback)
so window-specific coefficients can be selected.
}
\examples{
# -- Basic predictions ------------------------------------------------
set.seed(1)
fit <- hazard(time = rexp(50, 0.3), status = rep(1L, 50),
              theta = c(0.3, 1.0), dist = "weibull", fit = TRUE)
predict(fit, type = "survival")
predict(fit, newdata = data.frame(time = c(1, 2, 5)),
        type = "cumulative_hazard")

# -- Patient-specific survival curves ---------------------------------
set.seed(1001)
n   <- 180
dat <- data.frame(
  time   = rexp(n, rate = 0.35) + 0.05,
  status = rbinom(n, size = 1, prob = 0.6),
  age    = rnorm(n, mean = 62, sd = 11),
  nyha   = sample(1:4, n, replace = TRUE),
  shock  = rbinom(n, size = 1, prob = 0.18)
)
fit2 <- hazard(
  survival::Surv(time, status) ~ age + nyha + shock,
  data  = dat,
  theta = c(mu = 0.25, nu = 1.10, beta1 = 0, beta2 = 0, beta3 = 0),
  dist  = "weibull", fit = TRUE
)

new_patients <- data.frame(
  time = c(0.5, 1.5, 3.0),
  age  = c(50, 65, 75),
  nyha = c(1, 3, 4),
  shock = c(0, 0, 1)
)
# Compute predictions from the clean covariate frame before adding columns
surv   <- predict(fit2, newdata = new_patients, type = "survival")
cumhaz <- predict(fit2, newdata = new_patients, type = "cumulative_hazard")
new_patients$survival          <- surv
new_patients$cumulative_hazard <- cumhaz
new_patients

\donttest{
# -- Grouped survival curves ---------------------------------------
if (requireNamespace("ggplot2", quietly = TRUE)) {
  library(ggplot2)

  t_grid <- seq(0.05, max(dat$time), length.out = 80)
  profiles <- data.frame(
    label = c("Low risk (age 50, NYHA I)",
              "High risk (age 75, NYHA IV)"),
    age   = c(50, 75),
    nyha  = c(1, 4),
    shock = c(0, 1)
  )

  curve_list <- lapply(seq_len(nrow(profiles)), function(i) {
    nd <- data.frame(
      time  = t_grid,
      age   = profiles$age[i],
      nyha  = profiles$nyha[i],
      shock = profiles$shock[i]
    )
    nd$survival <- predict(fit2, newdata = nd, type = "survival") * 100
    nd$profile  <- profiles$label[i]
    nd
  })
  curve_df <- do.call(rbind, curve_list)

  ggplot(curve_df, aes(time, survival, colour = profile)) +
    geom_line() +
    scale_y_continuous(limits = c(0, 100)) +
    labs(x = "Months after surgery",
         y = "Freedom from death (\%)",
         title = "Predicted survival by risk profile",
         colour = NULL) +
    theme_minimal()
}
}

\donttest{
# -- Multiphase predictions with decomposition --------------------
set.seed(42)
n   <- 200
dat <- data.frame(
  time   = rexp(n, rate = 0.25) + 0.01,
  status = rbinom(n, size = 1, prob = 0.65)
)
fit_mp <- hazard(
  survival::Surv(time, status) ~ 1,
  data   = dat,
  dist   = "multiphase",
  phases = list(
    early = hzr_phase("cdf", t_half = 0.5, nu = 2, m = 0,
                       fixed = "shapes"),
    late  = hzr_phase("cdf", t_half = 5,   nu = 1, m = 0,
                       fixed = "shapes")
  ),
  fit     = TRUE,
  control = list(n_starts = 5, maxit = 1000)
)

t_grid <- seq(0.01, max(dat$time) * 0.9, length.out = 100)
nd     <- data.frame(time = t_grid)

# Overall survival
predict(fit_mp, newdata = nd, type = "survival")

# Per-phase decomposed cumulative hazard
decomp <- predict(fit_mp, newdata = nd,
                  type = "cumulative_hazard", decompose = TRUE)
head(decomp)
}

}
\seealso{
\code{\link[=hazard]{hazard()}} for model fitting,
\code{\link[=summary.hazard]{summary.hazard()}} for model summaries,
\code{\link[=hzr_phase]{hzr_phase()}} for multiphase temporal shapes.

\code{vignette("prediction-visualization")} for detailed prediction
workflows including decomposed hazard plots and patient-specific curves.
}
