MCMC, Particle Filtering, and Programmable Hierarchical Modeling

A system for writing hierarchical statistical models largely compatible with 'BUGS' and 'JAGS', writing nimbleFunctions to operate models and do basic R-style math, and compiling both models and nimbleFunctions via custom-generated C++. 'NIMBLE' includes default methods for MCMC, particle filtering, Monte Carlo Expectation Maximization, and some other tools. The nimbleFunction system makes it easy to do things like implement new MCMC samplers from R, customize the assignment of samplers to different parts of a model from R, and compile the new samplers automatically via C++ alongside the samplers 'NIMBLE' provides. 'NIMBLE' extends the 'BUGS'/'JAGS' language by making it extensible: New distributions and functions can be added, including as calls to external compiled code. Although most people think of MCMC as the main goal of the 'BUGS'/'JAGS' language for writing models, one can use 'NIMBLE' for writing arbitrary other kinds of model-generic algorithms as well. A full User Manual is available at <>.

One can specify the path to where the Eigen header files are located and also whether to link common C++ files into every DSO/DLL we create or whether to treat the files as an extra library with:

R CMD INSTALL --configure-args='--with-eigen=/home/duncan/local --enable-lib' nimble

or, within R

install.packages("nimble", configure.args = c("--with-eigen=/home/duncan/local", "--enable-lib=true"), repos = NULL)


Typically, you need the R developer tools (i.e., compiler, make, etc.) to use nimble. Accordingly, it is quite straightforward to install the package from source as you will have the necessary tools already installed. These are available from the Rtools page on CRAN.

To install the package from source, from within R,

install.packages("nimble", type = "source", INSTALL_opts = "--merge-multiarch")

or from a local copy of the source package,

install.packages("nimble_0.6-2.tar.gz", repos = NULL, INSTALL_opts = "--merge-multiarch")

Alternatively, use the shell command (in the DOS Command prompt)

R CMD INSTALL --merge-multiarch nimble_0.6-9.tar.gz

Of course, you can also compile directly from a clone of the git repository:

R CMD INSTALL --merge-multiarch nimble

The --merge-multiarch is necessary when using a version of R that supports both 32 and 64 bit. This option to installation will ensure that create both 32 and 64 bit installations.

Creating a Windows Binary

R CMD build nimble
R CMD INSTALL --build --merge-multiarch nimble_0.6-9.tar.gz

We need to create the .tar.gz file first, hence the first command.


                       CHANGES IN VERSION 0.6-9 (January 2018)


-- Dimensions will now be determined from either 'inits' or 'data' if not otherwise available.

-- Can now specify "nBootReps = NA" in the runCrossValidate() function, which will prevent the Monte Carlo error from being calculated.

-- runCrossValidate() now returns the averaged loss over all k folds, instead of the summed loss.

-- Added besselK function to DSL.


-- Fixed bug that prevented use of dynamic index combined with an index specified by a constant because of duplicated dynamicIndex nodeFunctionNames.

-- Added error trapping for dynamic indexing of constants.

-- Fixed a bug where calling nimbleModel() on a BUGS model with a node that was its own parent caused R to crash.

-- Fixed a bug in runCrossValidate(), where for certain models using the "random" foldFunction would cause an error.

-- Fixed a name conflict that caused an error when user-defined distributions had parameters named 'lower' or 'upper'.

-- Fixed WAIC bug in getting dependencies of logProb variables.


-- Fixed configure error that caused issues with -fpic compiler flag.

-- Removed use of "include" directive in Makefile on a path derived from R_HOME variable at request of CRAN.

-- Removed pragma regarding -Wno-ignored-attributes from NimArrBase.h to satisfy CRAN policy.

	           CHANGES IN VERSION 0.6-8 and 0.6-7 (November 2017)

Note: versions 0.6-8 and 0.6-7 are the same except for a non-user-facing change to the withNimbleOptions function example to pass CRAN checks.


-- Addition of dcar_proper distribution, the proper Gaussian conditional autoregressive (CAR) distribution, and MCMC sampling support.

-- Addition of nimbleMCMC function, providing the most direct one-line invocation of NIMBLE's MCMC engine.

-- Addition of runCrossValidate function, which conducts k-fold cross-validation of NIMBLE models fit by MCMC.

-- Improved efficiency of MCMC conjugate samplers.

-- Added dcat-ddirch conjugacy.

-- Added error-trapping for MCMC where there is a Wishart node without conjugacy.

-- Added warning that RW block sampler may behave poorly with default initial proposal covariance if elements are on very different scales.

-- Modified a variety of warning messages.

-- the nimEigen() function now has a symmetric argument, which can be set to TRUE if a matrix is guaranteed to be symmetric (default = FALSE).

