INLAMRA.control: Control parameters for INLAMRA
In villandre/MRAinla: IS-MRA: An algorithm for large spatiotemporal datasets

Description Usage Arguments Details Value

View source: R/INLAMRAfunctions.R

Tuning parameters for the INLA-MRA algorithm.

INLAMRA.control(
  Mlon = 1,
  Mlat = 1,
  Mtime = 1,
  numValuesForIS = 100,
  numKnotsRes0 = 20L,
  J = 2L,
  tipKnotsThinningRate = 1,
  numIterOptim = 25L,
  optimLowerBound = log(1e-06),
  optimUpperBound = log(40075),
  numOpenMPthreads = 1L,
  fileToSaveOptOutput = NULL,
  folderToSaveISpoints = NULL,
  IScompleted = FALSE,
  credIntervalPercs = c(0.025, 0.975),
  randomSeed = 24,
  nuggetSD = 1e-05,
  distMethod = "haversine",
  normalHyperprior = TRUE,
  spaceJitterMax = 1e-06,
  timeJitterMaxInDecimalDays = 1/8.64e+08,
  saveData = TRUE,
  numISpropDistUpdates = 0,
  skewNormMLE = TRUE,
  returnQmat = FALSE
)

`Mlon`	Number of longitude splits used to create the nested resolutions.
`Mlat`	Number of latitude splits used to create the nested resolutions.
`Mtime`	Number of time splits used to create the nested resolutions.
`numValuesForIS`	The number of IS samples to be used for marginalisation.
`numKnotsRes0`	Number of knots at resolution 0 (the resolution encompassing the entire spatiotemporal domain).
`J`	Multiplier used to determine the number of knots at each resolution. The number of knots in each subregion at resolution i is ceiling(numKnotsRes0 * (J/2)^i). We do not recommend setting J under 2, as some regions might end up with only two knots when M is large enough.
`tipKnotsThinningRate`	Numeric value indicating the proportion of observation spatiotemporal locations that should be used as knots at the finest resolution. Should be between 0 and 1.
`numIterOptim`	Integer giving the number of iterations in the L-BFGS algorithm used to identify the maximum of the join marginal posterior distribution of the hyperparameters. Could be set somewhat lower, 20 say, to reduce running time, but setting it too low might create imbalance in the importance sampling weights.
`optimLowerBound`	Numeric. Lower bound for the optimiser used to identify the maximum of the join marginal posterior distribution of the hyperparameters.
`optimUpperBound`	Numeric. Upper bound for the optimiser used to identify the maximum of the join marginal posterior distribution of the hyperparameters. Default is the logarithm of the Earth's circumference (in kilometers).
`numOpenMPthreads`	Integer giving the number of threads used in the processing of predictions.
`fileToSaveOptOutput`	Character. An optional file name indicating where the optimiser's output should be saved. Specifying it ensures that INLAMRA can resume after the optimisation step if an interruption occurs.
`folderToSaveISpoints`	Character. An optional folder name indicating where the importance sampling weight values should be saved. Specifying it ensures that INLAMRA can properly resume at the IS iteration it had reached if an interruption occurs.
`IScompleted`	Logical value indicating whether all importance sampling weights have been obtained. If TRUE, an intermediate result (based on fewer IS iterations than had been originally planned) is produced. Note that control$fileToSaveOptOutput and control$folderToSaveISpoints must be specified for this feature to work.
`credIntervalPercs`	Numeric vector of size 2 indicating the quantile boundaries of the reported credibility intervals. Produces a standard 95% credible interval by default.
`randomSeed`	Numeric value corresponding to the seed for the random number generator used for jittering and knot placement.
`nuggetSD`	Numeric value added to the diagonal of the covariance matrices to ensure that they are invertible.
`distMethod`	String indicating the method used to obtain distances in kilometers from longitude/latitude coordinates. Takes value "haversine" by default, for the Haversine distance formula. No alternative is implemented for now.
`normalHyperprior`	Logical. Should hyperparameters be modelled on the logarithmic scale and normal hyperpriors be used? Modelling hyperparameters on the original scale, with gamma priors, is possible, but not recommended.
`spaceJitterMax`	Numeric value. The maximum jittering to apply to longitude/ latitude coordinates. Putting this value at 0 disables the spatial jittering, which is not recommended.
`timeJitterMaxInDecimalDays`	Numeric value. The maximum jittering to apply to time values, in days. Default value is 1/864000000 (1e-5 seconds). Used for splitting data into subregions. Putting this value at 0 disables the time jittering, which is not recommended.
`saveData`	Logical. Indicates whether the data used to fit the model and prediction dataset (if applicable) should be bundled with the output, which is essential for plotting. Can be disabled if memory is limited.
`numISpropDistUpdates`	The number of importance sampling (IS) weight updates in the adaptive IS algorithm. We will most likely remove the adaptive IS scheme in a future update, and so, we do not recommend touching this.
`skewNormMLE`	Logical. Indicates whether MLE values of the skew normal parameters be used to approximate confidence intervals for fixed effect parameters and hyperparameters. If FALSE, method of moments are used instead.

Some of the control parameters should certainly be tuned to ensure better computational or predictive performance: Mlon, Mlat, Mtime, numKnotsRes0, J, numValuesForIS, numIterOptim, tipKnotsThinningRate. Setting sensible lower and upper bounds for the optimisation step may help quicken the convergence of the L-BFGS algorithm. The algorithm should work without them though: hyperparameters are expressed on the logarithmic scale, which makes their domains cover the entire real line. Although a lower value for tipKnotsThinningRate can reduce predictive performance, it can also greatly reduce the function's memory footprint. For very large datasets, lower values of this parameter are recommended, and can even be essential. Other control parameters make it possible to stop an INLAMRA run at any point and resume close to where the algorithm initially stopped: fileToSaveOptOutput, folderToSaveISpoints. Set IScompleted to TRUE if an intermediate result is needed once at least one importance sampling point has been processed. This will make the function summarise the results in folderToSaveISpoints, and output as though all points have already been processed. We do not recommend setting numKnotsRes0 under 8, as knots are first placed on the vertices of a rectangular prism nested within each subregion. The following control parameters should not normally need to be changed by the user: distMethod, normalHyperprior, nuggetSD, normalHyperprior, spaceJitterMax, timeJitterMaxInDecimalDays, randomSeed, saveData, numISpropDistUpdates.

A list with all control parameters.

villandre/MRAinla documentation built on April 20, 2021, 7:49 a.m.