Building Augmented Data to Run Multi-State Models with 'msm' Package

A fast and general method for restructuring classical longitudinal data into augmented ones. The reason for this is to facilitate the modeling of longitudinal data under a multi-state framework using the 'msm' package.

msmtools introduces a fast and general method for restructuring classical longitudinal datasets into augmented ones. The reason for this is to facilitate the modeling of longitudinal data under a multi-state framework using the msm package.

msmtools comes with 3 functions:

augment(): the main function of the package. This is the workhorse which takes care of the data reshaping. It is very efficient and fast so highly dimensional datasets can be processed with ease;
prevplot(): this is a plotting function which mimics the usage of msm function plot.prevalence.msm(), but with more things. Once you ran a multi-state model, use this function to plot a comparison between observed and expected prevalences;
survplot(): the aims of this function are double. You can use survplot() as a plotting tool for comparing the empirical and the fitted survival curves. Or you can use it to build and get the datasets used for the plot. The function is based on msm plot.survfit.msm(), but does more things and it is a lot faster.

For more information about msmtools, please check out the vignette with vignette( "msmtools" ).

News

msmtools 1.2

Major changes

msmtools can now run with R 3.0.0 and above for retro compatibility reasons.
augment() gains the new argument check_NA which allows the user to decide if the function should run some checks to find missing data in the following arguments: data_key, n_events, pattern, t_start and t_end. Default is FALSE. Missing data checks are always carried out on more_status.
augment() gains the new argument convert which if set to TRUE efficiently converts the output to the old school data.frame class.
survplot() gains the new argument return.all which saves you some typing time when requesting both the data of the Kaplan-Meier and the fitter survival. Arguments return.km and return.p now are set to NULL by default instead of FALSE.
survplot() gains the new argument convert which if set to TRUE efficiently converts any object returned to the old school data.frame class.

Changes in functions

augment() now also accepts an object of class data.frame as input. If so, the function internally converts it to a data.table.
augment() now accepts t_augmented without quotes too. Default name is still "augmented".
augment() gets a whole new implementation which comes into play when pattern has only 2 values ('alive' and 'dead'). Now the procedure runs with computational time only slightly longer than the standard 3 values in pattern. This is due thanks to the fast joins method adopted.
augment() now is much faster when defining the target size for the reshaping. This was a bottleneck which caused memory issues and wasted time.
General memory optimization in the function augment(). Now the function uses ~ 30% less memory.

Other changes

All the functions now have more detailed and better written helps.
Some minor changes in the vignette to encapsulate new functionalities.

Bug fixes

In augment(), the sequential status is now correctly computed. There was a wrong call which blocked the object defined by n_events.
In augment(), when pattern was detected with two unique values, inconsistent results were produced during the status flag assignment. This was due to a wrong rounding of the amount of augmenting factor for each unit.

msmtools 1.1

Changes in functions

augment() now is way faster then in v1.0 thanks to a new implementation when defining patterns
augment() now uses the faster uniqueN() to extract the number of unique values in a vector