R devel - Aug 2009 - Errors in manpage of bs() (splines) (PR#13912)

Full_Name: Benjamin Hofner
Version: 2.9.1
OS: Ubuntu
Submission from: (NULL) (92.229.82.215)


Hi

I found some mistakes in the documentation of function bs() in package splines
(I use R 2.9.1 but it also holds for the latest SVN Version
https://svn.r-project.org/R/trunk/src/library/splines/man/bs.Rd)

-----------------------------

\item{df}{degrees of freedom; one can specify \code{df} rather than
\code{knots}; \code{bs()} then chooses \code{df-degree-1} knots at
suitable quantiles of \code{x} (which will ignore missing values).}

This should read (or similar):

\item{df}{degrees of freedom; one can specify \code{df} rather than
\code{knots}; \code{bs()} then chooses \code{df-degree-as.numeric(intercept)}
knots at
suitable quantiles of \code{x} (which will ignore missing values).}

The problem here is: we only subtract 1 if we use an intercept! Probably this
becomes more readable if one uses a construction as e.g. \code{df-degree-1} if
\code{intercept=TRUE} and \code{df-degree} if \code{FALSE}.

-----------------------------

The next problematic part is:

A matrix of dimension \code{length(x) * df}, where either \code{df}
was supplied or if \code{knots} were supplied,
\code{df = length(knots) + 3 + intercept}. 	

This should read (or similar):

A matrix of dimension \code{length(x) * df}, where either \code{df}
was supplied or if \code{knots} were supplied,
\code{df = length(knots) + degree + as.numeric(intercept)}. 	

Always adding 3 is not suitable. Furthermore the "+ intercept" is not
very
clear. Another issue is the dimension of the matrix: I would rather suggest to
write it in LaTeX style "length(x) \times df".

-----------------------------

I hope this helps to improve the docs a bit.
Cheers,
  Benjamin