-- nimbleModel no longer outputs the names of all uninitialized variables in a model. Instead, users are directed to use the new $initializeInfo() method if uninitialized variables are detected.

-- Sped up WAIC calculation for large models.


-- Fixed MCMC autoBlocking procedure, to work with new sampler default values system.

-- Fixed MCMC conjugacy system, detection of indexed node names vs. indexed expressions.

-- Fixed bug in MCEM where bounds for multivariate top-level parameters were not stored correctly.

-- MCEM outputs a warning message if the provided model has discrete top-level parameters.

-- Fixed a bug in conjugacy processing when there were multiple dynamically indexed nodes in an expression.

-- Fixed a bug in handling of negative default values.

-- Fixed a bug in compiling multiple models in the same session.

-- Fixed a bug with step() for vectors.

-- Fixed handling of non-trivial conditions for a while() loop.

-- Results from R's eigen() and NIMBLE's eigen() functions should now match for non-symmetric matrices.


-- Added new method to generated nimbleFunction C++ classes to copy some member data from R to C++ as a batch, making this step faster.

-- Replaced reference classes with R6 classes for exprClass.

-- Replaced reference class with S3 class for nodeFunctionVector.

-- Added experimental system for expansion of model macros.

-- Removed -g debugger flags from CppCode/libnimble.a in unix-alike systems, thereby greatly reducing library size.

-- Removed various legacy browser() statements.

-- Cleaned up testing system to make more consistent across test files and in handling of known failures.

-- Flag NIMBLE as requiring C++11, mostly for future purposes.

-- Fix compilation bug when nimbleFunction has a "." in its name.

                       CHANGES IN VERSION 0.6-6 (July 2017)


-- One can now use dynamic indexes in BUGS code - indexes of a variable no longer have to be constants but can be other nodes or functions of other nodes. This allows mixture models with unknown membership. For this release, this is a beta feature and needs to be enabled with nimbleOptions(allowDynamicIndexing = TRUE).

-- The Intrinsic Gaussian conditional autoregressive (ICAR) distribution can now be used in BUGS code using the dcar_normal distribution, which behaves similarly to BUGS' car.normal distribution. Specialized MCMC samplers will be assigned to nodes that have this distribution.

-- Enabled use of optim (equivalently, nimOptim) in nimbleFunctions.

-- One can now calculate WAIC for model selection using the calculateWAIC method for MCMC objects.

-- There is a new nimbleExternalCall function that allows one to call separately compiled code from a nimbleFunction or a model (this feature is experimental for now).

-- There is a new nimbleRCall function that allows one to call an R function from a compiled nimbleFunction or model (this feature is experimental for now).

-- Enabled use of next in nimbleFunctions.

-- A resetFunctions flag have been added to buildMCEM.

-- Improved error management from compileNimble

-- NaN is now handled correctly as a constant by compiler

-- Variable names with "." are now handled correctly by the compiler.

-- pi is now handled as a constant or variable in a nimbleFunction (but cannot be used as a constant in model code).

-- There is a new returnESS method added for the bootstrap filter and auxiliary particle filter.


-- MCMC sampler control list default values are now internal to sampling algorithms, rather than a system-level option.

-- Improvements added to testing system, including safeguarding against silent failures, use of gold files, batching of compiler tests, more expected failures, conversion to running all tests using test_package, and parallelization on Travis-CI.

-- Names assigned to package-defined nimbleFunctions to improve C++ readability.

-- Use of R registrations for C functions was cleaned up.

-- Lots of vestigial code was cleaned up.

-- Un-referenced scalar arguments to rankSample.

-- We now use -fPIC rather than -fpic in most cases.

-- Updated the version of Eigen that we use to version 3.3.4.


-- Several bugs fixed in the automated factor slice sampler (AF_slice sampler), having to do with correctly resetting the internal member variables when an MCMC is run multiple times

-- Fixed harmless bug in managing split vertex numbering.

-- Fixed bugs in test-mcmc that resulted in ignoring comparisons against known results for node names with brackets or underscores.

-- Allow sum of length-zero vectors to compile correctly.

                       CHANGES IN VERSION 0.6-5 (June 2017)


-- The functions returned from a call to buildMCEM() now include an estimateCov() method, which can be used to estimate the asymptotic covariance of model parameters at their MLE values.

-- nimbleLists can now be used in nimbleFunctions that do not have setup code.

-- Enabled use of c(), rep(), seq(), diag() and ':' in BUGS code.

-- Added dflat and dhalfflat for improper uniform (prior) distributions on the real line and positive real line; includes conjugacies for dnorm dependents (in mean) with dflat distribution and dnorm dependents (in sd) with dhalfflat distribution.

