runPCModel: Run the model

In cammiller/imagingPC: Analysis of Imaging Mass Spectrometry Data using a Process Convolution Approach

Description

The runPCModel function runs the model created by the writePCModel function, using the information generated by the createPCData function.

Usage

runPCModel(modelObj, PCDataObj, nIter = 50000, nBurnin = 10000,
  nThin = 5, slideVar = NULL, keepModel = TRUE,
  keepModelObj = FALSE, monitorCoefOnly = TRUE, returnSample = TRUE,
  returnAllSummary = FALSE, justReturnData = FALSE,
  convergenceTol = 1.1, maxRuns = 5, iterIncrement = 500,
  iterWindow = 1000, sliceSamplers = FALSE)

Arguments

modelObj	An object of class PCModelList. This object is the result of using the writePCModel function.
PCDataObj	An object of class PCDataList. This object is the result of using the createPCData function.
nIter	An integer specifying he total number of iterations for the MCMC, pre-thinning. This includes the burn-in.
nBurnin	An integer specifying the number of iterations (pre-thinning) to be discarded.
nThin	An integer specifying the thinning interval.
slideVar	An optional argument specifying a slide variable. This option is only useful for data with zeros and when those zeros are assumed to be censored observations. In this case, the censoring threshold can vary by each run of the mass spectrometer. When this argument is used, the censoring threshold will be allowed to vary by slide.
keepModel	A TRUE/FALSE argument specifying whether or not to keep the model (found in the modelObj).
keepModelObj	A TRUE/FALSE argument specifying whether the compiled NIMBLE model object should be kept after running the model. This object can be large, but it is required for restarting the MCMC.
monitorCoefOnly	A TRUE/FALSE argument stating whether to monitor the the model coefficients only (TRUE) or all stochastic nodes (FALSE). Regardless of the value of this argument, if any categorical covariates are included in the model, the differences between all subgroups of the categorical covariate(s) will be monitored in the MCMC with assigned nodes.
returnSample	A TRUE/FALSE argument specifying whether to return the entire MCMC sample. If this argument is FALSE, only the summary measures will be returned.
returnAllSummary	A TRUE/FALSE argument specifying whether to return summary measures for all monitored nodes.
justReturnData	A TRUE/FALSE argument. If justReturnData=TRUE, then no MCMC will be run. Instead, the data and constants lists required to run the model will be returned. This is useful for modifying the model to personal specifications.
convergenceTol	A numeric value indicating the highest acceptable value for the Brooks-Gelman-Rubin (BGR) statistic to consider model nodes converged.
maxRuns	A numeric value indicating the maximum number of times a model will be restarted to try to achieve convergence. After running the MCMC for nIter iterations, the model is checked for convergence. A model is considered converged if the model coefficients converge according to the BGR statistic. For the marginalized two-part model, only the coefficients for the marginalized part are used. If the model does not converge, then the MCMC will be restarted and run for another iterIncrement iterations (post-thinning). Convergence will then be rechecked. The maxRuns argument specifies how many times the MCMC can be restarted after the initial run of nIter iterations.
iterWindow	A numeric value specifying the post-thinning number of iterations (per chain) that will be used to make inference, if the model does not converge with the first nIter iterations.
sliceSamplers	A TRUE/FALSE argument specifying whether or not to use slice samplers for all stochastic nodes. If sliceSamplers=TRUE then NIMBLE's onlySlice option in the configureMCMC is set to TRUE. If sliceSamplers=FALSE then NIMBLE's default MCMC settings are used. Using slice samplers is useful for reducing autocorrelation in the MCMC, though it significantly increases computation time.

Value

A list of class PCResults containing the results of running the MCMC. The list will contain additional objects and information specified by the arguments.

results

A matrix containing summary statistics (mean and the 2.5 coefficient. For ease of reading, the names of the model coefficients (beta1, beta2,...) are replaced with the names of their corresponding covariates.

model

The model specified from the writePCModel function. The model is output if keepModel=TRUE.

modelObj

The compiled NIMBLE model object after running until covergence or maxRuns is reached. This object is output only if keepModelObj=TRUE. This object can be large (>100MB) for even small imaging mass spectrometry datasets, so some thought should be put into deciding whether or not to keep this object.

fullSummary

A matrix of summary information for all nodes in the model, This will be returned if returnAllSummary=TRUE.

sample

An mcmc.list object. See the coda package for more details on such objects. This is a list of two matrices, one for each chain. Each matrix has rows equal to the number of thinned iterations and columns equal to the number of nodes monitored. The sample is returned if returnSample=TRUE.

dataList

The data list used to create a compiled NIMBLE model. For all data this list will include the matrix generated from the smoothing kernel function. For data with zeros (censored and true), the model is specified using the zeros trick. In this case dataList also has a vector of zeros.

constantsList

The list of constants used to create a compiled NIMBLE model. This list is typically composed of covariates and other vectors needed to navigate the covariate information. However, for data with zeros (censored and true), the model is specified using the zeros trick, and so the outcome data is also included in this list.

convergenceTol

The limit on the BGR statistic used to determine convergence. The default is 1.10, so if the BGR values for all model coefficients are <=1.10, then the model is considered converged.

References

de Valpine, P., D. Turek, C.J. Paciorek, C. Anderson-Bergman, D. Temple Lang, and R. Bodik. 2017. Programming with models: writing statistical algorithms for general model structures with NIMBLE. Journal of Computational and Graphical Statistics. 26: 403-413.

Examples

data("TAMdata")
# The dataset is trimmed only for the speed of the example
TAMdata <- TAMdata[TAMdata$subject < 3, ]
TAMdata <- rScale(TAMdata, subjectVar = 'subject', sampleVar = 'ROI',
                  xCoord = 'x', yCoord = 'y')
rangs <- estRange(TAMdata, outcome = 'X1282.auc', spatialVar = 'TAM',
                  semivEst = 'modulus', logTransform = TRUE)
structs <- chooseStructures(rangs)
PCdat <- createPCData(structs, trimData = FALSE,
                      covariates = c("secondary", "TAM", "secTAM"),
                      covariateTypes = c("binary", "binary", "binary"),
                      covariateLevels = c("sample", "raster", "raster"))
PCmod <- writePCModel(PCdat, multiSampsPerSubj = TRUE, typeOfZero = "censored")
PCresults <- runPCModel(modelObj = PCmod, PCDataObj = PCdat, slideVar='slide',
                        monitorCoefOnly = FALSE,
                        nBurnin = 15000, nIter = 40000, nThin = 25)

cammiller/imagingPC documentation built on June 28, 2019, 12:04 a.m.