---
title: "Stochastic Process Model for Analysis of Longitudinal and Time-to-Event Outcomes"
author: "Ilya Y. Zhbannikov"
date: "`r Sys.Date()`"
output: rmarkdown::html_document
bibliography: "references.bib"
vignette: >
  
  %\VignetteIndexEntry{stpm}
  %\VignetteEngine{knitr::rmarkdown}
  usepackage[utf8]{inputenc}
  %\VignetteEncoding{UTF-8}
---

```{r, message=FALSE, echo=FALSE, eval=FALSE}
library(knitcitations)
cleanbib()
options("citation_format" = "pandoc")
r<-citep("10.1016/0040-5809(77)90005-3") 
r<-citep("10.1016/j.mbs.2006.11.006")
r<-citep("10.1080/08898480590932296")
r<-citep("10.1007/s10522-006-9073-3")
r<-citep("10.1016/j.jtbi.2009.01.023")
r<-citep("10.3389/fpubh.2014.00228")
r<-citep("10.1002/gepi.22058")
r<-citep("10.3389/fpubh.2016.00003")
write.bibtex(file="references.bib")
```


## Overview

The Stochastic Process Model (SPM) was developed several decades ago [@Woodbury_1977, @Yashin_2007], and applied for analyses of clinical, demographic, epidemiologic longitudinal data as well as in many other studies that relate stochastic dynamics of repeated measures to the probability of end-points (outcomes). SPM links the dynamic of stochastical variables with a hazard rate as a quadratic function of the state variables [@Yashin_2007]. The R-package, "stpm", is a set of utilities to estimate parameters of stochastic process and modeling survival trajectories and time-to-event outcomes observed from longitudinal studies. It is a general framework for studying and modeling survival (censored) traits depending on random trajectories (stochastic paths) of variables.



## Installation
### Stable version from CRAN
```{r,eval=FALSE}
install.packages("stpm")
```

### Most-recent version from GitHub
```{r,eval=FALSE}
require(devtools)
devtools::install_github("izhbannikov/stpm")
```


## Data description

Data represents a typical longitudinal data in form of two datasets: longitudinal dataset (follow-up studies), in which one record represents a single observation, and vital (survival) statistics, where one record represents all information about the subject. Longitudinal dataset cat contain a subject ID (identification number), status (event(1)/censored(0)), time and measurements across the variables.

```{r,results='hide',warning=FALSE,echo=FALSE,message=FALSE}
library(stpm)
# Reading longitude data:
longdat <- read.csv(system.file("extdata","longdat.csv",package="stpm"))
```

Below there is an example of clinical data that can be used in ```stpm``` and we will discuss the fields later.

Longitudinal table:

```{r,echo=FALSE}
head(longdat)
```

#### Description of data fields

* ID - subject unique identificatin number.
* IndicatorDeath - 0/1, indicates death of a subject.
* Age - current age of subject at observation.
* DBP, BMI - covariates, here "DBP" represents a diastolic blood pressure, "BMI" a body-mass index.

#### "Short" and "Long" longitudinal data formats

The packate accepts longitudinal data in two formats: "short" and "long". 

##### "Short" format

```{r, echo=FALSE, message=FALSE}
data <- simdata_discr(N=1000, format="short")
```
```{r, echo=FALSE}
head(data)
```

##### "Long" format

```{r, echo=FALSE, message=FALSE}
data <- simdata_discr(N=1000, format="long")
```
```{r, echo=FALSE}
head(data)
```


## Discrete- and continuous-time models

There are two main SPM types in the package: discrete-time model [@Akushevich_2005] and continuous-time model [@Yashin_2007]. Discrete model assumes equal intervals between follow-up observations. The example of discrete dataset is given below.

```{r}
library(stpm)
data <- simdata_discr(N=10) # simulate data for 10 individuals, "long" format (default)
head(data)
```
In this case there are equal intervals between $t_1$ and $t_2$.

In the continuous-time SPM, in which intervals between observations are not equal (arbitrary or random). The example of such dataset is shown below:

```{r}
library(stpm)
data <- simdata_cont(N=5, format="short") # simulate data for 5 individuals, "short" format
head(data)
```



### Discrete-time model

The discrete model assumes fixed time intervals between consecutive observations. In this model, $\mathbf{Y}(t)$ (a $k \times 1$ matrix of the values of covariates, where $k$ is the number of considered covariates) and $\mu(t, \mathbf{Y}(t))$ (the hazard rate) have the following form:

