In EcoDynIZW/d6: Simplify Workflows of D6 Research Projects

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 four main functionalities:

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

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:

```{text eval=FALSE} . └── unicornus_wl_sdm_smith_j ├── data ├── docs ├── output ├── plots └── scripts

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

```{text}
. 
└── unicornus_wl_sdm_smith_j
    ├── .Rproj.user          —  Rproject files
    ├── data                 —  main folder data
    │    ├── processed       —  processed tabular data files
    │    │    └── geo        —  processed geospatial data files
    │    └── raw             —  raw tabular data files
    │    │    └── geo        —  raw geospatial 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
    ├── results              —  explorative plots, tables etc. (except final figures)
    ├── plots                —  final figures for manuscript and supplementary material
    ├── scripts              —  script files (e.g. .R, .Rmd, .Qmd, .py, .nlogo)
    │   └── zz_submit.R      —  final script to run before submission
    ├── .gitignore           —  contains which files to ignore for version control
    ├── README.md            —  contains project details and package dependencies
    └── 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.

Add Documentation to Your Project

After you have set up your project directory, open the file README.md and add your name, project details, and the goal of your study.

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 pre-installed versions and will only install packages that are not installed with your current R version.

The argument geo controls the installation of R packages for spatial analysis. 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:

```{text, eval=FALSE} tibble, dplyr, tidyr, tibble, ggplot2, readr, forecats, stringr, purrr, lubridate, here, patchwork, usethis, remotes

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

```{text, eval=FALSE}
sf, terra, stars, tmap

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")

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, …)