[Rcpp-commits] r1457 - pkg/Rcpp/inst/doc/Rcpp-FAQ

[noreply at r-forge.r-project.org]

Author: romain
Date: 2010-06-07 08:36:45 +0200 (Mon, 07 Jun 2010)
New Revision: 1457

Modified:
   pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw
Log:
added armadillo example

Modified: pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw
===================================================================
--- pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw	2010-06-07 03:14:32 UTC (rev 1456)
+++ pkg/Rcpp/inst/doc/Rcpp-FAQ/Rcpp-FAQ.Rnw	2010-06-07 06:36:45 UTC (rev 1457)
@@ -41,6 +41,35 @@
 	link( sprintf("%s-class", cl), package, text, root )
 }
 require(inline)
+# this will be integrated to package highlight later
+ex_highlight <- function( file, external.highlight = TRUE, verbatim = FALSE ){
+	if( verbatim ){
+		writeLines( "\\begin{verbatim}" )
+		writeLines( readLines( file ) )
+		writeLines( "\\end{verbatim}" )
+	} else {
+		tf <- tempfile()
+		if( external.highlight ){
+			cmd <- sprintf( 'highlight --input="%s" --output="%s" -L --pretty-symbols', file, tf )
+			tryCatch( {
+				system( cmd )
+				tex <- readLines( tf )
+				keep <- seq( which( tex == "\\noindent" ), which( tex == "\\normalfont" ) )
+				tex <- c(
+					"\\vspace{1em}\\noindent\\fbox{\\begin{minipage}{0.9\\textwidth}" ,
+					tex[ keep ],
+					"\\end{minipage}}\\vspace{1em}" )
+				writeLines( tex )
+			})
+		} else {
+			r = renderer_latex( minipage = TRUE, doc = FALSE )
+			tex <- highlight( file, renderer = r , output = NULL )
+			writeLines( tex )
+		}
+	}
+	invisible(NULL)
+}
+
 @
 
 \newcommand{\faq}[1]{\textbf{FAQ~\ref{#1}}}
@@ -101,7 +130,9 @@
 \Sexpr{link("readLines")} :
 
 <<eval=FALSE>>=
-fx <- cxxfunction( signature(), readLines( "myfile.cpp"), plugin = "Rcpp" )
+fx <- cxxfunction( signature(), 
+	paste( readLines( "myfile.cpp"), collapse = "\n" ), 
+	plugin = "Rcpp" )
 @
 
 The \texttt{verbose} argument of \Sexpr{link("cxxfunction")} is very
@@ -198,11 +229,46 @@
 faster by using fiendishly clever ways available via the so-called template
 meta programming, an advanced \proglang{C++} technique.
 
-% TODO: add an example of using armadillo to do matrix operations
-% <<lang=cpp>>=
-%
-% @
+The following example is adapted from the examples available at the project 
+page of Armadillo. It calculate $ x' \times Y^{-1} \times z$
 
+<<echo=FALSE>>=
+writeLines( '
+    // copy the data to armadillo structures
+    arma::colvec x = Rcpp::as<arma::colvec> (x_);
+    arma::mat Y = Rcpp::as<arma::mat>( Y_ ) ;
+    arma::colvec z = Rcpp::as<arma::colvec>( z_ ) ;
+       
+    // calculate the result 
+    double result = arma::as_scalar(
+        arma::trans(x) * arma::inv(Y) * z
+        );
+    
+    // return it to R
+    return Rcpp::wrap( result );	
+', "myfile.cpp" )
+@
+<<echo=FALSE,results=tex>>=
+ex_highlight( "myfile.cpp" )
+@
+
+<<>>=
+fx <- cxxfunction( 
+	signature(x_ = "numeric", Y_ = "matrix", z_ = "numeric" ), 
+	paste( readLines( "myfile.cpp" ), collapse = "\n" ), 
+	plugin = "RcppArmadillo" )
+fx( 1:4, diag( 4 ), 1:4 ) 
+@
+<<echo=FALSE>>=
+unlink( "myfile.cpp" )
+@
+
+The focus is on the code \verb|arma::trans(x) * arma::inv(Y) * z|, which 
+performs the same operation as the R code \verb|t(x) %*% solve(Y) %*% z|, 
+although Armadillo turns it into only one operation, which makes it quite fast. 
+See \href{http://arma.sourceforge.net/speed.html}{http://arma.sourceforge.net/speed.html}
+for Armadillo benchmarks against other \proglang{C++} matrix algebra libraries. 
+
 \subsection{Is the API documented ? }
 
 You bet. We use \proglang{doxygen} to generate html, latex and man page