package.Rmd

---
title: "Package"
author: "`r Sys.Date()`<br><p style='color:royalblue'>[Mansun Kuo](https://tw.linkedin.com/pub/mansun-kuo/82/3b4/344)</p>"
date: '`r Sys.Date()`'
#ratio: 4x3
ratio: 16x10
output: 
  rmdshower::shower:
    self_contained: true
    katex: false
    theme: material
    css: css/shower.css
params:
  refresh: no
---

```{r include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

# Package {.white .Section}

<img src="img/bali.jpg" class="cover">


# What is inside a R package

A typical R package may have following components:

- **R code**: Source codes written in R
- **Compiled code**: Compiled C, C++ or Fortran code 
- **Package metadata**: Metadata such as description, dependency, author, etc. 
- **Documentation**: Package and function's usage
- **Vignettes**: More detailed instruction about how to use this package
- **Tests**: Unit tests for functions
- **Namespace**: Define what functions import/export respect to other packages
- **External data**: Additional dataset in this package
- **Demo**: A interface to running some demonstration R scripts


# How to find a package you want

- Google with appropriate keyword. For example:
    - R \<algorithm name\>
    - R \<data format\>
    - R \<package name\>
- Task view
    - [Cran Task Views](https://cran.r-project.org/web/views/)
    - [R Documentation](http://www.rdocumentation.org/)
- [Awesome R](https://awesome-r.com/): A curated list of awesome R packages and tools
- [R-blogger](http://www.r-bloggers.com/) for latest R news


# Load package

- *library*
    - Load the namespace of the package with name package and attach it on the search list.
    - Return error if package not found

```{r}
library(argparser)
library("argparser")
```

- *require*: Just like *library* but return warning if package not found

```{r}
require(mansun)
```


# Namespace

Sometimes functions in different packages may have the same name.

- **pkg::name**: Export specific function in a package
- **pkg:::name**: Export internal variable/function in a package. 
  Don't modify these items if you know what you are doing.

```{r}
lubridate::date("2016-05-14") # access without load whole package    
library(lubridate, quietly = TRUE)
date("2016-05-14")  # convert date. base::date is masked
base::date()    # return system data and time
```




# Location of libraries

- **User specific library**: *R_LIBS_USER*
    - Libraries under user's home directory
    - Only can be accessed by the user in most situation.

- Common library: libraries for all users. Need administrator permissoion.
    - **System library**: *R_HOME/library*
        - Comes with R installation
    - **Site library**: 
        - Configured in *R_HOME/etc/Rprofile.site*

```{r}
Sys.getenv(c("R_LIBS_USER", "R_HOME"))
```


# libPaths

Libraries in R are loaded in order:

```{r}
.libPaths()
```

You can also add an additional library path:

```r
.libPaths(c("your/library/path", .libPaths()))
```

Or change the order of library search path:

```{r}
lpath <- .libPaths()
.libPaths(lpath[c(length(lpath), 1:max(1, length(lpath)-1))])
.libPaths()
```


# Change Privilege(Windows)

<img src="img/change_privilege.png" width="100%">


# Change Privilege(Linux/Mac)

Use chown and chmod to change owner and write permission of your install path.

- [chown](https://en.wikipedia.org/wiki/Chown): Change owner


```bash
chown mansun:mansun /usr/local/lib/R/site-library
```

- [chmod](https://en.wikipedia.org/wiki/Chmod): Change permission of access

```bash
chmod u+w /usr/local/lib/R/site-library
```


# Where can you find a R package 

- [CRAN](https://cran.r-project.org/): Official R package
- [GitHub](https://github.com/): The most popular web-based git repository hosting service
- [Bitbucket](https://bitbucket.org/): Also a git repository hosting service
- [R-Forge](https://r-forge.r-project.org/): Another CRAN-like website to access package
- [Bioconductor](https://www.bioconductor.org/): Specific for biostatistician


# Install from CRAN

- [install.packages](https://stat.ethz.ch/R-manual/R-devel/library/utils/html/install.packages.html)
    - Download and install packages from CRAN-like repositories or from local files
    - Type *?install.packages* to get further information
    - Packages are installed in the first element of *.libpaths()* if *lib* ins missing 
    - In RStudio: Tools -> Install Packages...
    - Be careful of system dependency
        - [Rtools](https://cran.r-project.org/bin/windows/Rtools/)(Windows), Java, XML, MySQL, ...

Install multiple packages: 

```r
install.packages(c("argparser", "jsonlite"), 
    lib = "/usr/local/lib/R/site-library")
```


Install development version of data.table:

```r
install.packages("data.table", type = "source",
    repos = "https://Rdatatable.github.io/data.table")
```


# Install package with RStudio

Yun can even using RStudio to install a package into system library or site library.

<img src="img/install_package.png" width="90%">


# Exercise

Try to install package **argparser** in system library or site library.


# Install a local files

You can also install a local tarball:

```r
install.packages("/tmp/Rtmp99mvkt/downloaded_packages/argparser_0.4.tar.gz", 
    lib = "/usr/local/lib/R/site-library", repo = NULL, type = "source")
```


# Install from github

Using *devtools::install_github* can easily install any R package on GitHub: 

To install [devtools](https://www.rstudio.com/products/rpackages/devtools/) make sure you have:
    
- [Rtools](https://cran.r-project.org/bin/windows/Rtools/) on Windows
- [Xcode command line tools](https://developer.apple.com/downloads) for Mac
- *r-devel* or *r-base-dev* on Linux

Then:

```r
install.packages("devtools")
```

Now you can install any package on github with single command:

```r
devtools::install_github('Rdatatable/data.table')
```

Just take a look what happened when you execute above command.

# References

- [Managing libraries](https://support.rstudio.com/hc/en-us/articles/215733837-Managing-libraries)
- [Initialization at Start of an R Session](https://stat.ethz.ch/R-manual/R-devel/library/base/html/Startup.html)
- [R Packages](http://r-pkgs.had.co.nz/)
- [package Development](https://support.rstudio.com/hc/en-us/sections/200130627-Package-Development)