d6

R package to simplify workflows of D6 research projects. The package provides utilities to set up a standardized folder structure and version control, and Rmarkdown templates and rendering functionality for a reproducible workflow.

EcoDynIZW

d6

Simplify Workflows of D6 Research Projects

The goal of the {d6} package is to simplify the project workflow
within the department “Ecological Dynamics” at the Leibniz Institute
for Zoo and Wildlife Research by providing a standardized folder
structure, templates for reports, and utility functions.

There are five main functionalities:

Create standardized project directories with new_project()
Install a set of common packages with install_d6_packages()
Create figures that match our lab identity via theme_d6()
Provide custom Rmarkdown templates via File > New File > Rmarkdown... > From Template
Render all your Rmarkdown documents to ./docs/report with render_all_reports() or render_report()

The function simple_load() is a utility function that is currently in an experimental state. It allows you to install (if not yet) and load a set of packages—even a combination of CRAN and GitHub packages—in a single step.

Installation

The package is not on CRAN and needs to be installed from GitHub. To do
so, open Rstudio and run the following two lines in the console. In case
the {devtools} package is already installed, skip that step.

install.packages("devtools")
devtools::install_github("EcoDynIZW/d6")

(Note: If you are asked if you want to update other packgaes either
press “No” (option 3) and continue or update the packages before running
the install command again.)

Create Project Directory

Run the function new_project() to create a new project. This will
create a standardized directory with all the scaffolding we use for all
projects in our department. It also add several files needed for
documentation of your project.

To start a new project in the current working directory, simply run:

d6::new_project("unicornus_wl_sdm_smith_j")

Please give your project a unique and descriptive name:
species_country_topic_name

For example, when John Smith is developing a species distribution models
for unicorns in Wonderland, a descriptive title could be:
unicornus_wl_sdm_smith_j. Please use underscores and the
international Alpha-2 encoding for
countries.

The main folders created in the root folder (here
unicornus_wl_sdm_smith_j) are the following:

.
└── unicornus_wl_sdm_smith_j
    ├── data
    ├── docs
    ├── output
    ├── plots
    └── scripts

The full scaffolding structure including all subdirectories and
additional files looks like this:

. 
└── unicornus_wl_sdm_smith_j
    ├── .Rproj.user          —  Rproject files
    ├── data                 —  main folder data
    │    ├── geo             —  main folder spatial data (if `geo = TRUE`)
    │    │    ├── processed  —  processed spatial data files
    │    │    └── raw        —  raw spatial data files
    │    ├── processed       —  processed tabular data files
    │    └── raw             —  raw tabular data files
    ├── docs                 —  documents main folder
    │   ├── admin            —  administrative docs, e.g. permits 
    │   ├── literature       —  literature used for parametrization + manuscript
    │   ├── manuscript       —  manuscript drafts (main + supplement)
    │   ├── presentations    —  talks and poster presentations
    │   └── reports          —  rendered reports
    ├── output               —  everything that is computed (except plots)
    ├── plots                —  plot output
    ├── scripts              —  script files (e.g. .R, .Rmd, .Qmd, .py, .nlogo)
    │   ├── 00_start.R       —  first script to run after project setup
    │   └── zz_submit.R      —  final script to run before submission
    ├── .gitignore           —  contains which files to ignore for version control
    ├── .Rbuildignore        —  contains which files to ignore for package builds
    ├── DESCRIPTION          —  contains project details and package dependencies
    ├── NAMESPACE            —  contains context for R objects
    └── project.Rproj        —  Rproject file: use to start your project

Use A Custom Root Directory

You don’t need to change the working directory first—you can also
specify a path to a custom root folder in which the new project folder
is created:

## both work:
d6::new_project("unicornus_wl_sdm_smith_j", path = "absolute/path/to/the/root/folder")
## or:
d6::new_project("unicornus_wl_sdm_smith_j", path = "absolute/path/to/the/root/folder/")

The resulting final directory of your project would be
absolute/path/to/the/root/folder/unicornus_wl_sdm_smith_j.

Use Version Control

If you want to create a GitHub repository for the project at the same
time, use instead:

d6::new_project("unicornus_wl_sdm_smith_j", github = TRUE)

By default, the visibility of the GitHub repository is set to “private”
but you can also change that:

d6::new_project("unicornus_wl_sdm_smith_j", github = TRUE, private_repo = FALSE)

Note that to create a GitHub repo you will need to have configured your
system as explained
here.

Setup without Geo Directories

If your project does not (or will not) contain any spatial data, you can
prevent the creation of the directories geo-raw and geo-proc by
setting geo to FALSE:

