Is R functional or object-oriented

FUNCTIONAL AND OBJECT-ORIENTED PROGRAMMING IN R

Dr. Christian Knüpfer Institute for Computer Science, Friedrich Schiller University Jena FUNCTIONAL AND OBJECT-ORIENTED PROGRAMMING IN R LECTURE IN SS 2019 06/10/2019 R1. READER PACKAGES http://ogy.de/fopr Last change: 27.05.2019 12:01

Dr. Christian Knüpfer Institute for Computer Science, Friedrich Schiller University Jena FOPR R1. Reader packages (06/10/2019) Front page (R1-1) FUNCTIONAL AND OBJECT-ORIENTED PROGRAMMING IN R LECTURE IN SS 2019 06/10/2019 R1. READER PACKAGES http://ogy.de/fopr Packages: Summary of functionality Control of the visibility of variables through imports and exports using the namespace of a package

PACKAGES IN R Organization of R programs Extensions of functionality and data Dynamic loading / unloading Standardized installation and updating Integration of external code Control of dependencies Validation of standardized documentation Modularity and encapsulation Distribution of R programs Knüpfer: FOPR R1. Reader packages 06/10/2019 R1-2

PACKAGES IN R FOPR R1. Reader packages (10.06.2019) Packages in R (R1-2) Organization of R programs Extensions of functionality and data Dynamic loading / unloading Standardized installation and updating Integration of external code Control of dependencies Validation Standardized documentation Modularity and encapsulation Distribution of R- Installation standardized for programs: simple management of the installed packages, both system-wide and user-specific, two types of packages: Source package: Package distributed in the source code, automatic translation during installation Binary package: already compiled for the corresponding platform (Windows, Mac OS, Linux) Integration of external code for example in C, C ++, Fortran. For source packages with external code, appropriate compilers must be available.

STRUCTURE OF A PACKAGE Package directory: DESCRIPTION Description of the package INDEX index of all data and functions NAMESPACE imports and exports of the namespace R / directory with R code data / directory with data records man / directory of the documentation ... For details see [R-extensions] Knüpfer: FOPR R1. Reader packages 06/10/2019 R1-3

STRUCTURE OF A PACKAGE For details see [R-extensions] FOPR R1. Reader packages (10.06.2019) Structure of a package (R1-3) Package directory: DESCRIPTION Description of the package INDEX Index of all data and functions NAMESPACE Imports and exports of the namespace R / directory with R code data / directory with data records man / directory of the documentation ... name of the package directory is the same as the package name here only the most important files and directories other files: LICENSE, NEWS, configure other directories: src / (external code), demo, vignettes DESCRIPTION also contains dependencies INDEX normally automatically generated man / documentation in Rd format , other formats are generated automatically (e.g. in the html / directory) for details on the documentation see below

PACKAGES IN RSTUDIO Package management: lower right panel, tab Packages Load / Unload Set / remove check mark in front of package name Install package Install button INDEX file: click package (Help Pages section) DESCRIPTION file: click DESCRIPTION file Documentation from man /: click function name package Uninstall button X (behind package name) Knüpfer: FOPR R1. Reader packages 06/10/2019 R1-4

PACKAGES IN RSTUDIO FOPR R1. Reader packages (06/10/2019) Packages in RStudio (R1-4) Package management: lower right panel, tab Packages Load / Unload Set / remove check mark in front of package name Install package Install INDEX file button: Click package (Help Pages section) DESCRIPTION file : Click on the DESCRIPTION file Documentation from man /: Click on the function name Uninstall the package Button X (behind the package name) Try it out in R-Studio! Package management distinguishes between user-specific (User Library) and system-wide (System Library) packages. Directory for user-specific packages is system-dependent. Installation path is displayed during installation. Tasks: Install any package with RStudio! Explore the package in RStudio! Find the directory in which the package was installed! Compare the contents of the directory with the RStudio information for this package!

EXERCISE R1.1 Task: Creating a package structure Use the package.skeleton () function to create a package directory for your project work! First find out how to use this function in the help! After creating the package structure, create a corresponding description of your package in the DESCRIPTION file! Find out about the structure of this file in the documentation for creating R packages 1! 1 [R-extensions] knotter: FOPR R1. Reader packages 06/10/2019 R1-5

EXERCISE R1.1 1 [R-extensions] FOPR R1. Reader packages (10.06.2019) Exercise R1.1 (R1-5) Task: Creation of a package structure Use the package.skeleton () function to create a corresponding package directory for your project work! First find out how to use this function in the help! After creating the package structure, create a corresponding description of your package in the DESCRIPTION file! Find out about the structure of this file in the documentation for creating R packages 1! Note: Package created in subdirectory of the current directory (change directory beforehand if necessary) Further steps in Read-and-delete-me View content of the package directory Transfer: Do not create the package yet! We will deal with that afterwards.