$\mathbf{Y}(t+1) = \mathbf{u} + \mathbf{R} \mathbf{Y}(t) + \mathbf{\epsilon}$

$\mu (t, \mathbf{Y}(t)) = [\mu_0 + \mathbf{b} \mathbf{Y}(t) + \mathbf{Y}(t)^* \mathbf{Q} \mathbf{Y}(t)] e^{\theta t}$

Coefficients $\mathbf{u}$ (a $k \times 1$ matrix, where $k$ is a number of covariates), $\mathbf{R}$ (a $k \times k$ matrix), $\mu_0$, $\mathbf{b}$ (a $1 \times k$ matrix), $\mathbf{Q}$ (a $k \times k$ matrix) are assumed to be constant in the particular implementation of this model in the R-package ```stpm```. $\mathbf{\epsilon}$ are normally-distributed random residuals, $k \times 1$ matrix. A symbol '*' denotes transpose operation. $\theta$ is a parameter to be estimated along with other parameters ($\mathbf{u}$, $\mathbf{R}$, $\mathbf{\mu_0}$, $\mathbf{b}$, $\mathbf{Q}$).

#### Example

```{r}
library(stpm)
#Data simulation (200 individuals)
data <- simdata_discr(N=100)
#Estimation of parameters
pars <- spm_discrete(data)
pars
```

### Continuous-time model

In the specification of the SPM described in 2007 paper by Yashin and collegaues [@Yashin_2007] the stochastic differential equation describing the age dynamics of a covariate is:

$d\mathbf{Y}(t)= \mathbf{a}(t)(\mathbf{Y}(t) -\mathbf{f}_1(t))dt + \mathbf{b}(t)d\mathbf{W}(t), \mathbf{Y}(t=t_0)$

In this equation, $\mathbf{Y}(t)$ (a $k \times 1$ matrix) is the value of a particular covariate at a time (age) $t$. $\mathbf{f}_1(t)$ (a $k \times 1$ matrix) corresponds to the long-term mean value of the stochastic process $\mathbf{Y}(t)$, which describes a trajectory of individual covariate influenced by different factors represented by a random Wiener process $\mathbf{W}(t)$. Coefficient $\mathbf{a}(t)$ (a $k \times k$ matrix) is a negative feedback coefficient, which characterizes the rate at which the process reverts to its mean. 
In the area of research on aging, $\mathbf{f}_1(t)$ represents the mean allostatic trajectory and $\mathbf{a}(t)$ represents the adaptive capacity of the organism. Coefficient $\mathbf{b}(t)$ (a $k \times 1$ matrix) characterizes a strength of the random disturbances from Wiener process $\mathbf{W}(t)$.

The following function $\mu(t, \mathbf{Y}(t))$ represents a hazard rate:

$\mu(t, \mathbf{Y}(t)) = \mu_0(t) + (\mathbf{Y}(t) - \mathbf{f}(t))^* \mathbf{Q}(t) (\mathbf{Y}(t) - \mathbf{f}(t))$

here $\mu_0(t)$ is the baseline hazard, which represents a risk when $\mathbf{Y}(t)$ follows its optimal trajectory; $\mathbf{f}(t)$ (a $k \times 1$ matrix) represents the optimal trajectory that minimizes the risk and $\mathbf{Q}(t)$ ($k \times k$ matrix) represents a sensitivity of risk function to deviation from the norm.

#### Example

```{r}
library(stpm)
#Simulate some data for 50 individuals
data <- simdata_cont(N=50)
head(data)
#Estimate parameters
# a=-0.05, f1=80, Q=2e-8, f=80, b=5, mu0=2e-5, theta=0.08 are starting values for estimation procedure
pars <- spm_continuous(dat=data,a=-0.05, f1=80, Q=2e-8, f=80, b=5, mu0=2e-5, theta=0.08)
pars
```

### Coefficient conversion between continuous- and discrete-time models

The coefficient conversion between continuous- and discrete-time models is as follows ('c' and 'd' denote continuous- and discrete-time models respectively; note: these equations can be used if intervals between consecutive observations of discrete- and continuous-time models are equal; it also required that matrices $\mathbf{a}_c$ and $\mathbf{Q}_{c,d}$ must be full-rank matrices):

$\mathbf{Q}_c = \mathbf{Q}_d$

