In bniebuhr/howtoRpackage: Tips to create R packages
knitr::opts_chunk$set(echo = TRUE, cache = TRUE, message = FALSE, warning = FALSE)
Goals
- Learn to build R packaged
- Learn workflow with Github
Part I: building an R package
Why!?
- Conquer and permanently tame confusing folder soups of data and R scripts
eventually:
- (truly) publish tools and methods
Processing before:
(this is a small snippet of a data processing nightmare)
gps.dir <- "data/SonoranPronghorn/Locations_GPSCollarTelemetry/"
pronghorn <- read.csv(paste0(gps.dir,f.v1[i])) %>% processRaw_v1(id = id.v1[i], filename = f.v1[i])
pronghorn.sf <- st_as_sf(df.raw, coords = c("ECEF_X..m.","ECEF_Y..m.","ECEF_Z..m.")) %>% st_set_crs(4978) %>%
st_transform(4326) %>% st_coordinates
with(df.raw,
data.frame(
File = filename,
ID = CollarID,
DateTime = mdy_hms(paste(UTC_Date, UTC_Time)),
Latitude = ll[,"Y"],
Longitude = ll[,"X"],
Elevation = ll[,"Z"])) %>%
subset(!is.na(DateTime))
Processing now
require(pronghorn)
data("pronghorn_gps")
str(pronghorn_gps)
require(pronghorn)
data("pronghorn_gps")
str(pronghorn_gps[,-1])
R package structure
knitr::opts_chunk$set(echo = TRUE, cache = TRUE, message = FALSE, warning = FALSE)
Goals
- Learn to build R packaged
- Learn workflow with Github
Part I: building an R package
Why!?
- Conquer and permanently tame confusing folder soups of data and R scripts
eventually:
- (truly) publish tools and methods
Processing before:
(this is a small snippet of a data processing nightmare)
gps.dir <- "data/SonoranPronghorn/Locations_GPSCollarTelemetry/" pronghorn <- read.csv(paste0(gps.dir,f.v1[i])) %>% processRaw_v1(id = id.v1[i], filename = f.v1[i]) pronghorn.sf <- st_as_sf(df.raw, coords = c("ECEF_X..m.","ECEF_Y..m.","ECEF_Z..m.")) %>% st_set_crs(4978) %>% st_transform(4326) %>% st_coordinates with(df.raw, data.frame( File = filename, ID = CollarID, DateTime = mdy_hms(paste(UTC_Date, UTC_Time)), Latitude = ll[,"Y"], Longitude = ll[,"X"], Elevation = ll[,"Z"])) %>% subset(!is.na(DateTime))
Processing now
require(pronghorn) data("pronghorn_gps") str(pronghorn_gps)
require(pronghorn) data("pronghorn_gps") str(pronghorn_gps[,-1])
Rfolder contains codedatafolder contains data - as.rdamanfolder contains documentationDESCRIPTION- file contains essential infoNAMESPACE- complicated file (mainly automated)
DESCRIPTION file
Package: pronghorn Type: Package Title: Sonoran pronghorn analysis project Version: 0.1.0 Author: Elie, Nicky, others Maintainer: The package maintainer <yourself@somewhere.net> Description: The pronghorn package is a PRIVATE collaborative package containing processed data, code and results for analysis of sonoran pronghorn. License: PRIVATE Encoding: UTF-8 LazyData: false Depends: lubridate, magrittr, plyr, dplyr, ggplot2, ggpubr, sp, sf, stringr Suggests: mapview RoxygenNote: 7.1.1
Documentation
R help document
R man file
wzxhzdk:5
Using Roxygen
Streamlines documentation by turning "comments" into help files.
Need to install roxugen2 package and fiddle with some "build" settings.
#' GPS data of Sonoran pronghorn
#'
#' 43 GPS collared pronghorn collared between 2008 and 2020
#'
#' @usage
#' data(pronghorn_gps)
#'
#' @format Contains only five columns:
#' \describe{
#' \item{File}{Original file name}
#' \item{ID}{ID of animal}
#' \item{DateTime}{Date and time in POSIXct}
#' \item{Longitude,Latitude}{}
#' }
#' @example
#' examples/pronghorn_gps_examples.R
#' @source Unclear. Arizona DFG? Anyways - via Andy Goodwin.
#' @keywords data
How to create a package
-
By hand
-
base::package.skeleton() -
usethis::create_package() -
build directly off of existing GitHub project
Building an R package - lab exercise
David provided some code and a function ...
Bernardo will walk us through building a package from "scratch" ...
Part II: git and Github
Version control - a system to track and organize all progress on a project. Mainly ... programming and coding projects. Facilitates project management.
git (most common tool) runs locally, and tracks all the changes, via command line or a GUI.
{with = 80%}
Steps of version controlling
There's a controlled sequence of steps!
- Step 1: **modify** files in your working directory.
- Step 2: **stage** files you’ve worked on. This prepares a snapshot of the directory.
- Step 3: **commit** the files you’ve staged. This stores that snapshot in the Git repository. Every commit **must** come with a comment.
Command lines (in the `git bash` terminal):
wzxhzdk:7
GitHub (or GitLab or bitbucket)
Are **remote** repositories of `git`, which allow multiple people people to work with the **same repository**.
This adds two important steps:
- Step 0: **pull** any changes from remote version of repo
- Step 5: **push** any changes you've "committed" to.
wzxhzdk:8
{width=100%}
How to create a git repository and upload to GitHub
## Order 1:
1. Create GitHub repository online
2. Create new R project from `GitHub` repository
3. Use Rstudio's stage-commit-push-pull tools.
{width=80%}
## Order 2:
1. Create new **R project** (e.g., a package, e.g. `usethis::create_package()`)
2. Create empty repository locally: `usethis::use_git()`
3. Create Github repository: `usethis::use_github()`
4. Use Rstudio's stage-commit-push-pull tools.
