Getting started with respondR

Phil J. Bouchet

Centre for Research into Ecological & Environmental Modelling, University of St Andrews

2021-02-15

This vignette illustrates the use of the respondR package for writing responses to peer-review comments.

Rationale

Responding to comments on a manuscript is an essential yet sometimes daunting part of the peer-review process, particularly as clear and well-crafted responses are often tedious to formulate but can go a long way towards ensuring acceptance. respondR was designed to take away some of that strain by providing a user-friendly RMarkdown template that can produce professional-looking and consistently formatted response documents — encouraging authors to focus on content rather than style.

In particular, respondR conforms to best practice rules for academic peer-reviewing (Noble 2017), and facilitates the tasks of:

  • Providing an overview of edits (Rule 1).
  • Making the response self-contained (Rule 3).
  • Using typography to assist reviewers and editors in navigating the response (Rule 6).
  • Clearly identifying the changes made to the submitted draft (Rule 9).

Installation

The package can be installed using the following command:

# install.packages("remotes")
remotes::install_github("pjbouchet/respondR")

respondR is built around two core files:

  • A Microsoft Word (.docx) document housing the content of the response.
  • An RMarkdown document (and LaTeX backend) used for formatting.

The idea is to write up responses to reviewer comments in Word using the provided template, and subsequently generate a formatted PDF directly from within RStudio.

After installation, follow these simple steps:

  • Step 1: In RStudio, go to File > New File > R Markdown > From Template [Note: You may need to restart RStudio first].
  • Step 2: Select the Response to Reviewers template from the list and click OK. This will create an Rmd file, populated with a default template.

Figure 1. Creating a new file.

  • Step 3: Save the file to disk.
  • Step 4: Knit the document by going to File > Knit Document or clicking on the Knit icon in the top bar of the Rstudio editor and choosing Knit to response.

Figure 2. Knitting the RMarkdown file.

This will generate a Microsoft Word document entitled response_template.docx in the same directory as the current RMarkdown file (by default, when using RStudio). If desired, users can specify a file name and output directory by replacing the appropriate values in the first R code chunk, as shown below.

Figure 3. Custom file name and output directory.

Writing responses

The Word template consists of several tables, to be filled in by the authors.

Each table corresponds to either an Editor or a Reviewer. By default, respondR assumes that the article was handled by a single editor and two reviewers (i.e., a total of three tables). The table type is indicated in the header of the left-most column. Tables can be copied/pasted or deleted as necessary to match the correct number of editors/reviewers on a specific article.

Each table consists of the following columns:

  • Line: Line number, where applicable.

  • Comment: Reviewer comments.

  • Response: Response(s) to reviewer comments.

  • Action: Action(s) taken to address reviewer comments.

  • As_is: Indicates whether or not the changes made follow the reviewer’s suggestion. If so, leave the cell blank or use any of following terms: “Yes”, “yes”, “YES”, “true”, “TRUE”, “Y”, “y”. If not, use “No”, “no”, “N”, “NO”, “FALSE” or “false”.

  • Extra: Any additional/alternative edits made.

The below illustrates the range of outputs produced by respondR for different combinations of entries:

Action As_is Extra PDF output
<blank> <blank> <blank> No edits required ✓
NA (1) <blank> <blank> No action taken (text unchanged) x
Revised <blank> or yes (2) <blank> Revised, as suggested ✓
Revised No (3) <blank> Revised, with additional edits ✓
Revised No (3) e.g., updated metadata Revised + updated metadata ✓
Revised <blank> or yes (2) e.g., updated metadata Revised, as suggested + updated metadata ✓

(1) or: n/a, na, N/A, Not applicable, not applicable, Not Applicable

(2) or: Yes, yes, YES, Y, y, true, TRUE

(3) or: no, N, NO, FALSE, false

respondR also contains functions to compare text excerpts and identify differences between them. This can be used to highlight revisions made on specific sentences or paragraphs.

  • Txt_orig: Original text as it appeared in the submitted draft.
  • Txt_revised: Revised text.

Finally, the last table in the template is a single-column table used for referencing, should any literature be cited within the response document. If none are used, this table should be left blank. Users are free to rely on any Word-compatible reference management software of their choosing (e.g., Mendeley, Endnote, Zotero, PaperPile). Note, however, that references must be flattened before knitting, as reference fields will otherwise be imported as text and will mess with the output.

Once the response text is finalised, go back to RStudio and knit the RMarkdown file to generate a formatted PDF ready for submission to the journal.

Customisation options

respondR offers a number of options for customising the look and feel of the final PDF.

  • Article metadata: The YAML header includes fields to display the article title, author list, and manuscript ID. These should be fairly self-explanatory and can be updated as needed.

Figure 4. Author list and manuscript details.

  • Colour scheme: The colours used for background elements and text fonts can be changed within the YAML header. These are expressed in Normalized decimal RGB form, and are given as vectors of three values between 0 and 1 for the red, green, and blue colour channels, respectively. There are many online colour pickers - a good one can be found at https://doc.instantreality.org/tools/color_calculator/.

    • dark controls the background colour of the header (‘Response to reviewers’) shown on the first page.
    • light controls the background colours of all section titles.
    • mid controls the colour of the text used for section titles, actions, and text edits.

    - noaction defaults to a light grey font, which is used to identify areas where no changes were made in response to specific comments.

Figure 5. Custom colour scheme.

In addition, the second R code chunk offers the below options:

  • include_summary: When set to TRUE, the final response PDF will display a summary of all edits on the first page, to help assess the actions taken in response to reviewer comments ‘at a glance’.
  • comment_font: Font used for comments. Defaults to "standard" for a normal font. Other values include "italics" and "bold".
  • response_font: Font used for the response text. Set to "bold" by default. Other values include "italics" and "standard".
  • highlight_textrevisions: Font style used to highlight text edits when the Txt_orig and Txt_revised columns of the Word template are not empty. Set to "underline" by default. Other values include "bold", "italics", and "standard".
  • text_unchanged: Custom text to show when no edits were made on the original text. Defaults to: "Text unchanged".
  • newpage_sections: If set to TRUE, adds a page break between sections (e.g., between reviewers/editors).

References

Noble WS (2017). Ten simple rules for writing a response to reviewers. PLoS Comput. Biol. 13, e1005730. DOI: 10.1371/journal.pcbi.1005730