-- Allow compilation of cases like model$getParam(nodes[i], 'mean'), even if nodes is empty, in a nimbleFunction instance (in which case the code would not execute, but it must be able to compile).

-- Added inverse-wishart distribution to NIMBLE's provided distributions.

-- Improved a variety of error-trapping.

-- New nimbleOptions()$verboseErrors, default FALSE. If TRUE, the call stack will be output when an error is trapped.


-- Added error trapping to report useful error message when the type of the returned object does not match the declared returnType of a nimbleFunction.

-- Added onAttach message to point users to website and manual.

-- Updated script for creating roxygen-based documentation.

-- Added more complete handling of split vertices during graph construction and model-querying methods.


-- Fixed underflow error in MCMC binary sampler.

-- Fixed bug preventing use of nimC() with an argument like model[[node]].

-- Fixed model$getDependencies(nodes) to return only what is needed (and no extra) when nodes contains a subset of elements of a non-scalar node. e.g. model$getDependencies('x[1]') if BUGS code has 'x[1:5] ~ dmnorm(...)'.

-- Fixed bug in model definition processing where some (rare) syntax could lead to very inefficient computation.

-- Fixed bug when multiple nimbleFunctions with multiple levels of nesting led to incomplete inclusion of multiple .o files in compilation.

-- Fixed compilation of cases where a scalar is computed from vectors and then used in scalar operations, e.g. inprod(X, Y) + a.

-- Fixed bug where return(rnorm(2)) and some other cases of a return argument that is an expression returning a vector would fail to compile.

-- Fixed bug where identical BUGS declarations with expression arguments in different for-loops could yield incorrect models.

-- Fixed bug where a LHS node split in the middle by a RHS usage would fail during model building.

-- Fixed bug in compiling code that constructs logical scalars and vectors.

-- Fixed bug preventing installation on Solaris.

-- Fixed issue with PROTECT flagged by rchk.

-- Fixed C++ array deletion issue in two multivariate densities.

                       CHANGES IN VERSION 0.6-4 (April 2017)


-- The user manual has been heavily revised and reorganized, with material on NIMBLE programming now more carefully organized.

-- Versions of R functions c(), seq(), :, rep(), diag(), diag()<-, and which() are now allowed in nimbleFunction run code and in BUGS code.

-- Functions numeric(), integer(), logical(), matrix(), and array() can now take non-scalar value arguments and will populate the newly created object by using the contents of value sequentially.

-- Distribution functions (d, p, r and q) now follow R's recycling rule, allowing non-scalar arguments and return values. Unlike R, return values will never have dimension > 1. Hence matrix arguments will result in a vector return value.

-- Logical vectors and operators are now supported.

-- Indexing of vectors and matrices can now use arbitrary numeric (with integer contents) and logical vectors.

-- Added inverse-gamma distribution to NIMBLE's provided distributions.

-- dim() now returns an integer vector. It is not limited to uses like dim(x)[i].

-- Updates to MCMC configuration API: Member methods conf$addMonitors() and conf$addMonitors2() now accept argument ..., allowing multiple monitors to be added using the syntax conf$addMonitors('x', 'y', 'z'). Introduced a new member method, conf$printMonitors(), which nicely prints the current MCMC monitors. This takes the place of the former method conf$getMonitors(). Now, conf$getMonitors() returns a character vector of the MCMC monitors, and the new method conf$getMonitors2() returns a character vector of the MCMC monitors2 field.

-- Added options to the printSamplers() method of MCMC configuration objects that control the level of detail displayed. These allow control for displaying default values, displaying values of non-scalar elements, and displaying the dependency lists of conjugate samplers.

-- Indexing of nodes as an argument to values() now allowed, so syntax such as x <- model$values(nodes[i]) or values(model, nodes[i]) <- x is supported.

-- More general indexing of vectors of node names now allowed in calculate(), simulate(), calculateDiff(), getLogProb() and values().

-- The adaptive factor slice sampler can now be used in NIMBLE's MCMC framework by specifying "AF_slice" as the sampler type.

-- New sampling algorithm (RW_dirichlet) added to MCMC engine, for sampling non-conjugate Dirichlet distributions.

-- Added checking at time of model definition to catch errors where implied dimensions of a variable are different in different BUGS declarations.

-- nimbleLists are a new list-style data structure that can now be created and used in nimbleFunctions. nimbleList definitions can be created in R's global environment, or in setup code. Instances of nimbleLists can be created in R's global environment, in setup code, or in run code. nimbleLists can contain other nimbleLists. nimbleLists can be used as arguments to nimbleFunction run and other methods, and returned from such nimbleFunctions.

