1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/Hist.R
3\name{Hist}
4\alias{Hist}
5\title{Create an event history response variable}
6\usage{
7Hist(time, event, entry = NULL, id = NULL, cens.code = "0",
8  addInitialState = FALSE)
9}
10\arguments{
11\item{time}{for right censored data a numeric vector of event times -- for
12interval censored data a list or a data.frame providing two numeric vectors
13the left and right endpoints of the intervals.  See \code{Details}.}
14
15\item{event}{A vector or a factor that specifies the events that occurred at
16the corresponding value of \code{time}. Numeric, character and logical
17values are recognized.  It can also be a list or a data.frame for the
18longitudinal form of storing the data of a multi state model -- see
19\code{Details}.}
20
21\item{entry}{Vector of delayed entry times (left-truncation) or list of two
22times when the entry time is interval censored.}
23
24\item{id}{Identifies the subjects to which multiple events belong for the
25longitudinal form of storing the data of a multi state model -- see
26\code{Details}.}
27
28\item{cens.code}{A character or numeric vector to identify the right
29censored observations in the values of \code{event}.  Defaults to "0" which
30is equivalent to 0.}
31
32\item{addInitialState}{If TRUE, an initial state is added to all ids for the
33longitudinal input form of a multi-state model.}
34}
35\value{
36An object of class \code{Hist} for which there are print and plot
37methods.  The object's internal is a matrix with some of the following
38columns: \item{time}{ the right censored times} \item{L}{the left endpoints
39of internal censored event times} \item{R}{the right endpoints of internal
40censored event times} \item{status}{\code{0} for right censored, \code{1}
41for exact, and \code{2} for interval censored event times.} \item{event}{an
42integer valued numeric vector that codes the events.} \item{from}{an integer
43valued numeric vector that codes the \code{from} states of a transition in a
44multi state model.} \item{to}{an integer valued numeric vector that codes
45the \code{to} states of a transition in a multi state model.}
46
47Further information is stored in \code{\link{attributes}}.  The key to the
48official names given to the events and the from and to states is stored in
49an attribute "states".
50}
51\description{
52Functionality for managing censored event history response data. The
53function can be used as the left hand side of a formula: \code{Hist} serves
54\code{\link{prodlim}} in a similar way as \code{\link{Surv}} from the
55survival package serves `survfit'.  \code{Hist} provides the suitable
56extensions for dealing with right censored and interval censored data from
57competing risks and other multi state models. Objects generated with
58\code{Hist} have a print and a plot method.
59}
60\details{
61*Specification of the event times*
62
63If \code{time} is a numeric vector then the values are interpreted as right
64censored event times, ie as the minimum of the event times and the censoring
65times.
66
67If \code{time} is a list with two elements or data frame with two numeric
68columns The first element (column) is used as the left endpoints of interval
69censored observations and the second as the corresponding right endpoints.
70When the two endpoints are equal, then this observation is treated as an
71exact uncensored observation of the event time.  If the value of the right
72interval endpoint is either \code{NA} or \code{Inf}, then this observation
73is treated as a right censored observation. Right censored observations can
74also be specified by setting the value of \code{event} to \code{cens.code}.
75This latter specification of right censored event times overwrites the
76former: if \code{event} equals \code{cens.code} the observation is treated
77as right censored no matter what the value of the right interval endpoint
78is.
79
80*Specification of the events*
81
82If \code{event} is a numeric, character or logical vector then the order of
83the attribute "state" given to the \code{value} of \code{Hist} is determined
84by the order in which the values appear.  If it is a factor then the order
85from the levels of the factor is used instead.
86
87**Normal form of a multi state model**
88
89If \code{event} is a list or a data.frame with exactly two elements, then
90these describe the transitions in a multi state model that occurred at the
91corresponding \code{time} as follows: The values of the first element are
92interpreted as the \code{from} states of the transition and values of the
93second as the corresponding \code{to} states.
94
95**Longitudinal form of a multi state model**
96
97If \code{id} is given then \code{event} must be a vector. In this case two
98subsequent values of \code{event} belonging to the same value of \code{id}
99are treated as the \code{from} and \code{to} states of the transitions.
100}
101\examples{
102
103
104## Right censored responses of a two state model
105## ---------------------------------------------
106
107Hist(time=1:10,event=c(0,1,0,0,0,1,0,1,0,0))
108
109## change the code for events and censored observations
110
111Hist(time=1:10,event=c(99,"event",99,99,99,"event",99,"event",99,99),cens.code=99)
112
113TwoStateFrame <- SimSurv(10)
114SurvHist <- with(TwoStateFrame,Hist(time,status))
115summary(SurvHist)
116plot(SurvHist)
117
118## Right censored data from a competing risk model
119## --------------------------------------------------
120
121CompRiskFrame <- data.frame(time=1:10,event=c(1,2,0,3,0,1,2,1,2,1))
122CRHist <- with(CompRiskFrame,Hist(time,event))
123summary(CRHist)
124plot(CRHist)
125
126## Interval censored data from a survival model
127icensFrame <- data.frame(L=c(1,1,3,4,6),R=c(2,NA,3,6,9),event=c(1,1,1,2,2))
128with(icensFrame,Hist(time=list(L,R)))
129
130## Interval censored data from a competing risk model
131with(icensFrame,Hist(time=list(L,R),event))
132
133## Multi state model
134MultiStateFrame <- data.frame(time=1:10,
135			      from=c(1,1,3,1,2,4,1,1,2,1),
136			      to=c(2,3,1,2,4,2,3,2,4,4))
137with(MultiStateFrame,Hist(time,event=list(from,to)))
138
139##  MultiState with right censored observations
140
141MultiStateFrame1 <- data.frame(time=1:10,
142			      from=c(1,1,3,2,1,4,1,1,3,1),
143			      to=c(2,3,1,0,2,2,3,2,0,4))
144with(MultiStateFrame1,Hist(time,event=list(from,to)))
145
146## Using the longitudinal input method
147MultiStateFrame2 <- data.frame(time=c(0,1,2,3,4,0,1,2,0,1),
148			      event=c(1,2,3,0,1,2,4,2,1,2),
149			      id=c(1,1,1,1,2,2,2,2,3,3))
150 with(MultiStateFrame2,Hist(time,event=event,id=id))
151
152}
153\author{
154Thomas A. Gerds \email{tag@biostat.ku.dk}, Arthur Allignol
155\email{arthur.allignol@fdm.uni-freiburg.de}
156}
157\seealso{
158\code{\link{plot.Hist}}, \code{\link{summary.Hist}},
159\code{\link{prodlim}}
160}
161\keyword{survival}
162
163