restovec               package:rmutil               R Documentation

_C_r_e_a_t_e _a _r_e_s_p_o_n_s_e _O_b_j_e_c_t

_D_e_s_c_r_i_p_t_i_o_n:

     'restovec' can produce an object of class, 'response', from a
     vector of (1) independent univariate responses or (2) a single
     time series.

     It can produce such an object from repeated measurements in the
     form of (1) a list of vectors of event histories, (2) a list of
     two or more column matrices with times, response values, and and
     other information or (3) a matrix or dataframe of response values.
     The first two are for unbalanced data and the third for balanced
     data.

     Multivariate responses can be supplied as (1) a three-dimensional
     array of balanced repeated measurements, (2) lists of matrices for
     unbalanced repeated measurements, or (3) a matrix with either (a)
     several time series or (b) single observations per individual on
     several variables.

     In formula and functions, the key words, 'times' can be used to
     refer to the response times from the data object as a covariate,
     'individuals' to the index for individuals as a factor covariate,
     and 'nesting' the index for nesting as a factor covariate. The
     latter two only work for W&R notation.

     NAs can be detected with 'lvna' or removed with 'rmna' (where
     necessary, in coordination with the appropriate covariates) to
     create a 'repeated' object.

     'response' objects can be printed and plotted. Methods are
     available for extracting the response, the numbers of observations
     per individual, the times, the weights, the units of
     measurement/Jacobian, and the nesting variable: 'response',
     'nobs', 'times', 'weights', 'delta', and 'nesting'.

     The response and or the times may be transformed using
     'transform(z, newy=fcn1(y), times=fcn2(times))' where 'fcn1' and
     'fcn2' are transformations and 'y' is the name of a response
     variable. When the response is transformed, the Jacobian is
     automatically calculated. Note that, if the unit of
     precision/Jacobian ('delta') is available in the 'response'
     object, this is automatically included in the calculation of the
     likelihood function in all library model functions.

_U_s_a_g_e:

     restovec(response=NULL, times=NULL, nest=NULL, coordinates=NULL,
             censor=NULL, totals=NULL, weights=NULL, delta=NULL,
             type=NULL, names=NULL, units=NULL, oldresponse=NULL,
             description=NULL)

_A_r_g_u_m_e_n_t_s:

response: For (1) independent univariate responses with one observation
          per individual or (2) a single time series, one vector may be
          supplied (in the latter case, the times must be given even if
          equally spaced).

          Univariate repeated measurements responses can be given (1)
          if balanced, as a matrix or dataframe of response values with
          dimensions: number of individuals by number of
          responses/individual, (2) a list of vectors of event
          histories, or (3) a list of one or more column matrices, for
          each individual, with response values in the first column and
          times in the second (if there are no times, set 'times' to
          FALSE), possibly followed by columns with nesting categories,
          binomial totals, censoring indicators, and/or units of
          measurement.

          Multivariate responses can be supplied as (1) a
          three-dimensional array of balanced repeated measurements
          with dimensions: number of individuals by number of
          responses/individual by number of variables, (2) a list of
          matrices for unbalanced repeated measurements each with
          dimensions: number of responses on that individual by number
          of variables, plus a column for times if available (otherwise
          set 'times' to FALSE), or (3) a matrix with either (a)
          several time series, having dimensions: length of time series
          by by number of times series, or (b) single observations per
          individual on several variables with dimensions: number of
          individuals by number of variables. In all but case (1),
          'type' must be a character vector with length equal to the
          number of responses. In case (2), where applicable, 'censor',
          'totals', and 'delta' must be supplied as lists of matrices
          of the same size as for 'response', and 'nest' and 'weights'
          as lists of vectors of lengths equal to the number of
          observations on each individual.

   times: When 'response' is a matrix or multivariate array, these can
          be (1) a vector when the times are the same for all
          individuals, possibly unequally-spaced, or (2) a matrix with
          dimensions: number of individuals by number of
          responses/individual. Not necessary if times are equally
          spaced, except if a vector containing a single time series is
          supplied (if not given in this case, it takes the responses
          to be independent, not a time series). For clustered data
          with no time ordering, set to FALSE.

    nest: This is the second level of nesting, with the individual
          being the first level. Values for an individual must be
          consecutive increasing integers with all responses in the
          same cluster grouped together. For example, with three
          clusters of four observations each, the code would be
          1,1,1,1,2,2,2,2,3,3,3,3.

          When 'response' is a matrix or multivariate array, this can
          be a vector of length equal to the number of
          responses/individual indicating which responses belong to
          which nesting category.

          If 'response' is a multivariate list, this must also be a
          list.

          When 'response' is a univariate list of unbalanced repeated
          measurements, the nesting indicator may instead be included
          in that list but must respect the same ordering as described
          above.

