Introduction to pacman

Tyler W. Rinker & Dason Kurkiewicz

The pacman package is an R package management tool that combines the functionality of base library related functions into intuitively named functions. This package is ideally added to .Rprofile to increase workflow by reducing time recalling obscurely named functions, reducing code, and integrating functionality of base functions to simultaneously perform multiple actions. The function p_load is particularly well suited for help forums and blog posts, as it will load and, if necessary, install missing packages.

Function names in the pacman package follow the format of p_xxx where 'xxx' is the task the function performs. For instance the p_load function allows the user to load one or more packages as a more generic substitute for the library or require functions and if the package isn't available locally it will install it for you. In keeping with the library function, the user need not use quotes around package names for most *pacman functions.

Installing, Loading, Unloading, Updating, & Deleting

Quick Reference Table

pacman Function Base Equivalent Description
p_load install.packages + library Load and Install Packages
p_install install.packages Install Packages from CRAN
p_load_gh NONE Load and Install GitHub Packages
p_install_gh NONE Install Packages from GitHub
p_install_version install.packages &
packageVersion
Install Minimum Version of Packages
p_temp NONE Install a Package Temporarily
p_unload detach Unload Packages from the Search Path
p_update update.packages Update Out-of-Date Packages

The heart of pacman is it's ability to reduce typing in package management actions. The functions in this section act on packages.

Installing and Loading

p_load is a general use tool that can install, load, and update packages. The form for the function is:

p_load(..., char, install = TRUE, update = getOption("pac_update"), character.only = FALSE)

where the ... argument allows the user to pass in quoted (or unquoted) package names. For example, many blog posts begin coding with this sort of package call:

packs <- c("XML", "devtools", "RCurl", "fakePackage", "SPSSemulate")
success <- suppressWarnings(sapply(packs, require, character.only = TRUE))
install.packages(names(success)[!success])
sapply(names(success)[!success], require, character.only = TRUE)

With pacman this call can be reduced to:

pacman::p_load(XML, devtools, RCurl, fakePackage, SPSSemulate)

Just Installing

The user may wish to only install packages. The p_install (aliased as p_get) will allow the user to install with the same ease of format as p_load. For example:

p_install(dbConnect, qdap, reports)

This will install packages available on CRAN, or, if the user has previously installed Bioconductor, from the Bioconductor repos.

Installing & Loading from GitHub

pacman provides a wrapper to the devtools package's install_github function for installing and loading GitHub packages. p_load_gh and p_install_gh are wrapper functions that are named and operate similarly to pacman's p_load and p_install.

