Use buildReport() to begin writing your report
July 03 2022
Source:vignettes/A_use-buildReport.Rmd
A_use-buildReport.RmdQuick! Get started!
Here, I’ll show a basic script that you can quickly run to get started.
# 1. Load the NMFSReports Library
library(devtools)
devtools::install_github("EmilyMarkowitz-NOAA/NMFSReports", force = TRUE)
library(NMFSReports)
# 2. Build your report
NMFSReports::buildReport(
sections = c("abstract", "introduction", "history",
"methods", "results",
"results_discussion", "endmatter", "presentation"),
report_authors = "Me, Myself, and I",
report_title = "The best report ever",
styles_reference_pptx = "refppt_nmfs",
styles_reference_docx = "refdoc_noaa_tech_memo",
bibliography.bib = "bib_example",
csl = "bulletin-of-marine-science"
)
# 3. Run your run.R file
source("./code/run.R")More details about each option and step of the process is below!
Step by Step: Create initial structure of report
Do everyone here a favor and create a new R project or at least set
up a working directory (setwd()). There will be a lot of
file management here…
To build your intitial architecture for your new NOAA Tech Memo or Report, simply run the below script:
buildReport(report_title = …)
Default = ““. Here, put the title of your report. You can change this
later in the run.R file in needed.
report_title = "My Awesome Report!"buildReport(report_authors = …)
Here, add the first and last name of everyone who is producing the
report. You can change this later in the run.R file in
needed.
report_authors = "Me, Myself, and I"buildReport(sections = …)
Let’s first think about what you want/need your Tech Memo to look like. For my purposes, I’ll assume that you need the below sections:
# list the sections (that you will have different rmd scripts for) in order and with no spaces
sections <- c("frontmatter", # This is a specific template that matches the NOAA Template
"abstract", # This, and all others unless otherwise mentioned, come from the same plain-slate document but are appropriately named and linked up in the 'run' file.
"introduction",
"methods",
"results",
"discussion",
"endmatter" # This is a specific template that will document all of your citations throughout the report, the R packages you used to create this report. I'm biased, but please give credit where credit is due! There are also spots here to list people's ORCID numbers and acknowlegements.
) buildReport(styles_reference_docx = …)
styles_reference_docx is a document style reference
guide is essentially a word document where you have defined each style.
Either use a local document (insert “path”) or some of the pre-made
templates (“refdoc_noaa_tech_memo” or
“refdoc_fisheries_economics_of_the_us”). Default =
“refdoc_noaa_tech_memo”
To edit the stlyes in your word document, check out this resource.
Here’s what they look like:
buildReport(styles_reference_pptx = …)
styles_reference_pptx is a document style reference
guide is essentially a word document where you have defined each style.
Either use NULL to not have a presentation, a local document (insert
full path to local document), or a pre-made template (“refpptx_nmfs”).
Default = “refpptx_nmfs”. You can change this later by renaming the file
in the code folder.
Here’s what they look like:
buildReport(csl = …)
csl is a citation style. Either use a local document
(insert “path”) or some of the pre-made templates (“apa” or
“bulletin-of-marine-science”). Default = “apa” because it was easy to
find.
A primer on creating and modifying CSL styles can be found at http://citationstyles.org/downloads/primer.html. A repository of CSL styles can be found at https://github.com/citation-style-language/styles. See also http://zotero.org/styles for easy browsing.
csl = "bulletin-of-marine-science"
# it looks something like this:
csl0 <- base::readLines(system.file("cite","bulletin-of-marine-science.csl", package="NMFSReports"))
head(csl0)
#> [1] "<?xml version=\"1.0\" encoding=\"utf-8\"?>"
#> [2] "<style xmlns=\"http://purl.org/net/xbiblio/csl\" class=\"in-text\" version=\"1.0\" demote-non-dropping-particle=\"sort-only\" default-locale=\"en-US\">"
#> [3] " <info>"
#> [4] " <title>Bulletin of Marine Science</title>"
#> [5] " <id>http://www.zotero.org/styles/bulletin-of-marine-science</id>"
#> [6] " <link href=\"http://www.zotero.org/styles/bulletin-of-marine-science\" rel=\"self\"/>"buildReport(bibliography.bib = …)
bibliography.bib: Either use a local document (.bib
format; insert full “path”) or the example file from the package
(“bib_example”). Default = “bib_example”.
csl = "bib_example"
# it looks something like this:
bib <- base::readLines(system.file("rmd","bib_example.bib", package="NMFSReports"))
bib
#> [1] "@article{RN621,"
#> [2] " author = {Arrhenius, Svante},"
#> [3] " title = {Über die Reaktionsgeschwindigkeit bei der Inversion von Rohrzucker durch Säuren},"
#> [4] " journal = {Zeitschrift für physikalische Chemie},"
#> [5] " volume = {4},"
#> [6] " number = {1},"
#> [7] " pages = {226-248},"
#> [8] " ISSN = {2196-7156},"
#> [9] " year = {1889},"
#> [10] " type = {Journal Article}"
#> [11] "}"
#> [12] ""
#> [13] "@book{RN686,"
#> [14] " author = {Fry, Frederick Ernest Joseph},"
#> [15] " title = {The Physiology of Fishes},"
#> [16] " publisher = {Academic Press},"
#> [17] " address = {London},"
#> [18] " volume = {1},"
#> [19] " series = {The Physiology of Fishes},"
#> [20] " pages = {iii},"
#> [21] " ISBN = {978-1-4832-2817-4},"
#> [22] " DOI = {https://doi.org/10.1016/B978-1-4832-2817-4.50001-9},"
#> [23] " url = {http://www.sciencedirect.com/science/article/pii/B9781483228174500019},"
#> [24] " year = {1957},"
#> [25] " type = {Book}"
#> [26] "}"
#> [27] ""
#> [28] "@inbook{RN465,"
#> [29] " author = {Fry, Frederick Ernest Joseph},"
#> [30] " title = {The Effect of Environmental Factors on the Physiology of Fish},"
#> [31] " booktitle = {Fish Physiology},"
#> [32] " editor = {Hoar, W. S. and Randall, D. J.},"
#> [33] " publisher = {Academic Press},"
#> [34] " volume = {Volume 6},"
#> [35] " pages = {1-98},"
#> [36] " ISBN = {1546-5098},"
#> [37] " DOI = {http://dx.doi.org/10.1016/S1546-5098(08)60146-6},"
#> [38] " url = {http://www.sciencedirect.com/science/article/pii/S1546509808601466},"
#> [39] " year = {1971},"
#> [40] " type = {Book Section}"
#> [41] "}"
#> [42] ""Create Report Outline
Now, magic! Now for the sake of the vignette, I can’t actually run it here, but below is a picture of what this looks like:
NMFSReports::buildReport(
sections = sections,
report_authors = report_authors,
report_title = report_title,
styles_reference_pptx = styles_reference_pptx,
styles_reference_docx = styles_reference_docx,
bibliography.bib = bibliography.bib,
csl = csl
)
buildReport() output
Folder architecture post-buildReport()
Alternative report structures:
library(NMFSReports)
# Input variables for buildReport()
sections = c("coverpage", # This is a specific template for a 1 page coverpage
"history",
"studyimportance",
"actions",
"endmatter") # This is a specific template that will document all of your citations throughout the report, the R packages you used to create this report. I'm biased, but please give credit where credit is due! There are also spots here to list people's ORCID numbers and acknowlegements.
report_authors = "Very important people"
report_title = "Shorter Report!"
styles_reference_pptx = "refpptx_nmfs"
styles_reference_docx = "refdoc_fisheries_economics_of_the_us"
bibliography.bib = "bib_example"
# Find citation styles at: https://github.com/citation-style-language/styles
csl0 <- read.delim(file = "https://raw.githubusercontent.com/citation-style-language/styles/master/american-fisheries-society.csl", header = FALSE, )
colnames(csl0)<-NULL
rownames(csl0)<-NULL
write.table(x = csl0, file = "csl.csl",
quote = FALSE, row.names = FALSE, col.names = FALSE)
csl = ("./csl.csl")
head(csl0)
#>
#> 1 <?xml version=1.0 encoding=utf-8?>
#> 2 <style xmlns=http://purl.org/net/xbiblio/csl class=in-text version=1.0 demote-non-dropping-particle=sort-only default-locale=en-US>
#> 3 <info>
#> 4 <title>American Fisheries Society</title>
#> 5 <id>http://www.zotero.org/styles/american-fisheries-society</id>
#> 6 <link href=http://www.zotero.org/styles/american-fisheries-society rel=self/>
# Run buildReport() function
NMFSReports::buildReport(
sections = sections,
report_authors = report_authors,
report_title = report_title,
styles_reference_pptx = styles_reference_pptx,
styles_reference_docx = styles_reference_docx,
bibliography.bib = bibliography.bib,
csl = csl
)