$\mathbf{a}_c = \mathbf{R}_d - I(k)$

$\mathbf{b}_c = \mathbf{\Sigma}$

${\mathbf{f}_1}_c = -\mathbf{a}_c^{-1} \times \mathbf{u}_d$

$\mathbf{f}_c = -0.5 \mathbf{b}_d \times \mathbf{Q}^{-1}_d$

${\mu_0}_c = {\mu _0}_d - \mathbf{f}_c \times \mathbf{Q_c} \times \mathbf{f}_c^*$

$\theta_c = \theta_d$

where $k$ is a number of covariates, which is equal to model's dimension and '*' denotes transpose operation; $\mathbf{\Sigma}$ is a $k \times 1$ matrix which contains ```s.d.```s of corresponding residuals  (residuals of a linear regression $\mathbf{Y}(t+1) = \mathbf{u} + \mathbf{R}\mathbf{Y}(t) + \mathbf{\epsilon}$; ```s.d.``` is a standard deviation), $I(k)$ is an identity $k \times k$ matrix.

### Model with time-dependent coefficients

In previous models, we assumed that coefficients is sort of time-dependant: we multiplied them on to $e^{\theta t}$. In general, this may not be the case [@Yashin_2007a]. We extend this to a general case, i.e. (we consider one-dimensional case):

$\mathbf{a(t)} = \mathbf{par}_1 t + \mathbf{par}_2$ - linear function. 

The corresponding equations will be equivalent to one-dimensional continuous case described above.

#### Example

```{r}
library(stpm)
#Data preparation:
n <- 10
data <- simdata_time_dep(N=n)
# Estimation:
opt.par <- spm_time_dep(data, 
                        start = list(a = -0.05, f1 = 80, Q = 2e-08, f = 80, b = 5, mu0 = 0.001), 
                        frm = list(at = "a", f1t = "f1", Qt = "Q", ft = "f", bt = "b", mu0t= "mu0"))
opt.par
```


## Setting lower and upper boundaries of the model parameters

Lower and upper boundaries can be set up with parameters $lb$ and $ub$, which represents simple numeric vectors. Note: lengths of  $lb$ and $ub$ must be the same as the total length of the parameters. Lower and upper boundaries can be set for continuous-time and time-dependent models only.

### Setting lb and ub for continuous-time model
#### One covariate

Below we show the example of setting up $lb$ and $ub$ when we have a single covariate:

```{r}
library(stpm)
data <- simdata_cont(N=10, ystart = 80, a = -0.1, Q = 1e-06, mu0 = 1e-5, theta = 0.08, f1 = 80, f=80, b=1, dt=1, sd0=5)
ans <- spm_continuous(dat=data,
                      a = -0.1,
                      f1 = 82, 
                      Q = 1.4e-6,
                      f = 77,
                      b = 1,
                      mu0 = 1.6e-5,
                      theta = 0.1,
                      stopifbound = FALSE,
                      lb=c(-0.2, 60, 0.1e-6, 60, 0.1, 0.1e-5, 0.01), 
                      ub=c(0, 140, 5e-06, 140, 3, 5e-5, 0.20))
ans
```

#### Two covariates

This is an example for two physiological variables (covariates).