coordinates: When 'response' is a vector, a two-column matrix giving
          the coordinates for spatial data.

  censor: When 'response' is a matrix, this can be (1) a vector of the
          same length as the number of individuals, containing a binary
          indicator, with a one indicating that the last time period in
          the series terminated with an event and zero that it was
          censored, or (2) a matrix of the same size as 'response'.

          When 'response' is a multivariate array, this can be (1) a
          matrix with dimensions: number of individuals by number of
          responses, or (2) an array of the same size as 'response'. In
          the first case, for each column corresponding to a duration
          response, it should contain a binary indicator, with a one
          indicating that the last time period in the series terminated
          with an event and zero that it was censored, and NAs in
          columns not containing durations. In the second case, layers
          not corresponding to duration responses should contain NAs.

          If 'response' is a multivariate list, this must also be a
          list.

          For event history data, even with no censoring, an
          appropriate vector of ones must be supplied.

          When 'response' is a univariate list of unbalanced repeated
          measurements, the censoring indicator may instead be included
          in that list.

  totals: If the response is a matrix of binomial counts, this can be
          (1) a corresponding vector (one total per individual) or (2)
          a matrix of totals.

          When 'response' is a multivariate array, this can be (1) a
          matrix with dimensions: number of individuals by number of
          responses if all binomial responses for an individual have
          the same total, or (2) an array of the same size as
          'response'. In the first case, for each column corresponding
          to a binomial response, it should contain the corresponding
          totals, with NAs in columns not containing binomial. In the
          second case, layers not corresponding to binomial responses
          should contain NAs.

          If 'response' is a multivariate list, this must also be a
          list.

          When 'response' is a univariate list of unbalanced repeated
          measurements, the totals may instead be included in that
          list.

 weights: A vector, matrix, array, or list of vectors of frequencies or
          weights, with one value per 'response'. In other words, a
          multivariate response has only one corresponding weight
          value.

   delta: For continuous measurements, the unit of precision (if not
          equal to unity) for each response: a scalar, vector, matrix,
          array, or list of the same dimensions as 'response'. For
          example, if responses have two decimal places ('12.34'),
          'delta=0.01'. If the response has been transformed, this
          should be multiplied by the numerical values of the Jacobian.
          When the 'transform' method is applied to the 'response'
          object, this is automatically updated.

    type: The type(s) of observations: nominal, ordinal, discrete,
          duration, continuous, or unknown. If not specified otherwise,
          those responses with 'delta' and no 'censor' are assumed to
          be 'continuous', those with 'censor' indicator are assumed to
          be 'duration', those with 'totals' are assumed to be
          'nominal', and all others 'unknown'.

   names: Optional name(s) of the response variable(s).

   units: Optional character vector giving units of measurement of
          response(s).

oldresponse: An existing 'response' object to which the new data are to
          be added.

description: An optional named list of character vectors with names of
          some or all response variables containing their descriptions.

_V_a_l_u_e:

     Returns an object of class, 'response', containing a vector with
     the responses ('z$y'), a corresponding vector of times ('z$times')
     if applicable, a vector giving the number of observations per
     individual ('z$nobs', set to a scalar 1 if observations are
     independent), type  ('z$delta'), and possibly binomial totals
     ('z$n'), nesting (clustering, 'z$nest'), censoring ('z$censor'),
     weights ('z$wt'),  unit of precision/Jacobian ('z$delta'), units
     of measurement ('z$units'), and description ('z$description')
     information.

_A_u_t_h_o_r(_s):

     J.K. Lindsey

_S_e_e _A_l_s_o:

     'DataMethods', 'covind', 'delta', 'description', 'lvna', 'names',
     'nesting', 'nobs', 'read.list', 'read.surv', 'response',
     'resptype', 'rmna', 'tcctomat', 'times', 'transform', 'tvctomat',
     'units', 'weights'

_E_x_a_m_p_l_e_s:

     #
     #continuous response
     y <- matrix(rnorm(20),ncol=5)
     # times assumed to be 1:5
     restovec(y, units="m")
     #unequally-spaced times
     tt <- c(1,3,6,10,15)
     print(resp <- restovec(y, times=tt, units="m",
             description=list(y="Response measured in metres")))
     response(resp)
     response(resp, nind=2:3)
     response(transform(resp, y=1/y))
     transform(resp, y=1/y, units="1/m")
     units(resp)
     description(resp)
     times(resp)
     times(transform(resp, times=times-6))
     nobs(resp)
     weights(resp)
     nesting(resp)
     # because individuals are the only nesting, this is the same as
     covind(resp)
     #
     # binomial response
     y <- matrix(rpois(20,5),ncol=5)
     # responses summarized as relative frequencies
     print(respb <- restovec(y, totals=y+matrix(rpois(20,5),ncol=5), times=tt))
     response(respb)
     #
     # censored data
     y <- matrix(rweibull(20,2,5),ncol=5)
     print(respc <- restovec(y, censor=matrix(rbinom(20,1,0.9),ncol=5), times=tt))
     # if there is no censoring, censor indicator is not printed
     response(respc)
     # nesting clustered within individuals
     nest <- c(1,1,2,2,2)
     print(respn <- restovec(y, censor=matrix(rbinom(20,1,0.9),ncol=5),
             times=tt,nest=nest))
     response(respn)
     times(respn)
     nesting(respn)
     #
     # multivariate response
     restovec(y, censor=matrix(rbinom(20,1,0.9),ncol=5),
             units=c("m","days","l","cm","mon"),
             type=c("continuous","duration","continuous","continuous","duration"),
             description=list(y1="First continuous variable",
                     y2="First duration variable",y3="Second continuous variable",
                     y4="Third continuous variable",y5="Second duration variable"))
     restovec(y, censor=matrix(rbinom(20,1,0.9),ncol=5), 
             names=c("a","b","c","d","e"), units=c("m","days","l","cm","mon"),
             type=c("continuous","duration","continuous","continuous","duration"),
             description=list(a="First continuous variable",
                     b="First duration variable",c="Second continuous variable",
                     d="Third continuous variable",e="Second duration variable"))

