NIMBLE User Manual NIMBLE Development Team Version 0.6-10 http://R-nimble.org https://github.com/nimble-dev/nimble-docs Contents I Introduction6 1 Welcome to NIMBLE7 1.1 What does NIMBLE do?.............................7 1.2 How to use this manual..............................8 2 Lightning introduction9 2.1 A brief example..................................9 2.2 Creating a model.................................9 2.3 Compiling the model............................... 14 2.4 One-line invocation of MCMC.......................... 14 2.5 Creating, compiling and running a basic MCMC configuration........ 15 2.6 Customizing the MCMC............................. 17 2.7 Running MCEM................................. 18 2.8 Creating your own functions........................... 20 3 More introduction 23 3.1 NIMBLE adopts and extends the BUGS language for specifying models... 23 3.2 nimbleFunctions for writing algorithms..................... 24 3.3 The NIMBLE algorithm library......................... 25 4 Installing NIMBLE 26 4.1 Requirements to run NIMBLE.......................... 26 4.2 Installing a C++ compiler for NIMBLE to use................. 26 4.2.1 OS X.................................... 27 4.2.2 Linux................................... 27 4.2.3 Windows.................................. 27 4.3 Installing the NIMBLE package......................... 27 4.3.1 Problems with installation........................ 28 4.4 Customizing your installation.......................... 28 4.4.1 Using your own copy of Eigen...................... 28 4.4.2 Using libnimble.............................. 28 4.4.3 BLAS and LAPACK........................... 29 4.4.4 Customizing compilation of the NIMBLE-generated C++....... 29 1 CONTENTS 2 II Models in NIMBLE 30 5 Writing models in NIMBLE's dialect of BUGS 31 5.1 Comparison to BUGS dialects supported by WinBUGS, OpenBUGS and JAGS 31 5.1.1 Supported features of BUGS and JAGS................. 31 5.1.2 NIMBLE's Extensions to BUGS and JAGS............... 31 5.1.3 Not-yet-supported features of BUGS and JAGS............ 32 5.2 Writing models.................................. 33 5.2.1 Declaring stochastic and deterministic nodes.............. 33 5.2.2 More kinds of BUGS declarations.................... 36 5.2.3 Vectorized versus scalar declarations.................. 37 5.2.4 Available distributions.......................... 38 5.2.5 Available BUGS language functions................... 43 5.2.6 Available link functions.......................... 45 5.2.7 Truncation, censoring, and constraints................. 46 6 Building and using models 49 6.1 Creating model objects.............................. 49 6.1.1 Using nimbleModel to create a model.................. 49 6.1.2 Creating a model from standard BUGS and JAGS input files..... 54 6.1.3 Making multiple instances from the same model definition...... 54 6.2 NIMBLE models are objects you can query and manipulate......... 55 6.2.1 What are variables and nodes?..................... 55 6.2.2 Determining the nodes and variables in a model............ 56 6.2.3 Accessing nodes.............................. 57 6.2.4 How nodes are named.......................... 58 6.2.5 Why use node names?.......................... 59 6.2.6 Checking if a node holds data...................... 59 III Algorithms in NIMBLE 60 7 MCMC 61 7.1 One-line invocation of MCMC: nimbleMCMC .................. 62 7.2 The MCMC configuration............................ 63 7.2.1 Default MCMC configuration...................... 64 7.2.2 Customizing the MCMC configuration................. 65 7.3 Building and compiling the MCMC....................... 71 7.4 User-friendly execution of MCMC algorithms: runMCMC ............ 72 7.5 Running the MCMC............................... 73 7.5.1 Measuring sampler computation times: getTimes ........... 74 7.6 Extracting MCMC samples........................... 74 7.7 Calculating WAIC................................ 74 7.8 k-fold cross-validation............................... 75 7.9 Samplers provided with NIMBLE........................ 75 CONTENTS 3 7.9.1 Conjugate (`Gibbs') samplers...................... 75 7.9.2 Customized log-likelihood evaluations: RW llFunction sampler.... 75 7.9.3 Particle MCMC PMCMC sampler..................... 77 7.10 Detailed MCMC example: litters ....................... 77 7.11 Comparing different MCMCs with MCMCsuite and compareMCMCs ...... 82 7.11.1 MCMC Suite example: litters ..................... 82 7.11.2 MCMC Suite outputs........................... 83 7.11.3 Customizing MCMC Suite........................ 84 8 Sequential Monte Carlo and MCEM 86 8.1 Particle Filters / Sequential Monte Carlo.................... 86 8.1.1 Filtering Algorithms........................... 86 8.1.2 Particle MCMC (PMCMC)....................... 89 8.2 Monte Carlo Expectation Maximization (MCEM)............... 90 8.2.1 Estimating the Asymptotic Covariance From MCEM......... 93 9 Spatial models 94 9.1 Intrinsic Gaussian CAR model: dcar normal .................. 94 9.1.1 Specification and density......................... 94 9.1.2 Example.................................. 96 9.2 Proper Gaussian CAR model: dcar proper .................. 97 9.2.1 Specification and density......................... 97 9.2.2 Example.................................. 99 9.3 MCMC Sampling of CAR models........................ 100 9.3.1 Initial values............................... 100 9.3.2 Zero-neighbor regions........................... 101 9.3.3 Zero-mean constraint........................... 101 IV Programming with NIMBLE 102 10 Writing simple nimbleFunctions 104 10.1 Introduction to simple nimbleFunctions..................... 104 10.2 R functions (or variants) implemented in NIMBLE.............. 105 10.2.1 Finding help for NIMBLE's versions of R functions.......... 105 10.2.2 Basic operations............................. 106 10.2.3 Math and linear algebra......................... 108 10.2.4 Distribution functions.......................... 110 10.2.5 Flow control: if-then-else, for, while, and stop .......... 111 10.2.6 print and cat .............................. 111 10.2.7 Checking for user interrupts: checkInterrupt ............. 112 10.2.8 Optimization: optim and nimOptim ................... 112 10.2.9 \nim" synonyms for some functions................... 112 10.3 How NIMBLE handles types of variables.................... 113 10.3.1 nimbleList data structures....................... 113 CONTENTS 4 10.3.2 How numeric types work......................... 113 10.4 Declaring argument and return types...................... 116 10.5 Compiled nimbleFunctions pass arguments by reference............ 117 10.6 Calling external compiled code.......................... 117 10.7 Calling uncompiled R functions from compiled nimbleFunctions ...... 117 11 Creating user-defined BUGS distributions and functions 119 11.1 User-defined functions.............................. 119 11.2 User-defined distributions............................ 120 11.2.1 Using registerDistributions for alternative parameterizations and providing other information....................... 123 12 Working with NIMBLE models 125 12.1 The variables and nodes in a NIMBLE model................. 125 12.1.1 Determining the nodes in a model.................... 125 12.1.2 Understanding lifted nodes........................ 127 12.1.3 Determining dependencies in a model.................. 128 12.2 Accessing information about nodes and variables................ 129 12.2.1 Getting distributional information about a node............ 129 12.2.2 Getting information about a distribution................ 130 12.2.3 Getting distribution parameter values for a node............ 130 12.2.4 Getting distribution bounds for a node................. 131 12.3 Carrying out model calculations......................... 132 12.3.1 Core model operations: calculation and simulation........... 132 12.3.2 Pre-defined nimbleFunctions for operating on model nodes: simNodes, calcNodes, and getLogProbNodes ................... 134 12.3.3 Accessing log probabilities via logProb variables............ 136 13 Data structures in NIMBLE 138 13.1 The modelValues data structure......................... 138 13.1.1 Creating modelValues objects...................... 138 13.1.2 Accessing contents of modelValues................... 140 13.2 The nimbleList data structure.......................... 144 13.2.1 Using eigen and svd in nimbleFunctions................ 146 14 Writing nimbleFunctions to interact with models 149 14.1 Overview...................................... 149 14.2 Using and compiling nimbleFunctions...................... 151 14.3 Writing setup code................................ 152 14.3.1 Useful tools for setup functions..................... 152 14.3.2 Accessing and modifying numeric values from setup.......... 152 14.3.3 Determining numeric types in nimbleFunctions............. 153 14.3.4 Control of setup outputs......................... 153 14.4 Writing run code................................. 153 14.4.1 Driving models: calculate, calculateDiff, simulate, getLogProb 153 CONTENTS 5 14.4.2 Getting and setting variable and node values.............. 154 14.4.3 Getting parameter values and node bounds............... 156 14.4.4 Using modelValues objects........................ 156 14.4.5 Using model variables and modelValues in expressions......... 160 14.4.6 Including other methods in a nimbleFunction............. 161 14.4.7 Using other nimbleFunctions....................... 162 14.4.8 Virtual nimbleFunctions and nimbleFunctionLists........... 163 14.4.9 Character objects............................