The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Check your article before submission

H. Sherry Zhang and Di Cook

The rjtools package has implemented some automated checks to assess if it appropriately follows the R Journal format. It is important that authors read information at journal website.

This vignette will demonstrate these checks with an example article, paper-with-errors, where the argument path = path_to_article in the checks points to the directory of the .tex file. If you have created the article using create_article() with the default arguments, you can check with path = here::here("rjarticle").

All checks in one function

All the nine checks in rjtools can be completed with initial_check_article(), given a path to the article folder:

initial_check_article(path = path_to_article)

The check result will be saved in an initial_check.log file under the same folder, as well as displayed in the console. This is how it looks like for the sample article:

Initial check results:
ERROR: Submission does not have consistently named tex, bib, and R files
SUCCESS: No problematic file found
SUCCESS: Possible motivation letter found
ERROR: The title is not in title case! Suggest title to be changed to:
ToOoOlTiPs: An R Package for Customizable Tooltips in Interactive Graphics
SUCCESS: All sections are properly formatted in sentence case
SUCCESS: Abstract comes before the introduction section
NOTE: A potential list of spelling to check: tooltips, tooltip, alison, ggplot

Individual check functions

The nine individual checks contained in initial_check_article() are:

check_filenames()
check_unnecessary_files()
check_cover_letter()
check_title()
check_section()
check_spelling()
check_proposed_pkg()
check_packages_available()

and they can all be individually checked on the article.

Filenames

check_filenames(path = path_to_article)

The .bib file is named Rjreferences.bib when created and we recommend setting a consistent name across the .bib, .tex, and .Rmd file. A fix to this is to rename the Rjreferences.bib as the file name you used when create the article, in our case, paper-with-errors.

Presence of unnecessary files

check_unnecessary_files(path = path_to_article)

This function checks that the folder doesn’t contain the RJtemplate.tex file, which is included the past R journal template. The authors instruction requires the authors to replace the content of this RJtemplate.tex file with article content and name with the lowercase concatenated author name, so it is essentially the .tex file automatically generated in the previous section. Our article don’t have unnecessary files.

Presence of a motivating letter

check_cover_letter(path = path_to_article)

Cover letter should be provided for all articles and saved at the same folder as the article. The function checks whether there possible motivation letters are in the main directory, and recommends to put them in the motivation-letter folder if so. Our article passes this check.

Article title is in title case

check_title(path = path_to_article)

The article title needs to be in the title case and the check is not happy with our title here. Use tools::toTitleCase() to get the correct title case format:

tools::toTitleCase("ToOoOlTiPs: An R package for Customizable Tooltips in Interactive Graphics")
#> [1] "ToOoOlTiPs: An R Package for Customizable Tooltips in Interactive Graphics"

Here we forget to capitalise “P” in the word “package” - better make this change before submission! Also if the title contains the package you’re proposing, i.e ToOoOlTiPs in our article, use the \pkg{.} tag rather than \CRANpkg{.}.

Section title is in sentence case

check_section(path = path_to_article)

Section titles need to be in the sentence case and we are all good here :)

Spelling

check_spelling(path = path_to_article)

The spelling is checked from the abstract to bibliography section and only words with all lowercase letters are checked to avoid picking up on acronyms and names. The underlying checking is done through the hunspell package with US spelling by default. British spelling can be checked with argument dic = "en_GB". The R journal welcomes both the U.S and British spelling, along with other national variation, as long as consistency is maintained.

Notice that the spelling check may pick up some domain specific vocabularies and authors may want to further confirm if these are true spelling mistakes. In our article, “tooltip” is a specialised vocabulary in interactive graphics, rather than a misspell, so we are free to go :)

Package is available on CRAN

check_proposed_pkg()

The package proposed in an article should already be available on CRAN before article submission. check_proposed_pkg() prompts the following in the console:

What’s the name of package being proposed in the article? If none, please enter 0.

and authors need to enter the exact package name, with proper capitalisation, for an availability check on CRAN download. For our article, enter ToOoOlTiPs in the console and the check would say

NOTE: No CRAN activities detected for package ToOoOlTiPs

Not surprising that CRAN can’t find our package since it is a hypothetical one!

Package availability

check_packages_available(path = path_to_article)

All the packages mentioned with a \CRANpkg{.} or \BIOpkg{.} tag need to be available on CRAN or Bioconductor and check_packages_available() makes sure this is the case. For our article, we get

! ERROR: 1 of 5 package(s) not available on CRAN: ToOoOlTiPs

which is not really an issue here!

Checklist

Editors, associate editors and reviewers will routinely check that papers adhere to these criteria:

General

Filenames are sensible such as author-names.XXX
Add-on package, and dependent packages, are on CRAN
Code runs easily and quickly
Examples can be reproduced with the R code provided
Code is appropriately indented
Contact email address is provided for at least one author

Titles

Title need to be in title case
Section titles should be in sentence case
No special formatting can be used in the title

Abstract

Should not have math notation

Mathematics

Brackets need to be appropriately paired
Punctuation after equations needs to be consistent
Mathematical operators (e.g., log) should be roman, not italic

Code

Chunks of code in the text of the paper are concise and not overly long, is readable and nicely formatted.
Code provided with the paper reproduces the results reported in the paper.

Advice on good coding style can be found in the rjtools article “More details on the R Journal format”.

Figures and tables

Figures are readable and clear. Good advice on figure can be found in
- Healy (2018) Data Visualization: A practical introduction, available at https://socviz.co
- Wilke (2019) Fundamentals of Data Visualization, available at https://clauswilke.com/dataviz/
Tables are constructed effectively, with right-justified numbers, and don’t exceed text margins. See Schwabish (2020) Ten Guidelines for Better Tables for advice on tables.
Captions have three parts: (1) what is the plot/table about, (2) specific details of plot/table, like what type of display and how variables are mapped, (3) the most important thing that the reader should learn.

Citations

All R packages used in the work are appropriately cited. For example, if you use ggplot2 to make your plots, the citation for this package needs to be added to your paper. See more details below if you need help on how ot do this.
All references need to have a DOI where available, best added using the URL item.
The default bibliography style needs to be used.
Use consistent capitalization for titles in the citations, which may require manual editing if extracting citation information from different services.

How to get the package citations

The preferred citation is provided by:

> citation("ggplot2")

To cite ggplot2 in publications, please use

  H. Wickham. ggplot2: Elegant Graphics for Data Analysis.
  Springer-Verlag New York, 2016.

A BibTeX entry for LaTeX users is

  @Book{,
    author = {Hadley Wickham},
    title = {ggplot2: Elegant Graphics for Data Analysis},
    publisher = {Springer-Verlag New York},
    year = {2016},
    isbn = {978-3-319-24277-4},
    url = {https://ggplot2.tidyverse.org},
  }

To check if you’ve appropriately cited all the packages used in your code, the grateful package can help.

In the project where you are writing your paper, use

cite_packages(out.dir = ".")

to get a .bib file for all packages referenced. The entries can be added to the rest of your paper’s bib file.

The scan_packages function can give you a list of the packages you are using.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.