```{r}
library(stpm)

data <- simdata_cont(N=10, 
                     a=matrix(c(-0.1,  0.001, 0.001, -0.1), nrow = 2, ncol = 2, byrow = T),
                     f1=t(matrix(c(100, 200), nrow = 2, ncol = 1, byrow = F)),
                     Q=matrix(c(1e-06, 1e-7, 1e-7,  1e-06), nrow = 2, ncol = 2, byrow = T),
                     f=t(matrix(c(100, 200), nrow = 2, ncol = 1, byrow = F)),
                     b=matrix(c(1, 2), nrow = 2, ncol = 1, byrow = F),
                     mu0=1e-4,
                     theta=0.08,
                     ystart = c(100,200), sd0=c(5, 10), dt=1)

a.d <- matrix(c(-0.15,  0.002, 0.002, -0.15), nrow = 2, ncol = 2, byrow = T)
f1.d <- t(matrix(c(95, 195), nrow = 2, ncol = 1, byrow = F))
Q.d <- matrix(c(1.2e-06, 1.2e-7, 1.2e-7,  1.2e-06), nrow = 2, ncol = 2, byrow = T)
f.d <- t(matrix(c(105, 205), nrow = 2, ncol = 1, byrow = F))
b.d <- matrix(c(1, 2), nrow = 2, ncol = 1, byrow = F)
mu0.d <- 1.1e-4
theta.d <- 0.07

ans <- spm_continuous(dat=data,
                      a = a.d, 
                      f1 = f1.d,
                      Q = Q.d,
                      f = f.d,
                      b = b.d,
                      mu0 = mu0.d,
                      theta = theta.d,
                      lb=c(-0.5, ifelse(a.d[2,1] > 0, a.d[2,1]-0.5*a.d[2,1], a.d[2,1]+0.5*a.d[2,1]), ifelse(a.d[1,2] > 0, a.d[1,2]-0.5*a.d[1,2], a.d[1,2]+0.5*a.d[1,2]), -0.5,  
                           80, 100, 
                           Q.d[1,1]-0.5*Q.d[1,1], ifelse(Q.d[2,1] > 0, Q.d[2,1]-0.5*Q.d[2,1], Q.d[2,1]+0.5*Q.d[2,1]), ifelse(Q.d[1,2] > 0, Q.d[1,2]-0.5*Q.d[1,2], Q.d[1,2]+0.5*Q.d[1,2]), Q.d[2,2]-0.5*Q.d[2,2],
                           80, 100,
                           0.1, 0.5,
                           0.1e-4,
                           0.01),
                      ub=c(-0.08,  0.002,  0.002, -0.08,  
                           110, 220, 
                           Q.d[1,1]+0.1*Q.d[1,1], ifelse(Q.d[2,1] > 0, Q.d[2,1]+0.1*Q.d[2,1], Q.d[2,1]-0.1*Q.d[2,1]), ifelse(Q.d[1,2] > 0, Q.d[1,2]+0.1*Q.d[1,2], Q.d[1,2]-0.1*Q.d[1,2]), Q.d[2,2]+0.1*Q.d[2,2],
                           110, 220,
                           1.5, 2.5,
                           1.2e-4,
                           0.10))
ans

```


### Setting lb and ub for model with time-dependent coefficients

This model uses only one covariate, therefore setting-up model parameters is easy:

```{r}
n <- 10
data <- simdata_time_dep(N=n)
# Estimation:
opt.par <- spm_time_dep(data, start=list(a=-0.05, f1=80, Q=2e-08, f=80, b=5, mu0=0.001), 
                        lb=c(-1, 30, 1e-8, 30, 1, 1e-6), ub=c(0, 120, 5e-8, 130, 10, 1e-2))
opt.par


```


#### Special case when some model parameter functions are equal to zero

Imagine a situation when one parameter function you want to be equal to zero: $f=0$. Let's emulate this case:

```{r}
library(stpm)
n <- 10
data <- simdata_time_dep(N=n)
# Estimation:
opt.par <- spm_time_dep(data, frm = list(at="a", f1t="f1", Qt="Q", ft="0", bt="b", mu0t="mu0"))
opt.par
```

As you can see, there is no parameter $f$ in $opt.par$. This is because we set $f=0$ in $frm$!

Then, is you want to set the constraints, you must not specify the starting value (parameter $start$) and $lb$/$ub$ for the parameter $f$ (otherwise, the function raises an error):

```{r}
library(stpm)
set.seed(12345678)
n <- 10
data <- simdata_time_dep(N=n, format = "long")

# Estimation:
opt.par <- spm_time_dep(data, frm = list(at="a", f1t="f1", Qt="Q", ft="0", bt="b", mu0t="mu0"), 
                        start=list(a=-0.05, f1=80, Q=2e-08, b=5, mu0=0.001), 
                        lb=c(-1, 30, 1e-8, 1, 1e-6), ub=c(0, 120, 5e-8, 10, 1e-2),
                        opts=list(maxit=100), 
                        verbose=F)
opt.par

```

You can do the same manner if you want two or more parameters to be equal to zero.

## Fast parameter estimating for one-dimentional model using spm_con_1d

Function ```spm_con_1d(...)``` allows for very fast parameter estimating for one-dimensional model. This function implements a analytical solution to estimate the parameters in the continuous SPM model by assuming all the parameters are constants. Below there is an example.

```{r}
library(stpm) 
dat <- simdata_cont(N=500)
colnames(dat) <- c("id", "xi", "t1", "t2", "y", "y.next")
res <- spm_con_1d(as.data.frame(dat), a=-0.05, b=2, q=1e-8, f=80, f1=90, mu0=1e-3, theta=0.08)
res
```


