reports: An R Package to Assist in the Workflow of Writing Academic Articles and Other Reports

title: "reports Package Vignette" author: "Tyler Rinker" date: '2014-05-28' output: html_document: css: assets/fix-bootstrap.css toc: yes pandoc_args: [ "--biblio", "references.bib", "--csl", "ecology.csl" ]

reports Package Vignette

The reports package (Rinker, 2013) is designed to bring together the best R has to offer in report writing in an intuitive fashion. The user houses everything related to the writing process in one accessible location. The reports package assists in writing reports and presentations by providing a frame work that brings together existing R, LaTeX/.docx and Pandoc tools. The package is designed to be used with RStudio, MikTex/Tex Live/LibreOffice, knitr, slidify, knitcitations, Pandoc and pander. The user will want to download these free programs/packages to maximize the effectiveness of the reports package.

The reports package assumes the user has some familiarity with the report writing programs/packages it depends on. For a complete list of reports dependencies click here. This manual will not help the user to understand these dependencies as they have their own help documentation. Many functions in the reports package are set with defaults that assume the user is utilizing RStudio. This vignette assumes that the user is also operating out of the root directory of the new_report/presentation in RStudio.

1. Setting Up .Rprofile

2. Creating a New Report/Presentation

3. What's In the new_report/presentation Directory

4. Using reports Functions In-Text

5. Directory Management

6. Using notes.xlsx

7. Citations

8. Document Conversion

9. HTML Short Cuts

10. Custom Reports Templates

11. Odds and Ends

A. Reveal.js Slide Notes Locally

B. Custom style.css With RStudio + knitr

C. Presentations With slidify and RStudio

Symbol Conventions:

♦ = Example (R code)

[YT] = Video Demo (click to watch)

The user may want to set the following options in her .Rprofile. This will add efficiency to your workflow. [YT]

Option Function 1 bib.loc The path to the users primary .bib file (I store this in DropBox) 2 name.reports The name that will be automatically added to a report/presentation 3 sources.reports Path(s) to additional scripts to be sourced on project startup 4 temp.reports The primary template to use to generate reports (see template) 5 github.user GitHub user name 6 speed.temp A speed dial like interface that allows the template argument to take a number 7 present.template Path to, or default, .Rmd file template for use in as the .Rmd used in the slidify presentations

The following is the code I added to my own .Rprofile:

1. options(bib.loc = "C:/Users/trinker/Desktop/PhD Program/MASTER.bib")
2. options(name.reports = "Tyler Rinker\\\\University at Buffalo\\\\Department of Learning and Instruction")
3. options(sources.reports = path.expand("~/path_1"), path.expand("~/path_2"))
4. options(temp.reports = "apa6.mod.qual_tex")
5. options(github.user = "trinker")
6. options(speed.temp = list(`1` = "wordpress_rmd", `2` = "basic_rmd", `3` = "apa6.mod.qual_tex"))
7. options(present.template = "revealjs")

Creating a new report or presentation directory is easy. [YT]

The user can either preset the working directory or can supply a path to create the report/presentation directory in and then use the new_report or presentation functions.

setwd() method

setwd("C:/Users/trinker/Desktop")
new_report("MY REPORT")

path method

new_report("MY REPORT", path="C:/Users/trinker/Desktop")

You've just created your first report/presentation directory and you're ready to begin writing.

*Note The user can name the main directory differently from the names used within the directly by supplying a vector of length 2 to the report/presentation arguments as seen here:

new_report(c("Major1", "minor"))
presentation(c("Major2", "minor"))

The directory created by the new_report or presentation functions houses multiple subdirectories and files that integrate to speed up work flow. Please see the following links for PDF descriptions of the contents of the reports/presentation directory.

Report Workflow Presentation Workflow

click here

reports has a number of HTML shortcut functions that utilize two capital letters as names. These functions are ideally used in text with `r XX(args)`. Thus `r HR2("http://www.talkstats.com/")` yields:

www.talkstats.com

This use does not require wrapping with cat or the print argument.

To better display the HTML code the following examples do not use in-text (in-line) coding. The examples use the following code chunk form (rarely used in an actual report):