-- eigen() and svd() now work to conduct eigendecompositions and singular value decompositions on matrices. These are synonyms for nimEigen and nimSvd, respectively. If called from R, nimEigen() and nimSvd() will execute precompiled C++ code that conducts these decompositions using the Eigen library. Both decompositions return nimbleList objects. nimEigen() and nimSvd() can also be used in BUGS code.

-- Filtering algorithms now have "initModel" control list option. If initModel = TRUE, the model will be initialized at the start of the filtering algorithm. Defaults to TRUE.

-- User-defined distributions may now be defined based solely on a density ('d') function, without a simulation ('r') function. Algorithms that need to use the simulate function will fail if it is not provided.

-- Checking of conjugacy is now much quicker in cases where there are recursive dependencies.

-- Some refinement to the error checking of DSL code that occurs when a nimbleFunction is defined.


-- Reduced copying with values and modelValues.

-- Templates compatible with Eigen library to implement R's recycling rule can be used for other functions when needed.


-- Fixed bug preventing use of round() in nimbleFunction and BUGS code.

-- Fixed bugs in dmnorm_chol(), dmvt_chol(), dwish_chol(), and rwish_chol() that were causing input arguments to be overwritten when used in DSL run code (but not in nodeFunctions).

-- Fixed bug in multiplication and division of matrix by scalar in run code when run in R.

-- Fixed bug in RW_PF sampler where dependencies were not being updated after proposal value was inserted into target node.

-- Fixed bugs in RW_PF and RW_PF_block samplers where stored LP0 was not being updated with potentially new log probability for target node at each iteration.

-- Fixed bug in Wishart conjugacy calculations when the Wishart-distributed matrix was multiplied by another value in the dependent node precision matrix. Conjugacy for the Wishart now is handled only when the Wishart matrix is the precision of the dependent node without any scaling.

                       CHANGES IN VERSION 0.6-3 (December 2016)


-- Minor bug fixes: sd() and var() were not working in BUGS code, fix to MCEM code


-- Removed use of compileNimble in rankSample to avoid Solaris issues

                       CHANGES IN VERSION 0.6-2 (November 2016)


-- Added ability to add conjugate (Gibbs) samplers to particular nodes in an MCMC configuration object using: conf$addSampler(nodeName, 'conjugate').

-- dmulti(), rmulti(), dcat() and rcat() now allow 'probs' argument with arbitrary non-negative values and internally normalize these so they sum to one, to be consistent with R's multinom behavior.

-- Added optional (turned on by default) checking of nimbleFunction run code to warn users if they are calling functions (in particular, R functions) that are not part of the NIMBLE DSL.

-- Added getBound() functionality that provides dynamic access to lower and upper bounds on a node (from R or in the DSL), based on the underlying distribution and any user-defined truncation. Functionality is analogous to getParam(). Now used in the reflection sampler and the MCEM algorithm.

-- cleaned up and added functionality to get information about a distribution based on its name or to get distributional information about model nodes or variables. This functionality is expected to be useful in querying nodes in nimbleFunction setup code when writing algorithms. See help on getDistributionInfo for getting information based on distribution name and help on modelBaseClass for getting distribution information about nodes and variables.

-- user-defined distributions can be used in BUGS code without registration, which will be done automatically behind the scenes. Parameters and dimensions are determined automatically from the nimbleFunction density function. However, in cases where users want to provide alternative parameterizations, the range of the distribution, or indication the distribution is discrete, registerDistributions should be used in its full functionality.


-- Various bug fixes including: cases where compileNimble would not return a correct interface for a nimbleFunction used in multiple particular ways; access to one nimbleFunction's member data from another.

                       CHANGES IN VERSION 0.6-1 (October 2016)


-- Changes to to address Solaris installation issues and removal of some lingering std::cout calls.

-- Rearranged some parts of package and compileNimble compilation. no longer includes redundant compilation involving classes used only at the compileNimble stage. A sessions-specific DLL is created the first time compileNimble is used. It contains R function registration and a finalizer management system and links to CppCode/libnimble.[a|dylib|dll].

-- Added a layer to manage finalizers registered with R for nimble C++ objects. This allows nimble to manually finalize objects and then safely handle R's calls to finalizers.

-- Added an internal clearCompiled system to manually finalize C++ objects and safely manage any external pointers to them in R. This is not yet safe on Windows (can cause crash later upon exiting R) and is intended for developer use at this stage.

-- Fixed bug in making an internal function accessible to Nimble generated code.

-- Fixed bug in use of nimSwitch in getParam.



-- Added getBound() functionality that provides dynamic access to lower and upper bounds on a node (from R or in the DSL), based on the underlying distribution and any user-defined truncation. Functionality is analogous to getParam(). Now used in the reflection sampler.

                       CHANGES IN VERSION 0.6 (August 2016)


-- Building models is faster and uses less memory for the building steps themselves.