CREATING A PACKAGE 1. Creating the package structure: package.skeleton () 2. Editing the package content 3. Checking the package: $ R CMD check package name 4. Creating the package: $ R CMD build package name 5. Installation package: $ R CMD INSTALL package name Knotter: FOPR R1. Reader packages 06/10/2019 R1-6

CREATING A PACKAGE FOPR R1. Reader packages (10.06.2019) Creation of a package (R1-6) 1. Creation of package structure: package.skeleton () 2. Editing of package content 3. Checking package: $ R CMD check package name 4. Creation of package: $ R CMD build package name 5. Installation package: $ R CMD INSTALL package name typical process for creating a package Development of the R code completed as soon as possible Further development of the R code in the package directory! $: Execution in Shell Note that the commands are case-sensitive!

EXERCISE R1.2 Task: Creating a package Check and create your package for the project work! Then install the package and try to load it in R! RStudio supports working with packages! Create a new project in RStudio from your package and familiarize yourself with the possibilities! In particular, use the file browser (files) to view your package directory, the editor to edit DESCRIPTION and the built-in options for the above tasks of creating the package (build)! Knotter: FOPR R1. Reader packages 06/10/2019 R1-7

EXERCISE R1.2 FOPR R1. Reader packages (10.06.2019) Exercise R1.2 (R1-7) Task: Creating a package Check and create your package for the project work! Then install the package and try to load it in R! RStudio supports working with packages! Create a new project in RStudio from your package and familiarize yourself with the possibilities! In particular, use the file browser (files) to view your package directory, the editor to edit DESCRIPTION and the built-in options for the above tasks of creating the package (build)! Documentation incomplete check will therefore probably fail first remove the man / directory package management in RStudio see above

DOCUMENTATION WITH RD FORMAT Rd files for documentation of functions, data sets and packages Rd format translatable into other formats (LA TEX, HTML, PDF, Plain Text) Rd format based on LA TEX syntax translated into structured help view when installing packages \ name {perimeter} \ alias {perimenter} \ title {circumference} \ description {calculates the circumference of a circle.} \ usage {perimeter (d)} \ arguments {\ item {d} diameter of the circle.}} \ value {the perimeter of the circle.} ... weaver: FOPR R1. Reader packages 06/10/2019 R1-8

DOCUMENTATION WITH RD FORMAT \ name {perimeter} \ alias {perimenter} \ title {circumference} \ description {calculates the circumference of a circle.} \ Usage {perimeter (d)} \ arguments {\ item {d} diameter of the circle. }} \ value {the perimeter of the circle.} ... FOPR R1. Reader packages (10.06.2019) Documentation with Rd format (R1-8) Rd files for documentation of functions, data sets and packages Rd format translatable into other formats (LATEX, HTML, PDF, Plain Text) Rd format syntax LATEX based on package installation translated into structured help view Example comes from exercise F3.1 Description of several functions can be summarized in one Rd file (\ name vs. \ alias) Transition: Description incomplete, for details see the following exercise

EXERCISE R1.3 Task: Documentation of a function Document a function from the package of your project work! You can use prompt (function name) to prototype the rd file for a function. Find out about the structure of the Rd file in the documentation for creating R packages 2! Then move the rd file into the man / folder of your package and create / reload the package! Test the help for your function! 2 [R-extensions] knotter: FOPR R1. Reader packages 06/10/2019 R1-9

EXERCISE R1.3 2 [R-extensions] FOPR R1. Reader packages (10.06.2019) Exercise R1.3 (R1-9) Task: Documentation of a function Document a function from the package of your project work! You can use prompt (function name) to prototype the rd file for a function. Find out about the structure of the Rd file in the documentation for creating R packages 2! Then move the rd file into the man / folder of your package and create / reload the package! Test the help for your function! RStudio: Preview for Rd files Try it out in RStudio: View the elements of the structured documentation in the help view for your function!

NAMESPACE Make names visible: export (f, g) Make names visible: exportpattern ("^ [[: alpha:]] +") Import from another namespace: import (pkg1, pkg2) Special import from another namespace: importfrom (pkg, f, g) direct access to other namespace: pkg :: f; pkg ::: g knotter: FOPR R1. Reader packages 06/10/2019 R1-10

