In NicolasJBM/writer: Functions and interfaces to support academic writing with R

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
options(tibble.print_min = 5, tibble.print_max = 5)
library(writer)

writer

Overview

I designed the package writer to help researchers document their work all along the research process. It builds on and complements the packages rmarkdown and rticles developed by Rstudio.

Pre-requisites

• R: available on CRAN for Windows and for Mac OS X;
• RStudio: freely distributed by RStudio;
• Latex: Miktex for Windows or Texlive for Mac OS X.

Content

This package contains various functions to cite, format, and publish in R, preferably using Rstudio. It also offers several latex templates and associated .bst files (references are managed using bibtex natbib) to format documents in the style of various academic journals.

Functions

First, the package contains functions to cite references in rmarkdown document:

• update_ref() is a shiny gadget to build and store in the writer package folder a database of references (called my_references) from a .bib file specified by the user;
• cite_ref() is a shiny gadget to find references in the database created by update_ref() and insert these references in a rmardown document.

There are also some functions designed to format quickly (but without much control) specific parts of the report:

• univariate() produces a table with univariate statistics;
• bivariate() produces a correlation table;
• dbl() formats numbers with two digits;
• int() formats numbers without digits;
• pct() formats percentages as numbers between 0 and 100, with two digits.

Finally, two functions are designed to knit .rmd files into .tex and then .pdf files:

• gen_paper() generates a paper using the .tex template associated with a specified journal;
• gen_appendix() generates the appendices to be added to the document (without template, to let the format of the main document apply).

Templates

Templates are provided for notebooks, papers, and presentations. For papers, the following table displays the various journals currently covered, the acronym to be used in the .rmd document, the .tex template applied, and the associated .bst or .cls file:

library(dplyr)
library(htmlTable)
data.frame(
  Journal = c("The Accounting Review",
              "Behavioral Research in Accounting",
              "Journals of Management Accounting Research",
              "Contemporary Accounting Research",
              "European Accounting Review",
              "Accounting, Organizations, and Society",
              "Critical Perspectives on Accounting",
              "Journal of Accounting and Economics",
              "Management Accounting Research",
              "Journal of Accounting Research",
              "Journal of Accounting, Auditing, and Finance",
              "Journal of Financial Economics",
              "Academy of Management Journal",
              "Academy of Management Review",
              "Management Science",
              "Organization Science",
              "Journal of International Business Studies",
              "Journal of Management",
              "Strategic Management Journal",
              "Journal of Applied Psychology",
              "Organizational Research Methods"),
  Acronym = c("tar","bria","jmar","car","ear",
              "aos","cpa","jae","mar","jar",
              "jaaf","jfe","amj","amr","mnsc",
              "orsc","jibs","jom","smj","jap",
              "orm"),
  Tex     = c("aaa_num.tex","aaa_nonnum.tex","aaa_nonnum.tex","car.tex","ear.tex",
              "elsevier.tex","elsevier.tex","elsevier.tex","elsevier.tex","jar.tex",
              "sage.tex","elsevier.tex","aom.tex","aom.tex","informs.tex",
              "informs.tex","jibs.tex","jom.tex","smj.tex","apa.tex",
              "sage.tex"),
  Bst     = c("aaa.bst","aaa.bst","aaa.bst","car.bst","ear.bst",
              "elsarticle-harv.bst","elsarticle-harv.bst","elsarticle-harv.bst","elsarticle-harv.bst","jar.bst",
              "apa.bst","elsarticle-harv.bst","aom.bst","aom.bst","informs2014.bst",
              "informs2014.bst","jibs.bst","jom.bst","smj.bst","apa.bst",
              "apa.bst"),
  Cls     = c("","","","","",
              "elsarticle.cls","elsarticle.cls","elsarticle.cls","elsarticle.cls","",
              "sagej.cls","elsarticle.cls","","","informs3.cls",
              "informs3.cls","","","","",
              "sagej.cls")
) %>%
  htmlTable(
    rnames = F,
    header = names(.),
    rgroup = c("Accounting","Finance","Management","Social-Psychology","Method"),
    n.rgroup = c(11,1,7,1,1),
    align = c("l","l","l","l","l")
  )

