[Rcpp-commits] r1230 - in pkg/RcppGSL: . R man

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

Author: edd
Date: 2010-05-13 16:01:54 +0200 (Thu, 13 May 2010)
New Revision: 1230

Added:
   pkg/RcppGSL/R/fastLm.R
   pkg/RcppGSL/man/fastLm.Rd
Modified:
   pkg/RcppGSL/NAMESPACE
Log:
some missing pieces


Modified: pkg/RcppGSL/NAMESPACE
===================================================================
--- pkg/RcppGSL/NAMESPACE	2010-05-13 13:10:18 UTC (rev 1229)
+++ pkg/RcppGSL/NAMESPACE	2010-05-13 14:01:54 UTC (rev 1230)
@@ -1,2 +1,4 @@
 useDynLib(RcppGSL)
+
 #exportPattern("^[[:alpha:]]+")
+export(fastLm)

Added: pkg/RcppGSL/R/fastLm.R
===================================================================
--- pkg/RcppGSL/R/fastLm.R	                        (rev 0)
+++ pkg/RcppGSL/R/fastLm.R	2010-05-13 14:01:54 UTC (rev 1230)
@@ -0,0 +1,42 @@
+## fastLm.R: Rcpp/GSL implementation of lm()
+##
+## Copyright (C)  2010 Dirk Eddelbuettel and Romain Francois
+##
+## This file is part of RcppGSL.
+##
+## RcppGSL is free software: you can redistribute it and/or modify it
+## under the terms of the GNU General Public License as published by
+## the Free Software Foundation, either version 2 of the License, or
+## (at your option) any later version.
+##
+## RcppGSL is distributed in the hope that it will be useful, but
+## WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+## GNU General Public License for more details.
+##
+## You should have received a copy of the GNU General Public License
+## along with RcppGSL.  If not, see <http://www.gnu.org/licenses/>.
+
+fastLm <- function(y, X) {
+
+    stopifnot(is.matrix(X))
+    stopifnot(nrow(y)==nrow(X))
+
+    res <- .Call("fastLm", y, X, package="RcppGSL")
+}
+
+## What would be nice here:
+##
+##   fastLm <- function(x, ...) UseMethod("fastLm")
+##
+##   fastLm.formula <- ...
+##
+##   fastLm.default <- ...
+##
+##   print.fastLm <- function(x, ...)
+##
+##   summary.fastLm <- function(object, ...
+##
+##   print.summary.fastLm <- ...
+##
+## but on the other hand lm.fit() does not do any of this either

Added: pkg/RcppGSL/man/fastLm.Rd
===================================================================
--- pkg/RcppGSL/man/fastLm.Rd	                        (rev 0)
+++ pkg/RcppGSL/man/fastLm.Rd	2010-05-13 14:01:54 UTC (rev 1230)
@@ -0,0 +1,65 @@
+\name{fastLm}
+\alias{fastLm}
+\concept{regression}
+\title{Bare-bones linear model fitting function}
+\description{
+  \code{fastLm} estimates the linear model using the \code{gsl_multifit_linear}
+  function of the \code{GNU GSL} library.
+}
+\usage{
+fastLm(y, X)
+}
+\arguments{
+  \item{y}{a vector containing the explained variable.}
+  \item{X}{a data.frame or matrix containing the explanatory variables.}
+}
+\details{
+  Linear models should be estimated using the \code{\link{lm}} function. In
+  some cases, \code{\link{lm.fit}} may be appropriate.
+
+  This function provides a reference use case of the \code{GSL}
+  library via the wrapper functions in the \pkg{RcppGSL} package.
+
+  It does not provide a formula interface. It does check for missing
+  values. It does (yet?) return a proper object with suitable accessor
+  functions. That's why we call it bare-bones.
+
+  Lastly, one must be be careful in timing comparisons of
+  \code{\link{lm}} and friends versus this approach based on \code{GSL}
+  or \code{Armadillo}. The reason that \code{GSL} or \code{Armadillo} can
+  do something like \code{\link{lm.fit}} faster than the functions in
+  the stats package is because they use the Lapack version
+  of the QR decomposition while the stats package uses a \emph{modified}
+  Linpack version.  Hence \code{GSL} and \code{Armadillo} uses level-3 BLAS code
+  whereas the stats package uses level-1 BLAS.  However,
+  \code{GSL} or \code{Armadillo} will choke on rank-deficient model matrices whereas
+  the functions from the stats package will handle them properly due to
+  the modified Linpack code.  Statisticians want a pivoting scheme of
+  \dQuote{pivot only on (apparent) rank deficiency} and numerical
+  analysts have no idea why statisticians want this so it is not part of
+  conventional linear algebra software.
+
+}
+
+\value{
+  \code{fastLm} returns a list with two components:
+  \item{coefficients}{a vector of coefficients} \item{stderr}{a vector
+  of the (estimated) standard errors of the coefficient estimates}
+
+  In other words, no actual \sQuote{fastLm} object is provided unlike
+  for \code{\link{lm}} or \code{\link[MASS]{rlm}} but rather just a
+  simple list unlike \code{\link{lm.fit}}.
+}
+\seealso{\code{\link{lm}}, \code{\link{lm.fit}}} 
+\references{GNU GSL project: \url{http://www.gnu.org/software/gsl}}
+\author{
+  The GNU GSL library is being written by team of authors with the
+  overall development, design and implementation lead by Brian Gough and
+  Gerard Jungman.  RcppGSL is written by Romain Francois and Dirk Eddelbuettel.
+}
+\examples{
+  data(trees)
+  flm <- fastLm( log(trees$Volume),  cbind(rep(1,31), log(trees$Girth)) )
+}
+\keyword{regression}
+