More details on the R Journal format

H. Sherry Zhang and Di Cook

Source: vignettes/format-details.Rmd

This article will work you through the key parts of an R Journal template article as produced by create_article(). This assumes that you have already followed the “Create an R Journal Article” vignette, have created your initial article, and you have been able to knit both the pdf and html article. Here we explain the important parts you can see in the Rmd file that generates both output types, and how to modify them, and to debug if problems arise.

YAML header

This has these components:

  • title: "your article title"
  • abstract: > ....
  • author: with separate lines for name:, affiliation:, address:, url:, orcid:, email: and a block for each author
  • output format lines should look like
output:
  rjtools::rjournal_article
  • bibliography: RJreferences.bib

Figures

If you would like to have an interactive plot in the html output, you will also need to provide a static plot for the pdf output. You will need two code blocks, one for each, with conditional eval options. The inline reference will also need to do a conditional eval to write the appropriate reference link depending on the html or pdf knitting.

Of course, if only a static plot is to be rendered in both outputs, a single code chunk and a single inline reference will be sufficient.

Note that the structure of a thorough caption is three components: (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.

Static

For a static graph, use \@ref(fig:penguins) for in-text reference and your code chunk should look something like this:

```{r penguins, fig.cap="This is the figure caption"}
penguins %>% 
  ggplot(aes(x = flipper_length_mm, 
             y = body_mass_g, 
             color = species)) + 
  geom_point()
```

Interactive

For an interactive graphic, use separate code chunks to create a static plot for the pdf article and an interactive one for the html article:

```{r penguins-static, eval=knitr::is_latex_output(), fig.cap="This is the figure caption."}
penguins %>%
  ggplot(aes(x = bill_depth_mm, 
             y = bill_length_mm,
             color = species)) +
  geom_point()
```
```{r penguins-interactive, eval=knitr::is_html_output(), fig.cap="This is the figure caption."}
p1 <- penguins %>%
  ggplot(aes(x = bill_depth_mm, 
             y = bill_length_mm,
             color = species)) +
  geom_point()
plotly::ggplotly(p1)
```

Notice here you need eval=knitr::is_html_output() and eval=knitr::is_latex_output() to make sure that the pdf output only evaluates the first chunk and the html output only evaluates the second.

For in-text citation, you will something like this:

Figure \@ref(fig:`r ifelse(knitr::is_html_output(), 'penguins-interactive', 'penguins-static')` shows ...

This line is quite complicated so let’s dissect its components: the ifelse statement uses knitr::is_html_output() to decide if the output is an html or pdf output, then completes the figure reference to read either \@ref(fig:penguins-interactive), to reference the chunk of the interactive graphic in HTML output, or \@ref(fig:penguins-static), to reference the static figure for PDF output.

Sizing

For static plots, you can use fig.width and fig.height to adjust figure sizing for both pdf and html outputs.

For html output, distill provides several larger than text-width layouts, i.e. l-body (textwidth) l-body-outset (slightly extended from text width), l-page (pagewidth), and l-screen (window width). These can be set via the chunk option layout:

```{r layout = "l-body-outset", fig.width = 5, fig.height = 3}
library(ggplot2)
library(palmerpenguins)
ggplot(data = penguins, 
       aes(x = flipper_length_mm,
           y = body_mass_g, 
           color = species)) + 
  geom_point()
```

Notice that fig.width and fig.height still apply here and layout option will not affect the pdf rendering. Some interactive graphics set the figure sizing inside its function, for example,

  • plotly::ggplotly(p, width = ..., height = ...), and
  • ggiraph::girafe(p, width_svg = ..., height_svg = ...).

Sizing these figures should via the relevant arguments rather than the chunk options.

Captions with special formatting

To include formatted text or references in the caption to a figure requires a different approach for HTML and PDF output formats.

Here is an example of the necessary treatment:

```{r demo-html, eval=knitr::is_html_output(), fig.cap = "Here is _italics_ and a reference to @RJournal in a caption.", echo = FALSE}
knitr::include_graphics("figures/penguins.svg")
```

```{r demo-latex, eval=knitr::is_latex_output(), fig.cap = "(ref:demo-caption)", echo = FALSE}
knitr::include_graphics("figures/penguins.pdf")

And then to finish the caption text for the latex chunk use:

`r if (knitr::is_latex_output()) "(ref:demo-caption) Here is _italics_ and a reference to @RJournal in a caption."`

and to refer to it in the text:

Fig. \@ref(fig:demo-html) shows...

Alt text

Alt text is read by a screen reader for people with visual disability and authors are encouraged to include alt text in their figures to make them more accessible in the R community. You only need to add alt text for the html figures and this can be done via the fig.alt chunk option. There are a few guidelines on how to write an alt text can be found at here, here, and here. Remember an alt text is not supposed to tell the reader what can be learnt from the plot, but merely to describe what is on the plot. With a good alt text, people should be able to sketch a copy of the figure based on your description.

Tables

For simple markdown tables, please use the rmarkdown syntax for cross-referencing, i.e. 

  • in-line: The table \@ref(tab:foo) summarizes ...

  • markdown table caption: Table: (\#tab:foo) An overview of the ...

For tables generated using knitr::kable(), set up two chunks similar to the figures with different format arguments:

```{r penguins-interactive, eval = knitr::is_html_output()}
knitr::kable(head(penguins), format = "html", caption = "Table caption")
```
```{r penguins-static, eval = knitr::is_latex_output()}
knitr::kable(head(penguins), format = "latex", caption = "Table caption")
```

For inline reference, remember to use tab: instead of fig: in \\@ref(tab:penguins-interactive) and \\@ref(tab:penguins-static). The same layout used for figure sizing is also applicable for tables.

Equations

All equations need to have a label for consistency in both html and pdf outputs. For example:

\begin{equation} 
STP_{\textit{parity loss}} = \Big | \ln \Big( \frac{STP_b}{STP_a} \Big)\Big|. 
  (\#eq:parityLoss1)
\end{equation} 
\begin{equation} 
STP_{\textit{parity loss}} = \sum_{i \in \{a, b, ...\}} \Big|\ln \Big(\frac{STP_i}{STP_a} \Big)\Big|.  
  (\#eq:parityLoss2)
\end{equation}

Both equations will be numbered, and referenced with \@ref(eq:parityLoss2). So you can link to the equation in both html and pdf outputs.

Citations

The citation style will be added during the building process and you can find the csl file here. This style adopts a “capitalize-first” text case on title, which means it will capitalise the first world, including the one after the colon, and use lowercase for the rest. If you would like to preserve the text case of the title in the reference, wrap the word with curly braces. A common example of this is to preserve the lowercase R package name:

@Manual{crosstalk,
  title = {{crosstalk}: Inter-Widget Interactivity for HTML Widgets},
  author = {Joe Cheng and Carson Sievert},
  year = {2021},
  note = {R package version 1.1.1},
  url = {https://CRAN.R-project.org/package=crosstalk},
}

R Journal requires a link for easy access to the reference and this can be done through either the doi or url field. If both fields are presented, url takes priority and we recommend providing the URL link as url = {https://doi.org/.../...},, i.e.

@article{wickham_tidy_2014,
    title = {Tidy {Data}},
    author = {Wickham, Hadley},
    year = {2014},
    journal = {Journal of Statistical Software},
    volume = {59},
    number = {10},
    pages = {1--23},
    url = {https://doi.org/10.18637/jss.v059.i10}
}

For webpage entries, please use the url field instead of howpublished, under @misc, to provide the link (and the note field for access date), i.e.

@Misc{Wiki+HCL,
  author = {Wikipedia},
  title = {{HCL Color Space} --- {W}ikipedia{,} The Free Encyclopedia},
  year = {2023},  
  url = {https://en.wikipedia.org/wiki/HCL_color_space},
  note = {accessed 2023-07-12}
}

Styling

Custom css is discouraged, because all articles should look similar. However, if you would like to make small changes in style for the appearance of your paper, even to get sizing of plots and tables cleaner in the html output, you can add a custom css and point to it in the YAML along with the rjournal.css.

Converting from other Rmarkdown formats

If you are already writing your articles using Rmarkdown, and have written your article using the rticles::rjournal_article style it is straightforward to make the switch to the rjtools styling. These are the steps that you need to follow:

  1. change output formats to rjtools::rjournal_article to switch to the new style,
  2. remove any latex specific functionality,
  3. change figure, table references to \@ref() and
  4. add the rjournal.csl and rjournal.css template files to your folder, updating YAML to utilise them, and
  5. set the reference to the .bib in the YAML.

Code

Code chunks should provide the examples of usage of the package, if the paper is about an add-on package for R. Nice structure to the code is expected of R Journal papers.

Some good advice on code style can be found in:

Inline code, e.g., the function calc_stat from the bilby package, should be delimited by a single back-tick. The old latex command \code{} should not be used.

Your code should run reasonably fast. It is better to have a small example to illustrate your work.

Referring to packages

The old latex commands \CRANpkg{} or \BIOpkg{} can be used for all CRAN and Bioconductor package references. This will create a link in the document that links to the CRAN or Bioconductor site for the package. Any other package should be treated like code, and delimited using single backticks.

Handling data

Examples for your paper should be computed relatively quickly, which often means that the data files need to be relatively small (less than 5Mb).

If you have a large file that you believe should be used for the paper, you could store the file elsewhere, on your own GitHub repo, or on a data file share service like Figshare, and add download and handling code to your paper.

Handling slow computations

The editorial team needs to re-build your article to check that results are reproducible, and the editor will need to re-build your article when it is organised into an issue. Try to ensure that your code runs quickly. If you need to have a code chunk that takes several minutes or more to run, consider turning the chunk off, providing an intermediate state that is loaded into the next chunk. Generally, we advise against using the cache feature of Rmarkdown because when multiple articles are built in the issue construction it might render your article inadequately.

Trouble-shooting

If the pdf did not compile, check your latex installation, and update your version of rjtools. If this hasn’t fixed the problem, there may be a latex error in your file. If the .tex file was created you can use latex on your system to typeset from this file, and it might help you track down the location of the error in the .tex file, and hence narrow down the location in the .Rmd.