## Simulation (individual trajectory projection, also known as microsimulations)

We added one- and multi- dimensional simulation to be able to generate test data for hyphotesis testing. Data,  which can be simulated can be discrete (equal intervals between observations) and continuous (with arbitrary intervals).



### Discrete-time simulation

The corresponding function is (```k``` - a number of variables(covariates), equal to model's dimension):

```simdata_discr(N=100, a=-0.05, f1=80, Q=2e-8, f=80, b=5, mu0=1e-5, theta=0.08, ystart=80, tstart=30, tend=105, dt=1)```

Here:

```N``` - Number of individuals

```a``` - A matrix of ```k```x```k```, which characterize the rate of the adaptive response

```f1``` - A particular state, which if a deviation from the normal (or optimal). This is a vector with length of ```k```

```Q``` - A matrix of ```k``` by ```k```, which is a non-negative-definite symmetric matrix

```f``` - A vector-function (with length ```k```) of the normal (or optimal) state

```b``` - A diffusion coefficient, ```k``` by ```k``` matrix

```mu0``` - mortality at start period of time (baseline hazard)

```theta``` - A displacement coefficient of the Gompertz function

```ystart``` - A vector with length equal to number of dimensions used, defines starting values of covariates

```tstart``` - A number that defines a start time (30 by default). Can be a number (30 by default) or a vector of two numbers: c(a, b) - in this case, starting value of time is simulated via uniform(a,b) distribution.

```tend``` - A number, defines a final time (105 by default)

```dt``` - A time interval between observations.

This function returns a table with simulated data, as shown in example below:

```{r}
library(stpm)
data <- simdata_discr(N=10)
head(data)
```

### Continuous-time simulation

The corresponding function is (```k``` - a number of variables(covariates), equal to model's dimension):

```simdata_cont(N=100, a=-0.05, f1=80, Q=2e-07, f=80, b=5, mu0=2e-05, theta=0.08, ystart=80, tstart=c(30,50), tend=105)```

Here:

```N``` - Number of individuals

```a``` - A matrix of ```k```x```k```, which characterize the rate of the adaptive response

```f1``` - A particular state, which if a deviation from the normal (or optimal). This is a vector with length of ```k```

```Q``` - A matrix of ```k``` by ```k```, which is a non-negative-definite symmetric matrix

```f``` - A vector-function (with length ```k```) of the normal (or optimal) state

```b``` - A diffusion coefficient, ```k``` by ```k``` matrix

```mu0``` - mortality at start period of time (baseline hazard)

```theta``` - A displacement coefficient of the Gompertz function

```ystart``` - A vector with length equal to number of dimensions used, defines starting values of covariates

```tstart``` - A number that defines a start time (30 by default). Can be a number (30 by default) or a vector of two numbers: c(a, b) - in this case, starting value of time is simulated via uniform(a,b) distribution.

```tend``` - A number, defines a final time (105 by default)


This function returns a table with simulated data, as shown in example below:

```{r, eval=T}
library(stpm)
data <- simdata_cont(N=10)
head(data)
```

## SPM with partially observed covariates

Stochastic Process Model has many applications in analysis of longitudinal biodemographic data. Such data contain various physiological variables (known as covariates). Data can also potentially contain genetic information available for all or a part of participants. Taking advantage from both genetic and non-genetic information can provide future insights into a broad range of processes describing aging-related changes in the organism.

### Method

In this package, SPM with partially observed covariates is implemented in form of GenSPM (Genetic SPM), presented in [@Arbeev_2009] and further advanced in [@Arbeev_2014], further elaborates the basic stochastic process model conception by introducing a categorical variable, $Z$, which may be a specific value of a genetic marker or, in general, any categorical variable. Currently, $Z$ has two gradations: 0 or 1 in a genetic group of interest, assuming that $P(Z=1) = p$, $p \in [0, 1]$, were $p$ is the proportion of carriers and non-carriers of an allele in a population. Example of longitudinal data with genetic component $Z$ is provided below.

```{r, eval=T}
library(stpm)
data <- sim_pobs(N=10)
head(data)
```

In the specification of the SPM described in 2007 paper by Yashin and colleagues [@Yashin_2007] the stochastic differential equation describing the age dynamics of a physiological variable (a dynamic component of the model) is:

$dY(t) = a(Z, t)(Y(t) - f1(Z, t))dt + b(Z, t)dW(t), Y(t = t_0)$

Here in this equation, $Y(t)$ is a $k \times 1$ matrix, where $k$ is a number of covariates, which is a model dimension) describing the value of a physiological variable at a time (e.g. age) t. $f_1(Z,t)$ is a $k \times 1$ matrix that corresponds to the long-term average value of the stochastic process $Y(t)$, which describes a trajectory of individual variable influenced by different factors represented by a random Wiener process $W(t)$. The negative feedback coefficient $a(Z,t)$ ($k \times k$ matrix) characterizes the rate at which the stochastic process goes to its mean. In research on aging and well-being, $f_1(Z,t)$ represents the average allostatic trajectory and $a(t)$ in this case represents the adaptive capacity of the organism. Coefficient $b(Z,t)$ ($k \times 1$ matrix) characterizes a strength of the random disturbances from Wiener process $W(t)$. All of these parameters depend on $Z$ (a genetic marker having values 1 or 0).
The following function $\mu(t,Y(t))$ represents a hazard rate:

$\mu(t,Y(t)) = \mu_0(t) + (Y(t) - f(Z, t))^*Q(Z, t)(Y(t) - f(Z, t))$

In this equation: $\mu_0(t)$ is the baseline hazard, which represents a risk when $Y(t)$ follows its optimal trajectory; f(t) ($k \times 1$ matrix) represents the optimal trajectory that minimizes the risk and $Q(Z, t)$ ($k \times k$ matrix) represents a sensitivity of risk function to deviation from the norm. In general, model coefficients $a(Z, t)$, $f1(Z, t)$, $Q(Z, t)$, $f(Z, t)$, $b(Z, t)$ and $\mu_0(t)$ are time(age)-dependent.
Once we have data, we then can run analysis, i.e. estimate coefficients (they are assumed to be time-independent and data here is simulated):

```{r, eval=T}
library(stpm)
#Generating data:
data <- sim_pobs(N=10)
head(data)
#Parameters estimation:
pars <- spm_pobs(x=data)
pars
```

Here \textbf{H} and \textbf{L} represents parameters when $Z$ = 1 (**H**) and 0 (**L**).

###Joint analysis of two datasets: first dataset with genetic and second dataset with non-genetic component

```{r, eval=T}
library(stpm)
data.genetic <- sim_pobs(N=5, mode='observed')
head(data.genetic)
data.nongenetic <- sim_pobs(N=10, mode='unobserved')
head(data.nongenetic)
#Parameters estimation:
pars <- spm_pobs(x=data.genetic, y = data.nongenetic, mode='combined')
pars
```

Here mode 'observed' is used for simlation of data with genetic component $Z$ and 'unobserved' - without genetic component.

## Genetic SPM 'GSPM'

This type of SPM also uses genetic component by analogy from the previous chapters but uses explicit gradient function which speeds up computations significantly. See [@He_2017] for details. Below we provide examples of usage:

```{r, eval=T}
library(stpm) 
data(ex_spmcon1dg)
head(ex_data$spm_data)
head(ex_data$gene_data)
res <- spm_con_1d_g(spm_data=ex_data$spm_data, 
                    gene_data=ex_data$gene_data, 
                    a = -0.02, b=0.2, q=0.01, f=3, f1=3, mu0=0.01, theta=1e-05, 
                    upper=c(-0.01,3,0.1,10,10,0.1,1e-05), lower=c(-1,0.01,0.00001,1,1,0.001,1e-07), 
                    effect=c('q'), method = "tnewton")
res
```

Here:
```spm_data``` - A dataset for the SPM model. See the STPM package for more details about the format.

```gene_data``` - A two column dataset containing the genotypes for the individuals in spm_data. The first column ```id``` is the ID of the individuals in dataset ```spm_data```, and the second column ```geno``` is the genotype. 

```a``` - The initial value for the paramter \eqn{a}. The initial value will be predicted if not specified.

```b``` - The initial value for the paramter \eqn{b}. The initial value will be predicted if not specified. 

```q``` - The initial value for the paramter \eqn{q}. The initial value will be predicted if not specified.

```f``` -  The initial value for the paramter \eqn{f}. The initial value will be predicted if not specified.

```f1``` - The initial value for the paramter \eqn{f_1}. The initial value will be predicted if not specified.

```mu0``` - The initial value for the paramter \eqn{\mu_0} in the baseline hazard. The initial value will be predicted if not specified.

```theta``` - The initial value for the paramter \eqn{\theta} in the baseline hazard. The initial value will be predicted if not specified.

```lower``` - A vector of the lower bound of the parameters.

```upper``` - A vector of the upper bound of the parameters.

```effect``` - A character vector of the parameters that are linked to genotypes. The vector can contain any combination of \code{a}, \code{b}, \code{q}, \code{f}, \code{mu0}.

```control``` - A list of the control parameters for the optimization paramters.

```global``` - A logical variable indicating whether the MLSL (TRUE) or the L-BFGS (FALSE) algorithm is used for the optimization.

```verbose``` - A logical variable indicating whether initial information is printed.

```ahessian``` - A logical variable indicating whether the approximate (FALSE) or analytical (TRUE) Hessian is returned.

```est``` - The estimates of the parameters.

```hessian``` - The Hessian matrix of the estimates.

```lik``` - The minus log-likelihood.

```con``` - A number indicating the convergence. See the 'nloptr' package for more details.

```message``` - Extra message about the convergence. See the 'nloptr' package for more details.

```beta``` - The coefficients of the genetic effect on the parameters to be linked to genotypes.

## Multiple imputation with spm.impute(...)

The SPM offers longitudinal data imputation with results that are better than from other imputation tools since it preserves data structure, i.e. relation between 
Y(t) and mu(Y(t),t). Below there are two examples of multiple data imputation with function spm.impute(...).

```{r, eval=TRUE, message=FALSE}
library(stpm)

#######################################################################
############## One dimensional case (one covariate) ###################
#######################################################################

## Data preparation (short format)#
data <- simdata_discr(N=1000, dt = 2, format="short")

miss.id <- sample(x=dim(data)[1], size=round(dim(data)[1]/4)) # ~25% missing data
incomplete.data <- data
incomplete.data[miss.id,4] <- NA
# End of data preparation #

##### Multiple imputation with SPM #####
imp.data <- spm.impute(x=incomplete.data, id=1, case="xi", t1=3, covariates="y1", minp=1, theta_range=seq(0.075, 0.09, by=0.001))$imputed

##### Look at the incomplete data with missings #####
head(incomplete.data)

##### Look at the imputed data #####
head(imp.data)

#########################################################
################ Two-dimensional case ###################
#########################################################

## Parameters for data simulation #
a <- matrix(c(-0.05, 0.01, 0.01, -0.05), nrow=2)
f1 <- matrix(c(90, 30), nrow=1, byrow=FALSE)
Q <- matrix(c(1e-7, 1e-8, 1e-8, 1e-7), nrow=2)
f0 <- matrix(c(80, 25), nrow=1, byrow=FALSE)
b <- matrix(c(5, 3), nrow=2, byrow=TRUE)
mu0 <- 1e-04
theta <- 0.07
ystart <- matrix(c(80, 25), nrow=2, byrow=TRUE)

## Data preparation #
data <- simdata_discr(N=1000, a=a, f1=f1, Q=Q, f=f0, b=b, ystart=ystart, mu0 = mu0, theta=theta, dt=2, format="short")

## Delete some observations in order to have approx. 25% missing data
incomplete.data <- data
miss.id <- sample(x=dim(data)[1], size=round(dim(data)[1]/4)) 
incomplete.data <- data
incomplete.data[miss.id,4] <- NA
miss.id <- sample(x=dim(data)[1], size=round(dim(data)[1]/4)) 
incomplete.data[miss.id,5] <- NA
## End of data preparation #

###### Multiple imputation with SPM #####
imp.data <- spm.impute(x=incomplete.data, id=1, case="xi", t1=3, covariates=c("y1", "y2"), minp=1, theta_range=seq(0.060, 0.07, by=0.001))$imputed

###### Look at the incomplete data with missings #####
head(incomplete.data)

###### Look at the imputed data #####
head(imp.data)
```

## Prediction

We provide a simple function to predict the next value of \code{Y}.
Refer to the example below:

```{r}
#library(stpm)
#data <- simdata_discr(N=100, format="long")
#res <- spm_discrete(data)
#splitted <- split(data, data$id)
#df <- data.frame()
#lapply(1:100, function(i) {df<<-rbind(df,splitted[[i]][dim(splitted[[i]])[1],c("id", "xi", "t1", "y1")])})
#names(df) <- c("id", "xi", "t", "y")
#predicted <- predict(object=res, data=df, dt=3)
#head(predicted)
```

## Hypothesis testing

The package offers following five hypotheses to test for \code{spm_time_dep(...)} function [@Arbeev_2016]:

```H01```: $Q(t)=0$ (i.e., $a_Q = 0$ and $b_Q = 0$,so that there is no quadratic term in the hazard rate and mortality is described by the baseline Gompertz rate $μ_0(t)$).

```H02```: $Q(t) = a_Q$ (i.e., $b_Q = 0$). 

```H03```: $f_1(t) = 0$ (i.e., $a_{f1} = 0$ and $b_{f1} = 0$).

```H04```: $f_1(t) = a_{f_1}$ (i.e., $b_{f_1} = 0$).

```H05```: $a(t) = a_Y$ (i.e., $b_Y = 0$).


To perform hypothesis testing you should put the variable ```lrtest``` to ```TRUE``` (this is ```"H01"``` by default) or to any of the following: ```"H01"```, ```"H02"```, ```"H03"```, ```"H04"```, ```"H05"```.

### Examples of hypothesis testing

```{r, eval=FALSE}
library(stpm)
n <- 1000

# Data simulation:
data <- simdata_time_dep(N=n, format="long")
head(data)

# Hypotheses testing

## H01
res <- spm_time_dep(data, verbose=F, 
                    frm = list(at="a", f1t="f1", Qt="Q", ft="f", bt="b", mu0t="mu0"),
                    start=list(a=-0.05, f1=80, Q=1e-8, f=90, b=5, mu0=0.001), 
                    lb=c(a=-1, f1=30, Q=1e-9, f=10, b=1, mu0=1e-6), 
                    ub=c(a=0, f1=120, Q=1e-7, f=150, b=10, mu0=1e-2),
                    opts = list(algorithm = "NLOPT_LN_NELDERMEAD", 
                    maxeval = 200, ftol_rel = 1e-12), lrtest="H01")

res$alternative$lr.test.pval

## H02
res <- spm_time_dep(data, verbose=F, 
                    frm = list(at="a", f1t="f1", Qt="1e-6", ft="f", bt="b", mu0t="mu0"),
                    start=list(a=-0.05, f1=80, Q=1e-8, f=90, b=5, mu0=0.001), 
                    lb=c(a=-1, f1=30, Q=1e-9, f=10, b=1, mu0=1e-6), 
                    ub=c(a=0, f1=120, Q=1e-7, f=150, b=10, mu0=1e-2),
                    opts = list(algorithm = "NLOPT_LN_NELDERMEAD", 
                    maxeval = 200, ftol_rel = 1e-12), lrtest="H02")

res$alternative$lr.test.pval

## H03
res <- spm_time_dep(data, verbose=F, 
                    frm = list(at="a", f1t="f1", Qt="Q", ft="f", bt="b", mu0t="mu0"),
                    start=list(a=-0.05, f1=80, Q=1e-8, f=90, b=5, mu0=0.001), 
                    ub=c(a=0, f1=120, Q=1e-7, f=150, b=10, mu0=1e-2),
                    opts = list(algorithm = "NLOPT_LN_NELDERMEAD", 
                    maxeval = 200, ftol_rel = 1e-12), lrtest="H03")

res$alternative$lr.test.pval

## H04
res <- spm_time_dep(data, verbose=F, 
                    frm = list(at="a", f1t="120", Qt="Q", ft="f", bt="b", mu0t="mu0"),
                    start=list(a=-0.05, f1=80, Q=1e-8, f=90, b=5, mu0=0.001), 
                    lb=list(a=-1, f1=30, Q=1e-9, f=10, b=1, mu0=1e-6), 
                    opts = list(algorithm = "NLOPT_LN_NELDERMEAD", 
                    maxeval = 200, ftol_rel = 1e-12), lrtest="H04")

res$alternative$lr.test.pval

## H05
res <- spm_time_dep(data, verbose=F, 
                    frm = list(at="-0.1", f1t="f1", Qt="Q", ft="f", bt="b", mu0t="mu0"),
                    start=list(a=-0.05, f1=80, Q=1e-8, f=90, b=5, mu0=0.001), 
                    opts = list(algorithm = "NLOPT_LN_NELDERMEAD", 
                    maxeval = 200, ftol_rel = 1e-12), lrtest="H05")

res$alternative$lr.test.pval
```



## References