rmutil (version 1.1.10)

restovec: Create a response Object

Description

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.

Usage

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)

Value

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.

Arguments

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.

Author

J.K. Lindsey

See Also

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

Examples

#
#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"))