```{r}
R_CODE(_HERE)
```

This means that wrapping with cat or the print argument are usually required, however, this is not typical in standard usage.

The reports package contains functions to help maintain directories. They can speed up workflow through automation of directory related tasks.

`rdirs`, folder, and delete

rdirs is a function designed to recursively create directories. This is particularly useful when used in combination with new_report/presentation for creating weekly lecture notes for a class or other similar repeated tasks. The following code chunks demonstrate uses for 3 directory management functions in the reports package:

rdirs – recursive directory creation
folder – create a directory
delete – delete a directory(s)

*The next 5 code chunks are meant to be run sequentially

♦ Chunk 1- Create directory with multiple subdirectories ♦

fx <- folder(delete_me)
WD <- getwd()
setwd(fx)
rdirs(admin, 1:15, c("d", "f", "w"), c(1, 4, 6))

♦ Chunk 2- Return just the character vector. rdirs takes care of the front end padding of numbers. ♦

rdirs(admin, 1:15, c("d", "f", "w"), c(1, 4, 6), text.only = TRUE)

 [1] "admin_01_d_1" "admin_02_f_4" "admin_03_w_6" "admin_04_d_1"
 [5] "admin_05_f_4" "admin_06_w_6" "admin_07_d_1" "admin_08_f_4"
 [9] "admin_09_w_6" "admin_10_d_1" "admin_11_f_4" "admin_12_w_6"
[13] "admin_13_d_1" "admin_14_f_4" "admin_15_w_6"

♦ Chunk 3- Create dated folders ♦

rdirs(session, 1:12, seq(as.Date("2000/1/1"), by = "month", length.out = 12))

♦ Chunk 4- Create director of subdirectories of working reports folders ♦

setwd(WD)
gx <- folder(delete_me2)
setwd(gx)
x <- rdirs(admin, 1:15, c("d", "f", "w"), c(1, 4, 6), text.only = TRUE)
lapply(x, new_report)
View it...

♦ Chunk 5- Clean up with delete and reset working directory ♦

delete(c(fx, gx))
setwd(WD)

Image File Synchronization [YT]

The sync family of functions are also useful for syncing files between directories. This is particularly useful with the figure files in the REPORT and PRESENTATION directories and/or the img directory used by slidify (Vaidyanathan, 2012). The base version in the family, sync is generic and syncs files between 2 directories. The sync_all function is specifically designed to sync any files between the three image directories in a new_report/presentation directory.

To use sync_all simply type:

sync_all()

There are no arguments to sync_all, just run and the files between the following directories are synced:

~/REPORT/figure
~/PRESENTATION/figure
~/PRESENTATION/assets/img

Push Local Repo to GitHub

The user may choose to push a project (repository). The repo2github is designed for the initial push to github. Future pushes can be handled via RStudio or other git interface. The user may choose to initialize a push when new_report or presentation the project is created by adjusting the argument github = TRUE.

The notes.xlsx/notes.csv is a file located in the ARTICLES directory. It is useful to take notes from articles/websites/etc. and organize them here. The notes function can be used to view a truncated version of the notes. The citation functions also enables the user to insert in-text citations into a document with the quote taken from the article or other source. It is important that the format of notes.xlsx is respected in order for the citation family of functions to be utilized. In order for this workflow related to citations to be most effective the user must use a .bib file to manage citations. I use JabRef manage my bibliography. Here is a screen shot of notes.xlsx file.

notes.xlsx contains the following columns:

Document (bib key) - The bib key from the .bib file (usually authorYEAR)
Location (page) - The page number of the quote/passage (use an integer or integers separated by a dash)
Gist/Quote - The quote or a gist of a passage
Q - Is the row gist a quote? If so use b if not use n. Those marked y can be inserted as quotes into a document.
Notes - An optional column to add notes to self

The Gist/QuoteQ should be written in markdown/html. The notes.xlsx file also contains a quick reference for html on the right side:

Format Text for notes.xlsx [YT]

