\SweaveOpts{engine=R, keep.source=TRUE, prefix.string=fig/packages}
\SweaveOpts{eps=FALSE, pdf=TRUE, width=9, height=6, strip.white=true}
<<preliminaries,echo=FALSE,results=hide>>=
options(width=75)
@
\lecture[More R: Objects, Methods]{12. More R: Packages, Files}{week 13}

\SectionCont{R packages, CRAN, etc: the R Ecosystem}{%
  In this chapter you will learn more on \dots
\begin{itemize}
\pause\item[\ldots] exploring and installing \Rp packages
\pause\item[\ldots] CRAN, etc: a glimpse of ``The \Rp World''
\pause\item[\ldots] how to get help regarding R
%\pause\item[\ldots] how to communicate with the operating system and manipulate files
\end{itemize}
}

\Subsec{Packages}
\Bfr
% --- packages 2 ---
<<high-priority-packages, echo=false>>=
ip.H <- installed.packages(lib.loc = .Library, priority = "high")
baseP <- rownames(ip.H)[ip.H[,"Priority"] == "base"]
recoP <- rownames(ip.H)[ip.H[,"Priority"] == "recommended"]
@
  \begin{itemize}
  \item R already comes with $\Sexpr{length(baseP)} + \Sexpr{length(recoP)}
    = \Sexpr{length(baseP)+length(recoP)}$ packages pre-installed,
    namely the "standard" (or "base") packages
\par\medskip
%% echo=false -- dann kann ich hemmungslos Tricks verwenden:
<<standard-packages, echo=false>>=
printPs <- function(ch, wid = 60)
    writeLines(strwrap(paste(ch, collapse=", "), wid, prefix= "  "))
printPs(baseP)
@
%  [1] "base"      "datasets"  "graphics"  "grDevices" "grid"
%  [6] "methods"   "splines"   "stats"     "stats4"    "tcltk"
% [11] "tools"     "utils"

\medskip  \pause and the "recommended" packages
\par\smallskip
<<recommended-pkgs, echo=false>>=
printPs(recoP)
@
%\footnote{}.
%  \\
%%--- now we can count, how many functions there are in all base +
%%--- recommended packages
%%  (this would not count S4 methods, would it ?)
\end{itemize}
\end{frame}

\begin{frame}[fragile]
\begin{itemize}
\item
  In R, by default you "see" only a basic set of functions,
  e.g., \\ \T{c}, \T{read.table}, \T{mean}, \T{plot}, \dots, \dots.
\item They are found in your \ul{search path} of packages
\pause
\par\medskip
<<clean-search,echo=false>>=
tpkgs <- c("fortunes", "sfsmisc", "tools")
for(pkg in paste("package", tpkgs, sep=":"))
    if(any(pkg == search())) detach(pkg, character.only=TRUE)
<<search-and-ls>>=
search() # the first is your workspace
@
\pause
<<search-and-ls-2>>=
ls(pos=1) # == ls()  ~= "your workspace" - cf "introduction"
str(ls(pos=2)) # content of the  2nd  search() entry
str(ls(pos=9)) # content of the  9th  search() entry
@
\end{itemize}
\end{frame}

\begin{frame}[fragile]%-- packages --
\begin{itemize}
\item
  The default list of R objects (functions, some data sets) is actually not
  so small: Let's call \code{ls()} on each \code{search()} entry:
\par\medskip
<<ls-functions-default>>=
ls.srch <- sapply(grep("package:", search(),
                       value=TRUE), # "package:<name>" entries
                  ls, all.names = TRUE)
fn.srch <- sapply(ls.srch, function(nm) {
    nm[ sapply(lapply(nm, get), is.function) ] })
rbind(cbind(ls   = (N1 <- sapply(ls.srch, length)),
            funs = (N2 <- sapply(fn.srch, length))),
      TOTAL = c(sum(N1), sum(N2)))
@
\begin{flushright}
i.e., \Sexpr{sum(N2)} functions in
R version \Sexpr{with(R.version, paste(major, minor, sep="."))}
% MM: in ESS have at least  .help.ESS  in base (duuh..)
\end{flushright}
% i.e., 2348 functions in R version 2.14.0.
% i.e., 2297 functions in R version 2.11.1.
% i.e., 2332 functions in R version 3.0.2
\end{itemize}
\end{frame}

\begin{frame}[fragile]% --- packages 2b ---
\begin{itemize}
\item
Till now, we have used functions from
packages \texttt{"base"}, \texttt{"stats"},  \texttt{"utils"}, \texttt{"graphics"},
and \texttt{"grDevices"} without a need to be aware of that.

\pause
\item \T{find("$\langle$\textit{name}$\rangle$")} can be used:
\par\medskip
<<find>>=
c(find("print"), find("find"))
## sophisticated version of  
## rbind(find("mean"), find("quantile"), ....):
cbind(sapply(c("mean", "quantile", "read.csv", "plot"),
             find))
@
\end{itemize}
\end{frame}

