vignettes/check_functions.Rmd
check_functions.RmdThe 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 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, ggplotThe nine individual checks contained in initial_check_article() are:
and they can all be individually checked on the article.
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.
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.
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.
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{.}.
check_section(path = path_to_article) Section titles need to be in the sentence case and we are all good here :)
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 :)
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!
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!
Editors, associate editors and reviewers will routinely check that papers adhere to these criteria:
Advice on good coding style can be found in the rjtools article “More details on the R Journal format”.
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.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.