To assist in copying and pasting text from documents (particularly PDFs) the QQ (quick quote) takes a text string (optionally from the clipboard) and formats the text for use with notes.xlsx. Non-ascii characters (e.g. ligatures) and \n are removed/converted (though the string should still be checked). By default the string is copied to the clipboard for easy pasting into notes.xlsx.

The reports package has an integrated system citation related functions that can be accessed in .tex, .Rnw and .Rmd documents.

The user can view the bibkey and document title of the references in the .bib files via the BV (bib view) function.

♦ Example ♦

head(BV())

  num bibkey           title                                   
1   1 Yihui20131       knitr: A general-purpose package for dyn
2   2 Yihui20132       Dynamic Documents with {R} and knitr    
3   3 Yihui20133       knitr: A Comprehensive Tool for Reproduc
4   4 Boettiger2013    knitcitations: Citations for knitr markd
5   5 Vaidyanathan2012 slidify: Generate reproducible html5 sli
6   6 Rinker2013a      {qdap}: {Q}uantitative Discourse Analysi

Citation Family of Functions The citation family of functions grab a quote and format the text taken from the notes.xlsx/notes.csv for LaTeX/.Rmd with optional citation included. Functions attempt to copy the output to the clipboard for easy paste inclusion.

Each of the functions in the cite family follow a pattern of (cite, parencite, textcite, posscite, poscite) prefix and (L or M) suffix (note that currently only parencite and textcite functions exist for markdown). The cite and textcite are in the form of LaTeX commands by the same name. posscite and poscite are user defined LaTeX function styles that are extensions of the textcite command to fit possessive and -s- ending possessives. They can be defined as:

