mexhaz {mexhaz} | R Documentation |
mexhaz function
Description
Fit an (excess) hazard regression model using different shapes for the
baseline hazard (Weibull, piecewise constant, exponential of a B-spline
of degree 1 to 3, exponential of a restricted cubic spline), with the
possibility to include time-dependent effects of variable(s) and a
random effect defined at the cluster level. The function accepts
right-censored and counting process input styles for the follow-up
time. The latter allows the modelling of survival data with delayed
entries. The time-dependent effect of a covariable is modelled by adding
interaction terms between the covariable and a function of time of the
same class as the one used for the baseline hazard (in particular, with
the same knots for piecewise constant hazards; and with the same degree
and the same knots for B-spline or restricted cubic spline
functions). The random effect is assumed to be normally distributed with
mean 0 and standard deviation sigma. The optimisation process uses
adaptive Gaussian quadrature to calculate the cluster-specific marginal
likelihoods. The logarithm of the full marginal likelihood, defined as
the sum of the logarithms of the cluster-specific marginal likelihoods,
is then maximised using an optimisation routine such as nlm
(default) or optim
.
Usage
mexhaz(formula, data, expected = NULL, base = c("weibull",
"exp.bs", "exp.ns", "pw.cst"), degree = 3, knots = NULL,
bound = NULL, n.gleg = 20, init = NULL, random = NULL,
n.aghq = 10, recurrent = FALSE, fnoptim = c("nlm", "optim"), verbose = 0,
method = "Nelder-Mead", iterlim = 10000, numHess = FALSE,
print.level = 1, exactGradHess = TRUE, gradtol =
ifelse(exactGradHess, 1e-8, 1e-6), testInit = TRUE,
keep.data = FALSE, ...)
Arguments
formula |
a formula object, with the response on the left of the In case |
data |
a |
expected |
name of the variable (must be given in quotes) representing the
population (i.e., expected) hazard. By default, |
base |
functional form that should be used to model the baseline
hazard. Selection can be made between the following options:
For the Weibull hazard model, the cumulative hazard is given by the following relationship: H(t,x,z) = lambda*exp(x'b)*t^(rho*exp(z'g)) where lambda and rho are the parameters of the Weibull baseline hazard,
x represent variables with proportional effect (with corresponding
regression coefficients 'b') and z represent variables with
time-dependent effects (with corresponding regression coefficients
'g'). The For the spline-based hazards, it should be noted that the B-spline
and restricted cubic spline bases created internally in the
|
degree |
if |
knots |
if |
bound |
a vector of two numerical values corresponding to the boundary knots
of the spline functions. If |
n.gleg |
if |
init |
vector of initial values. By default for the baseline hazard: if if - if - if - if - if the parameters describing the effects of the covariables are all set to 0; the parameter representing the standard deviation of the random
effect is set to 0.1. In case of failed convergence, if
|
random |
name of the variable to be entered as a random effect (must be given
between quotes), representing the cluster membership. By default,
|
n.aghq |
number of quadrature points used for estimating the
cluster-specific marginal likelihoods by adaptive Gauss-Hermite
quadrature. By default, |
recurrent |
logical value indicating that the dataset
corresponds to recurrent events expressed in calendar time, in which
case the |
fnoptim |
name of the R optimisation procedure used to maximise the
likelihood. Selection can be made between |
verbose |
integer parameter representing the frequency at which the current state
of the optimisation process is displayed. Internally, an 'evaluation' is
defined as an estimation of the log-likelihood for a given vector of
parameters. This means that the number of evaluations is increased each
time the optimisation procedure updates the value of any of the
parameters to be estimated. If |
method |
if |
iterlim |
if |
numHess |
logical value allowing the user to choose between the Hessian returned
by the optimization algorithm (default) or the Hessian estimated by
the |
print.level |
this argument is only used if |
exactGradHess |
logical value allowing the user to decide
whether maximisation of the likelihood should be based on the
analytic gradient and Hessian computed internally (default,
corresponding to |
gradtol |
this argument is only used if |
testInit |
this argument is used only when
|
keep.data |
logical argument determining whether the dataset
should be kept in the object returned by the function: this can be
useful in certain contexts (e.g., to calculate cluster-specific
posterior predictions from a random intercept model) but might create
unnecessarily voluminous objects. The default
value is set to |
... |
represents additional parameters directly passed to |
Value
An object of class mexhaz
containing the following elements:
dataset |
name of the dataset used to fit the model. |
call |
function call on which the model is based. |
formula |
formula part of the call. |
expected |
name of the variable corresponding to the expected
hazard (takes the value |
xlevels |
information concerning the levels of the categorical
variables used in the model (used by |
n.obs.tot |
total number of observations in the dataset. |
n.obs |
number of observations used to fit the model (after exclusion of missing values). |
n.events |
number of events (after exclusion of missing values). |
n.clust |
number of clusters. |
n.time.0 |
number of observations for which the observed follow-up time was equal to 0 (only for right censored type data). |
base |
function used to model the baseline hazard. |
max.time |
maximal observed time in the dataset. |
boundary.knots |
vector of boundary values used to define the B-spline (or natural spline) bases. |
degree |
degree of the B-spline used to model the logarithm of the baseline hazard. |
knots |
vector of interior knots used to define the B-spline (or natural spline) bases. |
names.ph |
names of the covariables with a proportional effect. |
random |
name of the variable defining cluster membership (set to
|
recurrent |
logical value indicating whether the dataset corresponds to recurrent events. |
init |
a vector containing the initial values of the parameters. |
coefficients |
a vector containing the parameter estimates. |
std.errors |
a vector containing the standard errors of the parameter estimates. |
vcov |
the variance-covariance matrix of the estimated parameters. |
gradient |
the gradient of the log-likelihood function evaluated at the estimated parameters. |
hessian |
the Hessian of the log-likelihood function evaluated at the estimated parameters. |
mu.hat |
a |
var.mu.hat |
the covariance matrix of the cluster-specific shrinkage estimators. |
vcov.fix.mu.hat |
a |
data |
original dataset used to fit the model (if
|
n.par |
number of estimated parameters. |
n.gleg |
number of Gauss-Legendre quadrature points used to calculate the cumulative (excess) hazard (only relevant if a B-spline of degree 2 or 3 or a cubic restricted spline was used to model the logarithm of the baseline hazard). |
n.aghq |
number of adaptive Gauss-Hermite quadrature points used to calculate the cluster-specific marginal likelihoods (only relevant if a multi-level model is fitted). |
fnoptim |
name of the R optimisation procedure used to maximise the likelihood. |
method |
optimisation method used by |
code |
code (integer) indicating the status of the optimisation
process (this code has a different meaning for |
loglik |
value of the log-likelihood at the end of the optimisation procedure. |
iter |
number of iterations used in the optimisation process. |
eval |
number of evaluations used in the optimisation process. |
time.elapsed |
total time required to reach convergence. |
Author(s)
Hadrien Charvat, Aurelien Belot
References
Charvat H, Remontet L, Bossard N, Roche L, Dejardin O, Rachet B, Launoy G, Belot A; CENSUR Working Survival Group. A multilevel excess hazard model to estimate net survival on hierarchical data allowing for non-linear and non-proportional effects of covariates. Stat Med 2016;35(18):3066-3084 (doi: 10.1002/sim.6881)
Charvat H, Belot A. An R package for fitting flexible hazard-based regression models for overall and excess mortality with a random effect. J Stat Softw 2021;98(14):1-36 (doi: 10.18637/jss.v098.i14)
See Also
fixef.mexhaz
, predict.mexhaz
, print.mexhaz
,
ranef.mexhaz
, summary.mexhaz
, update.mexhaz
, vcov.mexhaz
Examples
data(simdatn1)
## Fit of a mixed-effect excess hazard model, with the baseline hazard
## described by a Weibull distribution (without covariables)
Mod_weib_mix <- mexhaz(formula=Surv(time=timesurv,
event=vstat)~1, data=simdatn1, base="weibull",
expected="popmrate", verbose=0, random="clust")
## More complex examples (not run)
## Fit of a mixed-effect excess hazard model, with the baseline hazard
## described by a cubic B-spline with two knots at 1 and 5 year and with
## effects of age (agecr), deprivation index (depindex) and sex (IsexH)
# Mod_bs3_2mix_nph <- mexhaz(formula=Surv(time=timesurv,
# event=vstat)~agecr+depindex+IsexH+nph(agecr), data=simdatn1,
# base="exp.bs", degree=3, knots=c(1,5), expected="popmrate",
# random="clust", verbose=1000)
## Fit of a mixed-effect excess hazard model, with the baseline hazard
## described by a restricted cubic spline with two knots at the
## tertiles of the distribution of follow-up times for individuals who
## presented the event and with effects of age (agecr) and sex (IsexH)
# Mod_ns3_2mix_nph <- mexhaz(formula=Surv(time=timesurv,
# event=vstat)~agecr+nph(agecr), data=simdatn1, base="exp.ns", degree=3,
# knots=quantile(simdatn1[simdatn1$vstat==1,]$timesurv, probs=c(1:2/3)),
# expected="popmrate", random="clust", verbose=1000)