README.md

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

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:

Journal Acronym Tex Bst Cls Accounting The Accounting Review tar aaa\_num.tex aaa.bst Behavioral Research in Accounting bria aaa\_nonnum.tex aaa.bst Journals of Management Accounting Research jmar aaa\_nonnum.tex aaa.bst Contemporary Accounting Research car car.tex car.bst European Accounting Review ear ear.tex ear.bst Accounting, Organizations, and Society aos elsevier.tex elsarticle-harv.bst elsarticle.cls Critical Perspectives on Accounting cpa elsevier.tex elsarticle-harv.bst elsarticle.cls Journal of Accounting and Economics jae elsevier.tex elsarticle-harv.bst elsarticle.cls Management Accounting Research mar elsevier.tex elsarticle-harv.bst elsarticle.cls Journal of Accounting Research jar jar.tex jar.bst Journal of Accounting, Auditing, and Finance jaaf sage.tex apa.bst sagej.cls Finance Journal of Financial Economics jfe elsevier.tex elsarticle-harv.bst elsarticle.cls Management Academy of Management Journal amj aom.tex aom.bst Academy of Management Review amr aom.tex aom.bst Management Science mnsc informs.tex informs2014.bst informs3.cls Organization Science orsc informs.tex informs2014.bst informs3.cls Journal of International Business Studies jibs jibs.tex jibs.bst Journal of Management jom jom.tex jom.bst Strategic Management Journal smj smj.tex smj.bst Social-Psychology Journal of Applied Psychology jap apa.tex apa.bst Method Organizational Research Methods orm sage.tex apa.bst sagej.cls

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.