\newcommand\posscite[1]{\citeauthor{#1}'s (\citeyear{#1})} 
\newcommand\poscite[1]{\citeauthor{#1}' (\citeyear{#1})}

The L and M correspond to LaTeX or markdown outputs; markdown relies on the knitcitations (Boettiger, 2014) package.

♦ Example 1 - parenthesis cite ♦

parenciteM(1, force.block = FALSE)

 "An **EXAMPLE**; feel "free" to *delete* it ***soon***" ´r  citep("Rinker2013a")´

"An EXAMPLE; feel "free" to delete it soon" (Rinker, 2013b, p. 12)

♦ Example 2 - textcite ♦

textciteM(1, force.block = FALSE)

´r  citet("Rinker2013a")´ "An **EXAMPLE**; feel "free" to *delete* it ***soon***"

Rinker (2013b)"An EXAMPLE; feel "free" to delete it soon"

The LaTeX (L) versions of the functions work in a similar fashion but are used in .Rnw documents.

Updating .bib File [YT]

The user may update the .bib files within the new_report/presentation created directories directly or may choose to update the master .bib file housed elsewhere (set with the bib.loc option in the .Rprofile). If the user opts for the second route the update_bib function will update all the .bib files in the respective directory(s) according to the master .bib file.

The Pandoc based file conversion family of functions use preset path defaults (default is REPORT directory) to enable the user to quickly convert between document types. The user must have Pandoc installed and on the OS path. The function names are intuitive with the portion before the 2 being the current document type and the portion after is the desired outcome document type (from2to). Here is an example, converting the doc.tex file from the reports package library directory to a .docx file (when the user is employing these functions it is not necessary to provide arguments).

♦ Example - file conversion ♦

DOC <- system.file("extdata/doc_library/apa6.qual_tex/doc.tex", package = "reports")
BIB <- system.file("extdata/docs/example.bib", package = "reports")
tex2docx(DOC, file.path(getwd(), "test.docx"), path = NULL, bib.loc = BIB)

*Note that all of the conversion functions can be used to convert any legitimate Pandoc conversion but if the from2to format is not followed the documents and paths must be explicitly supplied as arguments to the reports conversion function.

The general format of the HTML examples is:

(a) the display of the code used

(b) the HTML code produced

This table lists the HTML functions and the HTML tag types produced. Click on the left column function names to see a demonstration of its use.

Code HTML Tag CN courrier new EM email FT font HL highlight text HR hyperref HR2 hyperref (new window) BT button HS horizontal space VS verticle space IF iframe IM image IM2 image (short path) IW image wrap PN presenter notes RF reveal.js fragment SC sprecial character TB text box TB2 writable text box YT YouTube VM Vimeo col2hex hex colors

CN (courrier new)

Wraps text with a courier new font tag. A specified version of FT but more convenient for constant use of courier new tags.

CN("new_report()")

[1] <font face="courier">new_report()</font>

new_report()

EM (email)

Wrap an email to generate an HTML email tag.

EM("tyler.rinker@gmail.com", print = TRUE)

<a href="mailto:tyler.rinker@gmail.com" target="_blank">tyler.rinker@gmail.com</a>

tyler.rinker@gmail.com

FT (font)

Wraps text with a font tags. Conveniently detects c(face, size` and/or color) and creates a font tag with the supplied text.

♦ Example 1 ♦

FT(6, text="guy")

[1] <font size="6">guy</font>

[1] guy

♦ Example 2 ♦

FT(6, blue, text="guy")

[1] <font size="6" color="blue">guy</font>

[1] guy

♦ Example 3 ♦

FT(6, red, times_new_roman, text="guy")

[1] <font size="6" color="red" face="times new roman">guy</font>

[1] guy

HL (highlight text)

♦ Example 1 ♦

cat(HL("Do not trust robots!"), "They are bent on destruction.")

<font style="background-color: #FFFF00;">Do not trust robots!</font> They are bent on destruction.

Do not trust robots! They are bent on destruction.

♦ Example 2 ♦

cat(HL("Jake is a cookie scientist,", color="pink"), "an honorable profession.")

<font style="background-color: #FFC0CB;">Jake is a cookie scientist,</font> an honorable profession.

Jake is a cookie scientist, an honorable profession.

HR/HR2/BT (hyperrefs and buttons)

Convert path/url to HTML href tag.

HR - Wrap a path/url to generate an HTML href tag.
HR2 - Convenience version of HR that opens in a new page.
BT - Wrap a path/url to generate an HTML hyperlinked text button tag.

♦ Example 1 - HR demo: no text given--basename used; opens in same window ♦

HR(path="http://dl.dropbox.com/u/61803503/Likert.pdf", print = TRUE)

<a href="http://dl.dropbox.com/u/61803503/Likert.pdf">Likert.pdf</a>

Likert.pdf

♦ Example 2 - HR demo: no text given--basename used; opens in same window ♦

HR("http://cran.r-project.org/", print = TRUE)

<a href="http://cran.r-project.org/">cran.r-project.org</a>

cran.r-project.org

♦ Example 3 - HR demo: text given; opens in same window ♦

HR("http://www.rstudio.com/ide/download/desktop", "click me", print = TRUE)

<a href="http://www.rstudio.com/ide/download/desktop">click me</a>

click me

♦ Example 4 - HR2 demo: text given; opens in new window ♦

HR2("https://github.com/trinker/reports", "reports", print = TRUE)

<a href="https://github.com/trinker/reports" target="_blank">reports</a>

reports

♦ Example 5 - BT demo ♦

BT("http://trinker.github.io/reports/dependencies", "Click Here!", print = TRUE)

<form action="http://trinker.github.io/reports/dependencies">
    <input type="submit" value="Click Here!">
</form>

HS/VS (spaces)

Insert n iterations of HTML spacing into a document.

♦ Example 1 - HS demo ♦

cat(paste0("reports", HS(10), "end"))

reports&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;end

reports end

♦ Example 2 - VS demo: single space ♦

cat(paste0("the", VS(), "end"))

the</br>end

theend

♦ Example 3 - HS demo: multiple spaces ♦

cat(paste0("the", VS(3), "end"))

the</br></br></br>end

theend

IF (iframe embedding)

Wrap a url to generate an HTML iframe tag.

♦ Example 1 ♦

IF("https://dl.dropboxusercontent.com/u/61803503/MWE.html", print = TRUE, height=250)

<div style="text-align:center;">
     <iframe src="https://dl.dropboxusercontent.com/u/61803503/MWE.html" width="640" height="250">Your browser does not support iframes.</iframe>
</div>