Chapter 27 Style Guide

27.1 Filenames

Every chapter is in a file that contains only digits (0-9), lowercases letters (a-z), and dashes (-), followed by a period and the extension, which is always .Rmd. The digits determine the location of the chapter in the book. The first digit determines the Part of the book where the chapter is located:

  1. Basics: Preliminary information, for example about software.
  2. Univariate analyses: Analyses including exactly one variable, such as means and histograms.
  3. Psychometrics: Analyses used when developing or evaluating operationalizations of psychological constructs (i.e. measurement instruments or manipulations).
  4. Bivariate analyses: Analyses including exactly two variables, such as Pearson correlation coefficients, Cohen’s \(d\), and \(t\)-tests.
  5. Multivariate analyses: Analyses including three or more variables, either as predictors (e.g. multivariate regression analysis or two-way anova) or criteria (e.g. manova).
  6. Appendices: Information that is not important for readers, such as this style guide.

Within these Parts, the chapters are ordered based on the second and third digits. However, we only use this to manually set the order for Parts 1 and 6. In the Parts with most of the book’s content, Parts 2-4, the chapters should be sorted alphabetically. These chapters should all be named for the analysis they cover. This way, readers can easily find a given analysis. These filenames should always have 10 as second and third digits.

The first three digits should always be followed by exactly three dashes. For example, the chapters about anova and scatterplots are named 410---anova.Rmd and 410---scatterplot.Rmd, respectively. Spaces are replaced by one dash. For example, the chapter about coefficient Alpha is named 310---coefficient-alpha.Rmd.

27.2 Symbols and statistical characters

Symbols and statistics characters should always use LaTeX Math (which can also be used for equations, if necessary). For example, the “d” in Cohen’s \(d\) should be placed between single dollar symbols: $d$. This ensures consistency in typography between use in equations in in the running text.

27.3 Chapter and section identifiers

