My first package - IME-USP
Contents
1. functionnane Similar functions apropos functionname help search keyword search by keyword Editors for R In the R command line it is easy to quickly calculate things but writing functions is not very convenient Hence it is recommended to choose an appropriate editor A function can be saved in some kind of a text file on the hard disc and reloaded with source filename Tiny functions and code pieces can be submitted via Copy amp Paste Syntax highlighting auto completion and other features are desirable Editors for R o ESS Emacs Speaks Statistics http cran x project org other software htn1 for the well known Emacs or XEmacs editor With ESS it is possible to use X Emacs to control statistics software such as R and others conveniently o For Windows the free editor Tinn R attps sourcetorge net projects tinn r is available o as well as the R WinEdt interface for the commercial editor WinEdt not ready for WinEdt 6 x Packages O ee Package structured standardized unit of R code documentation data external code Packages are loaded by library Packagename and unloaded by detachO a Help on packages instead of functions can be accessed by library help Packagenane o On CRAN there are more almost 3000 packages available on all un thinkable topics you can not imagine o The Omega hat and BioConductor projects are maintaining their own2. What CRAN does _ ON a Initial check of the package on Linux o Make source package available in the repository Make binaries available for various OSs within less than a week Regular checks on different platforms Check summary pages http cran r project org web checks check_sumary html Package specific check summaries http cran r project org web checks check results tuneh html a Notifications in case the package is broken by a change in a dependency or R itself Win builder Builds Windows binaries and checks for validation of the R base system Builds and checks new and updated packages daily at least for Rerelease and R devel a Notification of developers Daily build of R devel 9 Re check all packages for R devel weekly Aim Make new errors of packages or R itself quickly visible to developers a Public system to build and check your won packages under Windows if that is not available for you http sin builder r project org at Win builder We need a check system that builds and checks at least within 24 hours for each flavor of R in order to provide check results when still of interest provide binaries directly after switching to alpha beta rc release phase CRAN Windows Binaries Last updated on 2011 04 04 09 50 06 Monday simplified No Package Verson R 2122 Inst time Check time 2953 ziecode 02 OK 3 a 2054 zipfR 065 OK 7 63 2
3. technische universitat dortmund Dept of Statistics Uwe Ligges April 2011 Bordeaux France Introduction and the usefulness of R packages a Installation and administration of R packages in libraries a Make the build tools work under Unix Mac OS and Windows Using R CMD build INSTALL check Development of R packages gt Data Functions Documentation format and processing o C Code gt Scoping issues gt Namespaces gt Debugging Let me start with some excerpts of a beginners R course _t Benefits and drawbacks Benefits Open Source Not a black box Within current research gt Extendability a Support Drawbacks What is R A language and environment for data analysis and graphics Open Source Tools for transfer of technology and methods using packages Data access mechanism a SSS es Where can I get R from R has some homepage http www R Project org and there is the CRAN Comprehensive R Archive Network http CRAN R Pro ject org R sources and binaries for some operating systems o Almost 3000 R packages for various statistical methods Functions All work is applied using functions Defaults are documented on the help pages Everything is an object both data and functions Help me Start the help system in a browser help start Help on a function help Functionnane
4. the default may be changed Functions Write your own functions in order to collect a sequence of other function calls to do the same thing more than once maybe with some parameters changed A function definition looks like this MyFunction lt function arguments statements where the arguments can be defined with or without defaults When the function is called the arguments are passed to the statements Statements may consist of several lines as far as they are enclosed in braces same is true for loops for example Functions A typical function definition might look like the following median lt fonction x na rm FALSE many lines of code sort x partial half half There are two arguments Only the second argument has a default FALSE o The last line of the function defines its value More than one object can be returned as a list of objects If return is called function evaluation stops and the argument of return is returned For a vector a the following calls may be sensible modian a na zm may be omitted the default median a TRUE arguments ordered correctly no names required median na rm TRUE x a named arguments Functions So we have to distinguish between formal arguments in a function s definition and actual arguments as specified in the function call The rules to match actual and formal arguments are applied in the following way At first
5. 2004 Lazy loading and packages in R 2 0 0 R News 4 2 2 4 a Ripley B D 2005a Internationalization features of R 2 1 0 R News 5 1 2 7 Ripley B D 2005b Packages and their management in R 2 1 0 R News 5 1 8 11 Venables W N and Ripley B D New York Venables W N and Ripley B D 2002 Modern Applied Statistics with S 4 ed Springer New York Zeileis A and Hornik K 2006 ctv CRAN Task Views R package version 0 3 2 2000 S Programming Springer
6. 5 2 for 64 bit R grouping of packages also by priority gt no need to specify 1b if the first place of the search path is the bi arch binaries for both R and packages right iran o administration package ctv Zeileis and Hornik 2006 gt the argument dependencies TRUE implies to install all declared o which structure is available available views dependent and suggested packages of the package a install all packages of one group install views o update packages Exampl Installs new versions of packages from the repositories argument checkBuilt TRUE implies recompiling of packages after a major upgrade of R Library ctv temp lt available views tenpL 8 install vieus Machinelearning coreOnly TRUE Source vs Source packages are independent of the platform hardware operating system gt Prerequisites for installing source packages Perl C compiler Fortran compiler CRAN accepts only source packages gt Standard way of distributing packages for Unix like systems Linux Solaris Binary packages are platform specific and may depend on the R Binary packages can be installed without prerequisites shared abject files and DLL help pages meta information are already precompiled in a binary package CRAN provides binary packages for recent R versions for some platforms e g Windows and MacOS X PowerPC Intel Binary pac
7. can explicitly import objects from other namespaces These cannot be accidently overloaded afterwards Packages loaded 2 package mothods d X id only here lt 2 import directives are not attached to the search path 1 package stats package stati newFoo lt function 0 GlobalEnv 4 Workspace S cei A frein fom some varpain ok objets eating the i enviroment i Fanction 1 Por following rules at first it looks into the own namespace then into 2 environment 2 Function 2 imported objects or namespaces then into the base namespaces 3 environment 3 Function 3 and then the already known scoping rules are applied value lt 1 scope Type search for the current search path VduBi geet diee ds ERR only here lt 4 value gt R 2 S Plus 4 Scoping rules Namespaces Namespaces Examples Some more rules in addition to the known scoping rules how to search a For explicit access to an object in a package with namespace the objects in existing environments have been introduced by R s 1 operator can be used which separates the name of the adipe lt 2 fases Namespaces support namespace and the object s name Hence stats ks test t accesses the object function ks test in namespace stats xci gt The number of contributed packages increases almost daily hence In rare cases you want to access non exported functions which can iier dc Fetal you can expect name clashes of function between all those
8. packages happen by calling getF osNamaspace print Ge Namespaces define which objects are visible to the user and to other Slo operati eaa en aas a vierte CC ds Wl innerO functions and which are only visible within the own namespace aides haiie eea favi iind Functions that are not exported are only visible within the own namespace x45 eau fce getAnyshere all objects in the search path and loaded scope 3 4 S Plus 5 namespaces are looked up Namespaces OO Cl Examples Library MASS 1da methods 1da lda default getS3method 1da default getAnywhere 1da default MASS 1da default load MASS function lda generic Which methods lda default is not exported look at it anyway the file NAMESPACE The file NAMESPACE in the toplevel directory of your package define objects to be imported and exported export and exportPattern for exporting many objects at a time define code to be loaded in form of an external library such as a DLL useDynLib define S3 methods S3method a import imports a whole namespace importFrom imports objects from another namespace S4 objects a exportClassesO exportitethods gt AmportClassesFron inportHethodsFron the file NAMESPACE Example useDynLib nyPackage export foo2 S3method print myClass import klan mportFrom MASS 1da Debugging If you writ
9. pi x This means a function that has been created in some specific a If a function returns its environment is deleted incl all the objects environment and assigned to some object outside of the function it contains Therefore you have to returnO objects for further then you probably expect that the objects sin and pi are from aftara alins haus all object Of the originating etviconment package base If there are functions with the same names in other packages or the workspace the latter objects would be found before those in base big Therefore under such circumstances an environment is not deleted but o The functions assignO and get can assign objects to or only if no furiction has been returved get objects from arbitrary environments This feature might be beneficial but also confusing because scoping rules are different In the latter case also consult Venables W N and Ripley B D 2000 foo function x sin 2 pix foo 1 8 Expected 1 2 4492130 16 4 898425 16 There are some more exceptions from the described scoping rules most sin lt sum important one is implemented by namespace rules which will be described pic 0 5 later foo 1 5 Sum of 1 5 15 mer ecc MTM E p Scoping rules CM Scoping rules Namespaces Examples a A namespace guarantees that no objects from base are masked for 8 package base functions in other namespaces 7 kutoloads n l scope lt function a You
10. 055 zoeppritz 102 OK 1 16 2956 200 164 OK 4 69 2087 yp 091 OK 2 18 Sum in hours 2x Xeon E5430 Quad 84 8 720 8 C C or Fortran code Why do we want to have compiled code Speed Make use of already existing external efficient libraries Calling compiled external sources can be done by the interfaces CO CallO Fortran and External A couple of important macros is defined in the header files R b and Rinternals h 2 Sometimes it is also useful to look into Rdefines h for S4 and friends C C or Fortran code o Cade is compiled automatically during package installation R CMD INSTALL compiles code in the package directory src dyn load filename resulting library Library packagename should load it if in a package library dymam can be used in function First libO in zez R oF define it in your Namespace later on loads and dyn unload unloads the R CMD SHLIB compiles the code without installing a whole package i e you can invoke compiler and linker manually do never forget the garbage collector Example C with Call As a simple example we are trying to add two real valued vectors a and b by a call through Cal10 File c test c include Rinternals h SEXP add SEXP a SEXP b int i n n length a for i 0 i lt n ie REAL a i REAL b i return a Example C with Call add a b SEXP Symbolic EX
11. Pression o returning the a still an R object No new R object has been generated hence no PROTECT required Example C with Call Now we can generate a library from the C file test c using R CHD SHLIB R CMD SHLIB test c gcc I t R include 03 Wall std gnu99 c test c o test o gcc shared s o test dll tmp def test o Lt R bin 1R Some files are generated now particularly file add d11 Windows or add so Unix respectively Example C with Call R code dyn load c test d11 load the library or library Packagename if in some package Definition of the calling R function add lt function a b if lis numeric a lis numeric b stop a and b must be numeric if ength a length b stop a and b must have same length Call add as double a as double b add 4 3 8 9 Functions a All work in R is done by functions a A function call has the form functionmame argumenti argi argument2 arg2 etc where the arguments can be specified by name or not gt There are some special functions with convenient abbreviations such You can rewrite 3 6 to its real function call The name is not a regular one hence the quotes An assignment has the full form lt x 3 se 8 o There are arguments with defaults An argument without default must be specified in a function call An argument with default may be specified in a function call and
12. all arguments with completely given names are matched x 1 10 Then arguments with partially given names are matched to the remaining formal arguments na TRUE Next all unnamed arguments are assigned in the given order to the remaining formal arguments All remaining arguments are assigned to the three dots argument You can test if a formal argument is missing in a call by missing Functions It is possible to use the formal three dots argument in the definition of a function All non matching actual arguments in the sense of not matching to any other argument are collected by This can be handled within the function or what is more common passed to other functions via Examples ThreePoints lt function x xex 2 median x gt x lt log 1 100 ThreePoints x ThreePoints x na rm TRUE o Sans Scoping rules Lazy evaluation _ ee R uses lazy evaluation of functions arguments i e statements used as actual arguments will be evaluated in their first usage but not before Exampl lazy function x calc TRUE if calc x lt x i print a H lazy a lt 3 calc FALSE lazy a 3 label function x return list call substitute x value x Label 1 2 During programming the question arises When are what objects visible for which functions If you work in the R console directly all new objects are created within
13. ation binary packages More than one library makes sense Summary of R functions Some tools are missing on typical Windows systems sues avallable packages packages in selected repasiterias o Windows shell command line differs from typical Unix systems o Structuring packages download packages download packages o Developer and user library install packoges install packages For CRAN like repositories R looks for packages in e g CRAN mirror bin windows contrib 2 12 central installation no write permission for users vs local library of installed packages locally installed package own packages new packages package in repository that are not installed locally ReadMe contains information what happened to packages not old packages locally installed package with newer versions in the passing R CHD check Examples repository o GUI available for R under Windows Packages provides the updatepackages update package interface for install packagesO etc o central library of standard packages e g all installations into 1ibPathsO 1 n software R x y 2 library contrib url generates canonical form of repository central library of CRAN packages e g n VsoftuareVRLibsVCRAN packageStatus considered to be the future since several years a central library of BioC packages e g n software Rlibs BioC o local user library e g d something myRlibs work a local developer library e g d so
14. e your own functions you will make mistakes IF it is a small function it may be easy to find the error gt In more complicated functions it may be worse to find a bug leading to nervous breakdowns R offers some tools for easy debugging It is advisable to debug your own package with deactivated Namespace i e just rename the NAMESPACE file and reinstall otherwise see debugInNamespace Beside those tools you can print print cat objects or informative texts to the console of course Debugging with tools o traceback shows which function has caused the last error including the stack path of calls This way you can find the bad function even within very encapsulated function calls gt debug foo enables debugging for the function foo i e it will be executed within some browser see below until debugging is turned off again with undebug foo browser starts the browser at this place within a function o recover and options error recover If an error emerges the browser is started so that you can jump into one of the environments that existed at the time where the error occured Debugging with tools Examples fool lt function s fool lt function x feol lt function x foo2 lt function 2 food lt function x s foo2 lt function x s xta 5 browser print yerri 1 xis S 1 ails s foxy s 13 1 B Iyexti Iyexei foo2 y s 8 1 f
15. functions by Venables and Ripley 2002 nnet Neural nets feed forward with one hidden layer and multinomial log linear models Spatial Spatial statistics Extensions R is extremely extensible by the user It is possible to write your own functions generate standardized documentation for these functions integrate C C or Fortran code in form of a shared library DLL o create packages that include the before mentioned things and that can easily be installed and distributed If you have written some useful code that implements some interesting method you might want to publish it on CRAN in form of a package like many others did already Why Packages Why should we package anything Dynamical loading of packages saves memory Easy installation and update of packages locally or from the web within R or from the OS s command line o Easy administration use global department s server and local libraries at the same time Validation R includes features for checking code documentation and installability as well as testing the results of pre defined calculations easy distribution to others using a standard mechanism o Example data The LUS 8 package Proposed S PLUS Packages AnS PLUS package is a collection of S PLUS functions data help files and other associated source files that have been combined into a single entity for dist
16. in XPATH Set environment variable TMPDIR otherwise TEMP is used Structure of packages A package consists of some standard files and directories the latter containing certain files as described in the manual Writing R Extensions DESCRIPTION file with standardized formatted entries for author license title dependencies NAMESPACE file for generating a Namespace o man directory contains documentation in Rd format RY directory contains R code data directory contains data sets o src directory contains C C or Fortran sources o tests directory contains files for validation demo directory contains R Code for demo purposes inst directory contains stuff that is to be copied in the main directory of a binary package e g Vignettes Except for the DESCRIPTION file all other items above are optional Package generation Examples gt package skeleton name Creating directories Creating DESCRIPTION Creating READMES Saving functions and data Making help files Done MyPackage ListOf bjects path Further steps are described in MyPackage README Package generation package skeleton o generates a skeleton for package MyPackage o with files from ListOfObjects a in the given path here the current working directory generates first version of the file DESCRIPTION generates first versions for the documentati
17. kages for Windows are provided roughly two days after the source packages appear Source vs Distinction between binary and source packages by line starting with Built in file DESCRIPTION Built R 2 12 2 i886 pe mingw32 2011 04 11 09 30 00 UTC ul o File extensions by agreement a tar gz Source package zip binary package for Windows tgz binary package for Mac gt deb or rpa binary package for Linux Package admi For locally available source package it is more common to use the OS s command line R CMD INSTALL 1 Path to library Paket If 1 Path to library is not given to specify the library explicitly first library from environment variable R LIBS is used main library is used Renviron is not evaluated by R CHD Source packages under Configure your environment See R Development Core Team 2011a Ligges and Murdoch 2005 R tools http waw murdoch sutherland com Rtools collection of cygwin based shell tools MinGW gee 4 5 x distribution libraries for bitmap jpeg support vanilla perl a libraries for tel tk support o BTEX e g MIKTeX http www miktex org Source packages under Set paths in environment variable PATH to local and all Nbin paths should happen automatically if selected PATH jc devel tools bin c devel WMinGi bin devel R 2 12 2 bin c devel Perl bin devel texmf miktex b
18. mething nyR1ibs devel Package adi strati n binary packager Package administration focal binary packages Package adm Document The argument type in install packages update packages Example and friends can be set to Install the binary package MyPackage from the local file a Manual R Installation and Administration c Vsoneshere MyPackage 0 0 1 zip into c myR nyLibrary a The R FAQ and R for Windows FAQ Loa o R Help Desk Package Management in R News 3 3 o win binary gt install packages o mac binary leopard c somewhere MyPackage_0 0 1 2ip Repositories lib c somewhere myLibrary CRAN NULL o mac binary CRAN GRAN extras for Windows BioConductor Omega The default is the appropriate binary type on Windows and on the CRAN o setRepositories or options repos binary Mac OS X distribution otherwise it is source Thes can be for selecting repositories overridden to install from sources under Windows for example o chooseCRANmirror and chooseBioOmirrorO for choosing mirror servers 32 vs 64 bit Windows bi CRAN Task install packages package lib Path to library Since 2120 o CRAN contains almost 3000 packages Confusing Package admi gt automatically downloads the most recent version of a package from o CRAN Task Views Provide some summary and structure by topics the repositories and installs it use gcc 4 5 0 for 32 bit and gcc 4
19. n Vasage function call including all arguments and their defaults Vargusents description of all arguments and their meaning Value description of the returned value s aetaile more detailed description references references methods implementation algorithms seealeo Tinks to other relevant documentation of other functions Vexamples examples how to use the function Weyucrd standardized keyword Packages Documentatii o standardized defaults as well as self defined sections allow for mathematical formulas URLs links to other help pages computation in and on help pages etc a Layouted documentation from Rd files can be generated directly by gt R QD R conv for conversion to LEX HTML and formatted ASCII text gt R CHD Rd2dvi for conversion to DVI and Adobe PDF Packages Documentation The R packaging system checks using R CMD check if documentation is available for all exported data sets and functions in a package o the usage part corresponds to the actual definition of the function o the code in section examples can be executed without any error all the arguments of a function are documented all the defaults are documented Rd files can be converted to the different formats Vignettes Vignettes are in the installed package in form of PDF files are in the source package in directory inst doc o are shown with vignette package vignette viewp
20. on file in Rd format you just need to them fill out a tells us what to do next Next steps are v If all files have been edited you can build the package by R CHD build R CHD INSTALL installs the package R CHD check checks for consistency installability documentation Packages Data and funci Each data set and each function lives in a separate file regularly named by object name gt function close to each other such as generics with methods are sometimes contained in one file regularly with corresponding documentation in man o Data can be loaded with data and has to be put into the data directory in one of the formats rectangular text file separated by blank or comma extension csv tab or tat a R source code written by dump extension z or amp and R binary file written by save extension rda or RData Code that should be executed once the package is loaded should go into the file R zzz R Packages Documentation o Help pages written in Rd format o Manuals and reports Package Vignettes with SWeave Help pages package skeleton prepares all Rd files for a package a prompt prepares a separate Rd file for one object to be documented o BTEX like syntax Example for an Rd file name Name of help page commonly alias Valias Name s of function s that are described itle tle Mdescription short descriptio
21. oo2Qy s n n 1 1 foot 1 6 toot 1 5 Moot 1 8 traceback 1 loptions error recover I o01 1 5 References Core manu Online at http CRAN R Project org nanuals html and in R R Development Core Team 2011a R Installation and Administration ISBN 3 900051 09 7 R Development Core Team 2011b R Language Definition ISBN 3 900051 13 5 R Development Core Team 2011c R A Language and Environment for Statistical Computing ISBN 3 900051 07 0 R Development Core Team 2011d Writing R Extensions ISBN 3 900051 11 9 The R Journal formerly R News http journal x project org References R I o Chambers J M 2008 Software for Data Analysis Programming with R Springer New York Gentleman R and Ihaka R 2000 Lexical Scope and Statistical Computing Journal of Computational and Graphical Statistics 9 491 508 Ihaka R and Gentleman R 1996 R A language for data analysis and graphics Journal of Computational and Graphical Statistics 5 299 314 Leisch F 2002 Sweave User Manual http www ci tuwien ac at leisch Sweave Ligges U 2003 R Help Desk Package Management R News 3 3 37 39 o Ligges U and Murdoch D 2005 R Help Desk Make R CMD Work under Windows an Example R News 5 2 27 28 References R II o Murdoch D and Urbanek S 2009 The New R Help System The R Journal 1 2 60 65 Ripley B D
22. ort grid package grid SWeave Generating vignettes using SWeave Leisch 2002 o Code Text Text lt lt Options gt gt Code chunk E more text Sweave helps to integrate code and text automatically R evaluates the code and returns the results TEX renders the text reproducible data analysis and research easily re generate reports with minor changes in the data c R CHD check checks whether code can be executed and evaluated there is something called odfWeave Package install and ch Package if all files have been generated R CHD build builds the package and generates the vignettes Install R CMD INSTALL o Check R CHD check Consistency installability Documentation as mentioned before Test cases files in directory test s Results Rout files are compared with true results given as Rout save files ees R forge http r orge r project org is a cental developer platform for R packages offering easy access to the best in SVN o daily built and checked packages o mailing lists message boards forums o bug tracking a site hosting a permanent file archival full backups total web based administration Submitting to CRAN o Be sure your package passes the checks without any WARNINGS or ERRORS in R devell o Upload the source package to ftp cran r project org incoming a Send e mail message to crantr project org
23. package repositories An R standard installation loads the packages base datasets graphics grDevices methods stats and utils on startup o Several package including base are shipped with R a as well as several important recommended packages additional standard packaj base R base package datasets Collection of datasets graphics Graphics functions grDevices Graphics devices grid Re design for graphics layout e g for lattice methods S 4 methods Chambers 1998 splines Splines stats Common statistical functions tests stats4 Same as stats with S 4 classes Teltk GUI programming with tcl tk tools Tools for package development administration documentation utils Some helper functions additional e O boot Bootstrap methods Davison and Hinkley 97 luster Cluster methods Rousseeuw et al codetools Code analysis foreign Import and export from and to Minitab S SAS SPSS Stata KernSmooth Kernel density estimation and smoothing Wand amp Jones 95 lattice Trellis graphics Cleveland 93 Matrix Matrix classes e g for sparse matrices me Generalized additive models nime Won linear models with mixed effects Pinheiro amp Bates 00 Tpart Recursive partitioning survival Survival analysis hazard Cox censoring Packages by V amp R dass Classification MASS Collection of
24. ribution to other S PLUS users This package system is modeled after the package system in R Insightful Corporation hosts the Comprehensive S PLUS Archival Network CSAN site at http csan insightful com to facilitate S PLUS package distribution Packages can be downloaded from the CSAN websites in two forms as raw source code or as Windows binaries S g paw c M int nn Load packages from lib Installed R packages live in a library i e some directory a and can be loaded from that library by library Packagename lib loc Path to library libPathsO shows which libraries are looked up for packages automatically A library can be added by or the library can be set before the start of R in the environment libPaths to the search path variable R_LIBS eg in file Renviron nome user myR myLibrary home user nyR develLibrary Both base and recommended packages are in the main library in directory R_HOME Library RHOME is the path that points to the current version of R e g asr 1ocal lib R or c Program Files R x y 2 Default is to install new packages into the first place of the result of Libpaths Load packages from librari Exampl Library help survival help Library survival load detach package survival unload libPaths c tenp set library libPaths ibraries B Package administration Package administr
25. the workspace In more complex functions many objects are generated that are only of temporary use Hence it makes sense to evaluate functions in separate environments in order not to clutter the workspace with unneeded objects Therefore things are more transparent and less RAM is consumed This means assignments within a function will not be saved in the workspace And objects from the workspace should be passed as arguments to functions that require those objects Scoping rules Some more detailed comments related to Scoping Rules follow R keeps all environments in its main memory RAM o All top level generated R objects go into the workspace GlobalEnv number 0 o There is some search path of environments containing packages for functions and data bases for data fram es At the center there is the GlobalEnv workspace at the end the base package and in between some objects added to the path by calls to libraryO or attach Ifa function is called a new environment starting with number 1 is created a W a function is called within the former function the next environment is generated Namespaces Search rule is that a function looks for objects a in its own R is capable of so called Lexical Scoping Gentleman R and Ihaka R Consider you define environment b the one of its parents c the workspace and d 2000 all the attached packages and data bases foo lt function x sin 2
Download Pdf Manuals
Related Search