ngme: Maximum likelihood estimation of non-Gaussian longitudinal...

In davidbolin/ngme: Linear Mixed Effects Models With Flexible Distributions

Maximum likelihood estimation of non-Gaussian longitudinal models

Description

Estimates model parameters for longitudinal models using maximum likelihood implemented by a computationally efficient stochastic gradient algorithm. See ngme.spatial for estimation of spatial models.

Usage

ngme(
  fixed,
  random = NULL,
  use.process = FALSE,
  reffects = "Normal",
  process = c("Normal", "fd2"),
  error = "Normal",
  error_assymetric = FALSE,
  data,
  timeVar = NULL,
  silent = TRUE,
  nIter = 1000,
  mesh = list(max.dist = NULL, cutoff = NULL, common.grid = FALSE, extend = NULL,
    n.cores = 1),
  controls = list(learning.rate = 0.2, polyak.rate = -1, nBurnin = 100, nSim = 2,
    pSubsample = NULL, nPar.burnin = 0, nIter.fisher = 1000, nSim.fisher = 1000, step0 =
    1, alpha = 0.6, nBurnin.learningrate = NULL, nBurnin.base = 0, subsample.type = 4,
    pSubsample2 = 0.3, standardize.mixedEffects = FALSE, estimate.fisher = FALSE,
    individual.sigma = FALSE, iter.start = 0),
  controls.init = list(learning.rate.init = 0, polyak.rate.init = 0.1, nBurnin.init =
    100, nSim.init = 2, nIter.init = 1000, pSubsample.init = 0.1, nPar.burnin.init = 0,
    step0.init = 0.3, alpha.init = 0.3, nBurnin.learningrate.init = NULL,
    nBurnin.base.init = 0, subsample.type.init = 0, pSubsample2.init = 0.3,
    standardize.mixedEffects.init = FALSE, individual.sigma.init = FALSE),
  init.fit = NULL
)

Arguments