-- The new model implementation uses less memory and seems to have faster compiled execution in many cases.

-- Compiling nimbleFunctions is generally faster.

-- compileNimble can handle model operation functions that use a vector of node names with a scalar index, e.g., model$calculate(nodes[i]). Index ranges are not supported.

-- The computation time spent in each sampler of an MCMC can be obtained by mcmc$run(niter, time = TRUE) and then mcmc$getTimes().

-- New RW_multinomial sampler incorporated into MCMC engine, for sampling nodes following a dmulti() distribution.

-- Progress bar added to MCMC.

-- New function runMCMC() available for easily running multiple MCMC chains.

-- model checking modified so that only size/dimension and NA checking is done by default. Extended checking of ability to calculate all model nodes is now invoked via model$check() only at user request.

-- MCMC and modelValues configuration syntax now uses 'conf' rather than 'spec' in its naming throughout NIMBLE.


-- New C++ nimbleGraph system for some steps of processing graphs.

-- New design of models, specifically nodeFunctions. This is a major implementation change.

-- New C++ memory allocation system using new double[] instead of vector. This is notably more efficient since it can avoid unnecessary initialization upon allocation of local variables in otherwise fast, heavily used nimbleFunctions.

-- New installation system for Windows and for binary builds on OS X. For non-Linux we now by default build a static library, libnimble.a, that is linked into compiled code for models or nimbleFunctions.

-- We now export many fewer functions, though some non-user facing functions are still exported.

-- Test suite now works in Windows.

-- Reduced Windows compiler warnings.

-- Various modifications to packaging to align with CRAN rules.

                       CHANGES IN VERSION 0.5-1 (May 2016)


-- Sequential Monte Carlo algorithms added: Bootstrap filter, Auxiliary particle filter, Ensemble Kalman filter, and Liu and West filter can be accessed by calls to buildBootstrapFilter(), buildAuxiliaryFilter, buildEnsembleKF(), and buildLiuWestFilter() respectively. buildPF() is no longer available, but that name will be re-used in a future version as a wrapper to some of the filter functions listed above.

-- Particle MCMC (Particle Marginal Metropolis Hastings) samplers can be used as samplers within an MCMC. 'RW_PF' can be used to sample scalar parameters, and 'RW_PF_block' can be used for multivariate parameters or multiple parameters.

-- An ascent-based version of the MCEM algorithm has been added to buildMCEM(), providing automated convergence assessment and stopping.

-- A block sampler that uses user-specified likelihoods has been implemented and can be used as a sampler within an MCMC, by using 'RW_llFunction_block'.

-- Added functions numeric(), integer(), matrix(), and array() to the NIMBLE DSL, for creating non-scalar variables in nimbleFunctions. These are intended to replace usage of declare(), with declare() being deprecated but still currently functional. setSize() is still available to change the size of an existing object prior to assigning into specific elements, but another call to one of the new functions can also be used for that purpose.

-- Added multivariate-t distribution for use in BUGS code and the DSL.

-- Added binary sampler for Gibbs sampling of discrete 0/1 nodes. This is the default sampler used for Bernoulli and Binomial(p, size=1) nodes.

-- New options for Metropolis-Hastings RW sampler: log=TRUE to sample on a log scale, and reflective=TRUE to reflect normal proposal distribution to stay within the range of the target distribution.

-- Improved printing in printSamplers() and getSamplers() methods of MCMC configuration objects.

-- Some steps of building and compiling models and algorithms are generally faster.

-- forwardsolve(), backsolve() and solve() now work more flexibly than before and can be used in BUGS code.

-- A variety of small bug fixes.


-- Testing has been added for SMC algorithms.

                       CHANGES IN VERSION 0.5 (March 2016)


-- Added support for solve(), forwardsolve(), and backsolve() to the NIMBLE DSL, with the same functionality as in R.

-- Improved performance of conjugate multivariate-normal - multivariate-normal sampling.

-- API changes for MCMCspec objects: new method printSamplers() prints the current samplers (replacing the old getSamplers() method); new functionality for getSamplers(), which now returns a list of samplerSpec objects; new overloaded functionality of setSamplers(), which can accept a list of samplerSpec objects, replacing the current set of samplers; new method getSamplerDefinition(), which returns the nimbleFunction definition of a sampler.

-- API created for modifying samplerSpec objects: setName(), setSamplerFunction(), setTarget(), setControl().

-- MCMC conjugate sampling efficiency improved by ~33%.

-- new system for automating the comparison of different MCMCs and generating html results pages: the main function is compareMCMCs.

-- enhanced checking of model to check for size and dimension mismatch in BUGS code.

-- some steps of building models and determining dependencies (e.g. getDependencies method for model classes) are faster and use less memory.

