msmtools (version 1.0)

augment: A fast and general method for building augmented data.

Description

A fast and general method for reshaping standard longitudinal data, where each observation contains the exact starting and ending time of the process, into a new structure called 'augmented' which is suitable for multi-state analyses using the msm package.

Usage

augment(data, data_key, n_events, pattern, state = list("IN", "OUT", "DEAD"),
  t_start, t_end, t_cens, t_death, t_augmented = "augmented", more_status,
  verbose = TRUE)

Arguments

data

A data.table object where each row represents an observation.

data_key

A keying variable which augment uses to define a key for data. This represents the subject ID.

n_events

An integer variable indicating the progressive (monotonic) event number of a given ID. If missing, augment fastly creates a variable named "n_events". augment always checks whether n_events is monotonic

pattern

Either an integer, a factor or a characer with 2 or 3 unique values which provides the ID status at the end of the study. pattern has a predefined structure. When 2 values are detected, they must be in the format: 0 = "alive", 1 = "dead". Whe

state

A list of 3 possible states which a subject can reach. state has a predefined structure as follows: IN, OUT, DEAD. If augment does not detect exactly 3 states, it stops with error.

t_start

The starting time of an observation. It can be passed as date, integer, or numeric format.

t_end

The ending time of an observation. It can be passed as date, integer, or numeric format.

t_cens

The censoring time of the study

t_death

The exact death time of a subject ID. If t_death is missing, t_cens is assumed to contain both censoring and death time.

t_augmented

The new time variable of the process in the augmented format. If t_augmented is missing, then the default name 'augmented' is assumed. The variable is added to data. If augment detects a date or a difftime format in

more_status

A variable which marks further transitions beside the default given by state. more_status can be a factor or a character. In particular, if the corresponding observation is a standard admission (i.e. no other information availabl

verbose

If FALSE, all information produced by print, cat and message are suppressed. All is done internally so that no global options are changed. verbose can be set to FALSE on all com

Value

• A restructured long format dataset of class "data.table" where each row represents a specific transition for a given subject. Moreover, augment adds some important variables: ----- augmented: the new timing variable for the process when looking at transitions. If t_augmented is missing, then augment creates augmented by default. augmented. The function looks directly to t_start and t_end to build it and thus it inherits their class. In particular, if t_start is a date format, then augment computes a new variable cast as integer and names it augmented_int. If t_start is a difftime format, then augment computes a new variable cast as a numeric and names it augmented_num; status: a status flag which looks at state. augment automatically checks whether argument pattern has 2 or 3 unique values and computes the correct structure of a given subject. The variable is cast as character; status_num: the corresponding integer version of status; n_status: a mix of status and status_num cast as character. status_num comes into play when a model on the progression of the process is intended. -----

Details

In order to get the data processed, a monotonic increasing process needs to be ensured. augment checks this both in case n_events is missing or not. The data are fastly ordered through setkey function and using data_key as the primary key and t_start as secondary key. Then it checks n_events and if it fails, it returns the subjects gived by data_key where issues occurred before giving an error and stopping. If n_events is not passed, then the ordering procedure remains the same, but the progression number is created internally with the name n_events.

References

Jackson, C.H. (2011). Multi-State Models for Panel Data: The msm Package for R. Journal of Statistical Software, 38(8), 1-29. URL http://www.jstatsoft.org/v38/i08/.

Examples

# 1.
# loading data
data( hosp )

# augmenting hosp
hosp_augmented = augment( data = hosp, data_key = subj, n_events = adm_number, pattern = label_3,
                          t_start = dateIN, t_end = dateOUT, t_cens = dateCENS )

# 2.
# augmenting hosp by passing more information regarding transition with arg. more_status
hosp_augmented_more = augment( data = hosp, data_key = subj, n_events = adm_number,
                               pattern = label_3, t_start = dateIN, t_end = dateOUT,
                               t_cens = dateCENS, more_status = rehab_it )

augmented = augment( data = hosp, data_key = subj, n_events = dateIN,
                     pattern = label_3, t_start = dateIN, t_end = dateOUT, t_cens = dateCENS )