Always manually specify the identifier for chapters and sections. Although Bookdown can produce such identifiers automatically, it may sometimes be necessary or desirable to rename chapters or sections, and manually specifying the identifiers allows doing this without breaking cross-references. Identifiers are added after the corresponding heading in between curly braces (accolades), and preceded by a hash (#). For example, the identifier of this chapter is specified using {#style-guide}.

Identifiers of chapters must always be identical to the filename of the chapter, but omitting the prefixed number and the extension. For example, the filename of this chapter is 960---style-guide.Rmd.

All section identifiers much start with their chapter identifier, separated by a dash. For example,

27.4 Cross-references

To refer to another chapter or section within a chapter, always use the chapter or section number. These numbers are automatically produced in Bookdown by referring to the identifiers of the chapter or section like this: \@ref(identifier), where identifier is replaced by the identifier of the target chapter or section. Note that you will have to include “Chapter” or “Section” in the text yourself, if you want to.

Cross-references should always use this method (i.e. using the number of the chapter or section that is referenced). Even though this is slightly less userfriendly for readers reading the HTML version (compared to named links), using numbers for cross-referring is the only way that also works for readers of other formats (e.g. the PDF or EPUB versions, which users may print).

27.5 Citations and references

Citations and references use Bookdowns native format. This requires the references to be present in a BibTeX file, and this BibTeX file is automatically generated by the script download_and_save_bibliography.R that is ran automatically before the book is rendered. It downloads the references in the Zotero groups “Rosetta Stats”, which is located at https://www.zotero.org/groups/2419994/rosetta_stats. If you contribute to Rosetta Stats, and you need to cite a source not yet in that library, join the group and request

To add a reference, place its unique identifier, prefixed with an @, between straight brackets: [@navarro_learning_2018]. You can see the identifier for a reference by running download_and_save_bibliography.R. This will show a list of the identifiers in the R console. It will also update bibliography.bib, which is then uploaded to the Git repository and is always available for inspection at https://gitlab.com/sci-ops/rosetta-stats/blob/master/bibliography.bib.

27.6 Figures

For software that relies on graphical user interfaces Figures are a great way to illustrate how to do something, especially for software using a GUI. When using figures, stick to the following conventions.

27.6.1 Try to avoid figures

This may seem ironic, but is important nonetheless. Whenever content can be presented using text, for example tables, statistical commands, or output, avoid figures. There are two reasons for this.

First, people who are visually impaired or blind rely on screen readers, and if you succumb to the relative effortlessness of screenshotting a table, that virtually makes the table inaccessible to them. However, if the table is specified using Markdown or HTML, screen readers can parse its structure, present it to readers, and facilitate their navigation through the table.

Second, especially for statistical commands, readers will often come to this book exactly to copy-paste commands. This is not directly possible from figures (although OCR software exists to facilitate the process, of course).

27.6.2 Screenshots

If you include screenshots, make sure they do not exceed 1000 pixels in width (ideally even 800 at most) and 1200 pixels in height. If you make them larger, the fonts will no longer be comfortably legible for everybody in the online version, the PDF ebook, or the EPUB ebook.

For software to support easily resizing window, and easily screenshot windows or a part of the screen, see Chapter 28.

27.6.3 Path and filenames

All figures must be placed in the /img directory. Their filename must always start with the filename of the chapter where they appear (so figures in this appendix would have 960-style-guide as a prefix), followed by a unique identifier for the figure within that chapter. For example, section 2.1 contains a figure called 120-software-basics-jamovi-fresh.png.

27.6.4 How to include a figure

To include figures, always use the knitr::include_graphics() function to ensure proper embedding of the figure in all output formats (see the Bookdown book for more details). Call this function in an R chunk that has as a chunk label the filename of the figure without the extension and prefixed number. Therefore, the R chunk used in section 2.1 to embed the figure from file 120-software-basics-jamovi-fresh.png has as its label software-basics-jamovi-fresh.

Also, always include caption for every figure. The caption should ideally describe the figure, with blind readers and readers with impaired eyesight in mind. In addition to this reason for supplying figure captions, this also triggers Bookdown’s automatic numbering of the figures, which in turn enables cross-referring to figures.

This is a full example, lifted from section 2.1:

```{r software-basics-jamovi-fresh, fig.cap='A fresh install of jamovi.'}
knitr::include_graphics(here::here("img", "120-software-basics-jamovi-fresh.png"));
```

It is important to note that chunk labels can only contain single dashes; they cannot include two dashes following each other. For the rest, the chunk labels conform to the rules for chapter names: only lower case letters (a-z), digits (0-9), and (single) dashes (-).

27.6.5 Referring to figures

Refer to figures using the same method as you use for referring to chapters and sections, using the chunk labels with fig: prepended as identifier. For example, to refer to the figure from the example from section 2.1, we use \@ref(fig:software-basics-jamovi-fresh), which Bookdown them automatically turn into a number (and hyperlink for the HTML version of the book), which we can then prepend with “Figure” to get a nice reference to Figure 2.1.

27.7 Software-specific guidelines

This section lists conventions for specific software packages.

27.7.1 R

27.7.1.1 Package parsimony

Only use base R or functions from the rosetta package that accompanies this book (to which you can of course contribute; the repo is at https://r-packages.gitlab.com/rosetta). You should experience a very, very high threshold to require the user to use any other packages than rosetta (the only exception to this rule is ggplot2, which is already installed with rosetta). This convention is based on two things.

First, Rosetta Stats should make it as easy as possible for people to transition to R, so the number of different packages we requires users to use should be somewhat aggressively kept to a minimum. If another package has functionality that is not available in base R or rosetta, write a wrapper function in rosetta, optimized to mimick the way that specific analysis is specified in other statistical packages, and mimicking the output generated in other statistical packages.

Second, everybody has different preferences for doing things. For example, at the moment (early 2020), the Tidyverse is a popular approach within R, and some people believe the Tidyverse to be better, and others to be worse, than using base R. In five or ten years, different trends will emerge. Rosetta Stats is meant to be agnostic concerning such preferences. This is why we do not use the tidyverse in the R sections.

If you think that despite these considerations, it is warranted to use another package anyway (for example, because developing a wrapper in the rosetta package is somehow not possible or desirable), contact the person responsible for the R bits in Rosetta Stats (see Appendix 25).

One exception is the Tidyverse itself. Because the Tidyverse is very popular, but also fundamentally different in how learns to think about working with objects in R, the Tidyverse has a special section, as if it were a different statistical package.

27.7.1.2 Calling::functions

When providing R code, always prepend functions with the corresponding namespace (i.e. package name). This is an important convention to avoid clashes for users who have loaded packages with the same function names. An added benefit is that this eliminates the need to let users attach the package’s namespace using library() or require(), simplifying the code to provide.

So, instead of using, for example:

library(dplyr);
dat <- rename(dat, newVariableName = oldVariableName);

Use:

dat <- dplyr::rename(dat, newVariableName = oldVariableName);

In addition, whenever using commands that are not part of base R, such as are included in rosetta, ggplot2, or tidyverse packages, caution users that they much have that package installed.