-- models have a new method, getDependenciesList, that provides a list of neighbor relationships in the model graph.

-- There is a new function, getParam(model, node, parameter), that returns the value of a parameter of a stochastic node. It works in R and in the NIMBLE DSL (compilable run code).

-- Models now have member functions for calculate, simulate, getLogProb, calculateDiff, and getParam. model$calculate(nodes) is equivalent to calculate(model, nodes), etc.

-- The NIMBLE DSL now allows drop=FALSE as the last argument for indices. e.g. x[1,,drop=FALSE]. This mimics R.

-- added ability to use any of the methods for R's optim function in MCEM optimization step.

-- There are more flexible ways to provide arguments to declare and setSize.

-- The random walk block sampler is a bit more efficient.

-- There is better error trapping during some compilation steps.


-- various modifications to conform to CRAN rules


-- Compilation of BUGS function inprod is fixed

-- some cases of handling multivariate variables of length one (e.g. a 1x1 matrix) have been fixed.

-- added warning when 'size' in multinomial is not sum of values

-- added missing terms (involving only the data values) in 'ddirchmulti' in test-user.R and in manual

                    CHANGES IN VERSION 0.4-1 (Oct. 3, 2015)


-- added support for OpenBUGS to MCMCsuite.

-- added additional option for MCMCsuite: 'calculateEfficiency' to calculate ESS and ESS/time.

-- added elliptical slice sampler 'ess' to MCMC engine.

-- added new MCMC option for MCMCsuite that omits conjugate samplers: 'nimble_noConj'


-- fixed bug preventing use of nimbleFunctions in packages depending on NIMBLE.

-- fixed bug preventing use of nimStop in R version of nimbleFunctions.

-- reduced generation of C++ compiler warnings on Windows during compileNimble.

                    CHANGES IN VERSION 0.4 (Aug. 2, 2015)


-- almost everything is faster in almost all cases (building models, configuring MCMCs, compiling models and nimbleFunctions), sometimes very much faster, especially during R processing.

-- added DSL functions stop("Error message") and checkInterrupt() to check for a user interrupt (via R_checkUserInterrupt() in C++).

-- added support for scalar and vector character strings in the compiler. The ony meaningful use currently is as argument(s) to print or stop.

-- added calculateDiff as a fourth fundamental method (after calculate, simulate, getLogProb) in model node functions.

-- nearly all calls to DSL functions or other nimbleFunctions handle R-style named or ordered arguments.

-- dots (".") are allowed in nimbleFunction argument names.

-- most Windows compiler warnings about comparing unsigned and signed ints should be gone. Harmless warnings remain and some objects possibly being used before initialization.

-- more informative error messages added in many cases.

-- nimble version of some common R functions is now consistently prefixed with "nim" instead of "nimble". E.g. nimRound, nimStop, nimPrint, nimCopy. These can still used without the prefix in the DSL, e.g. round, stop, print, copy.

-- added nimbleOptions useMultiInterfaceForNestedNimbleFunctions (default TRUE) and (experimental) clearNimbleFunctionsAfterCompiling (default FALSE) to reduce memory use. See User Manual section 9.6.

-- setSize now consistently works in both compiled and uncompiled uses as setSize(X, size1, size2, etc.), not setSize(X, c(size1, size2, etc.)).

-- added support for user-defined functions in BUGS code.

-- added support for use of user-defined distributions in BUGS code, with the distribution density, simulate, distribution and quantile functions coded as nimbleFunctions and registered via registerDistributions().

-- added support for truncation (T(,) and I(,) syntax in BUGS) plus dinterval distribution for censoring, both following the JAGS functionality.

-- added ability to impose constraints via the dconstraint syntax; these constraints act like data and therefore only take effect a posteriori and are not imposed when simulating from the model.

-- added alternative distribution names (aliases) usable in BUGS code (via an extensible system for adding additional aliases as desired): dbinom for dbin, dmultinom for dmulti, dnbinom for dnegbin, dchisqr for dchisq, dweibull for dweib, ddirich for ddirch, dwishart for dwish.

-- added additional parameterizations for dlnorm and dt.

-- improved handling of distribution functions in nimbleFunction run code (i.e., the DSL), allowing argument matching by name and use of default values. Distribution functions can also be used as deterministic functions (e.g., pnorm to do probit calculations) in BUGS code.

-- added an optional check when building model that alerts user to presence of nodes without values and log probability calculations that return NA.

-- model$checkConjugacy(nodes) now accepts a character vector argument of node/variable names, and returns a named list identifying conjugate relationships.

-- incorporated automated blocking into MCMC engine: configureMCMC(model, autoBLock=TRUE) returns an MCMCspec defined by automated blocking procedure, and buildMCMC(model, autoBlock=TRUE) returns the corresponding MCMC algorithm.

