Submitting a Vignette to the DANTE Project

Joshua Brinks, ISciences, LLC

Summary

The DANTE Project is a community based effort designed to accept contributions from researchers, practitioners, and students.
These vignettes assist users in contributing to the DANTE Projects automated GitLab “back-end”.

Introduction

The DANTE Project provides an open source community platform to lower the barriers of entry to climate security research and policy making. One of the core components of the project are research vignettes and tutorials. DANTE Project submissions are free, and provide a platform for prospective research, methods papers, and scientific tutorials with minimal review from our editors in addition to feedback from our user-base. This is an excellent opportunity for advanced undergraduate work, a consolidated location for teaching materials, and lighter or otherwise less refined research papers from those either lacking publication funds or time for a formal review process. We intend to provide a platform for written works encompassing a wide range of styling and tones. These include, but are not limited to:

Traditional R package vignettes.
Research blog posts with anecdotal introductions and a lighter tone.
Methods papers illustrating a new or otherwise novel data processing and visualization workflow.
Working papers or other reproducible scientific papers relaying models or other statistical inference.
Miniature lit-reviews that lie within our thematic focus.

In addition to the written content and reproducible code, danteSubmit vignettes require offer additional metadata fields to supplement the written content and provide a variety of cross-referenced complementary materials:

R packages or other software utilized for the vignette.
Datasets used for the creation of the vignette.
Data types used in the submission.
Accompanying vignettes related to the submission.
Direct commentary from DANTE users.

Completing the Template

Accessing the RMarkdown Template

The danteSubmit package can be installed vit GitLab with the devtools package using the following command:

devtools::install_gitlab("/dante-sttr/danteSubmit")

Following installation, the dataset template will be accessible in RStudio through the File > New File > R Mardown ... > From Template > Dante Vignette Submission menu. This will create a new directory in your home directory with the dataset skeleton.Rmd file. This provides the framework of the submission with several DANTE specific metadata fields.

Template Fields

RMarkdown skeleton.Rmd files are typically comprised of two sections: 1) the YAML metadata, and 2) the text body. The skeleton.Rmd begins with the YAML header. It is demarcated by two sets of ---. The text body uses traditional sectioning with the RMarkdown language. More information pertaining to RMarkdown formatting can be found on their official site. DANTE vignette submissions require no prior knowledge of RMarkdown syntax and users may delete any YAML fields not relevant to the dataset (additional authors, pros, cons, spatial information for non-spatial data, etc.)

YAML Metadata

title: The official title of the vignette submission. The title must be inside quotes.
metadata-date: You may set it manually or leave as is, and it will automatically generate the date when compiled.
author: Name(s), email(s), and affiliation(s) (if applicable), of the individual(s) or institution(s) who authored the submission.
vignette-highlights: Approximately 2-3 bullet points highlighting key points of the vignette. This section is best served by illustrating brief strengths and weaknesses of the document.
abstract: You may submit an abstract surrounded in quotes if you so desire.
data-presentation-forms: Categorical identifier(s) of submitted data. May be one or more of the following: raster, spatial polygons, spatial points, time series, or dyadic. Delete those that are non-applicable.
related-packages: R packages designed to acquire, process, analyze, or visualize the dataset. Related links utilize raw HTML. Examples for internal and external packages are populated in the rmarkdown template. Replace dante-package-name with the package name found in the associated DANTE url. For example, the entry for demcon would be

- <a href="/demcon">demcon</a>

External packages without a DANTE page can be linked to their hosting site:

- <a href="https://github.com/vdeminstitute/vdemdata">vdemdata</a>

related-datasets: Similar datasets to the one being presented in the submission. Examples for internal and external datasets are populated in the rmarkdown template. Replace dante-dataset-name with the dataset name found in the associated DANTE url. For example, the entry for The Standardized Precipitation Evapotranspiration Index (SPEI) would be:

- <a href="/datasets/spei">Standardized Precipitation Evapotranspiration Index</a>

External datasets without a DANTE page can be linked to their hosting site:

- <a href="https://ldas.gsfc.nasa.gov/gldas">GLDAS 2.1</a>

related-vignettes: Vignettes or other tutorials featuring the dataset. Examples for internal and external vignettes are populated in the rmarkdown template. Replace dante-vignette-name with the vignette name found in the associated DANTE url. For example, the entry for Country Coding Considerations for Dataset Harmonization and Applied Uses would be (Here we use a truncated title to improve website rendering.):

- <a href="/vignettes/ccode-considerations">Applied Country Code Uses</a>

External vignettes without a DANTE page can be linked to their hosting site:

- <a href="https://r-spatial.github.io/sf/articles/sf4.html">Manipulating Simple Features</a>

keywords: Keywords for submission to use for website filtering.
bibliography: Bibtex file containing citations used in body of the submission. This file should be placed in the home directory along with the skeleton.Rmd and any imagery.

The following sections may be left blank and filled in by DANTE staff. However, if you wish to provide imagery used for website catalog browsing and dataset page rendering you may provide images.

browse-image: File name for the image to be used while browsing on the DANTE website. This may be left blank for project administrators to handle. If you would like to provide an image please crop it to 300 x 225 pixels. The file name must match that of the dataset .Rmd submission using the format rmd-submission-browse.jpg. For example, the SPEI file is named spei-browse.jpg.
subhead-image: File name for the image to be used as a subheading of the dataset page on the DANTE website. This may be left blank for project administrators to handle. If you would like to provide an image please crop it to 920 x 180 pixels. This should be the same image, but re-cropped, as the browse-image.jpg. The file name must match that of the dataset .Rmd submission using the format rmd-submission-subhead.jpg. For example, the SPEI file is named spei-subhead.jpg.
image-attribution: All submitted website imagery must be properly attributed using raw HTML. These links are almost always available from the open-source photo website where the imagery was acquired. Paste it into the slot verbatim. Here is attribution for the MapSPAM DANTE page:

image-attribution: <span>Photo by<a href="https://markusspiske.com/">Markus Spiske</a></span>

output: This identifies the rmarkdown template to compile the submission. Should not be altered by the user.

Written Body

DANTE vignettes can fulfill a variety of purposes. You may wish to write a mini lit-review on a particular subject, or perhaps demonstrate an analytic method or a tool that demonstrates data acquisition, pre-processing, visualization, or modeling. Either way, set up the vignette with (at least) a brief introduction providing some context.

You should use standard formatting and syntax conventions for RMarkdown. Additionally, properly cite written material using standard rmarkdown conventions.

You can generate figures with inline code just as with any other example, however, if you intend to include a figure from an external .PNG please use the following method:

library(png)

img<-png::readPNG("screenshot.png")
grid::grid.raster(img)

Submitting the Template

If you’re still uncertain on how to proceed, please review completed vignettes pages on our GitLab Project Page. You can see several examples for a variety of vignette formats.

After all relevant fields are complete, the user should compile and review the HTML submission by knitting the document inside of RStudio. At this point, the submission is ready and the vignette-name.html output, vignette-name.Rmd, all relevant files may be pushed to development section of danteSubmit in a folder with the same name as the .Rmd submission using a merge request.

If you’re not comfortable with Git, you may simply reach out to me through email Josh Brinks.