Note: Packages are passed as character vector repository addresses in the form of username/repo[/subdir][@ref|#pull].
p_install_gh(c("Dasonk/githubSearch", "trinker/regexr", "hadley/httr@v0.4"))
p_load_gh("Dasonk/githubSearch", "trinker/regexr", "hadley/httr@v0.4")

Installing a Minimal Package Version

The user may need a minimal version of a particular package installed. The p_install_version ensures that a package is at least some version cut off. If the package does not exist or the minimum version is not met, p_install attempts to install the package from CRAN. This may be helpful in blog posts where a new function is being demonstrated, requiring a particular version of a package. For example:

p_install_version(
    c("pacman", "testthat"),
    c("0.2.0", "0.9.1")
)

Version of pacman (v. 0.5.0) is suitable

Version of testthat (v. 2.0.1) is suitable

Installing Temporarily

Lastly, p_temp enables the user to temporarily install a package. This allows a session-only install for testing out a single package without muddying the user's library.

p_temp(aprof)

p_isinstalled(aprof)
p_isloaded(aprof)
> p_temp(aprof)
trying URL 'https://cran.rstudio.com/bin/windows/contrib/3.1/aprof_0.2.zip'
Content type 'application/zip' length 34037 bytes (33 Kb)
opened URL
downloaded 33 Kb

package 'aprof' successfully unpacked and MD5 sums checked

The downloaded binary packages are in
        C:\Users\you\AppData\Local\Temp\RtmpYh6bSr\downloaded_packages

aprof installed
Loading required package: aprof
> 
> p_isinstalled(aprof)
[1] FALSE
> p_isloaded(aprof)
aprof 
 TRUE 
Note: When using p_load and friends inside of functions, the user may want to explicitly supply the package name(s) as character strings and set character.only = FALSE or supply a character vector of package names directly to the char argument if it is available.

Unloading

To unload package(s) from the search path use p_unload. p_unload will not unload the base install packages that load when R boots up. The form for the function is:

p_unload(..., negate = FALSE, char, character.only = FALSE)

where the ... argument allows the user to pass in quoted package names. Users may also supply "all" to ... to remove all add on packages. The negate argument negates, unloading all packages except those supplied to ....

p_load(lattice)
p_isloaded(lattice)
p_unload(lattice)
p_isloaded(lattice)
> p_load(lattice)
> p_isloaded(lattice)
lattice 
   TRUE 
> p_unload(lattice)
The following packages have been unloaded:
lattice

> p_isloaded(lattice)
lattice 
  FALSE 

Updating

The p_update (aliased as p_up) is a wrapper for update.packages (defaults to ask = FALSE) and old.packages. To update packages use:

p_update() 

The user may just query (not actually update) for out-of-date packages using:

p_update(FALSE) 

Deleting

The task of recalling the name remove.packages for permanently deleting a package from your library has been replaced by the more consistently named p_delete (aliased as p_del). Additionally, the user may delete multiple packages in a single call. The function protects the user from accidental attempted base package deletion as it will not delete base installed packages (see installed.packages(priority = "base")). Try it out:

p_delete(fakePackage, stats)
> p_delete(fakePackage, stats)
The following packages are a base install and will not be deleted:
stats

The following packages not found in library:
fakePackage

Session Information

Quick Reference Table

pacman Function Base Equivalent Description
p_loaded .packages & sessionInfo List Attached Packages
p_isloaded NONE Logical Test of Attached Package

The p_loaded function allows the user to quickly determine what packages are attached.

p_loaded()

This returns non-base packages that are attached. Adding all = TRUE will return the base packages as well.

p_loaded(all = TRUE)

Supplying a package name to p_loaded (or alternatively p_isloaded()) provides a logical check of whether package(s) are attached:

p_loaded(base, MASS)
 base  MASS 
 TRUE FALSE 
p_isloaded(methods, stats)
methods   stats 
   TRUE    TRUE 

Local Package Information

Quick Reference Table

pacman Function Base Equivalent Description
p_author packageDescription Author of Package
p_citation citation Citation for Package
p_data data List Package Data Sets
p_depends &
p_depends_reverse
package_dependencies &
dependsOnPkgs
Package Dependencies/Reverse Dependencies Locally/on CRAN
p_exists available.packages &
list.files + .libPaths
Logical Check if Package
Exists Locally/on CRAN
p_functions loadNamespace + getNamespaceExports Functions from Package
p_help help HTML/PDF Manuals Viewing
p_information packageDescription Information for Package
p_interactive NONE Search Packages Interactively
p_news news Package NEWS
p_version packageVersion & R.Version Version of Package
p_vignette browseVignettes Package Vignettes Viewing

The functions in this section provide information about a user's local packages.

Package Existence (CRAN & Locally)

The p_exists function checks if a package exists either on CRAN (default) or locally. p_isinstalled is a convenience wrapper for p_exists that is defaulted to check local existence.

p_exists(pacman)  
[1] TRUE
p_exists(pacman, local = TRUE)
[1] TRUE
p_exists(I_dont_exist)
[1] FALSE
## wrapper for `p_exists(local = TRUE)`
p_isinstalled(pacman)
[1] TRUE

Package Dependencies & Reverse Dependencies

The p_depends function checks the dependencies of package either on CRAN (default) or locally. The p_depends_reverse function accomplishes the same task for a package's reverse dependencies.

p_depends(lattice)  
$Imports
[1] "grid"      "grDevices" "graphics"  "stats"     "utils"    

$Suggests
[1] "KernSmooth"   "MASS"         "latticeExtra"
p_depends(lattice, local = TRUE)
$Imports
[1] "grid"      "grDevices" "graphics"  "stats"     "utils"    

$Suggests
[1] "KernSmooth"   "MASS"         "latticeExtra"
p_depends(MASS)  
$Depends
[1] "grDevices" "graphics"  "stats"     "utils"    

$Imports
[1] "methods"

$Suggests
[1] "lattice"  "nlme"     "nnet"     "survival"
p_depends(MASS, local = TRUE)
$Depends
[1] "grDevices" "graphics"  "stats"     "utils"    

$Imports
[1] "methods"

$Suggests
[1] "lattice"  "nlme"     "nnet"     "survival"

Package Attributes

The following subsections discuss pacman functions that are used to grab package information.

Package Information

p_information (aliased as p_info) is a more general use function to grab information about a package from its 'DESCRIPTION' file; for example, the following fields come from the base package: (a) Package, (b) Version, (c) Priority, (d) Title, (e) Author, (f) Maintainer, (g) Description, (h) License, (i) Suggests, and (j) Built.

The form for the function is:

p_info(package, ..., fields = NULL)

where package is a package name and ... argument allows the user to request specific fields (the fields argument is a character only 'escape hatch' for use of p_info inside of functions). If both ... and fields are blank, p_info returns a list of all package fields from the package 'DESCRIPTION' file. p_info returns a list.

## Defaults to supply a list of fields with information about R's base package
p_info()
Package: base
Version: 3.5.1
Priority: base
Title: The R Base Package
Author: R Core Team and contributors worldwide
Maintainer: R Core Team <R-core@r-project.org>
Description: Base R functions.
License: Part of R 3.5.1
Suggests: methods
Built: R 3.5.1; ; 2018-07-02 09:11:50 UTC; windows

-- File: C:/R/R-35~1.1/library/base/Meta/package.rds 
names(p_info())
 [1] "Package"     "Version"     "Priority"    "Title"       "Author"     
 [6] "Maintainer"  "Description" "License"     "Suggests"    "Built"      
p_info(pacman, Author)
$Author
[1] "Tyler Rinker [aut, cre, ctb], Dason Kurkiewicz [aut, ctb], Keith Hughitt [ctb], Albert Wang [ctb], Garrick Aden-Buie [ctb], Albert Wang [ctb], Lukas Burk [ctb]"
p_info(pacman, BugReports, URL)
$BugReports
[1] "https://github.com/trinker/pacman/issues?state=open"

$URL
[1] "https://github.com/trinker/pacman"
p_info(pacman, fields = "Version")
$Version
[1] "0.5.0"
Extracting Package Names
Note: The p_extract function is particularly useful for converting the “Depends”, “Imports”, and “Suggests” fields from a single string into a vector of package names.
## without `p_extract`
p_info(MASS, "Depends")  
$Depends
[1] "R (>= 3.1.0), grDevices, graphics, stats, utils"
p_extract(p_info(MASS, "Depends"))
R (>= 3.1.0)    grDevices     graphics        stats        utils 
         "R"  "grDevices"   "graphics"      "stats"      "utils" 
p_extract(p_info(methods, "Imports"))
  utils   stats 
"utils" "stats" 

Package Author

p_author provides author information for a package as a string.

p_author(pacman)
[1] "Tyler Rinker [aut, cre, ctb],\n  Dason Kurkiewicz [aut, ctb],\n  Keith Hughitt [ctb],\n  Albert Wang [ctb],\n  Garrick Aden-Buie [ctb],\n  Albert Wang [ctb],\n  Lukas Burk [ctb]"
p_author()
[1] "R Core Team and contributors worldwide"

Package Citation

p_citation (aliased as p_cite) provides citation information for a package to the console and in interactive sessions, attempts to copy to the users clipboard (OS dependent).

p_cite(pacman)

To cite pacman in publications, please use:

  Rinker, T. W. & Kurkiewicz, D. (2017). pacman: Package
  Management for R. version 0.5.0. Buffalo, New York.
  http://github.com/trinker/pacman

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {{pacman}: {P}ackage Management for {R}},
    author = {Tyler W. Rinker and Dason Kurkiewicz},
    address = {Buffalo, New York},
    note = {version 0.5.0},
    year = {2018},
    url = {http://github.com/trinker/pacman},
  }
p_citation()

To cite R in publications use:

  R Core Team (2018). R: A language and environment for
  statistical computing. R Foundation for Statistical Computing,
  Vienna, Austria. URL https://www.R-project.org/.

A BibTeX entry for LaTeX users is

  @Manual{,
    title = {R: A Language and Environment for Statistical Computing},
    author = {{R Core Team}},
    organization = {R Foundation for Statistical Computing},
    address = {Vienna, Austria},
    year = {2018},
    url = {https://www.R-project.org/},
  }

We have invested a lot of time and effort in creating R, please
cite it when using it for data analysis. See also
'citation("pkgname")' for citing R packages.

Package Data

p_data provides a data.frame of a package's data sets and a description.

p_data(lattice)
  Data                Description                                          
1 USMortality         Mortality Rates in US by Cause and Gender            
2 USRegionalMortality Mortality Rates in US by Cause and Gender            
3 barley              Yield data from a Minnesota barley trial             
4 environmental       Atmospheric environmental conditions in New York City
5 ethanol             Engine exhaust fumes from burning ethanol            
6 melanoma            Melanoma skin cancer incidence                       
7 singer              Heights of New York Choral Society singers           

Package Functions

p_functions (aliased as p_funs) provides a list of the functions utilized by a package. Setting all = TRUE will yield the non-exported functions as well.

p_functions(pacman)
 [1] "p_author"             "p_base"               "p_boot"              
 [4] "p_citation"           "p_cite"               "p_cran"              
 [7] "p_data"               "p_del"                "p_delete"            
[10] "p_depends"            "p_depends_reverse"    "p_detectOS"          
[13] "p_exists"             "p_extract"            "p_functions"         
[16] "p_funs"               "p_get"                "p_help"              
[19] "p_info"               "p_information"        "p_install"           
[22] "p_install_gh"         "p_install_version"    "p_install_version_gh"
[25] "p_inter"              "p_interactive"        "p_iscran"            
[28] "p_isinstalled"        "p_isloaded"           "p_lib"               
[31] "p_library"            "p_load"               "p_load_current_gh"   
[34] "p_load_gh"            "p_loaded"             "p_news"              
[37] "p_old"                "p_opendir"            "p_path"              
[40] "p_sa"                 "p_search_any"         "p_search_library"    
[43] "p_sl"                 "p_temp"               "p_unload"            
[46] "p_unlock"             "p_up"                 "p_update"            
[49] "p_ver"                "p_ver_cran"           "p_ver_diff"          
[52] "p_version"            "p_version_cran"       "p_version_diff"      
[55] "p_vign"               "p_vignette"          
p_funs(pacman, all=TRUE)
 [1] "Trim"                        "comma_string2vector"        
 [3] "is.base_package"             "is.installed"               
 [5] "is.loaded_package"           "left.just"                  
 [7] "object_check"                "p_author"                   
 [9] "p_base"                      "p_basepath"                 
[11] "p_boot"                      "p_citation"                 
[13] "p_cite"                      "p_cran"                     
[15] "p_data"                      "p_del"                      
[17] "p_delete"                    "p_delete_single"            
[19] "p_delete_warning"            "p_dependencies_single"      
[21] "p_depends"                   "p_depends_helper"           
[23] "p_depends_reverse"           "p_detectOS"                 
[25] "p_egg"                       "p_exists"                   
[27] "p_extract"                   "p_functions"                
[29] "p_funs"                      "p_get"                      
[31] "p_help"                      "p_info"                     
[33] "p_information"               "p_install"                  
[35] "p_install_gh"                "p_install_version"          
[37] "p_install_version_gh"        "p_install_version_single"   
[39] "p_install_version_single_gh" "p_inter"                    
[41] "p_interactive"               "p_iscran"                   
[43] "p_isinstalled"               "p_isloaded"                 
[45] "p_lib"                       "p_library"                  
[47] "p_load"                      "p_load_current_gh"          
[49] "p_load_current_single_gh"    "p_load_gh"                  
[51] "p_load_single"               "p_load_single_gh"           
[53] "p_loaded"                    "p_news"                     
[55] "p_old"                       "p_opendir"                  
[57] "p_path"                      "p_sa"                       
[59] "p_search_any"                "p_search_library"           
[61] "p_set_cranrepo"              "p_sl"                       
[63] "p_tar"                       "p_temp"                     
[65] "p_unload"                    "p_unlock"                   
[67] "p_up"                        "p_update"                   
[69] "p_ver"                       "p_ver_cran"                 
[71] "p_ver_diff"                  "p_version"                  
[73] "p_version_cran"              "p_version_diff"             
[75] "p_vign"                      "p_vignette"                 
[77] "parse_git_repo"              "paste0"                     
[79] "print.p_version_diff"        "print.search_any"           
[81] "print.wide_table"            "try_bioc"                   
[83] "writeToClipboard"           

Package Version

p_version (aliased as p_ver) gives the version of a package.

p_version()
[1] '3.5.1'
p_ver(pacman)
[1] '0.5.0'
p_ver(pacman) >= "0.2.0"
[1] TRUE

Documentation

The following subsections discuss pacman functions that are used to view help manuals, news, and vignettes for a package.

Package Help Manual

The p_help function accesses a package's help documentation in HTML or PDF form. If no Internet connection is available the pdf can be built from the package's internal files.

p_help(pacman)
p_help(pacman, web = FALSE)
p_help(pacman, build.pdf = TRUE)

Package News

p_news provides the NEWS file for for R or an add-on package.

p_news()
p_news(pacman)
## Grab specfic version subsets
subset(p_news(lattice), Version == 0.7)  
Note: p_news yields an object of class: “news_db_from_Rd”, “news_db”, and “data.frame” and can be coerced to an ordinary data.frame via: as.data.frame.

Package Vignette

p_vignette (aliased as p_vign) enables an interactive HTML exploration of packages' vignettes. The default (i.e., no package supplied) is to interact with all of the package vignettes available from a user's local library.

p_vignette()
p_vign(pacman)

Interactive Package Exploration

Lastly, the user may explore packages and package functions more interactively with p_interactive (aliased as p_inter). This function is an interactive mix of p_library and p_functions. p_interactive provides the user's local packages (their library) to choose to explore and then displays available functions for the chosen package. The user may optionally view the documentation for the chosen function from the chosen package. This function has no arguments as this information is passed interactively.

p_interactive()

Internet Based Package Information

Quick Reference Table

pacman Function Base Equivalent Description
p_cran available.package List CRAN Package
p_iscran %in% + available.package Logical Test of CRAN
p_search_any NONE Search for Package by Author

The functions in this section are Internet based and provide information about available CRAN packages.

CRAN Packages

p_cran provides a list of available CRAN packages. Its counterpart, p_iscran provides a logical check whether a package is available on CRAN.

p_cran()
length(p_cran())
[1] 13207
p_iscran("qdap")
[1] TRUE

Search CRAN

p_search_any (aliased as p_sa) enables approximate matching by package or author/maintainer names containing the search term. The first argument to p_search_any, term, is the word or name to search for. The second argument search.by tells the function what fields to search through: 1-"Maintainer", 1-"Author", 2-"Package", 3-"Version".

For example, we may choose to search for packages with the word “color” in the package name or packages with authors/maintainers named “hadley”. We could accomplish these tasks as follows:

p_sa("color", "package")
p_sa("hadley", "author")

Library Information

Quick Reference Table

pacman Function Base Equivalent Description
p_base NONE List Base Package
p_library Sys.getenv + .packages List Packages in User's Library
p_path .libPaths Path to User's Package Library
p_search_library NONE Search Library Packages Via Partial Matching
p_unlock NONE Deletes 00LOCK Directory

The functions in this section interact with the user's local library.

Library Location

p_path, a wrapper for .libPaths, provides the location to the user's library of add-on packages.

p_path()
[1] "C:/Users/trinker/AppData/Local/Temp/Rtmp4G5Mj9/Rinst3f5c68202d6c"
[2] "C:/R/R-3.5.1/library"                                            
[3] "C:/Users/trinker/AppData/Local/Temp/RtmpKEnhl7"                  

Available Packages

p_library (aliased as p_lib) yields a vector of a user's packages and optionally opens the library location. p_base, similarly, provides the user's packages, but, marks base install packages with a marker (defaults to **).

p_lib()
p_base()

Search Library

p_search_library (aliased p_sl) is a handy function to search the library for a package that's on the tip of your tongue but you can't remember the full name or how to spell it. p_search_library takes then form:

p_search_library(begins.with = NULL, contains = NULL)

The first argument, begins.with allows the user to search for a package by initial characters. The contains argument allows the user to search for character strings within the package name. This will yield a list of matching packages that the user can then choose one to load.

p_sl("pa")
p_sl(contains = "man")
p_sl(begins.with ="pa", contains = "man")

Unlock Library

p_unlock deletes the 00LOCK directory that is accidentally left behind by a fail in install.packages. The documentation for install.packages states that sometimes install.packages can:

fail so badly that the lock directory is not removed: this inhibits any further installs to the library directory (or for –pkglock, of the package) until the lock directory is removed manually.

When this occurs simply enter p_unlock() and the 00LOCK directory is removed.

pacman Tools

Quick Reference Table

pacman Function Base Equivalent Description
p_detectOS Sys.info Detect Operating System
p_extract NONE Extract Packages from String
p_opendir system/shell Open a Directory

The functions in this section are general tools used within the pacman package. They are not package specific functions. Discussion of their functionality is beyond the scope of this vignette.