fixed	A two-sided formula to specify the fixed effects design matrix.
random	A one-sided formula to specify the random effects design matrix.
use.process	A logical variable for inclusion of the stochastic process in the mixed model: "TRUE" indicates inclusion, "FALSE" exclusion.
reffects	A character string that indicates the distribution of the random effects. Available options are: "Normal" for Normal distribution, and "NIG" for Normal-inverse Gaussian.
process	A character vector with two elements to specify the process. Whilst the first element is for the covariance structure, the second element for the process distribution. Available options for the first are: "fd2" for integrated Random-Walk (integrated Brownian Motion), "matern" for Matern covarince with smoothnes 3/2, "exponential" for exponential covarince (Matern with smoothnes 1/2); for the second element are: "Normal" for Normal distribution, "NIG" for Normal-inverse Gaussian, "GAL" for generalised-asymmetric Laplace, and "CH" for Cauchy. process is ignored when use.process is set to FALSE.
error	A character string to specify the distribution of the error term. Available options are: "Normal" for Normal distribution, "NIG" for Normal-inverse Gaussian, "tdist" for t.
error_assymetric	if true the non-Gaussian error is assymetric
data	A data-frame from which the response and covariates to be extracted.
silent	A logical value for printing the details of the iterations; "TRUE" indicates do not print, "FALSE" print.
nIter	A numeric value for the number of iteration that will be used by the stochastic gradient.
mesh	A list of control variables for creating mesh. max.dist cutoff A numeric value. All time points that are separated less than cutoff will be merged to one node. commond.grid A logical value for creating same grids for different subjects. "TRUE" indicates common grid, "FALSE" uncommon grid. extend A numeric value or two element numeric vector for extending the meshes beyond the measurement locations with the specified percentage(s). If extend is specified by a single value, it indicates extending the mesh towards left and right by the same amount. If specified by a two element vector, whilst the first element is for extending towards the left, the second is for extending towards the right. If you want to extend by a fixed amount instead of with a percentage of the interval length, use a negative value of extend. So for example, extend = c(-1,0.1) means that the interval is extend by 1 to the left and by 10 percent to the right. n.cores A numeric value for the number of cores to be used to create the mesh.
controls	A list of control variables for parameter estimation. learning.rate A numeric value for the parameter of stochastic gradient. polyak.rate A numeric value for moving average of parameters; -1: inactive, 0: pure mean. nBurnin A numeric value for the number of steps before starting gradient estimation. nSim A numeric value for the number of samples of the Gibbs sampler to estimate the gradient. pSubsample A numeric value for the portion of data to be used in each gradient iteration. pSubsample = 1 indicates use of all subjects' data. nPar.burnin A numeric value; "M-step" updates will be used until this iteration. nIter.fisher A numeric value for the number of iterations to be used to obtain the Fisher-Information matrix. nSim.fisher A numeric value for the number of samples of the Gibbs sampler to obtain the Fisher-Information matrix. step0 A numeric value for step-size of the optimizer; where step-size is defined as step0 / i^alpha, i being the iteration, alpha is another tuning parameter specified next. alpha A numeric value for stepsize of the optimizer; step0 / i^alpha. nBurnin.learningrate A numeric value until which the learning will not be started. nBurnin.base A numerical value for burn-in simulations that are performed for a subject that is sampled for the first time in the estimation method. subsample.type A numeric value for the type of subsampling; 1: uniform sampling, 2: sample size weighted, 3: weighted sampling by gradient size, 4: grouped sub-sampler. pSubsample2 A numeric value for the portion of the data to be used in each gradient subsampling weighted by gradient. standardize.mixedEffects A logical variable for standardising the covariates; "FALSE" indicates no standardisation, "TRUE" standardisation. estimate.fisher A logical variable or numeric scalar for whether Fisher-Information matrix to be obtained; "FALSE" indicates do not obtain, 1 expected Fisher matrix, 2 for observed. individual.sigma A logical variable for specifying patient-specific mixture random variable for the error-term; "FALSE" indicates do not obtain, "TRUE" obtain.
controls.init	A list of control variables to be used to fit the normal model to get the initial values for fitting a model with at least one of random effects, process and error being non-Gaussian. learning.rate.init See learning.rate in controls. polyak.rate.init See polyak.rate in controls. nBurnin.init See nBurnin in controls. nSim.init See nSim in controls. nIter.init See nIter in controls. pSubsample.init See pSubsample in controls. nPar.burnin.init See nPar.burnin in controls. step0.init See step0 in controls. alpha.init See alpha in controls. nBurnin.learningrate.init See nBurnin.learningrate in controls. nBurnin.base.init See nBurnin.base in controls. subsample.type.init See subsample.type in controls. pSubsample2.init See pSubsample2 in controls. standardize.mixedEffects.init See standardize.mixedEffects in controls. individual.sigma.init = FALSE See individual.sigma in controls.
init.fit	A fitted ngme object with normal distribution for random effects, process and error.
timevar	A character string that indicates the column name of the time variable in data.

Details

We strongly suggest to use ngme.par instead of this function, for parallell computations and automatic stopping criteria. Generic functions summary, print and plot are available for the output returned by the function ngme. For Matern covariance function, currently the shape parameter is set to 0.5 which corresponds to exponential correlation function.

Value

A list of outputs.

See Also

ngme.spatial

Examples

  ## Not run: 
  data(srft_data)
  
  #Consider a subsample of the data
  rs_id <- sample(unique(srft_data$id), 731, replace = FALSE)
  srft_data_sub <- srft_data[srft_data$id %in% rs_id, ]

  # fit the model with normal assumption for random effects, process and error
  fit_normal <- ngme(fixed = log(egfr) ~ sex + bage + fu + pwl,
                     random = ~ 1|id,
                     data = srft_data_sub,
                     reffects = "Normal",
                     process = c("Normal", "fd2"),
                     error = "Normal",
                     timeVar = "fu",
                     nIter = 1000,
                     use.process = TRUE,
                     silent = FALSE,
                     mesh = list(cutoff = 1/365, max.dist = 1/12, extend = 0.01),
                     controls = list(pSubsample = 0.1))
                     
 #Plot trajectories of fixed effect estimates
 plot(fit_normal, param = "fixed")
 
 #plot the other parameter trajectories
 par(mfrow=c(2,2))
 plot(fit_normal, param = "random")
 plot(fit_normal, param = "error")
 plot(fit_normal, param = "process")
                     
# fit the model with NIG assumption for all the random components
fit_nig <- update(fit_normal, 
                  reffects = "NIG",
                  process = c("NIG", "fd2"),
                  error = "NIG",
                  init.fit = fit_normal)

#plot updated fixed effect estimates
plot(fit_nig,param="fixed")

## End(Not run)

davidbolin/ngme documentation built on Dec. 5, 2023, 11:48 p.m.