1\name{mcutLexis}
2\alias{mcutLexis}
3\title{
4Cut follow-up at multiple event dates and keep track of order of events
5}
6\description{
7A generalization of \code{\link{cutLexis}} to the case where different
8events may occur in any order (but at most once for each).
9}
10\usage{
11mcutLexis( L0, timescale = 1, wh,
12              new.states = NULL,
13        precursor.states = transient(L0),
14              seq.states = TRUE,
15              new.scales = NULL,
16            ties.resolve = FALSE )
17}
18\arguments{
19  \item{L0}{A Lexis object.}
20  \item{timescale}{Which time scale do the variables in \code{L0[,wh]}
21    refer to. Can be character or integer.}
22  \item{wh}{Which variables contain the event dates. Character or
23    integer vector}
24  \item{new.states}{Names of the events forming new states. If
25    \code{NULL} equal to the variable names from \code{wh}.}
26  \item{precursor.states}{Which states are precursor states. See
27    \code{\link{cutLexis}} for definition of precursor states.}
28  \item{seq.states}{Should the sequence of events be kept track of? That
29    is, should A-B be considered different from B-A. If \code{FALSE},
30    the state with combined preceding events A and B will be called
31    A+B (alphabetically sorted).
32
33    May also be supplied as character: \code{s} - sequence, keep
34    track of sequence of states occupied (same as \code{TRUE}), \code{u}
35    - unordered, keep track only of states visited (same as
36    \code{FALSE}) or \code{l}, \code{c} - last or current state, only
37    record the latest state visited. If given as character, only the
38    first letter converted to lower case is used.}
39  \item{new.scales}{Should we construct new time scales indicating the
40    time since each of the event occurrences.}
41  \item{ties.resolve}{Should tied event times be resolved by adding
42    random noise to tied event dates. If \code{FALSE} the function will
43    not accept that two events occur at the same time for a person
44    (ties). If \code{TRUE} a random quantity in the range
45    \code{c(-1,1)/100} will be added to all event times in all records
46    with at least one tie. If \code{ties.resolve} is numeric a random
47    quantity in the range \code{c(-1,1)*ties.resolve} will be added to
48    all event times in all records with at least one tie.}
49}
50\value{A \code{\link{Lexis}} object with extra states created by
51  occurrence of a number of intermediate events.
52}
53\author{
54Bendix Carstensen, \url{http://bendixcarstensen.com}
55}
56\seealso{
57  \code{\link{cutLexis}},
58  \code{\link{rcutLexis}},
59  \code{\link{addCov.Lexis}},
60  \code{\link{Lexis}},
61  \code{\link{splitLexis}}
62}
63\examples{
64# A dataframe of times
65set.seed(563248)
66dd <- data.frame( id = 1:30,
67                 doN = round(runif(30,-30, 0),1),
68                 doE = round(runif(30,  0,20),1),
69                 doX = round(runif(30, 50,60),1),
70                 doD = round(runif(30, 50,60),1),
71                 # these are the event times
72                 doA = c(NA,21,NA,27,35,NA,52, 5,43,80,
73                         NA,22,56,28,53,NA,51, 5,43,80,
74                         NA,23,NA,33,51,NA,55, 5,43,80),
75                 doB = c(NA,20,NA,53,27,NA, 5,52,34,83,
76                         NA,20,23,37,35,NA,52, 8,33,NA,
77                         25,NA,37,40,NA,NA,15,23,36,61) )
78
79# set up a Lexis object with time from entry to death/exit
80Lx <- Lexis( entry = list(time=doE,
81                           age=doE-doN),
82              exit = list(time=pmin(doX,doD)),
83       exit.status = factor(doD<doX,labels=c("OK","D")),
84              data = dd )
85summary( Lx )
86
87# cut the follow-up at dates doA and doB
88L2 <- mcutLexis( Lx, "time", wh=c("doA","doB"),
89                 new.states = c("A","B"),
90           precursor.states = "OK",
91                 seq.states = TRUE,
92                 new.scales = c("tfA","tfB") )
93summary( L2 )
94L2
95
96# show the states
97boxes( L2, boxpos=list(x=c(10,60,50,90,50,90),
98                       y=c(50,50,90,90,10,10)),
99           scale.R=100, show.BE=TRUE, DR.sep=c(" (",")"))
100
101
102L3 <- mcutLexis( Lx, "time", wh=c("doA","doB"),
103                 new.states = c("A","B"),
104           precursor.states = "OK",
105                 seq.states = FALSE,
106                 new.scales = c("tfA","tfB") )
107summary( L3 )
108boxes( L3, boxpos=list(x=c(10,50,50,90,50),
109                       y=c(50,50,90,50,10)),
110           show.R=FALSE, show.BE=TRUE )
111}
112\keyword{survival}
113