-- new syntax for MCMCspec$addSampler(type, target, control). mandatory 'type' argument specifies sampler type, which may be a character string or nimbleFunction object. mandatory 'target' argument specifices a character vector of target model nodes. optional 'control' list argument overrides default sampler control parameters.

-- default control parameters for MCMC sampling algorithms are now a NIMBLE system level option: MCMCcontrolDefaultList.

-- MCMCspec$getSamplers(ind), MCMCspec$setSamplers(ind), and MCMCspec$removeSamplers(ind) can optionally also accept a character vector argument, and will act on all samplers which sample the nodes specified.

-- cleaned up formatting of output when querying and setting MCMC samplers.

-- NIMBLE will no longer "hang" when used in RStudio.

-- reordered argument names to nimbleModel to put in more logical order of importance. first four arguments are: code, constants, data, inits.

-- added documentation of NIMBLE's built-in MCMC samplers via help(samplers).

-- added more informative error messages for common errors encountered when calling nimbleModel() and compileNimble().


-- re-wrote model definition processing and R nodeFunction instantiation to do more work at the level of a BUGS declaration rather than for each individual node.

-- re-wrote checkConjugacy to use the new model definition content.

-- re-wrote C++ nimCopy system and corresponding R partial evaluation to do more processing in R and set up C++ for faster processing.

-- added test-copy for nimCopy, values() and values()<- .

-- added nimbleProjectClass method for adding groups of nimbleFunctions from same generator at once.

-- modified core samplers like RW to use the new calculateDiff nodeFunction method.

-- added CmultiNimbleFunctionInterface to interface compiled nimbleFunctions contained within other nimbleFunctions.

-- removed some old code deemed to be fully defunct.

-- added 'range' variable to all distributions; when truncation is specified this modifies the range and also sets the 'truncated' flag to TRUE; range is not at the moment used but could be used by developers in algorithms.

-- added a variety of error checking for various distribution functions and now generally use doubles in distribution functions in C++.

-- modified API for nimble options to mimic R's options(), including nimbleOptions() and getOptions() and renaming of the underlying nimble options object to be .nimbleOptions.

-- added an environment, nimbleUserNamespace, in the package namespace, that allows user-supplied information to control the behavior of NIMBLE. At the moment, only used for user-supplied distributions list.

-- testing of user-defined distributions and functions in BUGS code (tests/test-user.R).

-- full suite of testing for truncation/censoring/constraints added (tests/test-trunc.R).

-- names of custom MCMC sampler nimbleFunctions need not begin with "sampler_".

-- added initializeModel() nimbleFunction for use in algorithms; it performs sensible model initialization at the onset of an algorithm.


-- setSize fixed.

-- generation of "1/(scale)" type bits in keyword processing for exp and gamma fixed.

-- fixed bug where quitting R after dyn.unload()ing in OS X / Linux caused a segfault. Now we rely on a finalizer that uses the base class virtual destructor, which is in the package dll, not the generated one(s). We still have segfaults on Windows after dyn.unload()ing.

-- made row subset assignment work in the compiler, e.g. x[i,] <- foo(a).

-- updated package to use new igraph 1.x.x API and now explicitly link in LAPACK_LIBS and BLAS_LIBS when building as dpotrf not being found when using igraph 1.x.x.

-- fixed bug where dexp was passing the wrong parameter (rate instead of scale) to C++; we now use our own dexp_nimble, which calls Rmath's dexp correctly.

-- set default for deparse to width.cutoff=500L to avoid splitting of lines when going from expressions to string names.

                    CHANGES IN VERSION 0.3-1 (Mar. 7, 2015)


-- fully allow data to be provided as part of constants argument in nimbleModel for compatibility with JAGS and BUGS, which mix data and constants

-- added Dirichlet-multinomial conjugacy handling

-- Added 'oldSpec' argument to configureMCMC. Allows rebuilding of MCMCs without the need to recompile code if there are no new types of samplers.

-- Now allow for up to 4D arrays

-- Added handling of raising a vector of values to a scalar power in nimble functions (i.e., the NIMBLE DSL)


-- fixed naming issue in checking posterior summaries against known values in test_mcmc


-- fixed bug that allowed inits to overwrite data values in variables that are mixtures of data and parameters. Also now detect elements of initial values that are not variables in the model.

-- fixed bug in naming of nodes in as.matrix() when there is a variable with a single indexed node (e.g. x[1], but no other nodes in the variable 'x')

-- fixed bug regarding logProbs with gaps (e.g., if logProb_x[1] and logProb_x[3] are defined but not logProb_x[2])

-- fixed bug in handling of unary minus for non-scalars

	  	CHANGES IN VERSION 0.3 (Dec. 31, 2014)