\begin{frame}[fragile]% --- packages 3 ---
  \begin{itemize}
  \item
  Additional functions (and datasets) are obtained by \\
  (possibly first \emph{installing} and then) loading additional packages.

  \item
  \Sc{library(MASS)} \quad or \quad\T{require(MASS)}
  \item
  How to find a command and the corresponding package?\\
    \Sc{help.search("...")}\footnote{can
      take l..o..n..g.. (only the first time it's called in an R session !)},
    \ (see Intro)
  \item On the internet: CRAN (\url{http://cran.r-project.org}, see
    %% The points to slide 1 instead of slide 15  --- AND that slide disappears (!??!)
    %% \\ \hyperlink{intro:CRAN-etc}{\beamergotobutton{Resources on the internet (slide 15)}}
    \ \beamergotobutton{Resources on the internet (slide 15)} \
    is a huge repository\footnote{actually a distributed Network with a
      server and many mirrors,} of R packages, written by many experts.
  % \item More search possibilities
  %   http://www.r-project.org/search.html \quad (\emph{before} using Google!)

  \item  \href{http://stat.ethz.ch/CRAN/web/views/}{\underline{CRAN Task Views}} help
    find packages by application area
  \item What does a package do?\\
    \Sc{help(package = class)} \ \ or ($\longleftrightarrow$) % equivalently
  \\ \Sc{library(help = class)}.

Example (of small recommended) package:
\smallskip
%% -- this goes to standard error -- not (yet) in LaTeX for slide:
%% -- see  print.packageInfo() -> goes via file.show() of writeFiles(format(.))
<<help-pkg, eval=FALSE>>=
help(package = class)
@
\end{itemize}
\end{frame}

\ifLongcourse%----------------------------------------------------
\begin{frame}[fragile]
<<help-pkg-2a, eval=FALSE>>=
help(package = class)
<<help-pkg-2b, echo=FALSE>>=
ft <- format(help(package = class))
ll <- capture.output(writeLines(ft))
writeLines(ll[2:23])
@
\end{frame}

\begin{frame}[fragile]
Second part of
<<help-pkg-3a, eval=FALSE>>=
help(package = class)
<<help-pkg-3b, echo=FALSE>>=
writeLines(tail(ll, -24))
@
\end{frame}
\fi%-LongCourse-----------------------------------------------------

\begin{frame}[fragile]
\frametitle{Installing packages from CRAN}
  \begin{itemize}
  \item Via the ``Packages'' menu (in RStudio or other GUIs for R)
  \item Directly via \code{install.packages()}\footnote{which is called
      anyway from the menus mentioned above}.

   \ul{Syntax}: \par \smallskip
   \Ts{install.packages(\farg{pkgs},\farg{lib},\farg{repos= getOption("repos")}, \ldots)}
   \par\smallskip

   \begin{description}
   \item[\farg{pkgs}:] character vector names of packages whose current
     versions should be downloaded from the repositories.
   \item[\farg{lib}:] character vector giving the library directories where to
     install the packages.  If missing, defaults to the first element of \code{.libPaths()}.
   \item[\farg{repos}:] character with  base URL(s) of the repositories to use,
     typically from a CRAN mirror.
     You can choose it interactively via \code{chooseCRANmirror()} or explicitly
     by \code{options(repos= c(CRAN="http://..."))} .
   \item[\farg{\ldots}:] many more (\emph{optional}) arguments.
   \end{description}
 \end{itemize}
\end{frame}

\begin{frame}[fragile]
\frametitle{Installing packages -- Examples}
  \begin{itemize}
  \item Install once, then use it via \code{require()} or \code{library()}:
   \par\smallskip
<<install-pkg, eval=false>>=
chooseCRANmirror()
install.packages("sfsmisc")

## For use:
require(sfsmisc) # to "load and attach" it
@
\item
<<install-pkg-2, eval=false>>=
install.packages("sp", # using default "lib"
       repos = "http://cran.CH.r-project.org")
@
\item or into a non-default  \emph{library} of packages:
   \par\smallskip
<<install-pkg-3, eval=false>>=
install.packages("sp", lib = "my_R_folder/library",
       repos = "http://cran.CH.r-project.org")
## and now load it from that library (location):
library(sp, lib = "my_R_folder/library")
@
\end{itemize}

Note that you need \emph{"write permission"} in the corresponding
"library", \ \linebreak[3] i.e., folder of packages (by default: \code{.libPaths()[1]}).
\end{frame}


\begin{frame}[fragile]
\frametitle{Maintaining your package installations}

Packages are frequently updated or improved. When new R versions are released, some packages need changing too. Therefore it is necessary to maintain your package installations. An easy way to do this is also via command line:

<<update-package,echo=TRUE,eval=FALSE>>=
update.packages()
@

This will invoke a dialogue where you can select which packages you would like to update. It will list the current version of the package and the version installed on your computer.

\end{frame}

%%% Local Variables:
%%% TeX-master: "slides"
%%% End: