Renaming package

jamesmurray7 · Dec 5, 2022 · 7c7dd5f · 7c7dd5f
1 parent 8e31208
commit 7c7dd5f
Show file tree

Hide file tree

Showing 10 changed files with 113 additions and 80 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,8 +1,8 @@
-Package: GMVJM
+Package: gmvjoint
 Type: Package
 Title: Joint models of survival and multivariate longitudinal data
-Version: 0.5
-Date: 2022-12-02
+Version: 0.1
+Date: 2022-12-05
 Author: James Murray
 Maintainer: James Murray <[email protected]>
 Description: Fit joint models of survival and multivariate longitudinal data. The longitudinal
@@ -26,4 +26,4 @@ LinkingTo: Rcpp, RcppArmadillo
 Encoding: UTF-8
 RoxygenNote: 7.2.2
 LazyData: true
-URL: https://github.com/jamesmurray7/GMVJM
+URL: https://github.com/jamesmurray7/gmvjoint
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,4 +1,4 @@
-useDynLib(GMVJM, .registration=TRUE)
+useDynLib(gmvjoint, .registration=TRUE)
 importFrom(Rcpp, evalCpp)
 importFrom("methods", "el")
 importFrom("stats", "Gamma", "as.formula", "binomial", "coef", "cov",

diff --git a/NEWS.md b/NEWS.md
@@ -1,2 +1,2 @@
-# GMVJM version 0.1
+# gmvjoint version 0.1
 * First release
diff --git a/R/RcppExports.R b/R/RcppExports.R
@@ -4,90 +4,90 @@
 #' Specifically for obtaining pmf in simulations (since requisite doesn't exist in R).
 #' @keywords internal
 GP1_pmf_scalar <- function(mu, phi, Y) {
- .Call(`_GMVJM_GP1_pmf_scalar`, mu, phi, Y)
+ .Call(`_gmvjoint_GP1_pmf_scalar`, mu, phi, Y)
 }
 
 #' log-likelihood of Gamma
 #' @keywords internal
 ll_Gamma <- function(Y, shape, mu) {
- .Call(`_GMVJM_ll_Gamma`, Y, shape, mu)
+ .Call(`_gmvjoint_ll_Gamma`, Y, shape, mu)
 }
 
 #' 'GP1' from Zamani & Ismail (2012)
 #' @keywords internal
 ll_genpois <- function(eta, phi, Y) {
- .Call(`_GMVJM_ll_genpois`, eta, phi, Y)
+ .Call(`_gmvjoint_ll_genpois`, eta, phi, Y)
 }
 
 #' Survival log-density
 #' @keywords internal
 logfti <- function(b, S, SS, Fi, Fu, l0i, haz, Delta, gamma_rep, zeta) {
- .Call(`_GMVJM_logfti`, b, S, SS, Fi, Fu, l0i, haz, Delta, gamma_rep, zeta)
+ .Call(`_gmvjoint_logfti`, b, S, SS, Fi, Fu, l0i, haz, Delta, gamma_rep, zeta)
 }
 
 #' The joint density
 #' @keywords internal
 joint_density <- function(b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K) {
- .Call(`_GMVJM_joint_density`, b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K)
+ .Call(`_gmvjoint_joint_density`, b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K)
 }
 
 #' Quadrature - standard deviation of N(mu, tau^2).
 #' @keywords internal
 maketau <- function(S, Z) {
- .Call(`_GMVJM_maketau`, S, Z)
+ .Call(`_gmvjoint_maketau`, S, Z)
 }
 
 #' First derivative of the joint density with respect to b.
 #' @keywords internal
 joint_density_ddb <- function(b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K) {
- .Call(`_GMVJM_joint_density_ddb`, b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K)
+ .Call(`_gmvjoint_joint_density_ddb`, b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K)
 }
 
 #' Create vector of scores on fixed effects.
 #' @keywords internal
 Sbeta <- function(beta, X, Y, Z, b, sigma, family, beta_inds, K, quad, tau, w, v) {
- .Call(`_GMVJM_Sbeta`, beta, X, Y, Z, b, sigma, family, beta_inds, K, quad, tau, w, v)
+ .Call(`_gmvjoint_Sbeta`, beta, X, Y, Z, b, sigma, family, beta_inds, K, quad, tau, w, v)
 }
 
 #' Hessian matrix on fixed effects.
 #' @keywords internal
 Hbeta <- function(beta, X, Y, Z, b, sigma, family, beta_inds, K, quad, tau, w, v) {
- .Call(`_GMVJM_Hbeta`, beta, X, Y, Z, b, sigma, family, beta_inds, K, quad, tau, w, v)
+ .Call(`_gmvjoint_Hbeta`, beta, X, Y, Z, b, sigma, family, beta_inds, K, quad, tau, w, v)
 }
 
 #' Update for residual variance (sigma for gaussian family)
 #' @keywords internal
 vare_update <- function(X, Y, Z, b, beta, tau, w, v) {
- .Call(`_GMVJM_vare_update`, X, Y, Z, b, beta, tau, w, v)
+ .Call(`_gmvjoint_vare_update`, X, Y, Z, b, beta, tau, w, v)
 }
 
 #' Update for dispersion parameter (sigma for \code{"genpois"} family)
 #' @keywords internal
 phi_update <- function(b, X, Y, Z, beta, phi, w, v, tau) {
- .Call(`_GMVJM_phi_update`, b, X, Y, Z, beta, phi, w, v, tau)
+ .Call(`_gmvjoint_phi_update`, b, X, Y, Z, beta, phi, w, v, tau)
 }
 
 #' Score vector for survival parameters.
 #' @keywords internal
 Sgammazeta <- function(gammazeta, b, Sigma, S, SS, Fu, Fi, haz, Delta, w, v, b_inds, K, q, eps) {
- .Call(`_GMVJM_Sgammazeta`, gammazeta, b, Sigma, S, SS, Fu, Fi, haz, Delta, w, v, b_inds, K, q, eps)
+ .Call(`_gmvjoint_Sgammazeta`, gammazeta, b, Sigma, S, SS, Fu, Fi, haz, Delta, w, v, b_inds, K, q, eps)
 }
 
 #' Hessian matrix for survival parameters.
 #' @keywords internal
 Hgammazeta <- function(gammazeta, b, Sigma, S, SS, Fu, Fi, haz, Delta, w, v, b_inds, K, q, eps) {
- .Call(`_GMVJM_Hgammazeta`, gammazeta, b, Sigma, S, SS, Fu, Fi, haz, Delta, w, v, b_inds, K, q, eps)
+ .Call(`_gmvjoint_Hgammazeta`, gammazeta, b, Sigma, S, SS, Fu, Fi, haz, Delta, w, v, b_inds, K, q, eps)
 }
 
 #' Update to the baseline hazard
 #' @keywords internal
 lambdaUpdate <- function(survtimes, ft, gamma, gamma_rep, zeta, S, Sigma, b, w, v, b_inds, K, q) {
- .Call(`_GMVJM_lambdaUpdate`, survtimes, ft, gamma, gamma_rep, zeta, S, Sigma, b, w, v, b_inds, K, q)
+ .Call(`_gmvjoint_lambdaUpdate`, survtimes, ft, gamma, gamma_rep, zeta, S, Sigma, b, w, v, b_inds, K, q)
 }
 
 #' Second derivative of joint density wrt b
 #' @keywords internal
 joint_density_sdb <- function(b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K, eps) {
- .Call(`_GMVJM_joint_density_sdb`, b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K, eps)
+ .Call(`_gmvjoint_joint_density_sdb`, b, Y, X, Z, beta, D, sigma, family, Delta, S, Fi, l0i, SS, Fu, haz, gamma_rep, zeta, beta_inds, b_inds, K, eps)
 }
 
diff --git a/README.md b/README.md
@@ -1,20 +1,22 @@
-# `GMVJM`
+# `gmvjoint`
 
-## What is `GMVJM`?
+## What is `gmvjoint`?
 
-* "**G**eneralised"
-* **M**ulti**v**ariate
-* **J**oint **M**odels.
+* "**g**eneralised"
+* **m**ulti**v**ariate
+* **Joint** models.
 
 
-GMVJM allows the user to fit joint models of survival and multivariate longitudinal data, where the 
+`gmvjoint` allows the user to fit joint models of survival and multivariate longitudinal data, where the 
 longitudinal sub-models are specified by generalised linear mixed models (GLMMs). The joint models 
 are fit via maximum likelihood using an approximate EM algorithm first proposed by Bernhardt *et
 al*. (2015). The GLMMs are specified using the same syntax as for package `glmmTMB` (Brooks *et
 al*., 2017). The joint models themselves are then the flexible extensions to those in e.g.
 Wulfoshn and Tsiatis (1997). The user is able to simulate data under many different response
 types.
 
+Currently, five families can be fit: Gaussian; Poisson; binomial; Gamma and generalised Poisson. 
+
 ## To-do list
 The package in current incantation is relatively skeletal, as such not a lot of post-hoc
 anaylses on fitted joint models is possible. As such, an immediate to-do list currently looks like
@@ -26,6 +28,37 @@ which just needs to be ported over.
 No promises are made w.r.t timescale of these being implemented: Currently I am a PhD
 student and little cache is awarded for production or maintenance of R packages!
 
+## Example
+To fit a joint model, we first need to specify the longitudinal and survival sub-models. 
+
+The longitudinal sub-model **must** be a list which contains the specification of the longitudinal process along with its random effects structure 
+in the same syntax as a [glmmTMB](https://cran.r-project.org/web/packages/glmmTMB/index.html) model (which itself is the same as the widely-used `lme4`). 
+As an example, suppose we want to fit a trivariate model on the oft-used PBC data, with a linear time-drug interaction term on albumin, a spline term on
+(logged) serum bilirubin and a linear fit on spiders, we specify
+```r
+PBC$serBilir <- log(PBC$serBilir)
+long.formulas <- list(
+ albumin ~ drug * time + (1 + time|id),
+ serBilir ~ drug * splines::ns(time, 3) + (1 + splines::ns(time, 3)|id),
+ spiders ~ drug * time + (1|id)
+)
+```
+where we note interactions and spline-time fits are possible. Currently, transformations on variables (e.g. `log(Y)`) must be done *before* this setup of formulae. 
+
+The survival sub-model must be set-up using `Surv()` from the [survival](https://cran.r-project.org/web/packages/survival/) package e.g.
+```r
+surv.formula <- Surv(survtime, status) ~ drug
+```
+Currently interaction terms in the survival sub-model specification are unsupported. 
+
+Now we can do the joint model call through the main workhorse function `joint`. This notably take a *list* of family arguments which **must** match-up in the desired order as the longitudinal process
+list. We call our `fit` via
+```r
+fit <- joint(long.formulas = long.formulas, surv.formula = surv.formula, data = PBC, 
+ family = list("gaussian", "gaussian", "binomial"))
+```
+where extra control arguments are documented in `?joint`.
+
 ## References
 
 Bernhardt PW, Zhang D and Wang HJ. A fast EM Algorithm for Fitting Joint Models of a Binary 

diff --git a/GMVJM.Rproj → gmvjoint.Rproj b/GMVJM.Rproj → gmvjoint.Rproj
diff --git a/man/GMVJM-package.Rd → man/gmvjoint-package.Rd b/man/GMVJM-package.Rd → man/gmvjoint-package.Rd
@@ -1,12 +1,12 @@
-\name{GMVJM-package}
-\alias{GMVJM-package}
-\alias{GMVJM}
+\name{gmvjoint-package}
+\alias{gmvjoint-package}
+\alias{gmvjoint}
 \docType{package}
 \title{
-\packageTitle{GMVJM}
+\packageTitle{gmvjoint}
 }
 \description{
-GMVJM allows the user to fit joint models of survival and multivariate longitudinal data. The 
+gmvjoint allows the user to fit joint models of survival and multivariate longitudinal data. The 
 longitudinal data is specified by generalised linear mixed models (GLMMs). The joint models 
 are fit via maximum likelihood using an approximate EM algorithm first proposed by Bernhardt et
 al. (2015). The GLMMs are specified using the same syntax as for package \code{glmmTMB} Brooks et
@@ -16,7 +16,7 @@ types.
 }
 
 \author{ 
- \packageAuthor{GMVJM}
+ \packageAuthor{gmvjoint}
 }
 
 \references{