Installation

The package writer is currently only available under its development version. Indeed, I need to test and refine it before submitting it to CRAN. You can therefore install it from Github:

# The development version from GitHub:
# install.packages("devtools")
devtools::install_github("NicolasJBM/writer")

# to update the list of references you might want to insert in documents:
writer::update_ref()

# To allow the display of html figures in latex
install.packages("webshot")
webshot::install_phantomjs()

Usage

For any project you might be working on, I recommend creating first a folder "References" where you will store your .bib database of references; this will considerably facilitate citing prior literature, as I will illustrate later. Then, create a folder "Projects" in which you will make one folder per project you are currently working on. Finally, create a folder "Archives" where you will compress and store projects which have been completed or terminated.

In each folder dedicated to one project, I further recommend creating five sub-folders:

• Bibliography: the articles you have read in the context of the literature review;
• Dataset: a R package to collect, transform, and store your data for subsequent analyses;
• Notebooks: set of html reports where exploratory analyses are described and documented;
• Papers: rmarkdown, latex, and pdf documents for submission to various academic journals;
• Presentations: revealjs slides to present your research in conferences.

If you are interested in building packages of data to facilitate their subsequent use within the R environment, I recommend looking at this tutorial: creating a R data package. writer is more specifically designed to support researchers when they write notebooks, papers, and presentations. I will now review each kind of document, the role it plays in the research process, how writer helps you in writing it, and how you can adjust the output in case the templates I provide do not meet your needs.

Notebooks

In any research project, you have to start with an exploratory phase where you run many analyses before you find the ones you will eventually report in the final paper. Keeping a trace of these analyses is extremely useful, if only to avoid repeating them.

To create a notebook, create a new rmarkdown file:

This rmarkdown file has to be generated from a template called "Notebooks" and coming from the package "writer":

This procedure will create a folder containing the .rmd document where the user can describe and run exploratory analyses, a "ref.bib" file containing references (which can be replaced by the user's own library), and a sub-folder "fmt" where the "style.css" file formating the html document is stored (which can also be edited according to the user's preferences).

When the user knit the .rmd file, an independent html file formated according to the fmt/style.css specifications is produced.

Papers

Once you have a set of analyses you believe worthy of publication, you can start reporting them is a specific template designed to connect with the journal's template listed previously.

To create a paper, the first step is the same as for the notebook. Then, for the second step, you have to select the template called "Papers" coming from the package "writer":

This operation creates a folder with three files and a subfolder. Two .rmd files are produced, one for the paper itself, and another one for the appendices. A "ref.bib" file is also added, meant to be replaced later by the user's own list of references. Finally, the "fmt" subfolder contains .bst files to format the references for various journals, as well as some .cls files when they were provided by the publishers of these journals.

I recommend not to delete any file in the "fmt" subfolder, as they may be necessary when the user has to reformat the paper for another outlet. However, should some of the formating options currently coded be inadequate, the user can modify them.

When the user knit the .rmd file, many additional files will be generated, including the .tex file to which the template of the specified journal is applied.

Presentations

Finally, you might have to present your results in front of an audience. This is a lot easier when you can tie this presentation to your main analyses, so that all your documents can be updated together and rely on the same analytical and visualization techniques.

To create a presentation, the first step is the same as for the notebook or the paper. Then, for the second step, you have to select the template called "Presentations" coming from the package "writer":

This procedure will create a folder containing the .rmd document where the user can write the content of the presentation, a "ref.bib" file containing references (which can be replaced by the user's own library), and a sub-folder "fmt" where the "style.css" file formating the revealjs slides is stored (which can also be edited according to the user's preferences).

Next steps

The current templates need first to be tested and refined. Then, I might consider enriching the set of templates available for submissions to more journals.

Another avenue is to complement this research-oriented set of tools by adding more teaching-oriented templates: for on-line textbooks, posters, tutorials, and cases.

NicolasJBM/writer documentation built on Aug. 12, 2019, 2:36 p.m.