joineRML

R package for fitting joint models to time-to-event data and multivariate longitudinal data

https://github.com/graemeleehickey/joinerml

Keywords

Repository

R package for fitting joint models to time-to-event data and multivariate longitudinal data

README.Rmd

---
output: github_document
---



```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# joineRML 

[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version-last-release/joineRML)](https://cran.r-project.org/package=joineRML)
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/graemeleehickey/joineRML?branch=master&svg=true)](https://ci.appveyor.com/project/graemeleehickey/joineRML)

[![](http://cranlogs.r-pkg.org/badges/joineRML)](https://CRAN.R-project.org/package=joineRML)
[![](https://cranlogs.r-pkg.org/badges/grand-total/joineRML)](https://CRAN.R-project.org/package=joineRML)
[![Research software impact](http://depsy.org/api/package/cran/joineRML/badge.svg)](http://depsy.org/package/r/joineRML)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.1158231.svg)](https://doi.org/10.5281/zenodo.1158231)
[![R-CMD-check](https://github.com/graemeleehickey/joineRML/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/graemeleehickey/joineRML/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/graemeleehickey/joineRML/graph/badge.svg)](https://app.codecov.io/gh/graemeleehickey/joineRML)


`joineRML` is an extension of the joineR package for fitting joint models of time-to-event data and multivariate longitudinal data. The model fitted in joineRML is an extension of the Wulfsohn and Tsiatis (1997) and Henderson et al. (2000) models, which is comprised of $(K+1)$-sub-models: a Cox proportional hazards regression model (Cox, 1972) and a $K$-variate linear mixed-effects model - a direct extension of the Laird and Ware (1982) regression model. The model is fitted using a Monte Carlo Expectation-Maximization (MCEM) algorithm, which closely follows the methodology presented by Lin et al. (2002).

## Why use joineRML?

As noted in Hickey et al. (2016), there is a lack of statistical software available for fitting joint models to multivariate longitudinal data. This is contrary to a growing methodology in the statistical literature. `joineRML` is intended to fill this void.

# Example

The main workhorse function is `mjoint`. As a simple example, we use the `heart.valve` dataset from the package and fit a bivariate joint model.

```{r, eval = FALSE}
library(joineRML)
data(heart.valve)
hvd <- heart.valve[!is.na(heart.valve$log.grad) & !is.na(heart.valve$log.lvmi), ]

set.seed(12345)
fit <- mjoint(
    formLongFixed = list("grad" = log.grad ~ time + sex + hs,
                         "lvmi" = log.lvmi ~ time + sex),
    formLongRandom = list("grad" = ~ 1 | num,
                          "lvmi" = ~ time | num),
    formSurv = Surv(fuyrs, status) ~ age,
    data = list(hvd, hvd),
    timeVar = "time")
```

The fitted model is assigned to `fit`. We can apply a number of functions to this object, e.g. `coef`, `logLik`, `plot`, `print`, `ranef`, `fixef`, `summary`, `AIC`, `getVarCov`, `vcov`, `confint`, `sigma`, `update`, `formula`, `resid`, and `fitted`. In addition, several special functions have been added, including `dynSurv`, `dynLong`, and `baseHaz`, as well as plotting functions for objects inheriting from the `dynSurv`, `dynLong`, `ranef`, and `mjoint` functions. For example,

```{r, eval = FALSE}
summary(fit)
plot(fit, param = 'gamma')
```

`mjoint` automatically estimates approximate standard errors using the empirical information matrix (Lin et al., 2002), but the `bootSE` function can be used as an alternative.

# Errors and updates

If you spot any errors or wish to see a new feature added, please file an issue at https://github.com/graemeleehickey/joineRML/issues or email [Graeme Hickey](mailto:graeme.hickey@liverpool.ac.uk).

# Further learning

For an overview of the model estimation being performed, please see the technical vignette, which can be accessed by

```{r, eval = FALSE}
vignette('technical', package = 'joineRML')
```

For a demonstration of the package, please see the introductory vignette, which can be accessed by

```{r, eval = FALSE}
vignette('joineRML', package = 'joineRML')
```

# Funding

This project is funded by the [Medical Research Council](https://mrc.ukri.org) (Grant number MR/M013227/1).

![](https://www.ukri.org/wp-content/themes/ukri/assets/img/ukri-mrc-standard-logo.png)

# Using the latest developmental version

To install the latest **developmental version**, you will need R version (version 3.3.0 or higher) and some additional software depending on what platform you are using.

## Windows

If not already installed, you will need to install [Rtools](https://cran.r-project.org/bin/windows/Rtools/). Choose the version that corresponds to the version of R that you are using.

## Mac OSX

If not already installed, you will need to install Xcode Command Line Tools. To do this, open a new terminal and run

```bash
$ xcode-select --install
```

## From R

The latest developmental version will not yet be available on CRAN. Therefore, to install it, you will need `devtools`. You can check you are using the correct version by running

Once the prerequisite software is installed, you can install `joineRML` by running the following command in an R console

```r
library('devtools')
install_github('graemeleehickey/joineRML')
```

# Compatibility with [`broom`](https://github.com/tidymodels/broom/)

Tidiers methods for objects of class `mjoint` (i.e. models fit with `joineRML`) are included in the [`broom`](https://github.com/tidymodels/broom/) package; this provides methods that allow extracting model estimates, predictions, and comparing models in a straightforward way.

See `vignette(topic = "joineRML-broom", package = "joineRML")` for further details and examples.

# References

1. Cox DR. Regression models and life-tables. *J R Stat Soc Ser B Stat Methodol.* 1972; **34(2)**: 187-220.

2. Henderson R, Diggle PJ, Dobson A. Joint modelling of longitudinal measurements and event time data. *Biostatistics.* 2000; **1(4)**: 465-480.

3. Hickey GL, Philipson P, Jorgensen A, Kolamunnage-Dona R. Joint modelling of time-to-event and multivariate longitudinal outcomes: recent developments and issues. *BMC Med Res Methodol.* 2016; **16(1)**: 117.

4. Laird NM, Ware JH. Random-effects models for longitudinal data. *Biometrics.* 1982; **38(4)**: 963-974.

5. Lin H, McCulloch CE, Mayne ST. Maximum likelihood estimation in the joint analysis of time-to-event and multiple longitudinal variables. *Stat Med.* 2002; **21**: 2369-2382.

6. Wulfsohn MS, Tsiatis AA. A joint model for survival and longitudinal data measured with error. *Biometrics.* 1997; **53(1)**: 330-339.

Owner

GitHub Events

Committers

Last synced: about 2 years ago

Issues and Pull Requests

Last synced: 6 months ago

Packages