% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/twostage.R
\name{survival_twostage}
\alias{survival_twostage}
\alias{twostage_aalen}
\alias{twostage_cox.aalen}
\alias{twostage_coxph}
\alias{twostage_phreg}
\alias{randomDes}
\alias{readmargsurv}
\title{Twostage Survival Model for Multivariate Survival Data}
\usage{
survival_twostage(
  margsurv,
  data = NULL,
  method = "nr",
  detail = 0,
  clusters = NULL,
  silent = 1,
  weights = NULL,
  theta = NULL,
  theta.des = NULL,
  var.link = 1,
  baseline.iid = 1,
  model = "clayton.oakes",
  marginal.trunc = NULL,
  marginal.survival = NULL,
  strata = NULL,
  se.clusters = NULL,
  numDeriv = 1,
  random.design = NULL,
  pairs = NULL,
  dim.theta = NULL,
  numDeriv.method = "simple",
  additive.gamma.sum = NULL,
  var.par = 1,
  no.opt = FALSE,
  ...
)
}
\arguments{
\item{margsurv}{Marginal model object.}

\item{data}{Data frame (must be given).}

\item{method}{Scoring method: \code{"nr"} for lava NR optimizer.}

\item{detail}{Detail level for output.}

\item{clusters}{Cluster variable.}

\item{silent}{Debug information level.}

\item{weights}{Weights for score equations.}

\item{theta}{Starting values for variance components.}

\item{theta.des}{Design for dependence parameters; when pairs are given, the indices of the
theta-design for this pair are given in pairs as column 5.}

\item{var.link}{Link function for variance: 1 for exponential link.}

\item{baseline.iid}{To adjust for baseline estimation, using \code{phreg} function on same data.}

\item{model}{Model type: \code{"clayton.oakes"} or \code{"plackett"}.}

\item{marginal.trunc}{Marginal left truncation probabilities.}

\item{marginal.survival}{Optional vector of marginal survival probabilities.}

\item{strata}{Strata for fitting (see examples).}

\item{se.clusters}{Clusters for SE calculation with IID.}

\item{numDeriv}{To get numDeriv version of second derivative; otherwise uses sum of squared scores for each pair.}

\item{random.design}{Random effect design for additive gamma model; when pairs are given, the indices of the
pairs' random.design rows are given as columns 3:4.}

\item{pairs}{Matrix with rows of indices (two-columns) for the pairs considered in the pairwise
composite score; useful for case-control sampling when marginal is known.}

\item{dim.theta}{Dimension of the theta parameter for pairs situation.}

\item{numDeriv.method}{Method for numerical derivative (e.g., \code{"simple"} to speed up things).}

\item{additive.gamma.sum}{For \code{two.stage=0}, this is specification of the \code{lamtot} in the models via
a matrix that is multiplied onto the parameters theta (dimensions = number of random effects \eqn{\times} number of theta parameters);
when \code{NULL}, sums all parameters.}

\item{var.par}{Is 1 for the default parametrization with the variances of the random effects;
\code{var.par=0} specifies that the \eqn{\lambda_j}'s are used as parameters.}

\item{no.opt}{For not optimizing.}

\item{...}{Additional arguments to maximizer NR of lava.}
}
\value{
An object of class \code{"mets.twostage"} containing:
\item{theta}{Estimated dependence parameters.}
\item{coef}{Coefficients.}
\item{score}{Score vector.}
\item{hess}{Hessian matrix.}
\item{hessi}{Inverse Hessian matrix.}
\item{var.theta}{Variance of theta parameters.}
\item{robvar.theta}{Robust variance of theta parameters.}
\item{loglike}{Log-likelihood value.}
\item{theta.iid}{Influence functions for theta.}
\item{model}{Model type used.}
}
\description{
Fits Clayton-Oakes or bivariate Plackett models for bivariate survival data
using marginals that are on Cox form. The dependence can be modelled via:
\enumerate{
\item Regression design on dependence parameter.
\item Random effects, additive gamma model.
}
}
\details{
If clusters contain more than two subjects, a composite likelihood based on
pairwise bivariate models is used (for full MLE see \code{twostageMLE}).

The two-stage model is constructed such that, given gamma distributed random effects,
the survival functions are assumed independent, and the marginal survival functions
are on Cox form:
\deqn{ P(T > t| x) = S(t|x)= \exp( -\exp(x^T \beta) A_0(t) ) }

One possibility is to model the variance within clusters via a regression design,
specifying a regression structure for the independent gamma distributed random
effect for each cluster, such that the variance is given by:
\deqn{ \theta = h( z_j^T \alpha) }
where \eqn{z} is specified by \code{theta.des}, and a possible link function
\code{var.link=1} will use the exponential link \eqn{h(x)=\exp(x)}, and
\code{var.link=0} the identity link \eqn{h(x)=x}.

The reported standard errors are based on the estimated information from the
likelihood assuming that the marginals are known (unlike \code{twostageMLE}
and for the additive gamma model below).

Can also fit a structured additive gamma random effects model, such as the
ACE, ADE model for survival data. In this case, the \code{random.design}
specifies the random effects for each subject within a cluster. This is a
matrix of 1's and 0's with dimension \eqn{n \times d} (for \eqn{d} random effects).

For a cluster with two subjects, the \code{random.design} rows are \eqn{v_1}
and \eqn{v_2}. Such that the random effect for subject 1 is \deqn{v_1^T
(Z_1,...,Z_d)}, for \eqn{d} random effects. Each random effect has an
associated parameter \eqn{(\lambda_1,...,\lambda_d)}. By construction,
subject 1's random effect is Gamma distributed with mean
\eqn{\lambda_j/v_1^T \lambda} and variance \eqn{\lambda_j/(v_1^T
\lambda)^2}. Note that the random effect \eqn{v_1^T (Z_1,...,Z_d)} has mean
1 and variance \eqn{1/(v_1^T \lambda)}. It is assumed that \eqn{lamtot=v_1^T
\lambda} is fixed within clusters as it would be for the ACE model.

Based on these parameters, the relative contribution (the heritability, \eqn{h}) is
equivalent to the expected values of the random effects: \eqn{\lambda_j/v_1^T \lambda}.

The DEFAULT parametrization (\code{var.par=1}) uses the variances of the random effects:
\deqn{ \theta_j  = \lambda_j/(v_1^T \lambda)^2 }
For alternative parametrizations, specify how the parameters relate to \eqn{\lambda_j}
with the argument \code{var.par=0}.

For both types of models, the basic model assumptions are that given the
random effects of the clusters, the survival distributions within a cluster
are independent and on the form: \deqn{ P(T > t| x,z) = \exp( -Z \cdot
\text{Laplace}^{-1}(lamtot,lamtot,S(t|x)) ) } with the inverse Laplace of
the gamma distribution with mean 1 and variance \eqn{1/lamtot}.

The parameters \eqn{(\lambda_1,...,\lambda_d)} are related to the parameters of the model
by a regression construction \code{pard} (\eqn{d \times k}), that links the \eqn{d}
\eqn{\lambda} parameters with the \eqn{k} underlying \eqn{\theta} parameters:
\deqn{ \lambda = theta.des \times \theta }
here using \code{theta.des} to specify these low-dimension associations. Default is a diagonal matrix.
This can be used to make structural assumptions about the variances of the random-effects
as is needed for the ACE model for example.

The \code{case.control} option can be used with the pair specification of the pairwise parts
of the estimating equations. Here it is assumed that the second subject of each pair is the proband.
}
\examples{
data(diabetes)

# Marginal Cox model  with treat as covariate
margph <- phreg(Surv(time,status)~treat+cluster(id),data=diabetes)
### Clayton-Oakes, MLE
fitco1<-twostageMLE(margph,data=diabetes,theta=1.0)
summary(fitco1)

\donttest{ ## Reduce Ex.Timings
### Plackett model
mph <- phreg(Surv(time,status)~treat+cluster(id),data=diabetes)
fitp <- survival_twostage(mph,data=diabetes,theta=3.0,Nit=40,
               clusters=diabetes$id,var.link=1,model="plackett")
summary(fitp)

### Clayton-Oakes
fitco2 <- survival_twostage(mph,data=diabetes,theta=0.0,detail=0,
                 clusters=diabetes$id,var.link=1,model="clayton.oakes")
summary(fitco2)
fitco3 <- survival_twostage(margph,data=diabetes,theta=1.0,detail=0,
             clusters=diabetes$id,var.link=0,model="clayton.oakes")
summary(fitco3)

### without covariates but with stratafied
marg <- phreg(Surv(time,status)~+strata(treat)+cluster(id),data=diabetes)
fitpa <- survival_twostage(marg,data=diabetes,theta=1.0,
                clusters=diabetes$id,model="clayton.oakes")
summary(fitpa)


### Piecewise constant cross hazards ratio modelling
########################################################

d <- subset(sim_ClaytonOakes(1000,2,0.5,0,stoptime=2,left=0),!truncated)
udp <- piecewise_twostage(c(0,0.5,2),data=d,method="optimize",
                          id="cluster",timevar="time",
                          status="status",model="clayton.oakes",silent=0)
summary(udp)
}

\donttest{ ## Reduce Ex.Timings
### Same model using the strata option, a bit slower
########################################################
## makes the survival pieces for different areas in the plane
##ud1=surv_boxarea(c(0,0),c(0.5,0.5),data=d,id="cluster",timevar="time",status="status")
##ud2=surv_boxarea(c(0,0.5),c(0.5,2),data=d,id="cluster",timevar="time",status="status")
##ud3=surv_boxarea(c(0.5,0),c(2,0.5),data=d,id="cluster",timevar="time",status="status")
##ud4=surv_boxarea(c(0.5,0.5),c(2,2),data=d,id="cluster",timevar="time",status="status")

## everything done in one call
ud <- piecewise_data(c(0,0.5,2),data=d,timevar="time",status="status",id="cluster")
ud$strata <- factor(ud$strata);
ud$intstrata <- factor(ud$intstrata)

## makes strata specific id variable to identify pairs within strata
## se's computed based on the id variable across strata "cluster"
ud$idstrata <- ud$id+(as.numeric(ud$strata)-1)*2000

marg2 <- timereg::aalen(Surv(boxtime,status)~-1+factor(num):factor(intstrata),
               data=ud,n.sim=0,robust=0)
tdes <- model.matrix(~-1+factor(strata),data=ud)
fitp2 <- survival_twostage(marg2,data=ud,se.clusters=ud$cluster,clusters=ud$idstrata,
                model="clayton.oakes",theta.des=tdes,step=0.5)
summary(fitp2)

### now fitting the model with symmetry, i.e. strata 2 and 3 same effect
ud$stratas <- ud$strata;
ud$stratas[ud$strata=="0.5-2,0-0.5"] <- "0-0.5,0.5-2"
tdes2 <- model.matrix(~-1+factor(stratas),data=ud)
fitp3 <- survival_twostage(marg2,data=ud,clusters=ud$idstrata,se.cluster=ud$cluster,
                model="clayton.oakes",theta.des=tdes2,step=0.5)
summary(fitp3)

### same model using strata option, a bit slower
fitp4 <- survival_twostage(marg2,data=ud,clusters=ud$cluster,se.cluster=ud$cluster,
                model="clayton.oakes",theta.des=tdes2,step=0.5,strata=ud$strata)
summary(fitp4)
}

\donttest{ ## Reduce Ex.Timings
### structured random effects model additive gamma ACE
### simulate structured two-stage additive gamma ACE model
data <- sim_ClaytonOakes_twin_ace(2000,2,1,0,3)
out <- twin_polygen_design(data,id="cluster")
pardes <- out$pardes
pardes
des.rv <- out$des.rv
head(des.rv)
aa <- phreg(Surv(time,status)~x+cluster(cluster),data=data,robust=0)
ts <- survival_twostage(aa,data=data,clusters=data$cluster,detail=0,
	       theta=c(2,1),var.link=0,step=0.5,
	       random.design=des.rv,theta.des=pardes)
summary(ts)
}
}
\references{
\itemize{
\item Twostage estimation of additive gamma frailty models for survival data. Scheike (2019), work in progress.
\item Shih and Louis (1995) Inference on the association parameter in copula models for bivariate survival data, \emph{Biometrics}.
\item Glidden (2000), A Two-Stage estimator of the dependence parameter for the Clayton Oakes model, LIDA.
\item Measuring early or late dependence for bivariate twin data. Scheike, Holst, Hjelmborg (2015), LIDA.
\item Estimating heritability for cause specific mortality based on twins studies. Scheike, Holst, Hjelmborg (2014), LIDA.
\item Additive Gamma frailty models for competing risks data. Eriksson and Scheike (2015), \emph{Biometrics}.
}
}
\author{
Thomas Scheike
}
\keyword{survival}