d6::new_project("unicornus_wl_sdm_smith_j", geo = FALSE)

Add Documentation to Your Project

After you have set up your project directory, open the file 00_start.R
in the R folder. Add the details of your project, fill in the readme,
add a MIT license (if needed) and add package dependencies.

Install Common Packages

You can install the packages that are most commonly used in our
department via install_d6_packages():

d6::install_d6_packages()

Note that this function is going to check preinstalled versions and will
only install packages that are not installed with your current R
version.

Again, there is an argument geo so you can decide if you want to
install common geodata packages as well (which is the default). If you
are not intending to process geodata, set geo to FALSE:

d6::install_d6_packages(geo = FALSE)

The default packages that are going to be installed are:

tidyverse (tibble, dplyr, tidyr, ggplot2, readr, forcats, stringr, purrr), lubridate, here, vroom, patchwork, remotes

The following packages will be installed in case you specify
geo = TRUE:

sf, terra, stars, tmap

Corporate ggplot2 Theme

The package provides a ggplot2 theme with sensible defaults and additional
utilities to simplify the process of creating a good-looking, clean look.
Furthermore, we aim to have a consistent look across all our figures shown
in manuscripts, presentations, and posters.

The theme can be added to a ggplot object as usual:

library(ggplot2)
ggplot(mpg, aes(x = displ, y = cty)) +
  geom_point() +
  d6::theme_d6()

Or set as the new global theme by overwriting the current default:

theme_set(d6::theme_d6())

Typefaces

The D6 corporate theme uses the PT font superfamily and will inform you to
install the relevant files in case they are missing on your machine:

By default, the theme uses PT Sans. If you prefer serif fonts or such a
typeface is required, you can set serif = TRUE inside the theme:

ggplot(mpg, aes(x = displ, y = cty)) +
  geom_point() +
  d6::theme_d6(serif = TRUE)

Additional Utility Arguments

In addition to the common arguments to specify the bas settings
(base_family, base_size, base_line_size, and base_rect_size),
we have added the following utility settings to simplify the modification
of the theme:

grid: remove or add major grid lines ("xy" by default)
legend: control legend position ("bottom" by default)
mono: use a tabular, monospaced font for numeric scales such as x, y, and legends ("none" by default)
bg: define background color ("transparent" by default)
serif: set main typeface (FALSE by default; see above)

ggplot(mpg, aes(x = class, y = hwy, color = factor(year))) + 
  geom_boxplot() +
  d6::theme_d6(
    grid = "y",
    legend = "top",
    mono = "yl",
    bg = "cornsilk"
  )

Use Custom Rmarkdown Templates

The package also provides several templates for your scripts. In
Rstudio, navigate to File > New File > RMarkdown... > Templates and
choose the template you want to use. All templates come with a
preformatted YAML header and chunks for the setup.

The following templates are available for now:

EcoDynIZW Basic: Template for a basic Rmarkdown research report
including bits of codes and comments to get started
EcoDynIZW Minimal: Template for an Rmarkdown research report
(almost empty)

Render Rmarkdown Files to Reports

The render_*() functions take care of knitting your Rmarkdown files
into HTML reports. The functions assume that your .Rmd files are saved
in the R directory or any subdirectory, and will store the resulting
.html files in the according directory, namely ./docs/reports/.

You can render all .Rmd files that are placed in the R directory and
subdirectories in one step:

d6::render_all_reports()

You can also render single Rmarkdown documents via render_report():

d6::render_report("my-report.Rmd")
d6::render_report("notsurewhybutIhaveasubfolder/my-report.Rmd")

Install and Load a Set of Packages

The simple_load() function takes a vector of packages, checks if they
are installed already, installs them if needed, and loads them via
library() afterward. You can provide both, CRAN and GitHub packages,
at the same time. GitHub packages need to be specified as
“owner/repository” without any spaces.

d6::simple_load(pcks = c("dplyr", "ggplot2", "EcoDynIZ/d6berlin"))

You can also force a reinstallation of packages. CRAN and GitHub packages
are controlled individually via update_cran and update_gh, respectively.

d6::simple_load(pcks = c("dplyr", "ggplot2", "EcoDynIZ/d6berlin"),
                update_cran = TRUE, update_gh = TRUE)

Acknowledgements:

This package would not exist without the work of many great people!

The code to create the project folder is based on the template
package by Francisco
Rodriguez-Sanchez (and
references therein)
The 00_start script is inspired by the {golem}
package
Rstudio for the development of Rmarkdown and all the great things
that come with it (knitting, templates, themes, …)

d6

d6