mortar

The goal of mortar is to standardize how we USGS Data Science Community of Practice (DS CoP) structure our collaborative projects. The package’s functionality focuses on setting up project directories using the DS CoP conventions. Think of mortar as a collection of helper functions for creating files and folders we often use in our workflows.

library(mortar)

Set up a USGS git repo with use_project_usgs()

You may want or need to include common files in a project’s git repo to adhere to coding conventions or standards. These include a README that summarizes basic information about a repo, a License that details how the contents of a repo can be used, and others.

The use_*_usgs() family of functions create these sorts of files based on USGS-specific templates. These functions are heavily inspired by similar functions from the usethis R package.

At the top of each of these template files, the following message is included:

-NOTE: this is a template created using the mortar package. The contents below are for illustrative purposes and should be edited to reflect your use case. This message can be deleted in acknowledgement that you’ve added this file to your project.

This acts as a nudge to the author to update the documentation to the specifics of the project. It also acts as a quality control measure, allowing code authors and reviewers to ensure that they have at least opened and looked at each of these files.

For example, you can add a .gitignore file to your repo with some pre-set (often forgotten) ignores using the following. If you don’t like the contents of these template files, you’re able to customize it using or additions argument or to edit them afterward to your needs.

use_gitignore_usgs(additions = c("scratch*", "*/tmp/*"))

This creates the standard .gitignore with additional lines for scratch* and */tmp/*. Run ?mortar::`use-file-usgs` to view the function family’s documentation and more examples.

use_project_usgs() generates all the common files for your repository in one function call: CHANGELOG.md, code.json, CODE_OF_CONDUCT.md, CONTRIBUTING.md, DISCLAMER.md, .gitignore, LICENSE.md, and README.md.

use_project_usgs(
  gitignore_additions = c("scratch*", "*/tmp/*"),
  readme_rmd = TRUE,
  disclaimer_approved = FALSE
)

Run ?mortar::use_project_usgs to view the function’s documentation and more examples.

Set up a targets project with tar_init()

The tar_init() function will initialize a targets pipeline project directory according to the DS CoP conventions. Internal USGS users can see more on this in section 12 of the Targets 2 training course. Run this function at the beginning of a targets pipeline project to avoid manually setting up the project directory (and forgetting to add those pesky .empty files in each sub-directory).

The call below illustrates how to use tar_init().

tar_init(
  phase_names = c("fetch","process","summarize"),
  phase_subdirs = c("src","out"),
  use_leading_zeros = TRUE
)

Under the hood, tar_init() basically just repeatedly calls dir.create() and file.create() to accomplish the following tasks:

1. Creates a _targets.R file in the project’s root directory with some general starter code.
2. Creates .R scripts and directories in the projects root directory for each phase of the pipeline like 01_fetch.R and 01_fetch/, etc.
3. For each phase directory, creates sub-directories therein, such as src and out.
4. Adds a .empty file within each sub-directory so that it will be tracked by git.

Run ?mortar::tar_init to view the function’s documentation and more examples.