NAMESPACE FOPR R1. Reader packages (06/10/2019) NAMESPACE (R1-10) Make names visible: export (f, g) Make visible with name pattern: exportpattern ("^ [[: alpha:]] +") Import from another namespace: import (pkg1, pkg2) special import from another namespace: importfrom (pkg, f, g) direct access to another namespace: pkg :: f; pkg ::: g Mechanism of checking what is externally visible (export) and what is required by other packages (import) library (pkg) makes exported names available Name pattern (regular expression) exports all names that begin with a letter. This name pattern is created by package.skeleton (). :: allows access to exported names, ::: also to non-exported names (not recommended!) Imported packages must be listed as dependencies in DESCRIPTION! Likewise, all packages loaded with library () or require () and packages referenced in references using :: and :::.

Task: Namespace EXERCISE R1.4 Edit the file NAMESPACE of the package of your project work! Specify the exports and imports explicitly! Think carefully about which functions are visible to the outside and which names are required from other packages! Avoid using patterns for exports! Build and reload your package! Check the exports using getnamespaceexports ()! Knotter: FOPR R1. Reader packages 06/10/2019 R1-11

EXERCISE R1.4 FOPR R1. Reader packages (10.06.2019) Exercise R1.4 (R1-11) Task: Namespace Edit the NAMESPACE file of the package of your project work! Specify the exports and imports explicitly! Think carefully about which functions are visible to the outside world and which names are required from other packages! Avoid using patterns for exports! Build and reload your package! Check the exports using getnamespaceexports ()! exportpattern () should be avoided! It is better to explicitly state what is being exported. Economy in exports and imports improves modularity!

ROXYGEN2 inline documentation of functions (rd files) # 'Creates a vector in a new environment. # '#' @param n Length of vector. # '#' @return An environment containing a # 'random vector of length \ code {n}. Management of exports and imports (NAMESPACE) # '@export #' @importfrom stats rnorm Rstudio: Code / Insert Roxygen Skeleton Usage: roxygenise () Linker: FOPR R1. Reader packages 06/10/2019 R1-12

ROXYGEN2 FOPR R1. Reader packages (10.06.2019) roxygen2 (R1-12) inline documentation of functions (Rd files) # 'Creates a vector in a new environment. # '#' @param n Length of vector. # '#' @return An environment containing a # 'random vector of length \ code {n}. Management of exports and imports (NAMESPACE) # '@export #' @importfrom stats rnorm Rstudio: Code / Insert Roxygen Skeleton Use: roxygenise () Requires package roxygen2, which may have to be installed first (see exercise R1.5 below)! Advantages: R-code and documentation together, necessary files (Rd files, NAMESPACE) automatically generated further tags possible (see documentation for the roxygen2 package)

EXERCISE R1.5 Task: Using roxygen2 Install the roxygen2 package in R 3! Document a function from the package of your project work with roxygen2 comments! Also write appropriate instructions for imports and exports! Also add examples for the use of the function under the @examples tag! Execute roxygenise () for your project and look at the generated files! The Rcpp package must first be reinstalled in Linux Pool I! Knotter: FOPR R1. Reader packages 06/10/2019 R1-13

EXERCISE R1.5 In Linux Pool I, the Rcpp package must first be reinstalled! FOPR R1. Reader packages (10.06.2019) Exercise R1.5 (R1-13) Task: Using roxygen2 Install the package roxygen2 in R 3! Document a function from the package of your project work with roxygen2 comments! Also write appropriate instructions for imports and exports! Also add examples for the use of the function under the @examples tag! Execute roxygenise () for your project and look at the generated files! Dependency problem with installation in Linux pool I: required Rcpp package is installed system-wide in a version that is too old. Solution: Reinstall the Rcpp package before installing roxygen2 alternatively: Use the latest R Consult the help for the roxygen2 package!

LITERATURE [R-extensions] [Ligges] R Core Team: Writing R Extensions. Version 3.4.0. R Foundation for Statistical Computing. Vienna, Austria, April 21, 2017. url: https://cran.r-project.org/doc/manuals/rrelease/r-exts.pdf. Uwe Ligges: Programming with R. 3rd ed. Berlin, Heidelberg: Springer, 2008. isbn: 978-3-540-79998-6. doi: 10.1007 / 978-3-540-79998-6. Full text accessible from the FSU network. Knotter: FOPR R1. Reader packages 06/10/2019 R1-14

[R-extensions] [Ligges] REFERENCES R Core Team: Writing R Extensions. Version 3.4.0. R Foundation for Statistical Computing. Vienna, Austria, April 21, 2017. url: https://cran.r-project.org/doc/manuals/rrelease/r-exts.pdf. Uwe Ligges: Programming with R. 3rd ed. Berlin, Heidelberg: Springer, 2008. isbn: 978-3-540-79998-6. doi: 10.1007 / 978-3-540-79998-6. Full text accessible from the FSU network. FOPR R1. Reader packages (10.06.2019) Literature (R1-14) [R-extensions]: everything about R packages and documentation [Ligges]: short introduction to packages