The Neotoma Paleoecological Database is committed to outreach directed at multiple user groups including public school students and teachers, community groups, and academic users. To facilitate coordinated outreach we have developed a number of teaching modules, and will likely continue developing modules. These modules are stored in this repository. We welcome continued contribution and comment on our teaching modules. Bug reports can be made in the issue tracker.
We welcome contributions from any individual, whether code, documentation, or issue tracking. All participants are expected to follow the code of conduct for this project.
Creating New Workshop Docs
Getting Started Quickly
If you are interested in building a new workshop for Neotoma using R, you can begin by copying the zipped file in the Templates/R folder. Extract the
zip file locally and then edit the RMarkdown file
Workshop_Template_v0.1.Rmd using RStudio (or another text editor).
If you're using RMarkdown it is relatively straightforward to render the
Rmd file into the resulting
render function in the
library(rmarkdown) render(input = "Workshop_Template_v0.1.Rmd", output_format = "html_document")
or from the command line:
RScript -e "rmarkdown::render(input = 'Workshop_Template_v0.1.Rmd', output_format = 'html_document')"
If you are interested in working with version control and have a GitHub account, you can either fork the repository and add a pull request once you are done, or you can clone the repository locally and work on a new branch, creating a pull request when you are done.
What's in the ZIP?
R_template_v0.2.zip file is an archived ZIP file that contains several key components:
- The main document: This includes executable code (although execution requires a working internet connection). Feel free to edit to add examples with which you're familiar, or that focus on particular dataset types.
- This folder contains any images you might choose to use in the
docxdocument. This does not include files that will be generated by the script itself (such as plots). If you wish to add images to the document use the
!(images/...)having copied the file into the images folder.
- This folder contains a template file for processing the RMarkdown output to Word
docxformat. You're welcome to edit styles yourself (you can follow this tutorial). This folder also includes
footer.html, files that are added to any HTML output. Again, you can edit these as desired.
- A file for BiBTex references, used to render references inline in the RMarkdown document. Copy and paste bibtex references into this document to cite them (using the
[@tag]formar) and the references will be auto-generated when you render the
- A citation format used by ESA. Copied from here.
Bacon Files & Folders:
- Bacon is a method for building chronologies using Bayesian methods. The files are included here so that the workshop can "just run". This should not be considered a canonical distribution of Bacon.
Editing the Rmd
At the very simplest, this template is expected to work as a standalone document, providing an overview of the key components of Neotoma, both the web and R access portals, along with some simple data processing. Feel free to delete or add components as neccessary. If you have never worked with RMarkdown before please consult this Getting Started reference. RMarkdown is relatively straightforward in that it is basically a plain-text format, but there are aspects that can be difficult to sort out.
The YAML header
The YAML (YAML Ain't Markup Language) file provides information to instruct pandoc how to render the Rmd file into PDF, docx or html format (or other formats). The YAML header is found at the top of the
YAML may seem foreign & strange, but it doesn't have to be. The template is designed so you only have to edit two places, the
author block. Everything else should work as-is. For more details on how to customize the YAML header, read here.
The R blocks
Debugging problems in the R code can often be difficult with RMarkdown documents since they're embedded in the text document. It's often worth using the
purl command to generate a clean set of R code for debugging purposes. Otherwise, have fun! Setting the code chunk options can give you some more control over what code is shown and what code is hidden.
Dealing with problems
Once you're done
If you have a GitHub account already and have cloned the whole repository, copy your finished workshop documents into a new directory in the
Examples folder. You can create a new directory from the command line, or using your file explorer. Make sure to give it a clear name that indicates the place & time of the workshop, and then make a pull request.
If you aren't comfortable doing this, contact us through the issues tracker or via email and send us a zipped copy of the workshop. We'll put them up for you. Please note that this repository is licensed under an MIT License. If you are not comfortable sharing your work under these terms (or cannot legally) please let us know.
Thanks for helping out and being a part of the Neotoma Paleoecological Database group!