,
Romain Francois [aut] ,
Doug Bates [aut] ,
Binxiang Ni [aut],
Conrad Sanderson [aut] | Title: | 'Rcpp' Integration for the 'Armadillo' Templated Linear Algebra Library |
|---|---|
| Description: | 'Armadillo' is a templated C++ linear algebra library (by Conrad Sanderson) that aims towards a good balance between speed and ease of use. Integer, floating point and complex numbers are supported, as well as a subset of trigonometric and statistics functions. Various matrix decompositions are provided through optional integration with LAPACK and ATLAS libraries. The 'RcppArmadillo' package includes the header files from the templated 'Armadillo' library. Thus users do not need to install 'Armadillo' itself in order to use 'RcppArmadillo'. From release 7.800.0 on, 'Armadillo' is licensed under Apache License 2; previous releases were under licensed as MPL 2.0 from version 3.800.0 onwards and LGPL-3 prior to that; 'RcppArmadillo' (the 'Rcpp' bindings/bridge to Armadillo) is licensed under the GNU GPL version 2 or later, as is the rest of 'Rcpp'. |
| Authors: | Dirk Eddelbuettel [aut, cre] ,
Romain Francois [aut] ,
Doug Bates [aut] ,
Binxiang Ni [aut],
Conrad Sanderson [aut] |
| Maintainer: | Dirk Eddelbuettel <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 14.0.2-1.1 |
| Built: | 2024-10-10 16:20:46 UTC |
| Source: | https://github.com/rcppcore/rcpparmadillo |
The package brings the power of Armadillo to R.
Armadillo is a C++ linear algebra library, aiming towards a good
balance between speed and ease of use.
It provides efficient classes for vectors, matrices and cubes, as well as many functions which operate on the classes (eg. contiguous and non-contiguous submatrix views).
Various matrix decompositions are provided, and an automatic expression evaluator (via template meta-programming) combines several operations to increase efficiency.
The syntax (API) is deliberately similar to Matlab. It is useful for algorithm development directly in C++, or quick conversion of research code into production environments.
Armadillo has been primarily developed at NICTA (Australia) by Conrad Sanderson, with contributions from around the world.
RcppArmadillo acts as a bridge between Rcpp and Armadillo,
allowing the programmer to write code using Armadillo classes that integrate
seemlessly with R via Rcpp.
The simplest way to get started is to create a skeleton of a package
using RcppArmadillo. This can be done conveniently by the
RcppArmadillo.package.skeleton
function.
The important steps are
Include the RcppArmadillo.h header file, which also includes
armadillo.h.
Import Rcpp, and LinkingTo Rcpp and RcppArmadillo by adding these lines to the DESCRIPTION file:
Imports: Rcpp (>= 0.11.0)
LinkingTo: Rcpp, RcppArmadillo
Link against the BLAS and LAPACK libraries, by adding this line
in the Makevars and Makevars.win files:
PKG_LIBS = $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)
Please use the Rcpp-devel mailing list on r-forge for questions about RcppArmadillo (subscribe first). https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/rcpp-devel
For RcppArmadillo: Dirk Eddelbuettel, Romain Francois, Doug Bates and Binxiang Ni
Maintainer: Dirk Eddelbuettel <[email protected]>
For Armadillo: Conrad Sanderson
Armadillo project: https://arma.sourceforge.net/
Conrad Sanderson and Ryan Curtin. Armadillo: a template-based C++ library for linear algebra. Journal of Open Source Software, Vol. 1, pp. 26, 2016.
Dirk Eddelbuettel and Conrad Sanderson, "RcppArmadillo: Accelerating R with high-performance C++ linear algebra", Computational Statistics and Data Analysis, 2014, 71, March, pages 1054-1063, doi:10.1016/j.csda.2013.02.005. )
Report (or Set) Maximum Number of OpenMP Threads
armadillo_get_number_of_omp_threads() armadillo_set_number_of_omp_threads(n)armadillo_get_number_of_omp_threads() armadillo_set_number_of_omp_threads(n)
n |
Number of threads to be set |
For the getter, and on a system with OpenMP, the maximum number of threads that OpenMP may be using and on systems without it, one. The setter does not return a value.
Set the Armadillo Random Number Generator to the given value
armadillo_set_seed(val)armadillo_set_seed(val)
val |
The seed used to initialize Armadillo's random number generator. |
Depending on whether RcppArmadillo was compiled for the C++98 standard
(currently the default) or for C++11 (optional), two different RNGs may be used.
This function resets either. For C++98, the R programming language's RNG is used.
For C++11, the RNG included in the <random> library is used only when
#define ARMA_USE_CXX11_RNG is placed before #include <RcppArmadillo.h>.
Otherwise, the R programming language's RNG will be used.
The function is invoked for its side effect and has no return value.
This has been found to not work as espected in RStudio as its code also uses the system RNG library. You may have to either not run within RStudio or change your code to use a different RNG such as the one from R.
The R documentation on its RNGs all of which are accessible via Rcpp.
Set the Armadillo Random Number Generator to a random value
armadillo_set_seed_random()armadillo_set_seed_random()
Depending on whether RcppArmadillo was compiled for the C++98 standard
(currently the default) or for C++11 (optional), two different RNGs may be used.
This function resets either. For C++98, the R programming language's RNG is used.
For C++11, the RNG included in the <random> library is used only when
#define ARMA_USE_CXX11_RNG is placed before #include <RcppArmadillo.h>.
Otherwise, the R programming language's RNG will be used.
The function is invoked for its side effect and has no return value.
This has been found to not work as espected in RStudio as its code also uses the system RNG library. You may have to either not run within RStudio or change your code to use a different RNG such as the one from R.
The R documentation on its RNGs all of which are accessible via Rcpp.
Helper functions to throttle use of cores by RcppArmadillo-internal code on systems with OpenMP. On package load, the initial value is saved and used to reset the value.
armadillo_throttle_cores(n = 2) armadillo_reset_cores()armadillo_throttle_cores(n = 2) armadillo_reset_cores()
n |
Integer value of desired cores, default is two |
Report the version of Armadillo
armadillo_version(single)armadillo_version(single)
single |
A logical vector indicating whether a
single return values is requested, or a named vector with
three elements |
The version is defined by Armadillo in the header
arma_version.hpp.
Depending on the value of single, either a single
number describing the Armadillo version or a named vector
with three elements major, minor and
patch.
Armadillo header file arma_version.hpp.
fastLm estimates the linear model using the solve
function of Armadillo linear algebra library.
fastLmPure(X, y) fastLm(X, ...) ## Default S3 method: fastLm(X, y, ...) ## S3 method for class 'formula' fastLm(formula, data = list(), ...)fastLmPure(X, y) fastLm(X, ...) ## Default S3 method: fastLm(X, y, ...) ## S3 method for class 'formula' fastLm(formula, data = list(), ...)
y |
a vector containing the explained variable. |
X |
a model matrix. |
formula |
a symbolic description of the model to be fit. |
data |
an optional data frame containing the variables in the model. |
... |
not used |
Linear models should be estimated using the lm function. In
some cases, lm.fit may be appropriate.
The fastLmPure function provides a reference use case of the Armadillo
library via the wrapper functions in the RcppArmadillo package.
The fastLm function provides a more standard implementation of
a linear model fit, offering both a default and a formula interface as
well as print, summary and predict methods.
Lastly, one must be be careful in timing comparisons of
lm and friends versus this approach based on
Armadillo. The reason that Armadillo can do something
like lm.fit faster than the functions in the stats
package is because Armadillo uses the Lapack version of the QR
decomposition while the stats package uses a modified Linpack
version. Hence Armadillo uses level-3 BLAS code whereas the
stats package uses level-1 BLAS. However, Armadillo will
either fail or, worse, produce completely incorrect answers
on rank-deficient model matrices whereas the functions from the stats
package will handle them properly due to the modified Linpack code.
An example of the type of situation requiring extra care in checking for rank deficiency is a two-way layout with missing cells (see the examples section). These cases require a special pivoting scheme of “pivot only on (apparent) rank deficiency” which is not part of conventional linear algebra software.
fastLmPure returns a list with three components:
coefficients |
a vector of coefficients |
stderr |
a vector of the (estimated) standard errors of the coefficient estimates |
df.residual |
a scalar denoting the degrees of freedom in the model |
fastLm returns a richer object which also includes the
residuals, fitted values and call argument similar to the lm or
rlm functions..
Armadillo is written by Conrad Sanderson. RcppArmadillo is written by Romain Francois, Dirk Eddelbuettel, Douglas Bates and Binxiang Ni.
Armadillo project: https://arma.sourceforge.net/
data(trees, package="datasets") ## bare-bones direct interface flm <- fastLmPure( cbind(1, log(trees$Girth)), log(trees$Volume) ) print(flm) ## standard R interface for formula or data returning object of class fastLm flmmod <- fastLm( log(Volume) ~ log(Girth), data=trees) summary(flmmod) ## case where fastLm breaks down dd <- data.frame(f1 = gl(4, 6, labels = LETTERS[1:4]), f2 = gl(3, 2, labels = letters[1:3]))[-(7:8), ] xtabs(~ f2 + f1, dd) # one missing cell mm <- model.matrix(~ f1 * f2, dd) kappa(mm) # large, indicating rank deficiency set.seed(1) dd$y <- mm %*% seq_len(ncol(mm)) + rnorm(nrow(mm), sd = 0.1) summary(lm(y ~ f1 * f2, dd)) # detects rank deficiency summary(fastLm(y ~ f1 * f2, dd)) # some huge coefficientsdata(trees, package="datasets") ## bare-bones direct interface flm <- fastLmPure( cbind(1, log(trees$Girth)), log(trees$Volume) ) print(flm) ## standard R interface for formula or data returning object of class fastLm flmmod <- fastLm( log(Volume) ~ log(Girth), data=trees) summary(flmmod) ## case where fastLm breaks down dd <- data.frame(f1 = gl(4, 6, labels = LETTERS[1:4]), f2 = gl(3, 2, labels = letters[1:3]))[-(7:8), ] xtabs(~ f2 + f1, dd) # one missing cell mm <- model.matrix(~ f1 * f2, dd) kappa(mm) # large, indicating rank deficiency set.seed(1) dd$y <- mm %*% seq_len(ncol(mm)) + rnorm(nrow(mm), sd = 0.1) summary(lm(y ~ f1 * f2, dd)) # detects rank deficiency summary(fastLm(y ~ f1 * f2, dd)) # some huge coefficients
RcppArmadillo.package.skeleton automates the creation of
a new source package that intends to use features of RcppArmadilo.
It is based on the package.skeleton function which it executes first.
RcppArmadillo.package.skeleton(name = "anRpackage", list = character(), environment = .GlobalEnv, path = ".", force = FALSE, code_files = character(), example_code = TRUE)RcppArmadillo.package.skeleton(name = "anRpackage", list = character(), environment = .GlobalEnv, path = ".", force = FALSE, code_files = character(), example_code = TRUE)
name |
See package.skeleton |
list |
See package.skeleton |
environment |
See package.skeleton |
path |
See package.skeleton |
force |
See package.skeleton |
code_files |
See package.skeleton |
example_code |
If TRUE, example c++ code using RcppArmadillo is added to the package |
In addition to package.skeleton :
The ‘DESCRIPTION’ file gains a Depends line requesting that the package depends on Rcpp and RcppArmadillo and a LinkingTo line so that the package finds Rcpp and RcppArmadillo header files.
The ‘NAMESPACE’, if any, gains a useDynLib directive.
The ‘src’ directory is created if it does not exists and a ‘Makevars’ file is added setting the environment variable ‘PKG_LIBS’ to accomodate the necessary flags to link with the Rcpp library.
If the example_code argument is set to TRUE,
example files ‘rcpparma_hello_world.h’ and ‘rcpparma_hello_world.cpp’
are also created in the ‘src’. An R file ‘rcpparma_hello_world.R’ is
expanded in the ‘R’ directory, the rcpparma_hello_world function
defined in this files makes use of the C++ function ‘rcpparma_hello_world’
defined in the C++ file. These files are given as an example and should
eventually by removed from the generated package.
Nothing, used for its side effects
Read the Writing R Extensions manual for more details.
Once you have created a source package you need to install it:
see the R Installation and Administration manual,
INSTALL and install.packages.
## Not run: RcppArmadillo.package.skeleton( "foobar" ) ## End(Not run)## Not run: RcppArmadillo.package.skeleton( "foobar" ) ## End(Not run)