-- IMPORTANT SYNTAX CHANGE: nimbleFunctions are run via myNimbleFunction$run() instead of myNimbleFunction(). This means code written in v0.2 and earlier will not run without adding $run.

-- IMPORTANT SYNTAX CHANGES: --- writing code for nimble models is now done with nimbleCode (previously modelCode) --- to customize MCMC use myMCMCspec <- configureMCMC(myModel) (previously MCMCspec) --- to build an MCMC algorithm, either myGenericMCMC <- buildMCMC(myModel) for a generic build or myCustomizedMCMC <- buildMCMC(myMCMCspec) for a customized MCMC algorithm can be used (previously one always had to build an MCMCspec, even for generic build)

-- Variables and methods of a nimbleFunction can be accessed by myNimbleFunction$myVariable or myNimbleFunction$myMethod() rather than nfVar(myNimbleFunction, ‘myVariable’) or nfMethod(myNimbleFunction, ‘myMethod’)(). Similarly, names of objects/methods of a nimble function can be queried by ls(myNimbleFunction)

-- faster compiling, most notably when compiling MCMC algorithms


-- Addition of graphIDs for logProbs for models (separate set than graphIDs for nodes) and graphIDs for modelValue variables

-- Addition of $expandNodeNames() for modelValues

-- $expandNodeNames() now evals nodeNames text array to quickly retrieve graphIDs. expandNodeNames can also accept graphIDs and return names. Also can return multivariate nodes as either ‘x[1:10]’ or ‘x[1]’,’x[2]’, etc.

-- Addition of numberedObjects (both at R and C++ level) currently used for fast construction of C++ nodeFunctionVectors, modelVariableAccessors and modelValuesAccessors

-- Reduction of nimbleFunctions required for initialization functions of MCMCs

-- nimCopy now only requires that the number of nodes are equal, not that the sets of consecutive nodes be equal (i.e. previous nimCopy(…, nodes = c(‘x[1]’, ‘x[2]’), nodesTo = c(‘y[1,1]’, ‘y[2,2]’)) was not allowed).

-- Addition of keywordProcessing system for more organized compiling of nimbleFunctions

Bug fixes

-- Fixed bug regarding calculating log probabilities for multinomial distribution with probabilities equal to 0

                 CHANGES IN VERSION 0.2 (Oct. 12, 2014)

-- Internal changes to decrease time to build models and nimbleFunctions.

-- Multivariate conjugate updaters are now included in the default MCMC implementation, as well as block updating on scalar and/or multivariate nodes.

-- Vector treatment of and is.nan, so, nodes)) will work, equivalently to any( in R.

-- More extensive suite of tests.

-- Extension of node maps, which can be accessed via graphIDs, to increase speed of determining node types, checking if nodes in model, etc.

-- model$getNodeNames, expandNodeNames and getDependencies all return the full node function name, i.e. if 'x[1:2]' is multivariate, will return 'x[1:2]' rather than 'x[1]', 'x[2]', unless returnScalarComponents = TRUE

-- Added class of nodeVectors, which save the graphIDs of a set of nodes. Use of these is minimal at the moment.


-- Fixed issue with specifying multivariate nodes as rows/columns of matrices

-- Fixed bug in the conjugacy system

-- Fixed bug in compiled version of adaptive block updater

-- Fixed issue with building the NIMBLE package for Windows, as well as cleaning up causes of compiler warnings.

-- Fixed issue that values(model, nodes) sorted the outcome. Remaining bug to be fixed: nimCopy(nodesFrom, nodesTo) will NOT work if nodesFrom and nodesTo have different number/different lengths of ordered contingent blocks of memory, i.e. nimCopy(nodesFrom = c('x[1]', 'x[2]'), nodesTo = c('y[2]', 'y[1]')) will fail because nodesFrom is one block but nodesTo is two blocks

-- Fixed issue that chol(A+B) was being translated to chol(A) + B

                 CHANGES IN VERSION 0.1-1 (Aug. 28, 2014)


-- handling of spaces in installed directory name on Windows

-- ensured that various Makevars and and files are provided in the package for proper installation on all platforms

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


0.6-9 by Christopher Paciorek, 14 days ago

Browse source code at

Authors: Perry de Valpine, Christopher Paciorek, Daniel Turek, Cliff Anderson-Bergman, Nick Michaud, Fritz Obermeyer, Duncan Temple Lang, and see AUTHORS file for additional contributors.

Documentation:   PDF Manual  

Task views:

BSD_3_clause + file LICENSE | GPL (>= 2) license

Imports methods, igraph, coda, R6

Suggests testthat, R2WinBUGS, rjags, rstan, xtable, abind, ggplot2, tensorflow, reticulate

System requirements: GNU make

See at CRAN