Home

NIMBLE User Manual

1. 2 1 0 34222406 3 45822771 0 82805042 0 08796383 0 34440151 6 1 15835525 0 99001994 0 30737332 0 09461909 0 15720154 simNodesThetalto5 mv logProb_x 1 2 1 1 115 767500 20 856152 73 444053 8 258863 3 570190 6 7 429868 1 000761 1 453644 9 840589 39 096527 HH 2 1 19 688263 50 299758 37 107538 2 598331 1 825300 6 7 429868 1 000761 1 453644 9 840589 39 096527 In this code we have initialized the values of alpha and beta to their MLE and then recorded the theta values to use below Then we have requested 10 simulations from simNodesTheta1to5 Shown are the first two simulation results for theta and the log prob abilities of x Notice that theta 6 10 and the corresponding log probabilities for x 6 10 are unchanged because the nodes being simulated are only theta 1 5 In R this function runs slowly Finally let s compile the function and run that version CsimNodesThetaito5 lt compileNimble simNodesThetalto5 project pump resetFunctions TRUE Cpump alpha lt pumpMLE 1 Cpump beta lt pumpMLE 2 calculate Cpump Cpump getDependencies c alpha beta determOnly TRUE 1 0 Cpump theta lt saveTheta set seed 0 CsimNodesThetaito5 run 10 NULL CsimNodesThetaitoS mv theta 1 2 1 1 1 43717729 1 53093576 1 45028779 0 03716752 0 13310071 CHAPTER 2 LIGHTNING INTRODUCTION 19 6 1 15835525 0 99001994 0
2. Wy 4 y 38 Wy 1 y 8 isData Wy 2 Wy 9 theta 1 theta 5 thetal9 lambda 3 lambda 7 ee E xy 5 x 9 Wy 3 Wy 10 Wy 4 TRUE thetal 2i thetals theta 6 theta 7 theta 10 lambda 1 lambda 4 lambda 5 lambda 8 lambda 9 Wy 2 Wy 3 Wy 6 Wy 7 Wy 10 Wy 5 TRUE data0nly TRUE Wy 6 Wy 7 Finally you can query whether a node is flagged as data using the isData method applied to one or more nodes pump isData x 1 1 TRUE CHAPTER 6 USING NIMBLE MODELS FROM R 61 punpetreDaratce x iy a2 aloha 1 TRUE TRUE FALSE You can also query variables to determine if the nodes that are part of a variable are data nodes pump isData x 1 TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE TRUE pump isData x 1 3 1 TRUE TRUE TRUE 6 6 The modelValues data structure modelValues are containers designed for storing values for models They may be used for model outputs or model inputs A modelValues object will contain rows of variables Each row contains one object of each variable which may be multivariate The simplest way to build a modelValues object is from a model object This will create a modelValues object with the same variables as the model Although they were motivated by models one is free to set up a modelValues with any variables one wants pu
3. AA P 19ee6889 21539145 14771200 10272175 lie Groans 8 2 Particle Filter NIMBLE includes an algorithm for a basic particle filter to be used for approximating the log likelihood of a state space model A particle filter can be built for such a model by a call to buildPF This nimbleFunction requires setup arguments model and nodes which is a character vector specifying latent model nodes The particle filter can be run by specifying the number of particles Here is an example using a linear state space model for which we can also calculate the likelihood using the Kalman Filter to verify if the particle filter seems to be working Burlding a simple linear state space model x is latent space y ts observed data timeModelCode lt nimbleCode al a dnomm muh 4 yl1 dnorm x 1 1 foe Glam 2 1 4 x i dnorm x i 1 a b 1 vial dnorm x 1 e571 EL aunir Or by dnorn O 1 e drorm 1 mu_0 dnorm 0O 1 p simulate some data t 25 mu_O 1 xX rnorm 1 mu_O 1 CHAPTER 8 OTHER ALGORITHMS PROVIDED BY NIMBLE 94 y rnorm 1 x 1 a 05 b 1 c 1 for i im 2t x i rnorm 1 x i 1 a b 1 y lil rnorm 1 x i c 1 Il build and compile the model rTimeModel lt nimbleModel timeModelCode constants list t t data list y y check FALSE defining model building model setting data and initial values model building finished cTimeMode
4. lgamma sum alpha size if log return logProb else return exp logProb rdirchmulti lt nimbleFunction run function n integer 0 alpha double 1 size double 0 returnType double 1 ifi m l 1 print rdirchmulti only allows mn 1 usinge n 1 p lt rdirch Gl alpha return rmulti 1 size size prob p registerDistributions list dmyexp list BUGSdist dmyexp rate scale Rdist dmyexp rate 1 scale alltParams i e qeacallcu mlnatrewmmoanu ml sact ou ie pqAvail TRUE range c 0 Inf CHAPTER 5 BUILDING MODELS 41 Ja ddirchmulti list BUGSdist ddirchmulti alpha size types c value double 1 alpha double 1 code lt BUGScode yl1 K ddirchmulti alpha 1 K n noci ia LRO af alpha i T dmyexp scale 3 0 100 J The distribution related functions should take as input the parameters for a single pa rameterization which will be the canonical parameterization that NIMBLE will use If you would like to allow for multiple parameterizations you can do this via the Rdist element of the list provided to registerDistributions as illustrated If you provide CDF p and inverse CDF quantile i e q functions be sure to specify pqAvail TRUE when you call registerDistributions Here are more details on the requirements for distribution related nimbleFunctions which follow R s conventions A e Your distri
5. and calculate the logProb for any stochastic dependnets The total sum logProb is returned model_lp_proposed lt calculate model calcNodes calculate the log Metropolis Hastings ratio log_MH_ratio lt model_lp_proposed model_lp_initial Metropolis Hastings step determine whether or not to accept the newly proposed value Th lt i O L if u lt exp log_MH_ratio jump lt TRUE else jump lt FALSE if we accepted the proposal then store the updated values and logProbs from model into muSaved if the proposal was not accepted restore the values and logProbs from muSaved back into model if jump copy from model to mvSaved row 1 nodes calcNodes logProb TRUE CHAPTER 7 MCMC 89 else copy from mvSaved to model row 1 nodes calcNodes logProb TRUE sampler functions must have a member method reset which takes no arguments and has no return value this function is used to reset the sampler to its initial state since this sampler function maintains no internal member data variables reset needn t do anything methods list reset function now assume the existence of an R model object Rmodel which has a scalar valued stochastic node z create an MCMC configuration with no sampler functions mcmcspec lt configureMCMC Rmodel nodes NULL add our custom built random walk sampler on node z
6. 9 6 Some options for reducing memory usage o o ooo a 0004 119 Chapter 1 Welcome to NIMBLE NIMBLE is a system for building and sharing analysis methods for statistical models es pecially for hierarchical models and computationally intensive methods This is an early version 0 4 1 You can do quite a bit with it but it has some rough edges and gaps and we plan to keep expanding it If you want to analyze data we hope you will find something already useful If you want to build algorithms we hope you will program in NIMBLE and make an R package providing your method We also hope you will join the mailing lists R nimble org and help improve NIMBLE by telling us what you want to do with it what you like and what could be better We have a lot of ideas for how to improve it but we want your help and ideas too 1 1 Why something new There is a lot of statistical software out there Why did we build something new More and more statistical models are being customized to the details of each project That means it is often difficult to find a package whose set of available models and methods includes what you need And more and more statistical models are hierarchical meaning they have some unobserved random variables between the parameters and the data These may be random effects shared frailties latent states or other such things Or a model may be hierarchical simply due to putting Bayesian priors on parameters Except for
7. lt e ieee Gee ew ssa gee eect 101 04 1 Controlof setup outputs 2 24 6 db ds e twd ea ee ees 102 9 5 NIMBLE language components 0 00 ee eee eee ne 102 POA Te o de ele do ye dle oye we Eh eh ee Ra e 102 9 5 2 Declaring argument types and the return type 103 9 5 3 Driving models calculate calculateDiff simulate and getLogProb103 9 5 4 Accessing model and modelValues variables and using copy 103 9 5 5 Using model variables and modelValues in expressions 107 9 5 6 Getting and setting more than one model node or variable at a time WS Values o ses ae OP ee SSE RE Pw ee RO Oe BES 108 9 5 7 Basic flow control if then else for and while 108 9 5 8 How numeric types work 2 2 26 eee ee es 108 9 5 9 Querying and changing sizes 2 2 a 109 9 5 10 Basic math and linear algebra ooa 110 9 5 11 Including other methods in a nimbleFunction 111 9 5 12 Using other nimbleFunctions 6 6 684 4 ebb ae ees 112 9 5 13 Virtual nimbleFunctions and nimbleFunctionLists 113 gali print and Stop e ee coce Ke Pa g a ee ROE SH aE 115 CONTENTS 4 9 5 15 Checking for user interrupts caco ea sc ee eee eee es 115 9 5 16 Character objects 2 ee eee be he ee ee tee 115 9 5 17 Alternative keywords for some functions 116 9 5 18 User defined data structures ooo e 002 eae 116 9 5 19 Distribution functions e ce s s daos a aca we Ee wR a ES 118
8. 5 model a 1 5 model a 1 5 model y 2 4 lt rnorm 3 model y 1 NA 0 6545846 1 7672873 0 7167075 NA model y J e 1 5 lt rnorm model y 1 0 9101742 0 6545846 1 7672873 0 7167075 0 3841854 model z 1 1 0 2670988 1 5868335 0 4734006 6 2 1 Accessing log probabilities via logProb variables For each variable that contains at least one stochastic node NIMBLE generates a model variable with the prefix logProb_ When the stochastic node is scalar the logProb variable will have the same size For example model logProb_y 1 NA NA NA NA NA calculate model y 1 15 29134 CHAPTER 6 USING NIMBLE MODELS FROM R 53 model logProb_y ae 2 906565 3 66894 2592753 21987561 3135518 Creation of logProb variables for stochastic multivariate nodes is trickier because they can represent an arbitrary block of a larger variable In general NIMBLE records the logProb values using the lowest possible indices For example if x 5 10 15 20 follows a Wishart distribution its log probability density value will be stored in logProb_x 5 15 When possible NIMBLE will reduce the dimensions of the corresponding logProb variable For example in for i in 1 10 x i dmnorm mu precl x may be 10x20 dimensions must be provided but logProb_x will be 10x1 For the most part you do not need to worry about how NIMBLE is storing the log probability values because
9. Remove the last five samplers mcmcspec removeSamplers ind 6 10 Remove all samplers resulting in an empty MCMC configuration containing no samplers mcmcspec removeSamplers ind 1 10 Remove all samplers acting on x or any component of it mcmcspec removeSamplers x CHAPTER 7 MCMC 2 Default providing no argument removes all samplers mcmcspec removeSamplers Monitors and thinning intervals An MCMCspec object contains two independent lists of variables to monitor which corre spond to two independent thinning intervals thin corresponding to monitors and thin2 corresponding to monitors2 Monitors operate at the variable level Only entire model variables may be monitored Specifying a monitor on a node e g x 1 will result in the entire variable x being monitored The variables specified in monitors and monitors2 will be recorded with thinning inter val thin into the mvSamples and mvSamples2 both model Values objects of the MCMC respectively See Section 7 4 for information about extracting these modelValues objects from the MCMC algorithm object Monitors may be added to the MCMC configuration either in the original call to configureMCMC or using the addMonitors method Using an arguments to configureMCMC mcmcspec lt configureMCMC Rmodel monitors c alpha beta monitors2 x Calling a member method of the mcmcspec object This results in the same monitors as above mcmc
10. compile the two copies of the model Cmodel lt compileNimble Rmodel Cmodel2 lt compileNimble Rmodel2 compile both MCMC algorithms in the same project as the R model object NOTE at this time we recommend compiling ALL executable MCMC functions together Cmcmc lt compileNimble mcmc project Rmodel Cmcmc_CL lt compileNimble mcmc_CL project Rmodel2 adapt In adapt In adapt In adapt In CHAPTER 7 MCMC 83 run the default MCMC function and example the mean of mu 1 Cmcmc run 1000 NULL cSamplesMatrix lt as matrix Cmcmc mvSamples mean cSamplesMatrix mu 1 1 0 8882948 run the crossLevel MCMC function and examine the mean of mu 1 Cmcmc_CL run 1000 NULL cSamplesMatrix_CL lt as matrix Cmcmc_CL mvSamples mean cSamplesMatrix_CL mu 1 1 0 8871013 7 7 Comparing different MCMC engines with MCMCsuite NIMBLE s MCMCsuite function automatically runs WinBUGS OpenBUGS JAGS Stan and or multiple NIMBLE configurations on the same model Note that the BUGS code must be compatible with whichever BUGS packages are included and separate Stan code must be provided We show how to use MCMCsuite for the same litters example used in 7 6 Subsequently additional details of the MCMCsuite are given 7 7 1 MCMC Suite example litters The following code executes the following MCMC algorithms on the litters example WinBUGS JAGS NIMBLE d
11. list increment function sharedValue lt lt sharedValue 1 E times function factor double return factor sharedValue returnType double methodsDemo1 lt methodsDemo methodsDemoi run 1 10 sharedValues sharedValues 2 1 10 20 30 40 50 60 70 80 90 100 1 CHAPTER 9 WRITING NIMBLEFUNCTIONS 112 methodsDemoi sharedValue lt 1 CmethodsDemo1 lt compileNimble methodsDemo1 CmethodsDemo1 run 1 10 sharedValues sharedValues 2 6 6 1 10 20 30 40 50 60 70 80 90 100 Il is 9 5 12 Using other nimbleFunctions One nimbleFunction can use another nimbleFunction that was passed to it as a setup argu ment or was created in the setup function This can be an effective way to program When a nimbleFunction needs to access a setup variable or method of another nimbleFunction use usePreviousDemo lt nimbleFunction setup function initialSharedValue myMethodsDemo lt methodsDemo Je run function x double 1 myMethodsDemo sharedValue lt lt initialSharedValue print myMethodsDemo sharedValue A lt myMethodsDemo run x 1 5 print A B lt myMethodsDemo times 10 return B returnType double usePreviousDemo1 lt usePreviousDemo 2 usePreviousDemoi run 1 10 2 sharedValues 2 sharedValues 3 15 30 45 60 75 1 30 CusePreviousDemo1 lt compileNimble usePreviousDemo1 CusePreviou
12. EA jou ie jo a pli PL PLL plz pl2 pl ples ple pia DZ p27 ple pl io ae plZ ple pie pl2 pie sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler sampler TRUE TRUE TRUE TRUE Mle 210P one 4 Bl 6 ae SI 9p O Aae eae eile 14 eile aed ME 2I BAG 4 Sn Sl d lF 9 iole Lj L isle 14 isie ede adaptInterval adaptInterval adaptInterval adaptInterval dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin dependents_dbin double check our monitors and thinning interval mcmcspec getMonitors 1 mu build the executable R MCMC function mcmc lt buildMCMC mcmcspec 200 200 200 200 rie 1 Tibi 2 Pli 3 oi A rH
13. ess and the effective sample size per second of algorithm runtime effi ciency In addition to these node by node measures of efficiency an additional return list element is also provided This element efficiency is itself a named list containing two elements min and mean which contain the minimal and mean efficiencies effective sample size per second of algorithm runtime across all monitored nodes separately for each algorithm Plots Executing the MCMC Suite provides and saves several plots These include trace plots and posterior density plots for each monitored node under each algorithm Note that the generation of MCMC Suite plots in Rstudio may result in several warning messages from R regarding graphics devices but will function without any problems 7 7 3 Customizing MCMC Suite An MCMC Suite is customizable in terms of all of the following MCMC algorithms to execute optionally including WinBUGS OpenBUGS JAGS Stan and various flavours of NIMBLE s MCMC Custom specified NIMBLE MCMC algorithms Automated parameter blocking for efficienct MCMC sampling Nodes to monitor Number of MCMC iterations CHAPTER 7 MCMC 86 Thinning interval Burn in Summary statistics to report Calculating sampling efficiency effective sample size per second of algorithm runtime Generating and saving plots NIMBLE MCMC algorithms may be specified using the MCMCs argument to MCMCsuite which is character vector defining the MCMC
14. the following default summary statistics are calculated mean median sd the 2 5 quantile and the 97 5 quantile These summary statistics are easily viewable as output summary gt mu 1 mean median sd quant025 quant975 winbugs 0 8795868 0 8889000 0 04349589 0 7886775 0 9205025 jags 0 8872778 0 8911989 0 02911325 0 8287991 0 9335317 nimble 0 8562232 0 8983763 0 12501395 0 4071524 0 9299781 nimble_slice 0 8975283 0 9000483 0 02350363 0 8451926 0 9367147 CHAPTER 7 MCMC 85 nimble_CL 0 8871314 0 8961146 0 05243039 0 7640730 0 9620532 mu 2 mean median sd quant025 quant975 winbugs 0 7626974 0 7678000 0 04569705 0 6745975 0 8296025 jags 0 7635539 0 7646913 0 03803033 0 6824946 0 8313314 nimble 0 7179094 0 7246935 0 06061116 0 6058669 0 7970130 nimble_slice 0 7665562 0 7683093 0 04051432 0 6641368 0 8350716 nimble_CL 0 7605938 0 7655945 0 09138471 0 5822785 0 9568195 Timing timing contains a named vector of the runtime for each MCMC algorithm the total compile time for the NIMBLE model and MCMC algorithms and the compile time for Stan if specified All run and compile times are given in seconds Efficiency Using the MCMC Suite option calculateEfficiency TRUE will also provide several mea sures of MCMC sampling efficiency Additional summary statistics are provided for each node the total number of samples collected n the effective sample size resulting from these samples
15. the cholesky argument is treated as the Cholesky decomposition of a precision matrix Otherwise it is treated as the Cholesky decomposition of a covariance matrix In addition we provide alternative distribution names known as aliases as in JAGS as specified in Table 5 3 Distribution Canonical name Alias Binomial dbin dbinom Chi square dchisq dchisqr Dirichlet ddirch ddirich Multinomial dmulti dmultinom Negative binomial dnegbin dnbinom Weibull dweib dweibull Wishart dwish dwishart Table 5 3 Distributions with alternative names aliases CHAPTER 5 BUILDING MODELS 35 We plan to but do not currently include the following distributions as part of core NIMBLE double exponential Laplace beta binomial Dirichlet multinomial F inverse gamma Pareto inverse Wishart and various forms of multivariate t 5 2 3 Available BUGS language functions Tables 5 4 5 5 show the available operators and functions These are also available for nimbleFunction programming see Chapter 9 In fact BUGS model nodes are imple mented as nimbleFunctions that are custom generated from BUGS declarations so it would be more correct to say that functions and operators available for nimbleFunctions are also available for the model declarations For the most part NIMBLE supports the functions used in BUGS and JAGS with ex ceptions indicated in the table Additional functions provided by NIMBLE are also listed Note that we provide distribut
16. with a fired proposal standard deviation 0 1 mcmcspec addSampler target x type my_RW control list scale 0 1 Rmcmc lt buildMCMC mcmcspec etc Chapter 8 Other algorithms provided by NIMBLE In v0 4 1 the NIMBLE algorithm library is fairly limited beyond MCMC It includes some basic utilities for calculating and simulating sets of nodes And it includes a couple of algorithms particle filters and MCEM that illustrate the kind of programming with models that can be done with NIMBLE 8 1 Basic Utilities 8 1 1 simNodes calcNodes and getLogProbs simNodes calcNodes and getLogProb are basic nimbleFunctions that simulate calculate or get the log probabilities densities respectively of the same set of nodes each time they are called Each of these takes a model and a character string of node names as inputs If nodes is left blank then all the nodes of the model are used For simNodes the nodes provided will be topologically sorted to simulate in the correct order For calcNodes and getLogProb the nodes will be sorted and dependent nodes will be included Recall that the calculations must be up to date from a calculate call for getLogProb to return the values you are probably looking for simpleModelCode lt nimbleCode for i in 124 4 x i dnorm 0 1 yli dnorm x i 1 zli dnorm y i 1 z depend 2 D simpleModel lt nimbleModel simpleModelCode 90 CHAPTER 8 OTHER ALGORI
17. 0 D pumpConsts lt list N 10 it C9435 15 7 07629 196 5104 ipa 08 0b yet OLED punpWaba lt liste GlS 0 too wiles eg i ad a 2 pumpInits lt list alpha 1 beta 1 theta rep 0 1 pumpConsts N Now let s create the model and look at some of its nodes pump lt nimbleModel code data pumpCode name pump constants pumpConsts pumpData inits pumpInits defining model building model setting data and initial values checking model use nimbleModel model building finished check FALSE to skip model check pump getNodeNames 1 alpha beta H Sil Milstteduditovers beta Uthetralil fe 5 thetal2 tthetalslt H i thetal4 thetalsit 9 theta 6 theta lmit He ti thetalel theta 9 He 13 thetalto Hiambda bid 15 lambda 2 lambda 3 17 lambda 4 lambda 5 19 lambda 6 lambda 7 21 lambda 8 lambda 9 23 lambda 10 Weg Gola He 25 x 2 Usa he be ee 127 xf Meals y 29 x 6 Ura bale ci Sd wal RSet abe Ht BS x ito CHAPTER 2 LIGHTNING INTRODUCTION 9 pump x fe 1 amp 2 6 14 3 19 a 4 4 92 pump logProb_x 1 2 998011 1 118924 1 882686 2 319466 4 254550 6 20 739651 2 358795 2 358795 9 630645 48 447798 pump alpha 1 1 pump theta Fe E Ol sO oO eek Ome Oi Orsl Obl O Oren nO pump lambda 1 9 430
18. 1 570 6 290 12 600 0 524 3 140 0 105 0 105 HE 19 0210 12050 Notice that in the list of nodes NIMBLE has introduced a new node lifted_d1_over_beta We call this a lifted node Like R NIMBLE allows alternative parameterizations such as the scale or rate parameterization of the gamma distribution Choice of parameterization can generate a lifted node as can using a link function or a distribution argument that is an expression It s helpful to know why they exist but you shouldn t need to worry about them Thanks to the plotting capabilities of the igraph package that NIMBLE uses to represent the directed acyclic graph we can plot the model figure 2 1 plot pump graph You are in control of the model By default nimbleModel does its best to initialize a model but let s say you want to re initialize theta To simulate from the prior for theta overwriting the initial values previously in the model we first need to be sure the parent nodes of all theta i nodes are fully initialized including any non stochastic nodes such as lifted nodes We then use the simulate function to simulate from the distribution for theta Finally we use the calculate function to calculate the dependencies of theta namely lambda and the log probabilities of x to ensure all parts of the model are up to date First we show how to use the model s getDependencies method to query information about its graph Show all dependencies of alpha and beta
19. 30737332 0 09461909 0 15720154 HH 2 1 0 34222406 3 45822771 0 82805042 0 08796383 0 34440151 6 1 15835525 0 99001994 0 30737332 0 09461909 0 15720154 CsimNodesThetaitoS mv logProb_x 1 2 1 1 115 767500 20 856152 73 444053 8 258863 3 570190 6 2 593423 1 006239 1 180023 1 757379 2 531520 HH 2 1 19 688263 50 299758 37 107538 2 598331 1 825300 6 2 593423 1 006239 1 180023 1 757379 2 531520 Given the same initial values and the same random number generator seed we got iden tical results for theta 1 5 and their dependencies but it happened much faster Chapter 3 More Introduction Now that we have shown a brief example we will introduce more about the concepts and design of NIMBLE Subsequent chapters will go into more detail about working with models and programming in NIMBLE One of the most important concepts behind NIMBLE is to allow a combination of high level processing in R and low level processing in compiled C For example when we write a Metropolis Hastings MCMC sampler in the NIMBLE language the inspection of the model structure related to one node is done in R and the actual sampler calculations are done in compiled C The theme of separating one time high level processing and repeated low level processing will become clearer as we introduce more about NIMBLE s components 3 1 NIMBLE adopts and extends the BUGS language for specify
20. 76837 8 1 2 simNodesMV calcNodesMV and getLogProbsMV 92 There is a similar trio of nimbleFunctions that does each job repeatedly for different rows of a modelValues object For example simNodesMV will simulate in the model multiple times and record each simulation in a row of its modelValues calcNodesMV and getLogProbsMV iterate over the rows of a modelValues copy the nodes into the model and then do their job of calculating or collecting log probabilities densities respectively Each of these returns a numeric vector with the summed log probabilities of the chosen nodes from each each row calcNodesMV will save the log probabilities back into the modelValues object if saveLP TRUE a run time argument Here are some examples mv lt modelValues simpleModel rSimManyXY lt simNodesMV simpleModel nodes c x y mv mv rCalcManyXDeps lt calcNodesMV simpleModel nodes x mv mv rGetLogProbMany lt getLogProbNodesMV simpleModel nodes x mv mv cSimManyXY lt compileNimble rSimManyXY project simpleModel simpleModel cCalcManyXDeps lt compileNimble rCalcManyXDeps project CHAPTER 8 OTHER ALGORITHMS PROVIDED BY NIMBLE 93 cGetLogProbMany lt compileNimble rGetLogProbMany project simpleModel cSimManyXY run m 5 simulating 5 times NULL cCalcManyXDeps run saveLP TRUE calculating GI 19 36889 21 39145 14 71200 10 2175 11 67675 cGetLogProbMany run
21. D D Spiegelhalter A Thomas and N Best 2009 The BUGS project Evolu tion critique and future directions Statistics in Medicine 28 25 3049 3067 ns Murray I R Prescott Adams and D J C MacKay 2010 Elliptical slice sampling ArXiv e prints OU Neal R M 2003 Slice sampling The Annals of Statistics 31 3 705 741 6 Roberts G O and S K Sahu 1997 Updating schemes correlation structure blocking and parameterization for the Gibbs sampler Journal of the Royal Statistical Society Series B Statistical Methodology 59 2 291317 7 Shaby B and M Wells 2011 Exploring an adaptive Metropolis algorithm Department of Statistics Duke University 2011 14 120
22. S Talli el oi A ail S elia O rii 10 kiy K y 12 rite 13 rie 14 rit 15 fel ites allo w al ie 2 iol S Til 4 ily S il 6l eee A r 2 8 rio S F2 10 ea 14 i212 me Te 14 rel ae el ale scale scale scale scale Pree Pe CHAPTER 7 MCMC 82 let s try another MCMC as well this time using the crossLevel sampler for top level nodes generate an empty MCMC configuration we need a new copy of the model to avoid compilation errors Rmodel2 lt Rmodel newModel setting data and initial values checking model use nimbleModel check FALSE to skip model check mcmcspec_CL lt configureMCMC Rmodel2 nodes NULL monitors mu add two crossLevel samplers mcmcspec_CL addSampler target c a 1 b 1 type crossLevel 1 crossLevel sampler ali b 1 adaptive TRUE adaptScaleOnly FALSE mcmcspec_CL addSampler target c al 2 b 2 type crossLevel 2 crossLevel sampler a 2 b 2 adaptive TRUE adaptScaleOnly FALSE let s check the samplers mcmcspec_CL getSamplers 1 crossLevel sampler ali bl1 adaptive TRUE adaptScaleOnly FALSE 2 crossLevel sampler a 2 b 2 adaptive TRUE adaptScaleOnly FALSE build this second executable R MCMC function mcmc_CL lt buildMCMC mcmcspec_CL HHHHHHHHHAHHEHHHAHEEHPAAEEHEAAEEP ERE HHHHH compile to C and run HHAAHHHEHAAAEHHAAAEHAAAHEEHARAEE ERA
23. algorithms to run The MCMCs argument may include any of the following algorithms winbugs WinBUGS MCMC algorithm openbugs OpenBUGS MCMC algorithm jags JAGS MCMC algorithm Stan Stan MCMC algorithm nimble NIMBLE MCMC using the default configuration nimble_noConj NIMBLE MCMC using the default configuration with useConjugacy FALSE nimble RW NIMBLE MCMC using the default configuration with onlyRW TRUE nimble slice NIMBLE MCMC using the default configuration with onlySlice TRUE autoBlock NIMBLE MCMC algorithm with block sampling of dynamically determined parameter groups attempting to maximize sampling efficiency The default value for the MCMCs argument is c jags nimble nimble RW nimble slice autoBlock The names of additional custom MCMC algorithms may also be provided in the MCMCs argument so long as these custom algorithms are defined in the MCMCdefs argument An example of this usage is given with the crossLevel algorithm in the litters MCMC Suite example The MCMCdefs may be provided as named list of definitions for any custom MCMC algorithms specified in the MCMCs argument If MCMCs specified an algorithm called myMCMC then MCMCdefs must contain an element named myMCMC The contents of this element must be a block of code that when executed returns the desired MCMC configuration object This block of code may assume the exist
24. alternative parameterization Since NIMBLE provides compatibility with existing BUGS and JAGS code the order of parameters places the BUGS parameterization first For example the order of parameters for dgamma is dgamma shape rate scale mean sd Like R if parameter names are not given they are taken in order so that shape rate is the default This happens to match R s order of parameters but it need not If names are given they can be given in any order NIMBLE knows that rate is an alternative to scale and that mean sd are an alternative to shape scale or rate CHAPTER 5 BUILDING MODELS 33 Table 5 2 Distribution parameterizations allowed in NIMBLE The first column indicates the supported parameterizations for distributions given in Table 5 1 The second column indicates the relationship to the canonical parameterization used in NIMBLE Parameterization NIMBLE re parameterization dbern prob dbin size 1 prob dbeta shapel shape2 canonical dbeta mean sd dbin prob size dcat prob dchisq df ddirch alpha dexp rate dexp scale dgamma shape dgamma shape dgamma mean scale rate sd dlogis location scale dlogis location rate dlnorm meanlog sdlog dlnorm meanlog taulog dlnorm meanlog varlog dmulti prob dmnorm mean dmnorm mean dmnorm mean dmnorm mean dnegbin prob size cholesky prec_param 1 cholesky prec_param 0 prec cov size dnorm me
25. automatically expanded into c y 1 y 2 y 3 In fact simply y will be expanded into all nodes within y 2 An arbitrary number of nodes can be provided as a character vector 3 Simulations will be done in the order provided so in practice the nodes should often CHAPTER 6 USING NIMBLE MODELS FROM R 57 be obtained by functions like getDependencies described below These return nodes in topologically sorted order which means no node comes before something it depends on 4 The data nodes z were not simulated into until includeData TRUE was used Use of calculate calculateDiff and getLogProb are similar to simulate except that they return a value described above and they have no includeData argument 6 4 2 Direct access to each node s functions Access to the underlying calculate calculateDiff simulate and getLogProb functions built by NIMBLE can be had as follows y2lp lt model nodes y 2 calculate y2lp 1 2 192342 model nodes y 2 getLogProb 1 2 192342 6 5 Querying model structure NIMBLE provides functions for asking a model about its structure These can be used from R including from the setup code of a nimbleFunction setup code is described in Chapter 9 Here we demonstrate this functionality using the pump example because it has a few more interesting components than the example above defining model building model setting data and in
26. but not identical to R In addition there are some keywords in NIMBLE that have the same names as really different R functions For example step is part of the BUGS language but it is also an R function for stepwise model selection And equals is part of the BUGS language but is also used in the testthat package which we use in testing NIMBLE The way NIMBLE handles this to try to avoid conflicts is to replace some keywords immediately upon creating a nimbleFunction These replacements include e copy nimCopy e dim nimDim e print nimPrint e step nimStep e equals nimEquals e round nimRound e stop nimStop This system gives programmers the choice between using the keywords like nimPrint directly to avoid confusion in their own code about which print is being used or to use the more intuitive keywords like print but remember that they are not the same as R s functions 9 5 18 User defined data structures NIMBLE does not explicitly have user defined data structures but one can use nimbleFunc tions to achieve a similar effect To do so one can define setup code with whatever variables are wanted and ensure they are compiled using setupOutputs Here is an example dataNF lt nimbleFunction setup function Xe lt li Y lt as numeric c 1 2 will be a scalar if all sizes are Z lt matrix as numeric 1 4 nrow 2 will be a scalar setupOutputs X Y Z useDataNF lt
27. etc Sizes can be changed using e setSize X sizel size2 where size1 size2 etc provide the sizes of as many dimensions as needed by X CHAPTER 9 WRITING NIMBLEFUNCTIONS 110 9 5 10 Basic math and linear algebra NIMBLE uses the Figen library in C to accomplish linear algebra In v0 4 1 we use a lot of Eigen s capabilities but not all of them The supported operations are given in Tables 5 4 5 5 No vectorized operations other than assignment are supported for more than two di mensions in v0 4 1 That means A B C will work only if B and C have dimensions lt 2 Managing dimensions and sizes asRow asCol and dropping dimensions It can be tricky to determine the dimensions returned by a linear algebra expression As much as possible NIMBLE behaves like R but in some cases this is not possible because R uses run time information while NIMBLE must determine dimensions at compile time Suppose vl and v2 are vectors and M1 is a matrix Then e vi M1 generates a compilation error unless one dimension of M1 is known at compile time to be 1 If so then vl is promoted to a l row or l column matrix to conform with M1 and the result is a matrix of the same sizes This behavior occurs for all component wise binary functions e vi M1 defaults to promoting vl to a 1 row matrix unless it is known at compile time that M1 has 1 row in which case v1 is promoted to a 1 column matrix e M1 vi defaults to promoti
28. nimbleFunction setup function myDataNF run function newX double newY double 1 newZ double 2 myDataNF X lt lt newX myDataNF Y lt lt newY CHAPTER 9 WRITING NIMBLEFUNCTIONS 117 myDataNF Z lt lt newZ myDataNF lt dataNF myUseDataNF lt useDataNF myDataNF myUseDataNF run as numeric 100 as numeric 100 110 matrix as numeric 101 120 nrow myDataNF X 1 100 myDataNF y 1 100 101 102 103 104 105 106 107 108 109 110 myDataNF Z Ht PaaS Sita i si E ai e E ake fet 101 03 105 107 109 tal ie 11S 117 119 te 2 102 104 106 108 110 112 114 116 118 120 myUseDataNF myDataNF x 1 100 nimbleOptions useMultiInterfaceForNestedNimbleFunctions FALSE CmyUseDataNF lt compileNimble myUseDataNF CmyUseDataNF run 100 100 110 matrix 101 120 nrow 2 NULL CmyDataNF lt CmyUseDataNF myDataNF CmyDataNF x 1 100 CmyDataNF Y i eo O 102 7 103 100 05s 106 107 108 109 110 CmyDataNF Z Ht he BA LS ea S e A e he o aaa Ml O KOS N O O e S S e e He B 0A 1104 106 108 110 a 114 S S O You ll notice that CHAPTER 9 WRITING NIMBLEFUNCTIONS 118 After execution of the compiled function access to the X Y and Z is the same as for the uncompiled case This occurs because CmyUseDatalNF is an interface to the com piled version of myUseDataNF and it provides access to member objects and functions In this case one member object is myDataN
29. of nimbleFunctions is usually very similar but not identical between the two versions The primary purpose of uncompiled execution is to facilitate debugging More about writing algorithms is in Chapter 9 3 3 The NIMBLE algorithm library In v0 4 1 the NIMBLE algorithm library includes 1 MCMC with samplers including conjugate slice adaptive random walk and adaptive block random walk NIMBLE s MCMC system illustrates the flexibility of combining R and C An R function inspects the model object and creates an MCMC specification object representing choices of which kind of sampler to use for each node This MCMC specification can be modified in R such as adding new samplers for particular nodes before compiling the algorithm Since each sampler is written in NIMBLE you can use its source code or write new samplers to insert into the MCMC And if you want to build an entire MCMC system differently you can do that too 2 A nimbleFunction that provides a likelihood function for arbitrary sets of nodes in any model This can be useful for simple maximum likelihood estimation of non hierarchical models using R s optimization functions And it can be useful for other R packages that run algorithms on any likelihood function 3 A nimbleFunction that provides ability to simulate calculate or retrieve the summed log probability density of many sets of values for arbitrary sets of nodes 4 A nimbleFunction that provides a basic parti
30. order of parameters The value of the random variable is denoted by zx Name Usage Density Lower Upper Bernoulli dbern prob p r 1 0 1 1 x lapri p 1 p Beta dbeta shape1 a shape2 b xet 1 x 0 1 a gt 0 b gt 0 B a b Binomial dbin prob p size n nir Woe 0 n 0 lt p lt 1 n E N G0 p Categorical dcat prob p Px 1 N p Rt Di Pi Chi square dchisq df k xr271 exp a 2 0 k gt 0 257 k a ceed Dirichlet ddirch alpha qa 2 0 a 0 r o l T a Exponential dexp rate A 0 oh Aexp Az Gamma dgamma shape r rate A da exp Az 0 gt 0 r gt 0 T r Logistic dlogis location u rate 7 T exp x u r T gt 0 1 exp x Ha Log normal dlnorm meanlog u taulog 7 pe u 5 a exp rlloe a 1 2 Multinomial dmulti prob p size n p ny Py yt n j xj Multivariate dmnorm mean u prec A N r normal A positive definite 27 2 A exp u A x u 2 Negative dnegbin prob p size r 2 r 1 1 p 0 binomial 0 lt p lt l1 r gt 0 z P P Normal dnorm mean u tau 7 eal T gt 0 sz exp 7 x 1 2 Poisson dpois lambda A exp A 0 A gt 0 x _ k 1 Student t dt mu u tau 7 df k ne 2 1 7 a u 2 T gt 0 k gt 0 T z ka CHAPTER 5 BUILDING MODELS 32 Table 5 1 Distributions with their default order of parameters The value of the random variable is denoted by zx Name Usage
31. print or equivalently nimPrint prints an arbitrary set of outputs in order The NIMBLE function stop or equivalently nimStop throws control to R s error handling system and can take one string character argument 9 5 15 Checking for user interrupts When you write algorithms that will run for a long time in C you may want to explicitly check whether a user has tried to interrupt the execution e g by pressing Control C Simply include checkInterrupt in run code to do so If there has been an interrupt the process with stop and return control to R 9 5 16 Character objects NIMBLE provides limited uses of character objects in run code Character vectors created in setup code will be available in run code but the only thing you can really do with them is include them in a print or stop statement Note that character vectors of model node and variable names are processed during compilation For example in model node node may be a character object and the NIMBLE compiler processes this differently than print The node name was node In the former the NIMBLE compiler sets up a C pointer directly to the node in the model CHAPTER 9 WRITING NIMBLEFUNCTIONS 116 so that the character content of node is never needed in C In the latter node is used as a C string and therefore is needed in C 9 5 17 Alternative keywords for some functions NIMBLE uses some keywords such as dim and print in ways similar
32. print run i return sum x returnType double methods list CHAPTER 9 WRITING NIMBLEFUNCTIONS foo function print foo 1 return rnorm 1 0 1 returnType double H derived2 lt nimbleFunction contains baseClass setup function run function x double 1 print irun 24 return prod x returnType double methods list foo function print too 2 return runi I 100 200 returnType double DD useThem lt nimbleFunction setup function nfl lt nimbleFunctionList baseClass nfl 1 lt derivedi nf1 2 lt derived2 run function x double 1 for i in seq_along nfl print nfl lil runt print nf1 i fooQ useThem1 lt useThem set seed 0 useThem1 run 1 5 H H H H H H run 1 15 noo Il 1 262954 run 2 120 114 CHAPTER 9 WRITING NIMBLEFUNCTIONS 115 foo 2 HE Si 2124 CuseThem1 lt compileNimble useThem1 set seed 0 CuseThem1 run 1 5 run 1 15 foo 1 1 26295 run 2 120 foo 2 gis 137 212 NULL As in R the seq_along function is equivalent to 1 length nimFunList if length nimFunList gt 0 and it is an empty sequence if length nimFunList 0 Currently seq_along works only for nimbleFunctionLists Virtual nimbleFunctions cannot define setup values to be inherited 9 5 14 print and stop As demonstrated above the NIMBLE function
33. simple cases hierarchical statistical models are often analyzed with computationally intensive algorithms the best known of which is Markov chain Monte Carlo MCMC Several existing software systems have become widely used by providing a flexible way to say what the model is and then automatically providing an algorithm such as MCMC When these work and when MCMC is what you want that s great Unfortunately there are a lot of hard models out there for which default MCMCs don t work very well And there are also a lot of useful new and old algorithms that are not MCMC but they can be hard to find implemented for the model you need and you may have to go learn a new system to use a new algorithm That s why we wanted to create a system that combines a flexible system for model specification the BUGS language with the ability to program with those models That s the goal of NIMBLE CHAPTER 1 WELCOME TO NIMBLE 6 1 2 What does NIMBLE do NIMBLE stands for Numerical Inference for statistical Models for Bayesian and Likelihood Estimation Although NIMBLE was motivated by algorithms for hierarchical statistical models you could use it for simpler models too You can think of NIMBLE as comprising three pieces 1 A system for writing statistical models flexibly which is an extension of the BUGS language 2 A library of algorithms such as MCMC 3 A language called NIMBLE embedded within and similar in style to R for wri
34. slope2 4 predictedY 5 sigmay 6 lifted_d1l_over_sqrt_oPsigmaY_cP HH 7 uyn 8 x1 9 x2 CHAPTER 5 BUILDING MODELS 45 5 2 8 Truncation censoring and constraints NIMBLE provides three ways to declare boundaries on the value of a variable each for dif ferent situations We introduce these and comment on their relationships to related features of JAGS and BUGS The three methods are Truncation Either of the following forms e x dnorm 0 sd 10 TCO a or e x T dnorm 0 sd 10 O a declares that x follows a normal distribution between 0 and a Either boundary may be omitted or may be another node such as a in this example The first form is compatible with JAGS but in NIMBLE it can only be used when reading code from a text file When writing model code in R the second version must be used Truncation means the possible values of x are limited a priori hence the probability density of x must be normalized In this example it would be the normal probability density divided by its integral from 0 to af Like JAGS NIMBLE also provides I as a synonym for T to accommodate older BUGS code but T is preferred because it disambiguates multiple usages of I in BUGS As in JAGS mu dfoo theta T L U restricts X to lie in L U i e inclusive of L and U Censoring Censoring refers to the situation where one datum gives the lower or upper bound on an unobserved random variabl
35. terminating in stochastic nodes pump getDependencies c alpha beta CHAPTER 2 LIGHTNING INTRODUCTION 10 Figure 2 1 Directed Acyclic Graph plot of the pump model thanks to the igraph package CHAPTER 2 LIGHTNING INTRODUCTION 11 1 alpha beta HH eS Wilattedudimoverubetal utheta i 2 5 thetale thetalslt HE theta tthetalsit 9 theta 6 ttheral7it 42 140 theta leil theta 9 13 theta 10 Now show only the deterministic dependencies pump getDependencies c alpha beta determOnly TRUE tm dattedudimoverubeta Check that the lifted node was initialized pump lifted_di_over_beta It was 1 1 Now let s simulate new theta values set seed 0 This makes the simulations here reproducible simulate pump theta pump theta the new theta values 1 1 79180692 0 29592523 0 08369014 0 83617765 1 22254365 6 1 15835525 0 99001994 0 30737332 0 09461909 0 15720154 lambda and logProb_xz haven t been re calculated yet pump lambda these are the same values as above 1 92430 1 570 6 290 12 600 0 524 3 5140 02105 0 105 9 0 210 1 050 pump logProb_x 1 2 998011 1 118924 1 882686 2 319466 4 254550 6 20 739651 2 358795 2 358795 9 630645 48 447798 getLogProb pump x The sum of logProb_z 1 96 10932 calculate pump pump getDependencies c theta 1 286 6951 pump lambda Now they hav
36. testModel a a was set to 0 5 valueToAdd 1 1 25 The call to the R function called nimbleFunction returns a function similarly to defining a function in R That function logProbCalcPlus takes arguments for its setup function executes it and returns an object logProbCalcPlusA that has a run member function method accessed by run In this case the setup function obtains the stochastic depen dencies of the node using the getDependencies member function of the model see Section 6 5 2 and stores them in dependentNodes In this way logProbCalcPlus can adapt to any model It also creates a variable valueToAdd that can be used by the nimbleFunction The object logProbCalcPlusA returned by logProbCalcP1lus is permanently bound to the results of the processed setup function In this case logProbCalcPlusA run takes a scalar input value P assigns P valueToAdd to the given node in the model and returns the sum of the log probabilities of that node and its stochastic dependencies We say 3Note the use of the global assignment operator to assign into the model This is necessary for assigning into variables from the setup function at least if you want to void warnings from R These warnings come from R s reference class system CHAPTER 9 WRITING NIMBLEFUNCTIONS 99 logProbCalcPlusA is an instance of logProbCalcPlus that is specialized or bound to a and testModel Usually the setup code will be where
37. variable is a scalar using unlist in R to extract all rows as a vector can be useful customMV c 1 lt 1 customMV c 2 lt 2 customMV c 3 lt 3 unlist customMV c uae M al 2 Once we have a modelValues object we can see the structure of its contents via the varNames and sizes components of the object customMV varNames Ht Tal a h c CHAPTER 6 USING NIMBLE MODELS FROM R 65 customMV sizes a 1 2 b 1 2 2 c 1 1 As with most NIMBLE objects model Values are passed by reference not by value That means any modifications of modelValues objects in either R functions or nimbleFunctions will persist outside of the function This allows for more efficient computation as stored values are immediately shared among nimbleFunctions alter_a lt function mv mya 1 lt 2 customMV a 1 1 0 1 alter_a customMV customMV a 1 ee MA eed However when you retrieve a variable from a model Values object the result is a standard R list which is subsequently passed by value as usual in R 6 7 NIMBLE passes objects by reference NIMBLE relies heavily on R s reference class system When models model Values and nim bleFunctions with setup code are created NIMBLE generates a new customized reference class definition for each As a result objects of these types are passed by reference and hence modified in place by most NIMBLE operations T
38. we 6 2 1 Accessing log probabilities via logProb variables 6 3 Accessing nodes kk eee ee A ee he OR DO RE 6 3 1 How nodes are named 222 eee ee ee 6 3 2 Why use node names 000 eee es 04A calculate simulate and petLopProb 4 5846 ye es bd dee ea we 6 4 1 For arbitrary collections of nodes 0 0 0004 6 4 2 Direct access to each node s functions 6 5 Querying model structure lt lt 4 426 eee ea ee we OR Ee eG 6 5 1 getNodeNames getVarNames and expandNodeNames 6 5 2 getDependencies 64 Kao we EDEN ERR ESE GE ES Dao ISDA 2 r meone oe A ee ERS AK Ba Behan ao dee a 66 The model Values data str ct re o lt s oeo we be sad ee eRe ci 6 6 1 Accessing contents of modelValues o oo a a a 2 004 6 7 NIMBLE passes objects by reference onoo a 00000 eee eae 7 MCMC 71 The MCMC configuration 2 s esco ee eee eRe eee em 7 1 1 Default MCMC configuration ss 2 2666258 2 2p ee wee ee 7 1 2 Customizing the MCMC configuration 7 2 Building and compiling the MCMC algorithm 7 3 Executing the MCMC algorithm 2 0 TA Extracting MCMC samples so sea ew dtu he ee ee 7 5 Sampler Algorithms provided with NIMBLE 7 5 1 Terminal node end sampler 222004 CONTENTS 3 9 7 5 2 Scalar Metropolis Hastings random walk RWsampler 75 7 5 3 Multivariate Metropolis Hastings RW blo
39. while programming in NIMBLE allows simpler code Chapter 2 Lightning introduction 2 1 A brief example Here we ll give a simple example of building a model and running some algorithms on the model as well as creating our own user specified algorithm The goal is to give you a sense for what one can do in the system Later sections will provide more detail We ll use the pump model example from BUGS We could load the model from the standard BUGS example file formats Section 5 3 2 but instead we ll show how to enter it directly in R In this lightning introduction we will Create the model for the pump example Compile the model Create a basic MCMC specification for the pump model Compile and run the MCMC Customize the MCMC specification and compile and run that Create compile and run a Monte Carlo Expectation Maximization MCEM algorithm which illustrates some of the flexibility NIMBLE provides to combine R and NIMBLE 7 Write a short nimbleFunction to generate simulations from designated nodes of any model Ook UUN 2 2 Creating a model First we define the model code its constants data and initial values for MCMC pumpCode lt nimbleCode wove Gis aia LND theta i dgamma alpha beta lambda i lt theta i t i x i dpois lambda i 1The data set describes failure times of some pumps CHAPTER 2 LIGHTNING INTRODUCTION 8 alpha dexp 1 0 beta dgamma 0 1 1
40. you can always get them using getLogProb 6 3 Accessing nodes While nodes that are part of a variable can be accessed as above each node also has its own name that can be used to access it directly For example y 2 has the name y 2 and can be accessed by that name as follows model y 2 1 0 6545846 model i yil2i i lt 5 model y 1 0 9101742 5 0000000 1 7672873 0 7167075 0 3841854 model 2l2 Si iJ 1 0 6203667 modell 22245 4 2 it 2 1 0 5584864 model z 2 2 1 0 5584864 Notice that node names can include index blocks such as model z 2 4 1 2 and these are not strictly required to correspond to actual nodes Such blocks can be subsequently sub indexed in the regular R manner CHAPTER 6 USING NIMBLE MODELS FROM R 54 6 3 1 How nodes are named Every node has a name that is a character string including its indices with a space after every comma For example X 1 2 3 has the name X 1 2 3 Nodes following multivariate distributions have names that include their index blocks For example a multivariate node for X 6 10 3 has the name X 6 10 3 The definitive source for node names in a model is getNodeNames described below For example multiVarCode lt nimbleCode X 1 125 dmnorm ul covi ID X 6 10 3 dmnorm mu cov D multiVarModel lt nimbleModel multiVarCode dimensions list mu 5 cov c 5 5 check F
41. 10 pumpSpec addMonitors c alpha beta theta thin 1 alpha beta theta pumpMCMC lt buildMCMC pumpSpec CpumpMCMC lt compileNimble pumpMCMC project pump niter lt 1000 set seed 0 CpumpMCMC run niter NULL samples lt as matrix CpumpMCMC mvSamples par mtrow cCl 4 mai lt 6 5 1 2 plot samples alpha type l xlab iteration ylab expression alpha plot samples beta type l xlab iteration ylab expression beta plot samples alpha samples beta xlab expression alpha ylab expression beta plot samples theta 1 type 1 xlab iteration ylab expression theta 1 o o mM oO wo 9 re N N o gt N N gt 3 a n 2a n 5 a o gt z 2 9 9 oO oO o o oO oO 0 400 800 0 400 800 05 1 0 1 5 0 400 800 iteration iteration a iteration acf samples alpha acf samples beta CHAPTER 2 LIGHTNING INTRODUCTION 14 2 2 2 S O O wt lt x 3 N S 5 o 5 gt o oO 0 5 15 25 Lag Lag Notice the posterior correlation between alpha and beta A measure of the mixing for each is the autocorrelation for each parameter shown by the acf plots 2 5 Customizing the MCMC Let s add an adaptive block sampler on alpha and beta jointly and see if that improves the mixing pumpSpec addSampler target c alpha beta typ
42. 9 WRITING NIMBLEFUNCTIONS 111 Size warnings and the potential for crashes For matrix algebra NIMBLE cannot ensure perfect behavior because sizes are not known until run time Therefore it is possible for you to write code that will crash your R session In v0 4 1 NIMBLE attempts to issue warning if sizes are not compatible but it does not halt execution Therefore if you execute A lt M1 M2 and M1 and M2 are not compatible for matrix multiplication NIMBLE will output a warning that the number of rows of M1 does not match the number of columns of M2 After that warning the statement will be executed and may result in a crash Another easy way to write code that will crash is to do things like Y 5 10 20 30 lt model x without ensuring Y is at least 10x30 In the future we hope to prevent crashes but in v0 4 1 we limit ourselves to trying to provide useful information 9 5 11 Including other methods in a nimbleFunction Other methods can be included with the methods argument to nimbleFunction These methods can use the objects created in setup code in just the same ways as the run function In fact the run function is just a default main method name methodsDemo lt nimbleFunction setup function sharedValue lt 1 run function x double 1 print sharedValues sharedValue n increment print sharedValues sharedValue n A lt times 5 return A x returnType double 1 Jio methods
43. ALSE defining model building model model building finished multiVarModel getNodeNames 1 lifted_chol_oPcov_oBito5_1to5_cB_cP 1 5 1 5 ei I Ned als alte aca bell OG O ee You can see one lifted node for the Cholesky decomposition of cov and the two multi variate normal nodes In the event you need to ensure that a name is formatted correctly you can use the expandNodeNames method For example to get the spaces correctly inserted into X 1 1 5 multiVarModel expandNodeNames X 1 1 5 es EO Veils eY Alternatively for those inclined to R s less commonly used features a nice trick is to use its parse and deparse functions deparse parse text X 1 1 5 keep source FALSE 1 1 X 1 1 5 The keep source FALSE makes parse more efficient CHAPTER 6 USING NIMBLE MODELS FROM R 59 6 3 2 Why use node names Syntax like pump x 2 3 may seem strange at first because the natural habit of an R user would be pump x 2 3 To see its utility consider the example of writing the nimbleFunction given in Section 2 7 By giving every scalar node a name even if it is part of a multivariate variable one can write functions in R or NIMBLE that access any single node by a name regardless of the dimensionality of the variable in which it is embedded This is particularly useful for NIMBLE which resolves how to access a particular node during the compilation process 6 4 calcul
44. APTER 7 MCMC 68 e Two sets of variables that will be monitored recorded during execution of the MCMC and thinning intervals for how often each set will be recorded Two sets are allowed because it can be useful to monitor different variables at different intervals 7 1 1 Default MCMC configuration Assuming we have a model named Rmodel the following will generate a default MCMC configuration mcmcspec lt configureMCMC Rmodel1 The default configuration will contain a single sampler for each node in the model and the default ordering follows the topological ordering of the model configureMCMC creates an MC MCspec reference class object The MC MCspec reference class has a number of methods such as addSampler that are described later Default assignment of sampler algorithms The default sampling algorithm assigned to each stochastic node is determined by the fol lowing in order of precedence 1 If the node has no stochastic dependents a predictive end sampler is assigned The end sampling algorithm merely calls simulate on the particular node 2 The node is checked for presence of a conjugate relationship between its prior distri bution and the distributions of its stochastic dependents If it is determined to be in a conjugate relationship then the corresponding conjugate Gibbs sampler is assigned 3 If the node is discrete valued then a slice sampler is assigned 5 4 If the node follows a multivariate distribut
45. Density Lower Upper Uniform dunif min a max b 1 a b a lt b b a Weibull dweib shape v lambda A ge 0 Wre i v z exp x Wishart dwish R R df k ac P D 2 RIK exp tr Ra 2 Rp x p pos def k gt p 2Pk 2P k 2 Alternative parameterizations for distributions NIMBLE allows one to specify distributions in model code using a variety of parameteri zations including the BUGS parameterizations Behind the scenes NIMBLE uses a single parameterization NIMBLE s canonical parameterization when definining nodes and rela tionships between nodes and when doing calculations The full set of parameterizations that one can used in model code is listed in Table 5 2 To understand how NIMBLE handles alternative parameterizations it is useful to distinguish three cases using the gamma distribution as an example 1 A canonical parameterization is used directly for computations Usually this is the parameterization in the Rmath header of R s C implementation of distributions For gamma this is shape scale 2 The BUGS parameterization is the one defined in the original BUGS language For gamma this is shape rate 3 An alternative parameterization is one that must be converted into the canonical pa rameterization For example NIMBLE provides a mean sd parameterization and creates nodes to calculate shape scale from mean sd In the case of gamma the BUGS parameterization is also an
46. F which is an interface to the compiled version of myUseDataNF myDataNF which in turn provides access to X Y and Z To reduce memory use NIMBLE defaults to not providing full interfaces to nested nim bleFunctions like myUseDataNF myDataNF In this example we made it provide a full interfaces by setting the useMultilnterfaceForNestedNimbleFunctions option via nimbleOptions as shown If we had left that option TRUE its default value we could still get to the values of interest using valueInCompiledNimbleFunction CmyDataNF X We need to take care that at the time of compilation the X Y and Z values contain doubles via as numeric so that they are not compiled as integer objects The myDataNF could be created in the setup code We just provided it as a setup argument to illustrate that option 9 5 19 Distribution functions Distribution d r p and q functions can all be used from nimbleFunctions and in BUGS model code but the care is needed in the syntax We support only the canonical NIMBLE parameterization as listed below with a small number of exceptions also listed The names of the distributions are the names used under the hood in NIMBLE and differ from the standard BUGS distribution names Currently r functions only return one random draw at a time and the first argument must always be 1 For the multivariate normal and Wishart distributions the prec_param or scale_param argument must b
47. G MODELS 43 will not be labeled as data The result will be that nodes with non NA values will be flagged as data nodes while nodes with NA values will not A node following a multivariate distribution must be either entirely observed or entirely missing Here s an example of running an MCMC on the pump model with two of the observa tions taken to be missing Some of the steps in this example are documented more below NIMBLE s default MCMC specification will treat the missing values as unknowns to be sampled as can be seen in the MCMC output here pumpMiss lt pump newModel pumpMiss resetData pumpDataNew lt pumpData pumpDataNew x c 1 3 lt NA pumpMiss setData pumpDataNew pumpMissSpec lt configureMCMC pumpMiss pumpMissSpec addMonitors c x alpha beta theta pumpMissMCMC lt buildMCMC pumpMissSpec Cobj lt compileNimble pumpMiss pumpMissMCMC niter lt 1000 set seed 0 Cobj pumpMissMCMC run niter samples lt as matrix Cobj pumpMissMCMC mvSamples samples 1 5 13 17 Missing values may also occur in variables appearing on the right hand side of BUGS declarations Values for such variables should be passed in via the data argument to nimbleModel with NA for the missing values In many contexts one would want to specify prior distributions for the elements with missing values 5 2 7 Defining alternative models with the same code Avoiding code duplication is a basic principl
48. H 8 Wy 8 Wy 9 Wy 10 pump getVarNames Wy 4 FH lelelihthedudimoverubetalmthetbal 3 lambda 5 alpha Weel beta Wy 5 theta 2 thetaLl7 Wy Wy zal Wy 6 theta 3 theta 8 Wy 3 x 8 Wy 7 CHAPTER 6 USING NIMBLE MODELS FROM R 59 Note that some of the nodes may be lifted nodes introduced by NIMBLE Section 5 2 9 Next note that we can determine the set of nodes contained in one or more nodes or variables using expandNodeNames The returnScalarComponents argument also allows us to return all of the scalar components of multivariate nodes to illustrate multiVarCode2 lt nimbleCode X 1 1 5 dmnorm mu cov NiG 10 si dmnomm mu cov ll fonn A Y i dnorm mn 1 D multiVarModel2 lt nimbleModel multiVarCode2 dimensions list mu 5 cov c 5 5 check FALSE defining model building model model building finished multiVarModel2 expandNodeNames Y HH 1 Dye ial uyi Vv 3 vy 4 multiVarModel2 expandNodeNames c X Y returnScalarComponents TRUE HH 1 Oya 1 UXA Dil Xai n 3 WS 3 Y 3 HH 6 Wy CES 3 X 9 3 Wy lt Lal 5 3 gt lt Lal 4 gt lt Lal 5 HH fala vy 1 wypo Vv 3 wya 6 5 2 getDependencies Next we ll see how to determine the node dependencies or descendents in a model There are a variety of ar
49. It may also be provided to indicate the number of MCMC samples to be used in the automated blocking procedure default 20 000 Note that this function compiles and runs MCMCs progressively exploring different sampler assignments so it takes some time and generates some output 7 1 2 Customizing the MCMC configuration The MCMC configuration may be customized in a variety of ways either through additional named arguments to configureMCMC or by calling member methods of an existing MCMCspec object Default samplers for particular nodes One can create an MCMC configuration with default samplers on just a particular set of nodes using the nodes argument to configureMCMC The value for the nodes argument may be a character vector containing node and or variable names In the case of a variable name a default sampler will be added for all stochastic nodes in the variable If the nodes argument is provided default samplers are created only for the stochastic nodes specified by this argument possibly including data nodes and the ordering of these sampling algorithms matches the ordering within the nodes argument It is worthwhile to note this is the only way in which a sampler may be placed on a data node which upon execution of the MCMC will overwrite any value stored in the data node Creating a configuration with no samplers If you plan to customize the choice of all samplers it can be useful to obtain a configuration with no sampler assi
50. LSE to skip model check model building finished pumpMCEM lt buildMCEM model newPump latentNodes theta burnIn 100 mcmcControl list adaptInterval 20 boxConstraints list list cC alpha beta limits Gl COP enD buffer 1e 6 Here newPump was created just like pump in Section 2 2 The first argument model is a NIMBLE model which can be either the uncompiled or compiled version At the moment the model provided cannot be part of another MCMC sampler The latentNodes argument should indicate the nodes that will be integrated over sam pled via MCMC rather than maximized These nodes must be stochastic not determinis tic latentNodes will be expanded as described in Section 6 4 1 e g either latentNodes x or latentNodes c x 1 x 2 will treat x 1 and x 2 as latent nodes if x is a vector of two values All other non data nodes will be maximized over Note that latentNodes can include discrete nodes but the nodes to be maximized cannot The burnIn argument indicates the number of samples from the MCMC for the E step that should be discarded when computing the expected likelihood in the M step Note that burnIn can be set to values lower than in standard MCMC computations as each iteration will start off where the last left off The mcmcControl argument will be passed to configureMCMC to define the MCMC to be used The MCEM algorithm allows for box constraints on the node
51. MC configuration for a model generated from the following model code will serve as our example for this section code lt nimbleCode a dgamma 1 1 b dgamma 1 1 p dbeta a b yi dbinom prob p size 10 y2 dbinom prob p size 20 p CHAPTER 7 MCMC 75 7 5 1 Terminal node end sampler The end sampler is only appropriate for use on terminal stochastic nodes that is those having no stochastic dependencies Note that such nodes play no role in inference but have often been included in BUGS models to accomplish posterior predictive checks NIMBLE allows posterior predictive values to be simulated independently of running MCMC for example by writing a nimbleFunction to do so This means that in many cases where terminal stochastic nodes have been included in BUGS models they are not needed when using NIMBLE The end sampler functions by calling the simulate method of the relevant node then updating model probabilities and deterministic dependent nodes The end sampler will automatically be assigned to all terminal non data stochastic nodes in a model by the default MCMC configuration so it is uncommon to manually assign this sampler The end sampler accepts no control list arguments Example usage mcmcspec addSampler target y 1 type end 7 5 2 Scalar Metropolis Hastings random walk RW sampler The RW sampler executes adaptive Metropolis Hastings sampling with a normal proposal distribution implem
52. MCMC configuration and building FETED ALTE TEE TEE TL EE TE ETE EE TE HEAL TE HE HE TE DE TE TE DE TE TE PE PETE TE ALPE EEE generate the default MCMC configuration only wish to monitor the derived quantity mu mcmcspec lt configureMCMC Rmodel monitors mu check the samplers assigned by default MCMC configuration mcmcspec getSamplers CHAPTER 7 MCMC H H H H H H H H H H H H H H H H H H H H H H H H H H H H H H H H H H H H thin 1 2 3 4 5 6 A 8 9 10 11 12 miai 14 15 16 pial 18 19 20 21 221 23 24 25 26 EA 28 29 30 31 32 33 34 35 36 RW RW sampler sampler RW sampler RW sampler conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta conjugate_dbeta ald abot bli DEIF adaptive adaptive adaptive adaptive DEL Diks pnp pH DHF joy pls joy Es pie ple 12
53. NIMBLE User Manual NIMBLE Development Team Version 0 4 1 Contents 1 Welcome to NIMBLE 12 What does NIMBLE dot cc ec wane BO Cre RPL OER Saw E eS 1 3 How to use this manual 2 2 4 coa e u ad aa BEER See hE BRET ka 2 Lightning introduction 2 1 A brief example 2 2444 Rk dR eR Oe ER ew eS 2a See s mod l cend ee he hs ee ee he eR ee ek See 23 Compiling the model ce s ee a ee ee PO owe ew 2 4 Creating compiling and running a basic MCMC specification 2 J5 Toei the SIU lt s cocoke a A ee RS ee Re ee 20 Ione MOEM ng eee we BA ee Ree Ee ORE Oe wo 2 7 Creating your own Chen s s ea eV ee Ye wee wee YAS 3 More Introduction 3 1 NIMBLE adopts and extends the BUGS language for specifying models 3 2 The NIMBLE language for writing algorithms oo The NIMBLE algorithm library 2c e cee ew SEER ORME ESL eee G 4 Installing NIMBLE 4 1 Requirements to run NIMBLE 2 0 222 0 42 Installation ce eatu eR ee eR Pe ee ee ee Oe ee 4 2 1 Using your own copy of Eigen 2 2204 foe Voie Dene uf a nared aoe DEE PHS ee BS eH Ex 4 2 3 LAPACK and BLAS a x s amp s Cea He ER He Oe ee aS 42 8 Probleme with Installation s o s Se ie 2 Be dres a we ee ee 4 3 Installing a C compiler for Rtouse 2 2204 Be MMs rah i ee eh act es amp ee Be ei ees es es S Ope MA 6 262 62 bi ee Ree R a SEEDER ERE EOE Boom UGE con co howe cg dhe reh e CED ED eee Oe 4 4 4 Customizing Co
54. OT usr include eigen3 Eigen 4 2 2 Using libnimble NIMBLE generates specialized C code for user specified models and nimbleFunctions This code uses some NIMBLE C library classes and functions By default on Linux and OS X the library code is compiled once as a linkable library abnimble This single instance of the library is then linked with the code for each generated model Alternatively one can have the library code recompiled in each model s own dynamically loadable library DLL This does repeat the same code across models and so occupies more memory There may be a marginal speed advantage This is currently what happens on Windows One can disable using libnimble via the configuration argument enable 1ib e g R CMD INSTALL configure args enable lib false nimble_VERSION tar gz 4 2 3 LAPACK and BLAS NIMBLE also uses BLAS and LAPACK for some of its linear algebra in particular cal culating density values and generating random samples from multivariate distributions NIMBLE will use the same BLAS and LAPACK installed on your system that R uses Note that a fast and where appropriate threaded BLAS can greatly increase the speed of linear algebra calculations See Section A 3 1 of the R Installation and Administration manual for more details on providing a fast BLAS for your R installation 4 2 4 Problems with Installation We have tested the installation on the three commonly used platforms OS X Linux Windo
55. TER 7 MCMC 71 examples Each example assumes the MCMCspec object initially contains 10 samplers and each example is independent of the others Truncate the current list of samplers to the first 5 mcmcspec setSamplers ind 1 5 Retain only the third sampler which will subsequently become the first sampler mcmcspec setSamplers ind 3 Reverse the ordering of the samplers mcmcspec setSamplers ind 10 1 The new set of samplers becomes the first first first second third from the current list Upon each wteration of the MCMC the first sampler will be executed 3 times however each instance of the sampler will be independent in terms of scale adaptation etc mcmcspec setSamplers ind c 1 1 1 2 3 Set the list of samplers to only those acting on model node alpha mcmcspec setSamplers alpha Set the list of samplers to those acting on any components of the model variables x y or z mcmcspec setSamplers c x y z Samplers may be removed from the current sampler ordering with the removeSamplers method The following examples demonstrate this usage where again each example assumes that mcmcspec initially contains 10 samplers and each example is independent of the others removeSamplers may also accept a character vector argument and will remove all samplers acting on these target model nodes Remove the first sampler mcmcspec removeSamplers ind 1
56. THMS PROVIDED BY NIMBLE 91 defining model building model checking model use nimbleModel check FALSE to skip model check NAs were detected in model variables x logProb_x y logProb_y z logProb_z model building finished cSimpleModel lt compileNimble simpleModel1 siumulates all the x s and y s rSimXY lt simNodes simpleModel nodes c x y calls calculate on r and its dependents y but not z rCalcXDep lt calcNodes simpleModel nodes x calls getLogProb on z s and y s rGetLogProbXDep lt getLogProbNodes simpleModel nodes x compiling the functions cSimXY lt compileNimble rSimXY project simpleModel cCalcXDep lt compileNimble rCalcXDep project simpleModel cGetLogProbXDep lt compileNimble rGetLogProbXDep project simpleModel cSimpleModel x 1 NA NA NA NA cSimpleModel y 1 NA NA NA NA simulating x and y cSimxY run NULL cSimpleModel x 1 0 81408104 1 50846186 0 60719211 0 03049741 cSimpleModel y 1 0 9819697 1 5360858 0 7381187 0 8891184 CHAPTER 8 OTHER ALGORITHMS PROVIDED BY NIMBLE cCalcXDep run 1 10 34766 Gives correct answer because logProbs updated by calculate after simulation cGetLogProbxXDep run 1 10 34766 cSimXY run NULL Gives old answer because logProbs not updated after simulate cGetLogProbXDep run 1 10 34766 cCalcXDep run 1 10
57. a run function to use these model Values runFunction function gets the number of rows of propSamples m lt getsize propModelValues resized savedWeights to have the proper rows resize savedWeights m for i an Em Copying from propSamples to model Node names of propSamples and model must match nimCopy from propModelValues to model row i nodes modelNodes logProb FALSE calculates the log likelihood of the model targLL lt calculate model retreaves the saved log likelihood from the proposed model propLL lt propModelValues propLL i 1 saves the importance weight for the i th sample savedWeights w i 1 lt lt exp targLL propLL does not return anything Once the nimbleFunction is built the modelValues object can be accessed using using which is shown in more detail below In fact since modelValues like most NIMBLE objects are reference class objects one can get a reference to them before the function is executed and then use that reference afterwards Simple model and modelValue for example targetModelCode lt nimbleCode CHAPTER 9 WRITING NIMBLEFUNCTIONS 105 x dnonrm COk for i in 1 4 yli dnorm 0 1 p Code for proposal model propModelCode lt nimbleCode x dnorm 0 2 for i an 1 4 yli dnorm 0 2 J Building R models targetModel nimbleModel targetModelCode check FALSE defining model building mode
58. an sd dnorm mean tau dnorm mean var dpois lambda dt mu sigma df dt mu tau df dt mu sigma2 df dunif min max dweib shape dweib shape dweib shape dwish R df dwish S df scale rate lambda dbeta shape1 mean 2 1 mean sd 2 mean shape2 mean 1 mean 2 sd 2 mean 1 canonical canonical canonical canonical canonical dexp rate 1 scale canonical dgamma shape scale 1 rate dgamma shape mean 2 sd 2 scale sd 2 mean canonical dlogis location scale 1 rate canonical dlnorm meanlog sdlog 1 sqrt taulog dlnorm meanlog sdlog sqrt varlog canonical canonical precision canonical covariance dmnorm mean cholesky chol prec prec_param 1 dmnorm mean cholesky chol cov prec_param 0 canonical canonical dnorm mean sd 1 sqrt var dnorm mean sd sqrt var canonical canonical dt mu sigma 1 sqrt tau df dt mu sigma sqrt sigma2 df canonical canonical dweib shape scale 1 rate dweib shape scale lambda 1 shape dwish cholesky chol R df scale_param dwish cholesky chol S df scale_param 0 1 CHAPTER 5 BUILDING MODELS 34 Note that for multivariate normal and Wishart the canonical parameterization uses the Cholesky decomposition of either of the precision or covariance matrix In some cases it may be more efficient to use that parameterization directly If prec_param is TRUE
59. ases the general compilation mechanism will suffice However one can customize this One can specify the location of an alternative Makevars or Make vars win file to use Such an alternative file should define the variables PKG_CPPFLAGS and PKG_LIBS These should contain respectively the pre processor flag to locate the NIMBLE include directory and the necessary libraries to link against and their location as necessary e g Rlapack and Rblas on Windows and libnimble Use of this file allows users to specify additional compilation and linking flags See the Writing R Extensions manual for more details of how this can be used and what it can contain Chapter 5 Building models NIMBLE aims to be compatible with the original BUGS language and also the version used by the popular JAGS package as well as to extend the BUGS language However at this point there are some BUGS features not supported by NIMBLE and there are some extensions that are planned but not implemented For readers familiar with BUGS we begin with an overview of supported features and extensions 5 1 Overview of supported features and extensions of BUGS and JAGS 5 1 1 Supported features of BUGS and JAGS NOB wp Stochastic and deterministic node declarations Most univariate and multivariate distributions Link functions Most mathematical functions for loops for iterative declarations Arrays of nodes up to 4 dimensions Truncatio
60. ate simulate and getLogProb The four basic ways to operate a model are to calculate nodes simulate into nodes get the log probabilities or probability densities that have already been calculated and compare the log probability of a new value to that of an old value In more detail calculate For a stochastic node calculate determines the log probability value stores it in the appropriate logProb variable and returns it For a deterministic node calculate executes the deterministic calculation and returns 0 simulate For a stochastic node simulate generates a random draw For deterministic nodes simulate is equivalent to calculate without returning 0 simulate always returns NULL or void in C getLogProb getLogProb simply returns the most recently calculated log probability value or 0 for a deterministic node calculateDiff calculateDiff is identical to calculate but it returns the new log proba bility value minus the one that was previously stored This is useful when one wants to change the value or values of node s in the model e g by setting a value or simulate and then determine the change in the log probability such as needed for a Metropolis Hastings acceptance probability There are two ways to access calculate calculateDiff simulate and getLogProb The primary way is via the functions with those names which accept arbitrary collections of nodes as input In that case calculate and getLogProb return the sum of
61. basic concepts and terminology Before going further we need some basic concepts and terminology to be able to speak about NIMBLE clearly Say we have the following BUGS code mc lt nimbleCode a dnorm 0 0 001 fornia in las et yilt dnorm a 0 1 oe slay ales zLli j dnorm yli sd 0 1 yesduared 175 lt y ESR D model lt nimbleModel mc data list z matrix rnorm 15 nrow 5 check FALSE defining model building model setting data and initial values model building finished In NIMBLE terminology e The variables of this model are a y z and y squared e The nodes of this model are a y 1 y 5 z 1 1 z 5 3 and y squared 1 5 In graph terminology nodes are vertices in the model graph e the node functions of this model are a dnorm 0 0 001 y i dnorm a 0 1 zli j dnorm y i sd 0 1 and y squared 1 5 lt y 1 5 2 Each node has a corresponding node function Sometimes the distinction between nodes and node 51 CHAPTER 6 USING NIMBLE MODELS FROM R 52 functions is important but when it is not important we may refer to both simply as nodes e The scalar elements of this model include all the scalar nodes as well as the scalar elements y squared 1 y squared 5 of the multivariate node y squared 1 5 6 2 Accessing variables Model variables can be accessed and set just as in R using and For example modelg a lt
62. bution related functions must have names that begin with d r p and q The name of the distribution must not be identical to any of the NIMBLE provided distributions e The function name in the BUGSdist entry in the list provided to registerDistributions will be the name you can use in BUGS code e The name of your nimbleFunctions must match the function name in the Rdist entry If missing the Rdist entry defaults to be the same as the BUGSdist entry e All simulation r functions must take n as their first argument Note that you may simply have your function only handle n 1 and return an warning for other values of n e Your distribution related functions must take as arguments the parameters in default order starting as the second argument and in the order used in the parameterizations in the Rdist argument to registerDistributions or the BUGSdist argument if there are no alternative parameterizations NIMBLE uses doubles for numerical calculations so we suggest simply using doubles in general even for integer valued parameters or values of random variables e All density functions must have as their last argument log and implement return of the log probability density NIMBLE algorithms typically use only log 1 but we recommend you implement the log 0 case for completeness e All distribution and quantile functions must have their last two arguments be in order lower tail and log p These functions must wo
63. ck sampler 75 oe Slice sole o o ce ee ee ee ke eee eee eee wd Sed 76 7 5 5 Elliptical slice sampling ess sampler 76 7 5 6 Hierarchical crossLevel sampler 2 024 77 7 5 7 Customized log likelihood evaluations using the RW_11Function sampler 77 7 5 8 Conjugate Gibbs samplers 0000 78 7 6 Detailed MCMC example litters 5 che ba dee eee we ea ee 79 7 7 Comparing different MCMC engines with MCMCsuite 83 TLL MCMC Suite example litters e eo keen ee eee he Yes 83 Lre BIG Suite outputa s so seti soo ee ee 84 Tho Custommme MOMO Guile secc eee Ye we ee g a ES ox 85 To Advanced topis sis essre BAR RENE ODE REO DRED HERES 87 TRI Custom sampler Mnetiohs oo s s sewa e BR Bae Re eRe i 87 Other algorithms provided by NIMBLE 90 S Basie Wee ss ee ee hE ae Pe SORES OE aaa E ee eS 90 8 1 1 simNodes calcNodes and getLogProbs 90 8 1 2 simNodesMV calcNodesMV and getLogProbsMV 92 8 amp 2 Particle Piet ok o es eR Re eee POR EES eee ede 93 8 3 Monte Carlo Expectation Maximization MCEM 94 Writing nimbleFunctions 97 91 Writing nimbleFunctions sas cagau 2d ea eh dta dri padri 97 92 Using and compiling nimbleFunctions gt sasa 64 4 464 ee eae Pes 99 9 2 1 Accessing and modifying numeric values from setup 100 9 3 nimbleFunctions without setup code 2 625648 bebe ee es 100 04 Useful tools tor setup functions
64. cle filter for a state space model 5 A basic Monte Carlo Expectation Maximization MCEM algorithm MCEM has its issues as an algorithm such as potentially slow convergence to the maximum likelihood i e empirical Bayes in this context estimates but we chose it as a good illustration of how NIMBLE can be used Each MCMC step uses NIMBLE s MCMC the objective function for maximization is another nimbleFunction and the actual maximization is done through R s optim function More about the NIMBLE algorithm library is in Chapter 8 In the future we plan to provide direct access to R s optimizers from within nimbleFunctions Chapter 4 Installing NIMBLE 4 1 Requirements to run NIMBLE You can run NIMBLE on any of the three common operating systems Linux Mac OS X or Windows The following are required to run NIMBLE 1 R of course 2 The igraph R package 3 A working C compiler that R can use on your system There are standard open source C compilers that the R community has already made easy to install You don t need to know anything about C to use NIMBLE NIMBLE also uses a couple of C libraries that you don t need to install as they will already be on your system or are provided by NIMBLE 1 The Eigen C library for linear algebra This comes with NIMBLE or you can use your own copy 2 The BLAS and LAPACK numerical libraries These come with R Most fairly recent versions of these requirement
65. code must always exist in the setup code either by passing it in as a setup argument or creating it in the setup code To illustrate this we will create a nimbleFunction for computing importance weights for importance sampling This function will use two modelValues objects propModelValues will contain a set of values simulated from the importance sampling distribution and a field propLL for their log probabilities densities savedWeights will contain the difference in log probability density between the model and the propLL value provided for each set of values setupFunction function propModelValues model savedWeightsSpec lt modelValuesSpec vars w types double CHAPTER 9 WRITING NIMBLEFUNCTIONS 104 sizes 1 savedWeights lt modelValues spec savedWeightsSpec List of nodes to be used in run function modelNodes lt model getNodeNames stochOnly TRUE includeData FALSE The simplest way to pass values back and forth between models and model Values inside of a nimbleFunction is with copy which has the synonym nimCopy See help nimCopy for argument details Alternatively the values may be accessed via indexing of individual rows using the notation mv var i where mv is a modelValues object var is a variable name not a node name and i is a row number Likewise the getsize and resize functions can be used as discussed previously However the function as matrix does not work in run code Here is
66. could implement as a user defined distribution For example one could implement the dnormmiz distribution provided in JAGS as a user defined distribution in NIMBLE CHAPTER 5 BUILDING MODELS 38 User defined functions To provide a new function for use in BUGS code simply create a nimbleFunction that has no setup code Then use it in your BUGS code That s it Writing nimbleFunctions requires that you declare the dimensionality of arguments and the returned object Section 9 5 2 Make sure that the dimensionality specified in your nimbleFunction matches how you use it in BUGS code For example if you define scalar parameters in your BUGS code you will want to define nimbleFunctions that take scalar arguments Here is an example that returns twice its input argument timesTwo lt nimbleFunction run function x double 0 returnType double 0 return 2 x code lt BUGScode forn Gitanas mu i dnorm 0O 1 mu_times_two i lt timesTwo mu i D The x double 0 argument and returnType double 0 establish that the input and output will both be 0 dimensional scalar numbers You can define nimbleFunctions that take inputs and outputs with more dimensions Here is an example that takes a vector 1 dimensional as input and returns a vector with twice the input values vectorTimesTwo lt nimbleFunction run function x double 1 returnType double 1 return 2 x code lt BUGScode
67. customMV Currently only the syntax customMV a 2 works in the NIMBLE language not customMV a 2 Also note that c does not work in NIMBLE but one can do customMV a 2 lt X 1 2 We can query and change the number of rows using getsize and resize respectively These work in both R and NIMBLE Note that we don t specify the variables in this case all variables in a modelValues object will have the same number of rows getsize customMV ae L 2 resize customMV 3 getsize customMV 1 3 customMV a CHAPTER 6 USING NIMBLE MODELS FROM R 64 1 1 0 1 HH 2 1 2 4 HH 3 1 NA NA Often it is useful to convert a modelValues object to a matrix for use in R For example we may want to convert MCMC output into a matrix for use with the coda package for processing MCMC samples This can be done with the as matrix method for model Values objects This will generate column names from every scalar element of variables e g x 1 1 x 2 1 etc The rows of the modelValues will be the rows of the matrix with any matrices or arrays converted to a vector based on column major ordering as matrix customMV a convert a HH a 1 a 2 1 0 1 2 2 4 3 NA NA as matrix customMV convert all variables alt a2 bit able tl bit 2 ble 2 eH 1 0 1 il il 1 al NA 2 2 4 2 2 2 2 NA 3 NA NA NA NA NA NA NA If a
68. cutpoint interval This is done by setting data censored i as follows censored i oO if tli lt cli 1 censored i m if cli m lt tli lt cli m 1 for 1 lt m lt M M if cli M lt tli censored i The i index is provided only for consistency with the previous example The most common uses of dinterval will be for left and right censored data in which case c i will be a single value and typically given as simply c i and for interval censored data in which case c i will be a vector of two values Nodes following a dinterval distribution should normally be set as data with known values Otherwise the node may simulated during initialization in some algorithms e g MCMC and thereby establish a permanent perhaps unintended constraint Censoring differs from truncation because censoring an observation involves bounds on a random variable that could have taken any value while in truncation we know a priori that a datum could not have occurred outside the truncation range Constraints and ordering NIMBLE provides a more general way to enforce constraints using dconstraint cond For example we could specify that the sum of mui and mu2 must be positive like this mui dnorm 0 1 mu2 dnorm 0 1 constraint_data dconstraint mul mu2 gt 0 with constraint_data set as data to 1 This is equivalent to a half normal distribu tion on the half plane u u2 gt 0 However note that this equival
69. d JAGS input files Users with BUGS and JAGS experience may have files set up in standard formats for use in BUGS and JAGS readBUGSmodel can read in the model data constant values and initial values in those formats It can also take information directly from R objects somewhat more flexibly than nimbleModel specifically allowing inputs set up similarly to those for BUGS and JAGS In either case after processing the inputs it calls nimbleModel Note that unlike BUGS and JAGS only a single set of initial values can be specified in creating a model Please see help readBUGSmodel for argument details As an example of using readBUGSmodel1 let s create a model for the pump example from BUGS pumpDir lt system file classic bugs voli pump package nimble pumpModel lt readBUGSmodel pump bug data pump data R inits pump init R dir pumpDir defining model Detected x as data within constants Adding x as data for building model building model setting data and initial values checking model use nimbleModel check FALSE to skip model check model building finished CHAPTER 5 BUILDING MODELS 49 Note that readBUGSmodel allows one to include var and data blocks in the model file as in some of the BUGS examples such as inhaler The data block pre computes constant and data values Also note that if data and inits are provided as files the files should contain R co
70. d to a particular model This can be done in one step but when a user wants to customize the MCMC it can be done in several steps Creating an MCMC configuration consisting of a set of sampler choices Customizing the sampler choices in the configuration which may include provid ing new samplers written as nimbleFunctions and Building the MCMC function from the configuration e Compiling and running the MCMC function e Extracting the posterior samples This chapter also discusses Sampling algorithms provided with NIMBLE Default sampler assignments in an MCMC configuration Writing new samplers that conform to NIMBLE s MCMC system Using MCMCsuite to automatically run WinBUGS OpenBUGS JAGS Stan and or multiple NIMBLE MCMCs on the same model Using NIMBLE s algorithm to search blocks of nodes for efficient joint block sampling 7 1 The MCMC configuration The MCMC configuration contains information needed for building an MCMC We will show how to create this information as a first step so it can be customized before moving ahead but when no customization is needed one can jump directly to the buildMCMC step below An MCMC configuration includes e The model on which the MCMC will operate e The model nodes which will be sampled updated during execution of the MCMC e The particular sampling algorithms for each of these nodes including any control parameters required by each sampling algorithm 67 CH
71. de that creates objects analogous to what would populate the list if a list were provided instead Please see the JAGS manual examples or the classic_bugs directory in the NIMBLE package for example syntax NIMBLE by and large does not need the information given in a var block but occasionally this is used to determine dimensionality such as in the case of syntax like xbar lt mean x where x is a variable that appears only on the right hand side of BUGS expressions Note that NIMBLE does not handle formatting such as in some of the original BUGS examples in which data was indicated with syntax such as data x in x txt 5 3 3 Providing data via setData Whereas the constants are a property of the model definition since they may help determine the model structure itself data nodes can be different in different copies of the model generated from the same model definition For this reason data is not required to be provided when the model code is processed It can be provided later via the model member function setData e g pump setData pumpData where pumpData is a named list of data values setData does two things it sets the values of the data nodes and it flags those nodes as containing data nimbleFunction programmers can then use that information to control whether an algorithm should over write data or not For example NIMBLE s simulate functions by default do not overwrite data values but can be told to do so Values of da
72. e 1 168 9673926 4 6460261 5 2641096 105 3583839 6 4061287 6 36 3723548 1 0395209 0 3227420 0 1987001 1 6506161 pump logProb_x 1 148 106356 3 110014 1 747041 65 346457 2 626123 6 7 429868 1 000761 1 453644 9 840589 39 096527 CHAPTER 2 LIGHTNING INTRODUCTION 12 Notice that the first getDependencies call returned dependencies from alpha and beta down to the next stochastic nodes in the model The second call requested only deterministic dependencies The call to calculate pump theta expands theta to include all nodes in theta After simulating into theta we can see that lambda and the log probabilities of x still reflect the old values of theta so we calculate them and then see that they have been updated 2 3 Compiling the model Next we compile the model which means generating C code compiling that code and loading it back into R with an object that can be used just like the uncompiled model The values in the compiled model will be initialized from those of the original model in R but the original and compiled models are distinct objects so any subsequent changes in one will not be reflected in the other Cpump lt compileNimble pump Cpump theta 1 1 79180692 0 29592523 0 08369014 0 83617765 1 22254365 6 1 15835525 0 99001994 0 30737332 0 09461909 0 15720154 Note that the compiled model is used when running any NIMBLE algorithms via C so the model needs to be com
73. e RW_block control list adaptInterval 100 13 RW_block sampler alpha beta adaptive TRUE adaptScaleOnly FALSE adaptIn pumpMCMC2 lt buildMCMC pumpSpec need to reset the nimbleFunctitons in order to add the new MCMC CpumpNewMCMC lt compileNimble pumpMCMC2 project pump resetFunctions TRUE set seed 0 CpumpNewMCMC run niter NULL samplesNew lt as matrix CpumpNewMCMC mvSamples par ntrow cCl 4 mai cC 6 25 1 5 42 plot samplesNewL alpha type 1 xlab iteration ylab expression alpha plot samplesNewL beta type l xlab iteration ylab expression beta plot samplesNewL alpha samplesNew beta xlab expression alpha ylab expression beta plot samplesNewL theta 1 type 1 xlab iteration ylab expression thetal 1 CHAPTER 2 LIGHTNING INTRODUCTION 15 o 2 5 6 19 2 Te re ai ai o o ai ai Q lt 2 a a ee 5 2 2 9 S 0 0 S S o o So 0 400 800 0 400 800 0 400 800 iteration iteration a iteration acf samplesNew alpha acf samplesNewl beta 2 2 o o Oo o o oS o G O wt 1 lt amp N N So O o o 0 5 15 25 0 5 15 25 Lag Lag We can see that the block sampler has decreased the autocorrelation for both alpha and beta Of course these are just short runs and what we are really interested in is the effective sample size of the MCMC per computa
74. e This is common in survival analysis when for individuals still surviving at the end of a study their age of death is not known and hence is censored right censoring NIMBLE adopts JAGS syntax for censoring as follows using right censoring as an example censored Hii adintervai Ct cal pc ll p tli dweib r mu il where censored i should be given as data with a value of 1 if t i is right censored t i gt c i and 0 if it is observed The data vector for t should have NA indicating missing data for any censored t i entries As a result these nodes will be sampled in an MCMC The data vector for c should give the censoring times corresponding to censored entries and a value below the observed times for uncensored entries e g 0 assuming t i gt 0 Left censoring would be specified by setting censored i to 0 and t i to NA The dinterval is not really a distribution but rather a trick in the above example when censored i 1 it gives a probability of 1 if tli gt cli and 0 otherwise This 6If you have a model object model you can see exactly the calculation used by typing model nodes x calculate CHAPTER 5 BUILDING MODELS 46 means that tli lt cli is treated as impossible More generally than simple right or left censoring censoredli dinterval t i cli is defined such that for a vector of increasing cutpoints c i tli is enforced to fall within the censored i th
75. e of good programming In BUGS and JAGS if one wants to consider model variants one needs to create complete model code for each one This can lead to lots of code and potential errors In NIMBLE one can use definition time if then else statements to create different models from the same code As a simple example say we have a linear regression model and want to consider including or omitting x 2 as an explanatory variable regressionCode lt nimbleCode intercept dnorm 0 sd 1000 slopei dnorm 0 sd 1000 if includeX2 CHAPTER 5 BUILDING MODELS 44 slope2 dnorm 0 sd 1000 for Gean iN predictedY i lt intercept slope1 x1 i slope2 x2 i else for i in 1 N predictedY i lt intercept slopel x1 i sigmaY dunif 0 100 for i in 1 N Y i dnorm predictedY i sigmaY p includeX2 lt FALSE modelWithoutX2 lt nimbleModel regressionCode constants list N 30 check FALSE defining model building model model building finished modelWithoutX2 getVarNames 1 intercept 2 slopei 3 predictedY 4 sigmay 5 lifted_d1l_over_sqrt_oPsigmaY_cP HH 6 nyt 7 x1 includeX2 lt TRUE modelWithX2 lt nimbleModel regressionCode constants list N 30 check FALSE defining model building model model building finished modelWithX2 getVarNames 1 intercept 2 slope1 3
76. e provided indicating when a covariance or precision matrix has been given User defined distributions can also be used from nimbleFunctions Arguments are matched by order or by name if given If omitted default argument values based on the standard R distribution functions will be used Standard arguments to distribution functions in R log log p lower tail can be used and take the usual default values as in R User supplied distributions are handled analogously with regard to matching by position and use of defaults when provided via the nimbleFunction run time arguments Section 5 2 5 Supported distributions include dbinom size prob dcat prob dmulti size prob dnbinom size prob dpois lambda CHAPTER 9 WRITING NIMBLEFUNCTIONS 119 dbeta shape1 shape2 dchisq df dexp rate dexp nimble rate dexp_nimble scale dgamma shape rate dgamma shape scale dlnorm meanlog sdlog dlogis location scale dnorm mean sd dt_nonstandard df mu sigma dt df dunif min max dweibull shape scale ddirch alpha dmnorm_chol mean cholesky prec_param dwish_chol cholesky df scale_param In the last two cholesky stands for Cholesky decomposition of the relevant matrix prec_param indicates whether the Cholesky is of a precision matrix or covariance matrix and scale_param indicates whether the Cholesky is of a scale matrix or an inverse scale matrix In a future release we will also extend the a
77. efault configuration NIMBLE configuration with argument onlySlice TRUE NIMBLE custom configuration using two crossLevel samplers aR WN E output lt MCMCsuite code litters_code CHAPTER 7 MCMC 84 constants constants data data inits inits monitors mu MCMCs c winbugs jags nimble nimble_slice nimble_CL MCMCdefs list nimble_CL quote mcmcspec lt configureMCMC Rmodel nodes NULL mcmcspec addSampler target c al 1 b 1 type crossLevel mcmcspec addSampler target c al2 b 2 type crossLevel mcmcspec DDE plotName littersSuite 7 7 2 MCMC Suite outputs Executing the MCMC Suite returns a named list containing various outputs as well as generates and saves traceplots and posterior density plots The default elements of this return list object are Samples samples is a three dimensional array containing all MCMC samples from each algorithm The first dimension of the samples array corresponds to each MCMC algorithm and may be indexed by the name of the algorithm The second dimension of the samples array corresponds to each node which was monitored and may be indexed by the node name The third dimension of samples contains the MCMC samples and has length niter thin burnin Summary The MCMC suite output contains a variety of pre computed summary statistics which are stored in the summary matrix For each monitored node and each MCMC algorithm
78. ence of the R model object Rmodel Further this block of code need not worry about adding monitors to the MCMC configuration it need only specify the samplers As a final important point execution of this block of code must return the MCMC configuration object Therefore elements supplied in the MCMCdefs argument should usually take the form CHAPTER 7 MCMC 87 MCMCdefs list myMCMC quote mcmcspec lt configureMCMC Rmodel mcmcspec addSampler mcmcspec returns the MCMC configuration object D Full details of the arguments and customization of the MCMC Suite is available through the R help using help MCMCsuite 7 8 Advanced topics 7 8 1 Custom sampler functions The following code illustrates how a NIMBLE developer would implement and use a Metropolis Hastings random walk sampler with fixed proposal standard deviation The comments ac companying the code explain the necessary characteristics of all sampler functions the name of this sampler function for the purposes of adding it to MCMC configurations will be my_RW my_RW lt nimbleFunction sampler functions must contain sampler_BASE contains sampler_BASE sampler functions must have exactly these setup arguments model muSaved target control setup function model mvSaved target control first extract the control list elements which will dictate the behavior of this sampler the setup code will be la
79. ence only holds when conditioning on constraint_data e g in an MCMC and not when simulating from the model using simulate Nodes following dconstraint should be provided as data for the same reason of avoiding unintended initialization described above for dinterval Formally dconstraint condition is a probability distribution on 0 1 such that P 1 1 if cond is TRUE and P 0 1 if cond is FALSE Of course in many cases parameterizing the model so that the constraints are automat ically respected may be a better strategy than using dconstraint One should be cautious about constraints that would make it hard for an MCMC or optimization to move through the parameter space such as equality constraints that involve two or more parameters For such restrictive constraints general purpose algorithms that are not tailored to the con straints may fail or be inefficient If constraints are used it will generally be wise to ensure the model is initialized with values that satisfy them CHAPTER 5 BUILDING MODELS 47 Ordering To specify an ordering of parameters such as aj lt a2 lt a3 one can use dconstraint as follows constraint_data dconstraint alpha1 lt alpha2 amp alpha2 lt alpha3 Note that unlike in BUGS one cannot specify prior ordering using syntax such as alpha 1 dnorm 0 1 I alpha 2 alpha 2 dnorm 0 1 I alpha 1 alpha 3 alpha 3 dnorm 0 1 I alpha 2 as this does not represent a direc
80. enting the adaptation routine given in 7 This sampler can be applied to any scalar continuous valued stochastic node The RW sampler can be customized using the control list argument to set the initial proposal distribution scale and the adaptive properties of the sampler See help samplers for details Example usage mcmcspec addSampler target a type RW control list adaptive FALSE scale 3 mcmcspec addSampler target b type RW control list adaptive TRUE adaptInterval 200 Note that because we use a simple normal proposal distribution on all nodes negative proposals may be simulated for non negative random variables These will be rejected so the only downsides to this are some inefficiency and the presence of warnings during uncompiled but not compiled execution indicating NA or NaN values 7 5 3 Multivariate Metropolis Hastings RW_block sampler The RW_block sampler performs a simultaneous update of one or more model nodes using an adaptive Metropolis Hastings algorithm with a multivariate normal proposal distribution 6 implementing the adaptation routine given in 7 This sampler may be applied to any CHAPTER 7 MCMC 76 set of continuous valued model nodes to any single continuous valued multivariate model node or to any combination thereof The RW_block sampler can be customized using the control list argument to set the initial proposal covariance and the adaptive properties of the
81. erifyConjugatePosteriors TRUE buildConjugateSamplerFunctions 7 6 Detailed MCMC example litters Here is a detailed example of specifying building compiling and running two MCMC algo rithms We use the litters example from the BUGS examples PUHH ED TET BETTIE DLE TELET LTE TE TE TEDL TUE TE TELE TE HHHHH model configuration HHH BEELER LEELA ETL EEE TET define our model using BUGS syntar litters_code lt nimbleCode for Ci ia eG 1 ali dgamma 1 001 bli dgamma 1 001 ow C amet Ne clas dbomw pel mb pli j dbeta ali b i mu i lt aka 7 a biz CHAPTER 7 MCMC 80 theta hi lt lt 1 ala bi D list of fired constants constants lt list G 2 N 16 m matrix e IS 12 Io ORO O ti 6 10 13 WO PA 2 o NO te S e e Tf fn e i a 1o OOT Anr on 2 list specifying model data data lt iist matrix CHo re T2 OOTO ITS sie le ATS ifs Aa tO nrow 2 list specifying initial values ati lt lista wGl al w e DN p matrix 0 5 nrow 2 ncol 16 mu eC By a i theta c5 5N build the R model object Rmodel lt nimbleModel litters_code constants constants data data inits inits defining model building model setting data and initial values checking model use nimbleModel check FALSE to skip model check model building finished TELE REDE ETE MELEE ETT TERETE ETE SEL ELTA TELER UUE HHHHH
82. es and calculating every part of the model that depends on them Here is our nimbleFunction simNodesMany lt nimbleFunction setup function model nodes mv lt modelValues model deps lt model getDependencies nodes allNodes lt model getNodeNames run function n integer resize mv n fonG am lem simulate model nodes calculate model deps copy from model nodes allNodes to mv rowTo i logProb TRUE 3Their numbers were accidentally swapped in Table 2 CHAPTER 2 LIGHTNING INTRODUCTION 17 simNodesTheta1to5 lt simNodesMany pump theta 1 5 simNodesTheta6to10 lt simNodesMany pump theta 6 10 Here are a few things to notice about the nimbleFunction ie The setup function is written in R It creates relevant information specific to our model for use in the run time code The setup code creates a modelValues object to hold multiple sets of values for vari ables in the model provided The run function is written in NIMBLE It carries out the calculations using the information determined once for each set of model and nodes arguments by the setup code The run time code is what will be compiled The run code requires type information about the argument n In this case it is a scalar integer The for loop looks just like R but only sequential integer iteration is allowed The functions calculate and simulate which were introduced above in R ca
83. eter The node is then a direct descendant of the new deterministic node This is an optional feature but it is currently enabled in all cases e As discussed in Section 5 2 4 the use of link functions causes new nodes to be intro duced This requires care if you need to initialize values in stochastic declarations with link functions CHAPTER 5 BUILDING MODELS 48 e Use of alternative parameterizations of distributions described in Section 5 2 2 For example when a user provides the precision of a normal distribution as tau NIMBLE creates a new node sd lt 1 sqrt tau and uses sd as a parameter in the normal distribution If many nodes use the same tau only one new sd node will be created so the computation 1 sqrt tau will not be repeated redundantly 5 3 Creating model objects NIMBLE provides two functions for creating model objects nimbleModel and readBUGSmodel The first nimbleModel is the primary way to create models and was illustrated in Chapter 2 The second readBUGSmodel provides compatibility with BUGS file formats for models variables data and initial values for MCMC NIMBLE also provides some additional flexibility in setting data in a model and in defining multiple models from the same model definition as described at the end of this section 5 3 1 Using nimbleModel to specify a model The R help page nimbleModel provides more details on nimbleModel arguments 5 3 2 Specifying a model from standard BUGS an
84. etup cannot be modified numeric values and modelValues see below can be For example logProbCalcPlusA valueToAdd in the uncompiled version 1 1 logProbCalcPlusA valueToAdd lt 2 ClogProbCalcPlusA valueToAdd or in the compiled version 1 1 ClogProbCalcPlusA valueToAdd lt 3 ClogProbCalcPlusA run 1 5 1 16 46288 CtestModel a Ha 15 F3 1 4 5 9 3 nimbleFunctions without setup code The setup function is optional If it is omitted then nimbleFunction is more like function it simply returns a function that can be executed and compiled If there is no setup code there is no specialization step This is useful for doing math or the other kinds of processing available in NIMBLE when no model or modelValues is needed solveLeastSquares lt nimbleFunction run function X double 2 y double 1 ans lt inverse t X X t X h y return ans returnType double 2 J X lt matrix rnorm 400 nrow 100 y lt rnorm 100 solveLeastSquares X y H ea 1 0 1559144 4Actually they can be but only for uncompiled nimbleFunctions CHAPTER 9 WRITING NIMBLEFUNCTIONS 101 2 0 1874887 3 0 1541508 4 0 1063246 CsolveLeastSquares lt compileNimble solveLeastSquares CsolveLeastSquares X y Ltd 1 0 1559144 2 0 1874887 3 0 1541508 4 0 1063246 This example shows the textbook calculation of a least squa
85. extends the con cept of JAGS dinterval See Section 5 2 8 3 changed allowing one model to be used for different data sets without rebuilding the model each time 3 Not yet supported features of BUGS and JAGS In this release the following are not supported 1 Stochastic indices but see Section 5 2 5 for a description of how you could handle some cases with user defined distributions The appearance of the same node on the left hand side of both a lt and a declaration used in WinBUGS for data assignment for the value of a stochastic node Like BUGS NIMBLE generally determines the dimensionality and sizes of variables from the BUGS code However when a variable appears with blank indices such as in x sum lt sum x NIMBLE currently requires that the dimensions of x be provided Multivariate nodes must appear with brackets even if they are empty E g x cannot be multivariate but x or x 2 5 can be 5 2 Writing models 5 2 1 Declaring stochastic and deterministic nodes The WinBUGS OpenBUGS and JAGS manuals are useful resources for writing BUGS mod els Here we will just introduce the basics of the BUGS language and some of NIMBLE s extensions with a block of code showing a variety of declarations exampleCode lt nimbleCode x dnorm a b c tau y dnorm a b c sd sigma 2e g y dnorm 5 mu 3 exp tau 3But beware of the possibility of needing t
86. forane mu i dnorm 0 1 mu_times_two 1 3 lt vectorTimesTwo mu 1 3 JD There is a subtle difference between the mu_times_two variables in the two examples In the first example there are individual nodes for each mu_times_two i In the second ex ample there is a single multivariate node mu_times_two 1 3 Each implementation could CHAPTER 5 BUILDING MODELS 39 be more efficient for different needs For example suppose an algorithm modifies the value of mu 2 and then updates nodes that depend on it In the first example mu_times_two 2 would be updated In the second example mu_times_two 1 3 would be updated because it is a single vector node At present you cannot provide a scalar argument where a nimbleFunction expects a vector unlike in R scalars are not simply vectors of length 1 User defined distributions To provide a user defined distribution you need to do the following 66499 1 define density d and simulation r nimbleFunctions without setup code for your distribution 2 register the distribution using registerDistributions and 3 use your distribution in BUGS code 6699 You can optionally provide distribution p and quantile q functions which will al low truncation to be applied to a user defined distribution You can also provide a list of alternative parameterizations Here is an extended example of providing a univariate exponential distribution althoug
87. gacyRelationshipsInputList Conjugate samplers should not in gen eral be manually added or modified by a user since the control list requisites and syntax are lengthy and determining conjugacy and assigning conjugate samplers is fully handled by the default MCMC configuration A model may be checked for conjugate relationships using model checkConjugacy This returns a named list describing all conjugate nodes checkConjugacy can also accept a character vector argument specifying a subset of model node names to check for conjugacy The current release of NIMBLE supports conjugate sampling of the relationships listed in Table 7 1 Conjugate sampler functions may optionally dynamically check that their own pos terior likelihood calculations are correct If incorrect a warning is issued However this CHAPTER 7 MCMC 79 Prior Distribution Sampling Distribution Parameter Beta Bernoulli prob Binomial prob Negative Binomial prob Dirichlet Multinomial prob Gamma Poisson lambda Normal tau Lognormal taulog Gamma rate Exponential rate Normal Normal mean Lognormal meanlog Multivariate Normal Multivariate Normal mean Wishart Multivariate Normal prec Table 7 1 Conjugate relationships supported by NIMBLE s MCMC engine functionality will roughly double the run time required for conjugate sampling By default this option is disabled in NIMBLE This option may be enabled by executing the following nimbleOptions v
88. gnments at all This can be done by providing the nodes argument with the value NULL character or list CHAPTER 7 MCMC 70 Overriding the default sampler control list values The default values of control list elements for all sampling algorithms may be overridden through use of the control argument to configureMCMC which should be a named list Named elements in the control argument will be used for all default samplers added In addition they are retained in the MCMCspec object and will be used as defaults for any subsequent samplers added to this same MCMCspec object For example the following will create the default MCMC configuration except all RW samplers will have their initial scale set to 3 and none of the samplers RW or otherwise will be adaptive mcmcspec lt configureMCMC Rmodel control list scale 3 adaptive FALSE Note that when adding individual samplers next the default control list can be over ridden Adding samplers to the configuration Samplers may be added to a configuration using the addSampler method of the MCMCspec object The frst argument gives the node s to be sampled called the target as a char acter vector The second argument gives the types of sampler which may be provided as a character string or a nimbleFunction object Valid character strings include end RW RW_block slice crossLevel and RW_IlFunction which are described below Re quire
89. guments to getDependencies that allow one to specify whether to include the node itself whether to include deterministic or stochastic or data dependents etc By default getDependencies returns descendants up to the next stochastic node on all edges emanating from the node s specified as input This is what would be needed to calculate a Metropolis Hastings acceptance probability in MCMC for example pump getDependencies alpha 1 alpha theta 1i theta 2 theta 3 theta 4 6 theta 5 thetal6 theta 7 theta 8 theta 9 11 theta 10 CHAPTER 6 USING NIMBLE MODELS FROM R pump getDependencies c alpha beta H H H H H H H 1 3 5 7 9 ai 13 alpha beta Titted_diover_betal thetal1 theta oa theta 3i theta dii theta 5 theta 6 heta l7it Uthetalslt theta 9 theta 10 60 pump getDependencies theta 1 3 self FALSE H H 1 6 lambda 1 lambda 2 lambda 3 x 1 Wy 3 Wy 2 pump getDependencies theta 1 3 stochOnly TRUE self FALSE H 1 self aL w2 x 3 get all dependencies not gust the direct descendants pump getDependencies alpha downstream H H H H H H H H pump getDependencies alpha downstream 1 5 9 13 17 21 25 29 M 8 6 5 3 alpha theta 4 theta si lambda 2 lambda 6 lambda 10
90. h this is already provided by NIMBLE and a multivariate Dirichlet multinomial distribution dmyexp lt nimbleFunction run function x double 0 rate double 0 default 1 log integer 0 default 0 returnType double 0 logProb lt log rate x rate if log return logProb else return exp logProb rmyexp lt nimbleFunction run function n integer 0 rate double 0 default returnType double 0 if n 1 print rmyexp only allows n 1 using n 1 devic reunir PRON return log 1 dev rate IDDE pmyexp lt nimbleFunction run function q double 0 rate double 0 default 1 lower tail integer 0 default 1 log p integer 0 default 0 returnType double 0 if lower tail logp lt ratok q CHAPTER 5 BUILDING MODELS 40 if log p return logp else return exp logp else p lt 1 exp rate g if log p return p else return log p qmyexp lt nimbleFunction run function p double 0 rate double 0 default 1 lower tail integer 0 default 1 log p integer 0 default 0 returnType double 0 if log p p lt exp p cee CUilower call specs he ae return log 1 p rate ddirchmulti lt nimbleFunction run function x double 1 alpha double 1 size double 0 log integer 0 returnType double 0 logProb lt lgamma sum alpha sum lgamma alpha sum lgamma alpha x
91. his is necessary to avoid a great deal of copying and returning and having to reassign large objects both in processing model and nimbleFunctions and in running algorithms One cannot generally copy NIMBLE models or nimbleFunctions specializations or gener ators in a safe fashion because of the references to other objects embedded within NIMBLE objects However the model member function newModel will create a new copy of the model CHAPTER 6 USING NIMBLE MODELS FROM R 66 from the same model definition Section 5 3 4 This new model can then be used with newly instantiated nimbleFunctions The reliable way to create new copies of nimbleFunctions is to re run the R function called nimbleFunction and record the result in a new object For example say you have a nimbleFunction called foo and 1000 instances of foo are compiled as part of an algorithm related to a model called mode11 If you then need to use foo in an algorithm for another model model2 doing so may work without any problems However there are cases where the NIMBLE compiler will tell you during compilation that the second set of foo instances cannot be built from the previous compiled version A solution is to re define foo from the beginning i e call nimbleFunction again and then proceed with building and compiling the algorithm for mode12 Chapter 7 MCMC Using the MCMC engine provided with NIMBLE consists of several steps e Building an MCMC function specialize
92. imble Care must be taken to perform this compilation in the same project that contains the underlying model and compiled model objects A typical compilation call looks like Cmcmc lt compileNimble Rmcmc project Rmodel Alternatively if the model has not already been compiled they can be compiled together in one line Cmcmc lt compileNimble Rmodel Rmcmc 7 3 Executing the MCMC algorithm The MCMC function either the compiled or uncompiled version has one required argument niter representing the number of iterations to run the MCMC algorithm We ll assume the function is called mcmc Calling mcmc niter causes the full list of samplers as determined from the input MCMCspec object to be executed niter times and the monitored variables to be stored into the internal mvSamples and or mvSamples2 objects as governed by the corresponding thinning intervals The mcmc function has an optional reset argument When reset TRUE the default value the following occurs at the onset of the call to mcmc run e All model nodes are checked that they contain values and that model log probabilities are up to date with the current node values If a stochastic node is missing a value it is populated using a call to simulate The values of deterministic nodes are calculated to be consistent with their parent nodes If any right hand side only nodes are missing a value an error results e All MCMC sampler functions are reset to their i
93. imbleModel or readBUGSmodel Variables that define for loop indices N and M must be provided as constants The arbitrary block mvx 8 10 i follows a multivariate normal distribution with a named covariance matrix instead of BUGS default of a precision matrix As in R curly braces for for loop contents are only needed if there is more than one line w follows a user defined distribution See Section 5 2 5 di is a scalar deterministic node that when calculated will be set to a b d2 is a vector deterministic node using matrix multiplication in R s syntax d3 is a deterministic node using a user provided function See Section 5 2 5 More about indexing Examples of allowed indexing include e x i CHAPTER 5 BUILDING MODELS xli j x i j k 1 and indexing of higher dimensional arrays x i j x 3 i 7 x 3 i 5 i 1 30 When calling functions such as mean and sum on a vector variable the square brackets are required but can have blank indices e g xbar lt mean x if x is a vector and xbar lt mean x if x is a matrix NIMBLE does not allow multivariate nodes to be indicated without square brackets which is an incompatibility with JAGS Therefore a statement like xbar lt mean x in JAGS must be converted to xbar lt mean x for NIMBLE Here s an example of indexing in the context of multivariate nodes showing two ways to do the indexing The first provides indices so no d
94. imensions argument is needed while the second omits the indices and provides a dimensions argument instead code lt nimbleCode yK amuich Kn pli K ddirch alpha 1 K log alpha 1 K dmnorm alphaO 1 K R 1 K 1 K D KETS model lt nimbleModel code constants list n 3 K K alpha0 rep 0 K R diag K check FALSE defining model building model model building finished codeAlt lt nimbleCode yO a clei N in pl ddirch alphal log alpha dmnorm alphaO RI J p model lt nimbleModel codeAlt constants list n 3 K K alpha0 rep 0 K R diag K dimensions list y K p K alpha K check FALSE defining model building model model building finished 4This is a case where the dimension of x must be provided when defining the model CHAPTER 5 BUILDING MODELS 31 5 2 2 Available distributions and functions Distributions NIMBLE supports most of the distributions allowed in BUGS and JAGS Table 5 1 lists the distributions that are currently supported with their default parameterizations which match those of BUGS NIMBLE also allows one to use alternative parameterizations for a variety of distributions as described next Note that the same distributions are available for writing nimbleFunctions but in that case the default parameterizations match R s when possible see Chapter 9 Table 5 1 Distributions with their default
95. information about the model structure is determined and then the run code can use that information without repeatedly redundantly recomputing it A nimbleFunction can be called repeatedly each time returning a specialized nimbleFunction Readers familiar with object oriented programming may find it useful to think in terms of class definitions and objects nimbleFunction creates a class definition Each specialized nimbleFunction is one object in the class The setup arguments are used to define member data in the object 9 2 Using and compiling nimbleFunctions To compile the nimbleFunction together with its model we use compileNimble CnfDemo lt compileNimble testModel logProbCalcPlusA CtestModel lt CnfDemo testModel ClogProbCalcPlusA lt CnfDemo logProbCalcPlusA These have been initialized with the values from their uncompiled versions and can be used in the same way CtestModel a values were initialized from testModel 1 1 25 CtestModel b 1 1 5 lpA lt ClogProbCalcPlusA run 1 5 lpA 1 5 462877 verify the answer dnorm CtestModel b CtestModel a 1 log TRUE dnorm CtestModel a 0 1 log TRUE 1 5 462877 CtestModel a a was modified in the compiled model 1 2 5 testModel a the uncompiled model was not modified 1 1 25 CHAPTER 9 WRITING NIMBLEFUNCTIONS 100 9 2 1 Accessing and modifying numeric values from setup While models and nodes created during s
96. ing models We adopted the BUGS language and we have extended it to make it more flexible The BUGS language became widely used in WinBUGS then in OpenBUGS and JAGS These systems all provide automatically generated MCMC algorithms but we have adopted only the language for describing models not their systems for generating MCMCs We adopted BUGS because it has been so successful with over 30 000 users by the time they stopped counting 3 Many papers and books provide BUGS code as a way to document their statistical models We provide a brief introduction to BUGS later but we refer you to the WinBUGS OpenBUGS or JAGS websites for more material For the most part if you have BUGS code you can try NIMBLE NIMBLE takes BUGS code and does several things with it 1 NIMBLE extracts all the declarations in the BUGS code to create a model definition This includes a directed acyclic graph DAG representing the model and functions that can query model relationships from the graph Usually you ll ignore the model definition and let NIMBLE s default options take you directly to the next step 2 From the model definition NIMBLE builds a working model in R This can be used to manipulate variables and operate the model from R Operating the model includes 20 CHAPTER 3 MORE INTRODUCTION 21 calculating simulating or querying the log probability value of model nodes These basic capabilities along with the tools to query model structure al
97. ion then a RW_block sampler is assigned for all elements This is a Metropolis Hastings adaptive random walk sampler with a multivariate normal proposal 6 5 If none of the above criteria are satisfied then a RW sampler is assigned This is a Metropolis Hastings adaptive random walk sampler with a univariate normal proposal distribution The control parameters governing each of the default sampling algorithms are defined in the NIMBLE system option MCMCcontrolDefaultList These default values are described in Section 7 5 along with the related sampling algorithms Modifying the default sampler assignments configureMCMC accepts control arguments useConjugacy onlyRW onlySlice and multivariateNodesAsScalars to modify default sampler assignments See help configureMCMC for usage details CHAPTER 7 MCMC 69 Default monitors The default MCMC configuration includes monitors on all top level stochastic nodes of the model Automated parameter blocking The default configuration may be replaced by that generated from an automated parameter blocking algorithm This algorithm determines groupings of model nodes that when jointly sampled with a RW_block sampler increase overall MCMC efficiency Overall efficiency is defined as the effective sample size of the slowest mixing node divided by computation time This is done by autoBlockSpec lt configureMCMC Rmodel autoBlock TRUE In this usage the additional control argument auto
98. ion functions for use in calculations namely the p q and d functions See Section 9 5 19 for details on the syntax for using distribution functions as only some parameterizations are allowed and the names of some distributions differ from those used to define nodes in a model Table 5 4 Functions operating on scalars many of which can operate on each element component wise of vectors and matrices Status column indicates if the function is currently provided in NIMBLE Usage Description Comments Status Accepts vector input x y x amp y logical OR and AND amp V Ix logical not V x gt y x gt y greater than and or equal to V xX lt y Xx lt y less than and or equal to V x y x y not equals V x y x y x y component wise operators mix of scalar and vector ok V v x y component wise division vector x and scalar y ok V v x y pow x y power xY vector x and scalar y ok v Vv x hh y modulo remainder V min x1 x2 max x1 x2 min max of two scalars V exp x exponential V v log x natural logarithm V V sqrt x square root V V abs x absolute value V V step x step function at 0 0ifz lt 0 1ifz gt 0 v V equals x y equality of two scalars life y 0ifal y V cube x third power x V v sin x cos x tan x trigonometric functions V V asin x acos x atan x inverse trigonometric functions V v asinh x acosh x atanh x inv hyperbolic trig functions V V logit x log
99. ions and then terminates Halfway through the algorithm the sample size used for the E step switches from m1 to m2 This provides smaller MCMC error as the algorithm converges If m1 or m2 is less than or equal to burnIn as defined in build_MCEM the MCEM algorithm will immediately quit When using the MCEM algorithm we suggest first starting with small values of m1 and m2 to get an estimate of how long the algorithm will take for larger MCMC samples The speed of the algorithm will be linear in m2 assuming that m2 gt m1 as intended Chapter 9 Writing nimbleFunctions 9 1 Writing nimbleFunctions When you write an R function you say what the input arguments are you provide the code for execution and in that code you give the returned value Using the function keyword in R triggers the operation of creating an object that is the function Creating nimbleFunctions is similar but there are two kinds of code and two steps of execution 1 Setup code is provided as a regular R function but the programmer does not control what it returns Typically the inputs to setup code are objects like a model a vector of nodes a modelValues object or modelValuesSpec or another nimbleFunction The setup code as its name implies sets up information for run time code It is executed in R so it can use any aspect of R 2 Run code is provided in the NIMBLE language This is similar to a narrow subset of R but it is important to remember that i
100. it log x 1 x V V ilogit x expit x inverse logit exp x 1 exp x V V probit x probit Gaussian quantile x V v iprobit x phi x inverse probit Gaussian CDF x V V CHAPTER 5 BUILDING MODELS 36 Table 5 4 Functions operating on scalars many of which can operate on each element component wise of vectors and matrices Status column indicates if the function is currently provided in NIMBLE Usage Description Comments Status Accepts vector input cloglog x complementary log log log log 1 x V V icloglog x inverse complementary log log 1 exp exp z V V ceiling x ceiling function x V V floor x floor function x V V round x round to integer V V trunc x truncation to integer V V lgamma x loggam x log gamma function logT lt x V V logip x log of 1 x log 1 x V V lfactorial x logfact x log factorial log q v V logip x log one plus log a 1 V V qDIST x PARAMS q distribution functions canonical parameterization V pDIST x PARAMS p distribution functions canonical parameterization v rDIST 1 PARAMS r distribution functions canonical parameterization V dDIST x PARAMS d distribution functions canonical parameterization V sort x rank x s ranked x s order x Table 5 5 Functions operating on vectors and matrices Status column indicates if the function is currently provided in NIMBLE Usage Description Comme
101. itial values checking model use nimbleModel check FALSE to skip model check model building finished 6 5 1 getNodeNames getVarNames and expandNodeNames First we ll see how to determine the nodes and variables in a model pump getNodeNames CHAPTER 6 USING NIMBLE MODELS FROM R H H H H H H H H H H H H H H H H H pump getNodeNames determOnly H H H H H H 1 3 5 7 9 11 13 15 17 19 21 23 25 27 29 31 33 1 3 5 7 9 id alpha lifted_di_over_beta theta 2 theta 4 theta 6 theta 8 theta 10 lambda 2 lambda 4 lambda 6 lambda 8 lambda 10 ak2 y 4 y 6 x 8 ee Fall lifted_di_over_beta lambda 2 lambda 4 lambda 6 lambda 8 lambda 10 beta theta 1 theta 3 theta 5 theta 7 theta 9 lambda 1 lambda 3 lambda 5 lambda 7 lambda 9 te i Ose SH was waia x 9 TRUE lambda 1 lambda 3 lambda 5 lambdal 7 lambda 9 pump getNodeNames stochOnly TRUE H H H H H 1 6 ay 16 21 Well pha theta 4 thetaLl9 Wy 4 Wy 9 beta theta 5 theta 10 Wy 5 Wy 10 theta 1 theta 6 up yx 6 pump getNodeNames dataOnly TRUE HH T Wy 1 Wy i2 Wy 3 H
102. l model building finished propModel nimbleModel propModelCode check FALSE defining model building model model building finished cTargetModel compileNimble targetModel cPropModel compileNimble propModel sampleMVSpec modelValuesSpec vars c x y propLL types c double double double sizes list x 1 y 4 propLL 1 sampleMV lt modelValues sampleMVSpec mnimbleFunction for generating proposal sample PropSamp_Gen lt nimbleFunction setup function mv propModel nodeNames lt propModel getNodeNames run function m integer resize mv m fon sim tem 4 simulate propMode1 nimCopy from propModel to mv nodes nodeNames row i mv propLL i 1 lt lt calculate propModel CHAPTER 9 WRITING NIMBLEFUNCTIONS 106 Vw nimbleFunction for calculating importance weights Recylcing setupFunction and runFunction as defined in earlier example impWeights_Gen lt nimbleFunction setup setupFunction run runFunction Making instances of nimbleFuncttions Note that both functions share the same modelValues object RPropSamp lt PropSamp_Gen sampleMV propModel RimpWeights lt impWeights_Gen sampleMV targetModel Compiling CPropSamp lt compileNimble RPropSamp project propModel CImpWeights lt compileNimble RImpWeights project targetModel Generating and saving proposal sample of size 10 CPro
103. l lt compileNimble rTimeModel Build the particle filter rPF lt buildPF rTimeModel x cPF compileNimble rPF project rTimeModel Set parameter values cTimeModel mu_0 1 cTimeModel a 5 cTimeModel b cTimeModel c cTimeModel mu_0 1 il rer Oo Run particle filter with 5000 particles cPF run m 5000 1 42 54816 8 3 Monte Carlo Expectation Maximization MCEM Suppose we have a model with missing data or a layer of latent variables that can be treated as missing data and we would like to maximize the marginal likelihood of the model integrating over the missing data A brute force method for doing this is MCEM This is an EM algorithm in which the missing data are simulated via Monte Carlo often MCMC when the full conditional distributions cannot be directly sampled from at each iteration MCEM can be slow and there are other methods for maximizing marginal likelihoods that can be implemented in NIMBLE The reason we started with MCEM is to explore the flexibility of CHAPTER 8 OTHER ALGORITHMS PROVIDED BY NIMBLE 95 NIMBLE and illustrate the combination of R and NIMBLE involved with R managing the highest level processing of the algorithm and calling nimbleFunctions for computations We will revisit the pump example to illustrate the use of NIMBLE s MCEM algorithm defining model building model setting data and initial values checking model use nimbleModel check FA
104. l list argument to set the initial proposal distribution scale and the adaptive properties for the Metropolis Hastings sampling In addition the control list argument must contain a named 11Function ele ment which is specialized nimbleFunction that accepts no arguments and returns a scalar double number The return value must be the total log likelihood of all stochastic dependents of the target nodes and if includesTarget TRUE of the target node s themselves or whatever surrogate is being used for the total log likelihood This is a required control list element with no default See help samplers for details Complete example of correct usage CHAPTER 7 MCMC 78 code lt nimbleCode p dint 1 y dbin p 1 Rmodel lt nimbleModel code data list y 3 inits list p 0 5 n 10 11Fun lt nimbleFunction setup function model run function y lt model y p lt model p n lt model n lil lt Jfactorial n ifactorial y lfactorial n y y log p m y log 1i p returnType double return 11 RllFun lt 11Fun Rmodel mcmcspec lt configureMCMC Rmodel nodes NULL type RW_11Function mcmcspec addSampler target Ss ye RllFun includesTarget FALSE control list 1lFunction Rmcmc lt buildMCMC mcmcspec 7 5 8 Conjugate Gibbs samplers Gibbs samplers can be provided for nodes in conjugate relationships as specified by the system level conju
105. le the declaration logit pli dnorm mu i 1 is equivalent to the follow two declarations e logit_pli dnorm mu i 1 e pli lt expit logit_p i where expit is the inverse of logit When the BUGS expression defines a deterministic node such as logit p lt bO bi x the same operations are performed except that logit_p is a deterministic node Note that we do not provide an automatic way of initializing the additional node logit_p in this case which is a parent node of the explicit node p i without explicitly referring to the additional node by the name that NIMBLE generates For deterministic declarations this is of little import but for stochastic declarations it requires care 5 2 5 Adding user defined distributions and functions As of Version 0 4 NIMBLE allows you to define your own functions and distributions as nimbleFunctions for use in BUGS code As a result NIMBLE frees you from being con strained to the functions and distributions just discussed For example instead of setting up a Dirichlet prior with multinomial data and needing to use MCMC one could recognize that this results in a Dirichlet multinomial distribution and provide that as a user defined distribution instead Further while NIMBLE at the moment does not allow the use of random indices such as is common in clustering contexts you may be able to analytically integrate over the random indices resulting in a mixture distribution that you
106. lihood evaluation at that point This algorithm requires no tuning parameters and therefore no period of adaptation and may result in very efficient sampling from multivariate Gaussian distributions The ess sampler accepts no control list arguments See help samplers for details Example usage Hf tt O CAIA IA A nt es bars by Ala Wo F 17 naine np letanainmanto 1 ann ln atmna hanit H assuming noae 5 NO follows a multivariate normal distribution mcmcspec addSampler target x 1 10 type ess CHAPTER 7 MCMC TT 7 5 6 Hierarchical crossLevel sampler This sampler is constructed to perform simultaneous updates across two levels of stochastic dependence in the model structure This is possible when all stochastic descendents of node s at one level have conjugate relationships with their own stochastic descendents In this situation a Metropolis Hastings algorithm may be used in which a multivariate normal proposal distribution is used for the higher level nodes and the corresponding proposals for the lower level nodes undergo Gibbs conjugate sampling The joint proposal is either accepted or rejected for all nodes involved based upon the Metropolis Hastings ratio The crossLevel sampler can be customized using the control list argument to set the initial proposal covariance and the adaptive properties for the Metropolis Hastings sampling of the higher level nodes See help samplers for details Example usage mcmcspec addSa
107. low one to write programs that use the model and adapt to its structure 3 From the working model NIMBLE generates customized C code representing the model compiles the C loads it back into R and provides an R object that interfaces to it We often call the uncompiled model the R model and the compiled model the C model The C model can be used identically to the R model so code written to use one will work with the other We use the word compile to refer to the entire process of generating C code compiling it and loading it into R More about specifying and manipulating models is in Chapter 5 6 3 2 The NIMBLE language for writing algorithms NIMBLE provides a language embedded within and similar in style to R for writing algo rithms that can operate on BUGS models The algorithms can use NIMBLE s utilities for inspecting the structure of a model such as determining the dependencies between variables And the algorithms can control the model changing values of its variables and controlling execution of its probability calculations or corresponding simulations Finally the algo rithms can use automatically generated data structures to manage sets of model values and probabilities In fact the calculations of the model are themselves constructed as functions in the NIMBLE language as are the algorithms provided in NIMBLE s algorithm library This means that you can extend BUGS with new distributions and new fu
108. lternative parameterizations given in Section 5 2 2 to nimbleFunctions 9 6 Some options for reducing memory usage NIMBLE can make a lot of objects in its processing and some of them use R features like ref erence classes that are not light in memory usage We have noticed that building large models can use lots of memory To help alleviate this we provide two options which can be con trolled via nimbleOptions As noted above the option useMultiInterfaceForNestedNimbleFunctions defaults to TRUE which means NIMBLE will not build full interfaces to compiled nimble Functions that ony appear within other nimbleFunctions If you want access to all such nim bleFunctionsm use useMultilnterfaceForNestedNimbleFunctions FALSE The option clearNimbleFunctionsAfterCompiling is more drastic and it is experimental so buyer beware This will clear much of the contents of an uncompiled nimbleFunction object after it has been compiled in an effort to free some memory We expect to be able to keep making NIMBLE more efficient faster execution and lower memory use in the future Bibliography 1 Andrieu C A Doucet and R Holenstein 2010 Particle Markov chain Monte Carlo methods Journal of the Royal Statistical Society Series B Statistical Methodology 72 3 269 342 N George E I U E Makov and A F M Smith 1993 Conjugate likelihood distribu tions Scandinavian Journal of Statistics 20 2 147 156 w Lunn
109. ments for writing a nimbleFunction that can be used as a sampler are also described below and new samplers can be labeled with a name argument which is used in output of getSamplers When a control argument is provided in a call to addSampler the control list elements specified will have the highest priority The hierarchy of precedence for control list elements for samplers is 1 Those supplied in the control list argument to addSampler 2 Those supplied in the control list argument in the preceding preceding call to conf igureMCMC 3 Those supplied in the NIMBLE system option MCMCcontrolDefaultList A call to addSampler results in a single instance of the specified sampler which will be specialized to the specified target model node or nodes being added at end of the current sampler ordering Printing re ordering and removing samplers The current ordered list of all samplers in the MCMC configuration may be printed by calling the getSamplers method When you want to see only samplers acting on specific model nodes or variables provide those names as an argument to getSamplers The existing samplers may be re ordered using the setSamplers method The ind argu ment is a vector of sampler indices or a character vector of model node or variable names The samplers in the MCMC configuration will be replaced by the samplers corresponding to the indices provided or those samplers acting on the target nodes specified Here are a few CHAP
110. meric type of the elements In v0 4 1 objects from 0 scalar to 4 dimensions are supported and the numeric types integer and double are supported In addition the type logical is supported for scalars only While the number of dimensions cannot change during run time numeric objects can be resized using setSize or by full non indexed assignment 8C is a statically typed language which means the type of a variable cannot change CHAPTER 9 WRITING NIMBLEFUNCTIONS 109 When possible NIMBLE will determine the type of a variable for you In other cases you must declare the type The rules are as follows e For numeric variables from the setup function that appear in the run function or other member functions or are declared in setupOutputs the type is determined from the values created by the setup code The types created by setup code must be consistent across all specializations of the nimbleFunction For example if X is created as a matrix 2 dimensional double in one specialization but as a vector 1 dimensional double in another there will be a problem during compilation The sizes may differ in each specialization Treatment of vectors of length 1 presents special challenges because they could be treated as scalars or vectors Currently they are treated as scalars If you want a vector ensure that the length is greater than 1 in the setup code and then use setSize in the run time code e In run code when a numeric variable i
111. mpModelValues modelValues pumpModel m 2 pumpModel x fe 1 5 2 514 399 1 1 4 22 pumpModelValues x 1 1 NA NA NA NA NA NA NA NA NA NA HH 2 1 NA NA NA NA NA NA NA NA NA NA In this example pumpModelValues has the same variables as pumpModel and we set pumpModelValues to have m 2 rows As you can see the rows are stored as elements of a list Alternatively one can define a modelValues object manually via the modelValuesSpec function like this CHAPTER 6 USING NIMBLE MODELS FROM R 62 mvSpec modelValuesSpec vars c a b c type e idoubille intl doublenn size list Grate 2 D Gi Go a eG eel customMV modelValues mvSpec m 2 customMV a 1 1 NA NA HH 2 1 NA NA The arguments to modelValuesSpec are matching lists of variable names types and sizes See helpGnodelValuesSpec for more details Note that in R execution the types are not enforced But they will be the types created in C code during compilation so they should be specified carefully The object returned by modelValues is an uncompiled modelValues When a nimble Function is compiled any modelValues objects it uses are also compiled A NIMBLE model always contains a modelValues that it uses as a default location to store its variables Here is an example where the customMV created above is used as the setup argument for a nimbleFunction which is then compiled Its compiled m
112. mpilation of the NIMBLE generated Code 5 Building models 5 1 Overview of supported features and extensions of BUGS and JAGS 5 1 1 Supported features of BUGS and JAGS 0 4 DD or on NN CONTENTS 5 2 5 3 5 1 2 NIMBLE s Extensions to BUGS and JAGS 5 1 3 Not yet supported features of BUGS and JAGS Wining models oe eo he bee oe be SR Se ee SE EE eS ee 5 2 1 Declaring stochastic and deterministic nodes 5 2 2 Available distributions and functions 0 4 5 2 3 Available BUGS language functions 5 24 Available link famctions 2 6 464548 ee eee ee es 5 2 5 Adding user defined distributions and functions 526 Dateaemd constants s s a ascoc ao daaa dopa doa EOE r Goant 5 2 7 Defining alternative models with the same code 5 2 8 Truncation censoring and constraints o ses so croca st 52 9 Understanding lifted nodes gt lt cs ssar 2284 aa draad Creating model objects lt o cercuri rsrs nisie ci ER HEE ES 5 3 1 Using nimbleModel to specify a model 5 3 2 Specifying a model from standard BUGS and JAGS input files ga Providing data via setae ss sos a s s res p so n dah OR oe eww SG 5 3 4 Making multiple instances from the same model definition 6 Using NIMBLE models from R 6 1 Some basic concepts and terminology a aooaa e a 0004 6 2 Accessing variables ooa
113. mpler target c a b c type crossLevel The requirement that all stochastic descendents of the target nodes must themselves have only conjugate descendents will be checked when the MCMC algorithm is built This sampler is useful when there is strong dependence across the levels of a model that causes problems with convergence or mixing 7 5 7 Customized log likelihood evaluations using the RW_11Function sampler Sometimes it is useful to control the log likelihood calculations used for an MCMC updater instead of simply using the model For example one could use a sampler with a log like lihood that analytically or numerically integrates over latent model nodes Or one could use a sampler with a log likelihood that comes from a stochastic approximation such as a particle filter see below allowing composition of a particle MCMC PMCMC algorithm 1 The RW_11Function sampler handles this by using a Metropolis Hastings algorithm with a normal proposal distribution and a user provided log likelihood function To allow compiled execution the log likelihood function must be provided as a specialized instance of a nimbleFunction The log likelihood function may use the same model as the MCMC as a setup argument as does the example below but if so the state of the model should be unchanged during execution of the function or you must understand the implications otherwise The RW_11Function sampler can be customized using the contro
114. n and censoring as in JAGS using the T notation and dinterval 5 1 2 NIMBLE s Extensions to BUGS and JAGS NIMBLE extends the BUGS language in the following ways 1 User defined functions and distributions written as nimbleFunctions can be used in model code See Section 5 2 5 Multiple parameterizations for distributions similar to those in R can be used Named parameters for distributions and functions similar to R function calls can be used NIMBLE calls non stochastic nodes deterministic whereas BUGS calls them logical NIMBLE uses logical in the way R does to refer to boolean TRUE FALSE variables 27 CHAPTER 5 BUILDING MODELS 28 5 1 Link functions can be used in stochastic as well as deterministic declarations Data values can be reset and which parts of a model are flagged as data can be Distribution parameters can be expressions as in JAGS but not in WinBUGS Caveat parameters to multivariate distributions e g dmnorm cannot be expressions Alternative models can be defined from the same model code by using if then else statements that are evaluated when the model is defined More flexible indexing of vector nodes within larger variables is allowed For example one can place a multivariate normal vector arbitrarily within a higher dimensional object not just in the last index More general constraints can be declared using dconstraint which
115. n be used in NIMBLE The special function copy is used here to record values from the model into the modelValues object Multiple instances or specializations can be made by calling simNodesMany with dif ferent arguments Above simNodesTheta1to5 has been made by calling simNodesMany with the pump model and nodes theta 1 5 as inputs to the setup function while simNodesTheta6to10 differs by providing theta 6 10 as an argument The re turned objects are objects of a uniquely generated R reference class with fields member data for the results of the setup code and a run method member function Arbi trary other methods can be provided with a methods argument following the syntax of R s setRefClass function By the way simNodesMany is very similar to a standard nimbleFunction provided with nimble simNodesMV Now let s execute this nimbleFunction in R before compiling it set seed 0 make the calculation repeatable pump alpha lt pumpMLE 1 pump beta lt pumpMLE 2 make sure to update deterministic dependencies of the altered nodes calculate pump pump getDependencies c alpha beta determOnly TRUE 1 0 saveTheta lt pump theta simNodesThetalto5 run 10 simNodesThetaltoS mv theta 1 2 CHAPTER 2 LIGHTNING INTRODUCTION 18 1 1 1 43717729 1 53093576 1 45028779 0 03716752 0 13310071 6 1 15835525 0 99001994 0 30737332 0 09461909 0 15720154 HH
116. nctions written in NIMBLE Like the models themselves functions in the NIMBLE language are turned into C which is compiled loaded and interfaced to R Programming in NIMBLE involves a fundamental distinction between 1 the steps for an algorithm that need to happen only once at the beginning such as inspecting the model and 2 the steps that need to happen each time a function is called such as MCMC iterations When one writes a nimbleFunction each of these parts can be provided separately The former if needed are given in a setup function and they are executed directly in R allowing any feature of R to be used The latter are in one or more run time functions and they are turned into C Run time code is written in the NIMBLE language which you can think of as a carefully controlled small subset of R along with some special functions for handling models and NIMBLE s data structures What NIMBLE does with a nimbleFunction is similar to what it does with a BUGS model 1 NIMBLE creates a working R version of the nimbleFunction which you can use with an R model or a C model 2 NIMBLE generates C code for the run time function s compiles it and loads it back into R with an interface nearly identical to the R version of the nimbleFunction As with models we refer to the uncompiled and compiled versions as R nimbleFunctions CHAPTER 3 MORE INTRODUCTION 22 and C nimbleFunctions respectively In v0 4 1 the behavior
117. nd may be deprecated in the future The recommended newer way is P lt values model nodes values model nodes lt P where the first line would assign the collection of values from nodes into P and the second would to the inverse In both cases values from nodes with 2 or more dimensions are flattened into a vector in column wise order The older syntax which may be deprecated in the future is getValues P model nodes setValues P model nodes These are equivalent to the two previous lines Note that getValues modifies P in the calling environment With the new notation values model nodes may appear as a vector in other expres sions e g Y lt A values model nodes b 9 5 7 Basic flow control if then else for and while These basic control flow structures use the same syntax as in R However for loops are limited to sequential integer indexing For example for i in 2 5 works as it does in R Decreasing index sequences are not allowed We plan to include more flexible for loops in the future but for now we ve included just one additional useful feature for i in seq_along NFL will work as in R where NFL is a nimbleFunctionList This is described below 9 5 8 How numeric types work Numeric types in NIMBLE are much less flexible than in R a reflection of the fact that NIMBLE code can be compiled into C In NIMBLE the type of a numeric object refers to the number of dimensions and the nu
118. nding to your version of R We strongly recommend using the most recent version of R currently 3 2 1 and hence Rtools33 exe This installer leads you through several pages We think you can accept the defaults with one exception check the PATH checkbox page 5 so that the installer will add the location of the C compiler and related tools to your system s PATH ensuring that R can find them After you click Next you will get a page with a window for customizing the new PATH variable You shouldn t need to do anything there so you can simply click Next again We note that it is essential the checkbox for the R 2 15 toolchain page 4 be enabled in order to have gcc g make etc installed This should be checked by default Advanced users may wish to change their default compilers This can be done by editing the Makevars file see Writing R Externsions 1 2 1 4 4 Customizing Compilation of the NIMBLE generated Code For each model or nimbleFunction the NIMBLE package generates and compiles C code This uses classes and routines available through the NIMBLE run time library and also CHAPTER 4 INSTALLING NIMBLE 26 the Eigen library The compilation mechanism uses R s SHLIB functionality and therefore uses the regular R configuration in R_HOME etc R_ARCH Makeconf NIMBLE places a Makevars file in the directory in which the code is generated and R CMD SHLIB uses this file In all but specialized c
119. ng vl to a 1 column matrix unless it is known at compile time that M1 has 1 column in which case v1 is promoted to a 1 row matrix e vi v2 promotes vl to a l row matrix and v2 to a 1 column matrix so the returned values is a 1x1 matrix with the inner product of vl and v2 e asRow v1 explicitly promotes v1 to a l row matrix Therefore v1 asRow v2 gives the outer product of v1 and v2 e asCol v1 explicitly promotes v1 to a 1 column matrix e The default promotion for a vector is to a 1 column matrix Therefore vl t v2 is equivalent to vi asRow v2 e When indexing dimensions with scalar indices will be dropped For example M1 1 and Mi 1 are both vectors e The left hand side of an assignment can use indexing but if so it must already be correctly sized for the result For example Y 5 10 20 30 lt model x will not work and could crash your R session with a segmentation fault if Y is not already at least 10x30 in size Here are some examples to illustrate the above points assuming M2 is a square matrix e Y lt vi M2 v2 will return a 1 column matrix If Y is created by this statement it will be a 2 dimensional variable If Y already exists it must already be 2 dimesional and it will be automatically re sized for the result e Y lt vi M2 v2 1 will return a vector Y will either be created as a vector or must already exist as a vector and will be re sized for the result CHAPTER
120. nitial state the initial values of any sampler control parameters e g scale sliceWidth or propCov are reset to their initial values as were specified by the original MCMC configuration CHAPTER 7 MCMC 74 e The internal modelValues objects mvSamples and mvSamples2 are each resized to the appropriate length for holding the requested number of samples niter thin and niter thin2 respectively When mcmc run niter reset FALSE is called the MCMC algorithm picks up from where it left off No values in the model are checked or altered and sampler functions are not reset to their initial states Further the internal model Values objects containing samples are each increased in size to appropriately accommodate the additional samples Further arguments and details can be found by help buildMCMC 7 4 Extracting MCMC samples After executing the MCMC the output samples can be extracted as follows as mvSamples lt mcmc mvSamples mvSamples2 lt mcmc mvSamples2 These model Values objects can be converted into matrices using as matrix samplesMatrix lt as matrix mvSamples samplesMatrix2 lt as matrix mvSamples2 The column names of the matrices will be the node names of nodes in the monitored variables Then for example the mean of the samples for node x 2 could be calculated as mean samplesMatrix x 2 7 5 Sampler Algorithms provided with NIMBLE We now describe the samplers provided with NIMBLE The MC
121. nts Status inverse x matrix inverse x symmetric positive definite V chol x matrix Cholesky factorization x symmetric positive definite V eigen x matrix eigendecomposition svd x matrix singular value decomposition t x matrix transpose x V xL hy matrix multiply zy x y conformant V inprod x y dot product x y x and y vectors V logdet x log matrix determinant log z V asRow x convert vector x to l row matrix sometimes automatic V asCol x convert vector x to 1 column matrix sometimes automatic V sum x sum of elements of x V mean x mean of elements of x V sd x standard deviation of elements of x V prod x product of elements of x V min x max x min max of elements of x V pmin x y pmax x y vector of mins maxs of elements of x and y V interp lin x v1 v2 linear interpolation CHAPTER 5 BUILDING MODELS 37 5 2 4 Available link functions NIMBLE allows the link functions listed in Table 5 6 Table 5 6 Link functions Link function Description Range Inverse cloglog y lt x Complementary log log 0 lt y lt 1 y lt icloglog x log y lt x Log O lt y y lt exp x logit y lt x Logit O lt y lt l1i y lt expit x probit y lt x Probit O lt y lt 1 y lt iprobit x Link functions are specified as functions applied to a variable on the left hand side of a BUGS expression To handle link functions NIMBLE does some processing that in serts an additional node into the model For examp
122. o set values for lifted nodes created by NIMBLE CHAPTER 5 BUILDING MODELS 29 3 For loop and nested indexing for i ain Leh fong ani MEDE zli j dexp r blockID i i 4 multzivariate distribution with arbitrary indexing forG an 1 3 mvx 8 10 i dmnorm mvMean 3 5 cov mvCov 1 3 1 3 il 5 User provided distribution w dMyDistribution hello x world y 6 Semple deterministic node Gil lt gt a r lo T Vector deterministic node with matrix multiplication da2 lt AL mvMean 1 5 8 Deterministic node with user provided function d3 lt foo x hooray y This code does not show a complete model and includes some arbitrary indices e g mvx 8 10 i to illustrate flexibility When a variable appears only on the right hand side it must be provided in data or constants Notes on the comment numbered lines are 1 2 COND Ot x follows a normal distribution with mean a b c and precision tau default BUGS second parameter for dnorm y follows a normal distribution with the same mean as x but a named standard devi ation parameter instead of a precision parameter sd 1 sqrt precision z i j follows an exponential distribution with parameter r blockID i This shows how for loops can be used for indexing of variables containing multiple nodes Nested indexing can be used if the nested indices blockID are provided as constants when the model is defined via n
123. or alternative parameters e g rate 1 scale 9 5 2 Declaring argument types and the return type NIMBLE requires that types of arguments and a return type be explicitly declared The syntax for a type declaration is e type nDim sizes type can currently take values double integer character for scalars or vectors only or logical for scalars only In a returnType statement a type of void is valid but you don t need to include that because it is the default if no returnType statement is included nDim is the number of dimensions with 0 indicating scalar sizes is an optional vector of fixed known sizes These should use R s c function if nDim gt 1 e g double 2 c 4 5 declareds a 4 x 5 matrix If sizes are omitted they will either be set when the entire object is assigned to or an explicit call to setSize is needed 9 5 3 Driving models calculate calculateDiff simulate and getLogProb These four functions are the primary ways to operate a model Their syntax was explained in Section 6 4 Except for getLogProb it is usually important for the nodes object to be created in setup code such that they are sorted in topological order 9 5 4 Accessing model and modelValues variables and using copy The modelValues structure was introduced in Section 6 6 Inside nimbleFunctions mod elValues are designed to easily save values from a model object during the running of a nimbleFunction A modelValues object used in run
124. orithm to be applied to many data sets in the same model without re creating the model each time It also allows simulation of data in a model We encourage users to distinguish between data and constants when building a model via nimbleModel However for compatibility with BUGS and JAGS NIMBLE allows both to be provided in the the constants argument to nimbleModel in which case NIMBLE determines which are which based on which variables appear on the left hand side of BUGS declarations It is also possible to have variables appear only on the right hand side of BUGS declara tions e g covariates predictors If the values of these variables will never change one can specify these via constants However one might want to define a model and then change such values e g use a model with different covariate values Therefore one can provide the values of such variables via the data argument to nimbleModel and these will appear as variables in the model but will not have any corresponding nodes A user can change these values via direct assignment if desired Missing data values Sometimes one needs a model variable to have a mix of data and non data often due to missing data values In NIMBLE when data values are provided any nodes with NA values NIMBLE can t use R s standard scoping because it doesn t work for R reference classes and nimbleFunctions are implemented as custom generated reference classes CHAPTER 5 BUILDIN
125. pSamp run 10 NULL Calculating the importance weights and saving to mu CImpWeights run NULL Retrieving the modelValues objects Extracted objects are C based modelValues objects savedPropSamp_1 CImpWeights propModelValues savedPropSamp_2 CPropSamp mv Subtle note savedPropSamp_1 and savedPropSamp_2 both provide interface to the same compiled modelValues objects This is because they were both built from sampleMV savedPropSamp_1 x 1 1 0 09301016 savedPropSamp_2 x 1 1 0 09301016 CHAPTER 9 WRITING NIMBLEFUNCTIONS 107 savedPropSamp_1 x 1 lt O example of directly setting a value savedPropSamp_2 x 1 1 0 Viewing the saved importance weights savedWeights lt CImpWeights savedWeights unlist savedWeights w 1 0 2605783 0 3356819 0 3495975 0 5885002 3 1004167 0 7498434 7 0 1952209 0 4391091 0 5302746 0 8136953 Viewing first 3 rows Note that savedPropSsamp_1 x 1 was altered as matrix savedPropSamp_1 1 3 HH propLL 1 x y 1 y 2 y 3 1 3 637857 0 0000000 0 621395144 0 2282318 0 30055870 2 4 144378 0 1578032 0 050844789 0 2108267 0 84501521 3 4 225615 0 6333329 0 001691592 0 0151157 0 09695661 HH y 4 1 0 4886966 2 0 7046754 3 0 9762416 Importance sampling could also be written using simple vectors for the weights but we illustrated putting them in a modelValues object along
126. piled before or at the same time as any compilation of algorithms such as the compilation of the MCMC done in the next section 2 4 Creating compiling and running a basic MCMC specification At this point we have initial values for all of the nodes in the model and we have both the original and compiled versions of the model As a first algorithm to try on our model let s use NIMBLE s default MCMC Note that conjugate relationships are detected for all nodes except for alpha on which the default sampler is a random walk Metropolis sampler pumpSpec lt configureMCMC pump print TRUE 1 RW sampler alpha adaptive TRUE adaptInterval 200 scale 1 2 conjugate_dgamma sampler beta dependents_dgamma theta 1 theta 2 theta 3 3 conjugate_dgamma sampler theta 1 dependents_dpois x 1 4 conjugate_dgamma sampler theta 2 dependents_dpois x 2 5 conjugate_dgamma sampler theta 3 dependents_dpois x 3 6 conjugate_dgamma sampler theta 4 dependents_dpois x 4 7 conjugate_dgamma sampler theta 5 dependents_dpois x 5 8 conjugate_dgamma sampler theta 6 dependents_dpois x 6 CHAPTER 2 LIGHTNING INTRODUCTION 13 9 conjugate_dgamma sampler theta 7 dependents_dpois x 7 10 conjugate_dgamma sampler theta 8 dependents_dpois x 8 11 conjugate_dgamma sampler theta 9 dependents_dpois x 9 12 conjugate_dgamma sampler theta 10 dependents_dpois x
127. res solution for regression of 100 data points on 4 explanatory variables all generated randomly Such functions can be called from other nimbleFunctions or used in BUGS code If one wants a nimbleFunction that does get specialized but has empty setup code use setup function or setup TRUE 9 4 Useful tools for setup functions The setup function is typically used to determine information on nodes in a model set up any modelValues objects set up any nimbleFunctions or nimbleFunctionLists and set up any persistent numeric objects For example the setup code of an MCMC nimbleFunction creates the nimbleFunctionList of sampler nimbleFunctions The values of numeric objects created in setup can be modified by run code and will persist across calls Some of the useful tools and objects to create in setup functions include vectors of node names Often these are obtained from the getNodeNames and getDependencies methods of a model described in Section 6 5 1 modelValues objects These are discussed more below specializations of other nimbleFunctions A useful NIMBLE programming technique is to have one nimbleFunction contain other nimbleFunctions which it can use in its run time code lists of other nimbleFunctions In addition to containing single other nimbleFunctions a nimbleFunction can contain a list of other nimbleFunctions These are discussed more below Of course in general explicitly calculating the inverse is not
128. rk for lower tail 1 i e TRUE and log p 0 ie FALSE as these are the inputs we use when working CHAPTER 5 BUILDING MODELS 42 with truncated distributions It is your choice whether you implement the necessary calculations for other combinations of these inputs but again we recommend doing so for completeness e Define the nimbleFunctions in R s global environment Don t expect R s standard scoping to work Further details on using registerDistributions can be found via help registerDistributions NIMBLE uses the same list format as registerDistributions to define its distributions This list can be found in the R distributions_inputList R file in the package source code directory 5 2 6 Data and constants NIMBLE makes a distinction between data and constants that would both be considered data in BUGS and JAGS e Constants can never be changed and must be provided when a model is defined For example a vector of known index values such as for block indices helps define the model graph itself and must be provided as constants Variables used in the index ranges of for loops must also be provided as constants e Data is a label for the role a node plays in the model Nodes marked as data will by default be protected from any functions that would simulate over their values see simulate in Chapter 9 but it is possible to over ride that default or to change their values by direct assignment This allows an alg
129. s created by assignment its type is determined by that assignment Subsequent uses of that variable must be consistent with that type e If the first uses of a variable involves indexing the type must be declared explicitly using declare before using it In addition its size must be set before assigning into it Sizes can be included in the declare statement but if so they should not subsequently change If a variable may have its size changed during execution then the declare statement should omit the size argument and a separate call to setSize should be used to set the initial size s 9 5 9 Querying and changing sizes Sizes can be queried as follows e length behaves like R s length function It returns the entire length of X That means if X is multivariate length returns the product of the sizes in each dimension e dim which has synonym nimDim behaves like R s dim function for matrices or arrays and like R s length function for vectors In other words regardless of whether the number of dimensions is 1 or more it returns a vector of the sizes Using dim vs nimDim is a personal choice but if you use dim you should keep in mind that it behaves differently from R s dim A quirky limitation in v0 4 1 It not currently possible to assign the results from nimDim to another object using vector assignment So the only practical way to use nimDim is to extract elements immediately such as nimDim X 1 nimDim X 2
130. s should work 4 2 Installation Since NIMBLE is an R package you can install it in the usual way via install packages or related mechanisms We have not yet put in on CRAN so you ll have to find it at R nimble org For most installations you can ignore low level details However there are some options that some users may want to utilize 4 2 1 Using your own copy of Eigen NIMBLE uses the Eigen C template library for linear algebra Version 3 2 1 of Eigen is included in the NIMBLE package and that version will be used unless the package s 23 CHAPTER 4 INSTALLING NIMBLE 24 configuration script finds another version on the machine This works well and the following is only relevant if you want to use a different e g newer version The configuration script looks in the standard include directories e g usr include and usr local include for the header file Eigen Dense You can specify a particular location in either of two ways 1 Set the environment variable EIGEN_DIR before installing the R package e g export EIGEN _DIR usr include eigen3 in the bash shell 2 UseR CMD INSTALL configure args with eigen path to eigen nimble_VERSION tar or install packages nimble configure args with eigen path to eigen In these cases the directory should be the full path to the directory that contains the Eigen directory e g usr include eigen3 It is not the full path to the Eigen directory itself i e N
131. s that will be optimized specified via the boxConstraints argument This is highly recommended for nodes that have zero density on parts of the real linet Each constraint given should be a list in which the first element is the names of the nodes or variables that the constraint will be applied to and the second element is a vector of length 2 in which the first value is the lower limit and the second is the upper limit Values of Inf and Inf are allowed If a node is not listed it will be assumed that there are no constraints These arguments are passed as lower and upper to R s optim function using method L BFGS B Currently NIMBLE does not determine this automatically CHAPTER 8 OTHER ALGORITHMS PROVIDED BY NIMBLE 96 The value of the buffer argument shrinks the boxConstraints by this amount This can help protect against non finite values occuring when a parameter is on its boundary value Once the MCEM has been built for the model of interest using buildMCEM it can be run as follows pumpMCEM maxit 20 mi 250 m2 500 H alpha beta 0 817552 1 256396 pumpMCEM maxit 50 m1 1000 m2 5000 Ht alpha beta 0 8236072 1 2673791 There are three run time arguments The maxit argument is the number of total iterations to run the algorithm More ad vanced MCEM algorithms have a stopping criteria based on computing the MCMC error Our current draft implementation of the algorithm merely runs maxit iterat
132. sDemol run 1 10 CHAPTER 9 WRITING NIMBLEFUNCTIONS 113 2 sharedValues sharedValues 15 30 45 60 75 1 30 Il N Il w Note that the output from the print calls in the compiled function match those from the uncompiled function when run in an R session It may not be shown here because this document is created with knitr and for some reason output printed from C does not make it into knitr output 9 5 13 Virtual nimbleFunctions and nimbleFunctionLists Often it is useful for one nimbleFunction to have a list of other nimbleFunctions that have methods with the same arguments and return types For example NIMBLE s MCMC con tains a list of samplers that are each nimbleFunctions To make such a list NIMBLE provides a way to declare the arguments and return types of methods virtual nimbleFunctions created by nimbleFunctionVirtual Other nimbleFunctions can inherit from virtual nimbleFunctions which in R is called containing them Readers familiar with object oriented programming will recognize this as a simple class inheritance system In v0 4 1 it is limited to simple single level inheritance Here is how it works baseClass lt nimbleFunctionVirtual run function x double 1 returnType double methods list foo function returnType double derivedi lt nimbleFunction contains baseClass setup function run function x double 1
133. sampler See help samplers for details Example usage mcmcspec addSampler target c a b c type RW_block 7 5 4 slice sampler The slice sampler performs slice sampling of the scalar node to which it is applied 5 This sampler can operate on either continuous valued or discrete valued scalar nodes The slice sampler performs a stepping out procedure in which the slice is iteratively expanded to the left or right by an amount sliceWidth This sampler is optionally adaptive whereby the value of sliceWidth is adapted towards the observed absolute difference between successive samples The slice sampler can be customized using the control list argument to set the initial slice width and the adaptive properties of the sampler See help samplers for details Example usage mcmcspec addSampler target y 1 type slice control list adaptive FALSE sliceWidth 3 mcmcspec addSampler target y 2 type slice control list adaptive TRUE sliceMaxSteps 1 7 5 5 Elliptical slice sampling ess sampler The ess sampler performs elliptical slice sampling of a single node which must follow a multivariate normal distribution 4 The algorithm is an extension of slice sampling 5 generalized to the multivariate normal context An auxilliary variable is used to identify points on an ellipse which passes through the current node value as candidate samples which are accepted contingent upon a like
134. spec addMonitors c alpha beta mcmcspec addMonitors2 x Similarly either thinning interval may be set at either step Using an argument to confrigureMCMC mcmcspec lt configureMCMC Rmodel thin 1 thin2 100 Calling a member method of the mcmcspec object This results in the same thinning intervals as above mcmcspec setThin 1 mcmcspec setThin2 100 The current lists of monitors and thinning intervals may be displayed using the getMonitors method Both sets of monitors monitors and monitors2 may be reset to empty character vectors by calling the resetMonitors method 7 2 Building and compiling the MCMC algorithm Once the MCMC configuration object has been created and customized to one s liking it may be used to build an MCMC function CHAPTER 7 MCMC 73 Rmcmc lt buildMCMC mcmcspec buildMCMC is a nimbleFunction The returned object Rmcmc is an instance of the NIM BLE function specific to configuration mcmcspec When no customization is needed one can skip configureMCMC and simply provide a model object to buildMCMC The following two MCMC functions will be identical mcmcspec lt configureMCMC Rmodel default MCMC configuration Rmcmci lt buildMCMC mcmcspec Rmcmc2 lt buildMCMC Rmodel uses the default configuration for Rmodel For speed of execution we usually desire to compile the MCMC function to C as is the case for other NIMBLE functions To do so we use compileN
135. t is different defined by what can be compiled and much more limited Run code can use the objects created by the setup code In addition some information on variable types must be provided for input arguments the return object and in some circumstances for local variables There are two kinds of run code a There is always a primary function given as an argument called run b There can optionally be other functions or methods in the language of object oriented programming that share the same objects created by the setup function Here is a small example to fix ideas logProbCalcPlus lt nimbleFunction setup function model node dependentNodes lt model getDependencies node valueToAdd lt 1 normally the value of the last evaluated code or the argument to return This can be omitted if you don t need it 97 CHAPTER 9 WRITING NIMBLEFUNCTIONS 98 run function P double 0 model node lt lt P valueToAdd return calculate model dependentNodes returnType double 0 J code lt nimbleCode a dnorm O 1 b dnorm a 1 testModel lt nimbleModel code check FALSE defining model building model model building finished logProbCalcPlusA lt logProbCalcPlus testModel a testModel b lt 1 5 logProbCalcPlusA run 0 25 1 2 650377 dnorm 1 25 0 1 TRUE dnorm 1 5 1 25 1 TRUE direct validation 1 2 650377
136. ta variables can be replaced and the indication of which nodes should be treated as data can be reset by using the resetData method e g pump resetData 5 3 4 Making multiple instances from the same model definition Sometimes it is useful to have more than one copy of the same model For example nimbleFunctions are often bound to a particular model as a result of setup code A user could build multiple algorithms to use the same model instance or they may want each algorithm to have its own instance of the model There are two ways to create new instances of a model shown in this example simpleCode lt nimbleCode fon min al giN Se ial Chayonenn al simpleModelDefinition lt nimbleModel simpleCode constants list N 10 returnDef TRUE check FALSE defining model one instance of the model CHAPTER 5 BUILDING MODELS 50 simpleModelCopy1 lt simpleModelDefinition newModel check FALSE Make another instance from the same definition simpleModelCopy2 lt simpleModelDefinition newModel check FALSE Ask simpleModelCopy2 for another copy of itself simpleModelCopy3 lt simpleModelCopy2 newModel check FALSE Each copy of the model can have different nodes flagged as data and different values in any nodes They cannot have different values of N because that is a constant it must be a constant because it helps define the model Chapter 6 Using NIMBLE models from R 6 1 Some
137. ted acyclic graph Also note that specifying prior ordering using T can result in possibly unexpected results For example alphal dnorm 0 1 alpha2 dnorm 0 1 T alphal alpha3 dnorm 0 1 T alpha2 will enforce alpha1 lt alpha2 lt alpha3 but it does not treat the three parameters sym metrically Instead it puts a marginal prior on alpha1 that is standard normal and then constrains alpha2 and alpha3 to follow truncated normal distributions This is not equiva lent to a symmetric prior on the three alphas that assigns 0 probability density when values are not in order NIMBLE does not support the JAGS sort syntax 5 2 9 Understanding lifted nodes In some cases NIMBLE introduces new nodes into the model that were not specified in the BUGS code for the model such as the lifted_d1_over_beta node in the introductory example For this reason it is important that programs written to adapt to different model structures use NIMBLE s systems for querying the model graph For example a call to pump getDependencies beta will correctly include 1ifted_d1_over_beta in the results If one skips this step and assumes the nodes are only those that appear in the BUGS code one may not get correct results It can be helpful to know the situations in which lifted nodes are generated These include e When distribution parameters are expressions NIMBLE creates a new deterministic node that contains the expression for a given param
138. ter processed to determine all named elements extracted from the control list these will become the required elements for any control list argument to this sampler unless they also exist in the NIMBLE system option MCMCcontrolDefaultList the random walk proposal standard deviation scale lt control scale determine the list of all dependent nodes up to the first layer of stochastic nodes generally called calcNodes The values inputs and logProbs of these nodes will be retrieved and or altered CHAPTER 7 MCMC 88 by this algorithm calcNodes lt model getDependencies target the run function must accept no arguments execute the sampling algorithm leave the modelValues object muSaved as an exact copy of the updated values in model and have no return value initially muSaved contains an exact copy of the values and logProbs in the model run function extract the initial model logProb model_lp_initial lt getLogProb model calcNodes generate a proposal value for target node proposal lt rnorm 1 model target scale store this proposed value into the target node notice the double assignment operator lt lt necessary because model is a persistent member data object of this sampler model target lt lt proposal calculate target_logProb propagate the proposed value through any deterministic dependents
139. the log probabilities from each node while calculateDiff returns the sum of the new values minus the old values The other way is to directly access the corresponding function for each node in a model Normally you ll use the first way but we ll show you both 6 4 1 For arbitrary collections of nodes model y 1 0 9101742 5 0000000 1 7672873 0 7167075 0 3841854 simulate model y 1 3 model y CHAPTER 6 USING NIMBLE MODELS FROM R 56 1 10 3195078 2 9896248 3 5401512 0 7167075 0 3841854 simulate model y model y 1 9 529274 3 393389 4 344205 3 757832 3 988094 model z HH mag ee BS 1 0 2670988 1 5868335 0 47340064 2 0 5425200 0 5584864 0 62036668 3 1 2078678 1 2765922 0 04211587 4 1 1604026 0 5732654 0 91092165 5 0 7002136 1 2246126 0 15802877 simulate modeikme Cy MeS aZe model y 1 4 117366 6 562761 4 439232 3 757832 3 988094 model z HH fea P2 LS 1 0 2670988 1 5868335 0 47340064 2 0 5425200 0 5584864 0 62036668 3 1 2078678 1 2765922 0 04211587 4 1 1604026 0 5732654 0 91092165 5 0 7002136 1 2246126 0 15802877 simulate model c z 1 5 1 3 includeData TRUE model z HH 1 2 E3 1 4 066770 4 251670 4 095908 2 6 544805 6 552742 6 634027 3 4 431875 4 435468 4 371066 4 3 725405 3 763848 3 698943 5 4 041243 3 836254 4 018749 Notice the following 1 Inputs like y 1 3 are
140. the recommended numerical recipe for least squares 6On the machine this is being written on the compiled version runs a few times faster than the uncompiled version However we refrain from formal speed tests CHAPTER 9 WRITING NIMBLEFUNCTIONS 102 9 4 1 Control of setup outputs Sometimes setup code may create variables that are not used in run time code By default NIMBLE inspects run time code and omits variables from setup that do not appear in run time code from compilation However sometimes a programmer may want to force a numeric or character variable to be created in compilation even if it is not used directly in run time code As shown below such variables can be directly accessed in one nimbleFunction from another which provides a way of using nimbleFunctions as general data structures To force NIMBLE to include variables around during compilation for example X and Y simply include setupOutputs X Y anywhere in the setup code 9 5 NIMBLE language components 9 5 1 Basics There are several general points that will be useful before describing the NIMBLE language in more detail e NIMBLE language functions are not R functions In many cases we have used syntax identical or nearly so to R and in most cases we have provided a matching R function but it is important not to confuse the NIMBLE language definition with the behavior of the corresponding R function e As in R function calls in NIMBLE can provide argumen
141. ting algorithms that operate on BUGS models Both BUGS models and NIMBLE algorithms are automatically processed into C code compiled and loaded back into R with seamless interfaces Since NIMBLE can compile R like functions into C that use the Eigen library for fast linear algebra it can be useful for making fast numerical functions with or without BUGS models involved One of the beauties of R is that many of the high level analysis functions are themselves written in R so it is easy to see their code and modify them The same is true for NIMBLE the algorithms are themselves written in the NIMBLE language 1 3 How to use this manual We emphasize that you can use NIMBLE for data analysis with the algorithms provided by NIMBLE without ever using the NIMBLE language to write algorithms So as you get started feel free to focus on Chapters 2 8 The algorithm library in Version 0 4 1 is just a start so we hope you ll let us know what you want to see and consider writing it in NIMBLE More about NIMBLE programming comes in Chapter 9 But see Section 5 1 for information about both limitations and extensions to how NIMBLE handles BUGS right now The packages Rcepp and ReppEigen provide different ways of connecting C the Eigen library and R In those packages you program directly in C while in NIMBLE you program in an R like fashion and the NIMBLE compiler turns it into C Programming directly in C allows full access to C
142. tion time but that s not the point of this example Once you learn the MCMC system you can write your own samplers and include them The entire system is written in nimbleFunctions 2 6 Running MCEM NIMBLE is a system for working with algorithms not just an MCMC engine So let s try maximizing the marginal likelihood for alpha and beta using Monte Carlo Expectation Maximization pump2 lt pump newModel Note that for this model one could analytically integrate over theta and then numerically maximize the resulting marginal likelihood CHAPTER 2 LIGHTNING INTRODUCTION 16 setting data and initial values checking model use nimbleModel check FALSE to skip model check box list list c alpha beta c 0 Inf pumpMCEM lt buildMCEM model pump2 latentNodes theta 1 10 boxConstraints box pumpMLE lt pumpMCEM Note butldMCEM returns an R function that contains a nimbleFunction rather than a nimble function That is why pumpMCEM is used instead of pumpMCEM frun pumpMLE Hi alpha beta 0 8230659 1 2600147 Both estimates are within 0 01 of the values reported by George et al 2 crepancy is to be expected since it is a Monte Carlo algorithm Some dis 2 7 Creating your own functions Now let s see an example of writing our own algorithm and using it on the model We ll do something simple simulating multiple values for a designated set of nod
143. ts by name or in a default order e Like R NIMBLE uses 1 based indexing For example the first element of a vector x is x 1 not x 0 e To a large extent NIMBLE functions can be executed in R uncompiled or can be compiled Using them in R will be slow and is intended for testing and debugging algorithm logic e NIMBLE is the opposite of R for argument passing R nearly always uses pass by value NIMBLE nearly always uses pass by reference or pointer That means that in compiled execution only changing the value of a variable that was a function input will change the value in the calling function Thus it is possible to write a nimbleFunction that returns information by modifying an argument Yes that s a big difference in behavior Although compiled nimbleFunctions can modify arguments the R interface to a com piled nimbleFunction performs a copy to protect the original R argument from modi fication If you want to see arguments potentially modified as well as any return value from R you can modify the control argument to compileNimble to include returnAsList TRUE Then the returned object will be a list with the nimble Function s return value as the last element CHAPTER 9 WRITING NIMBLEFUNCTIONS 103 e BUGS model nodes are implemented as nimbleFunctions with member functions for calculate calculateDiff simulate and getLogProb There are also member func tions for obtaining the value of each parameter
144. v is then accessed with Simple nimbleFunction that uses a modelValues object resizeFunction_Gen lt nimbleFunction setup function mv run function k integer resize mv k rResize lt resizeFunction_Gen customMV cResize lt compileNimble rResize cCustomMV lt cResize mv cCustomMV is a C modelValues object Compiled modelValues objects can be accessed and altered in all the same ways as un compiled ones However only uncompiled modelValues can be used as arguments to setup code in nimbleFunctions 6 6 1 Accessing contents of modelValues The values in a modelValues object can be accessed in several ways from R and in fewer ways from NIMBLE CHAPTER 6 USING NIMBLE MODELS FROM R 63 S ts the first row of a to 0 i R only custonMV i aj Pi lt G54 Sets the second row of a to 2 3 CustomMV kat i kae Can access subsets of each row in standard R manner customMV a 2 2 lt 4 Accesses all values of a customMV a Output ts a last R only 1 1 0 1 HH 2 1 2 4 Sets the first row of b to a MOLNET with values 1 R only customMVill bl Li matri enron 25 ncoll 2 Sets the second row of b R only customMV b 2 lt matrix 2 nrow 2 ncol 2 Make sure the size of inputs is correct customMV a 1 lt 1 10 Problem dimension of a ts 2 not 10 Will cause problems when compiling nimbleFunction using
145. with model variables 9 5 5 Using model variables and modelValues in expressions Each way of accessing a variable node or modelValues can be used amid mathematical expressions including with indexing or passed to another nimbleFunction as an argument For example the following two statements would be valid inkerolaul LL e233 1 Pi ek akest Ges 7 if Z is a vector or matrix and C 6 10 lt mvi v i 1 5 k B if B is a vector or matrix The NIMBLE language allows scalars but models defined from BUGS code are never created as purely scalar nodes Instead a single node such as defined by z dnorm 0 1 is implemented as a vector of length 1 similar to R When using z via model z or model z NIMBLE will try to do the right thing by treating this as a scalar In the event of problems a more explicit way to access z is model z 1 or model z 1 please tell us CHAPTER 9 WRITING NIMBLEFUNCTIONS 108 9 5 6 Getting and setting more than one model node or variable at a time using values Sometimes it is useful to set a collection of nodes or variables at one time For example one might want a nimbleFunction that will serve as the objective function for an optimizer The input to the nimbleFunction would be a vector which should be used to fill a collection of nodes in the model before calculating their log probabilities NIMBLE has two ways to do this one of which was set up during development a
146. ws We don t anticipate problems with installation but we want to hear about any and help resolve them Please post about installation problems to the nimble users Google group or email nimble stats gmail com lWe ve tested NIMBLE on Windows 7 and 8 CHAPTER 4 INSTALLING NIMBLE 25 4 3 Installing a C compiler for R to use In addition to needing a C compiler to install the package from source you also need to have a C compiler and the utility make at run time This is needed during the R session to compile the C code that NIMBLE generates for a user s models and algorithms 4 3 1 OSX On OS X you should install Xcode The command line tools which are available as a smaller installation should be sufficient This is freely available from the Apple developer site and the App Store For the compiler to work correctly for OS X it is very important that the installed R be matched to the correct OS i e R for Snow Leopard will attempt to use the incorrect compiler if the user has OS 10 9 or higher 4 3 2 Linux On Linux you can install the GNU compiler suite gcc g You can use the package manager to install pre built binaries On Ubuntu the following command will install or update make gcc and libe sudo apt get install build essential 4 3 3 Windows On Windows you should download and install Rtools exe available from http cran r project org bin windows Rtools Select the appropriate executable correspo

NIMBLE User Manual

Contents

Download Pdf Manuals

Related Search

Related Contents