B Formatting Guidelines

Author: Martin Lysy, Trang Bui

Last Updated: Feb 04, 2021

B.1 General

  • For a module, name your file starting with mod_ and for a appendix, name your file starting with app_.

  • For headers, place a space between the last sharp symbol \(\#\) and the name of the header.

  • Let’s agree to use regular font for programming languages (e.g., R, Python, C++) and bold font for packages and libraries (e.g., TMB, rstan, NumPy, Tensorflow). Use code font for files, data sets, codes and arguments. For functions, use parentheses at the end, for example, my_func(). Use curly brackets \bm{} for LaTeX functions. Use <kbd>Key</kbd> for key strokes or buttons.

  • Paste a link to packages which are mentioned for the first time. For R packages, you can use the cran_link() function to do this. For example, rstan.

  • Please see Appendix B.2.3 for how to handle citations.

  • To refer to figures/tables/sections, use the standard academic style is e.g., “Figure 2”, “Section 2.5”, etc. In other words, the word is non-bold and non-italic, with the first letter capitalized, and the number following the word should have hyperlink. See relevant bookdown chapter for how to do this. To refer to modules, use the text name, details can be found here.

  • Refer to common_functions.R for commonly used functions across modules before writing your own.

  • To make cross-referencing consistent in bookdown, for all labels – code chunks, figures, tables, sections, equations, etc. – use the prefix of the corresponding file as the prefix of any label. So please choose and use a module-specific prefix for each cross-reference. For example, use label #formatguide for this section. Refer to prefixes.txt for the list of the used prefixes and add yours there. Try to use the prefix that is distinctive to other words in the text such that you can find and replace all without mistakes.

  • Give names to all code chunks, even e.g., pure code and figures you don’t refer to. Note: Chunk labels must consist of only letters, numbers, dashes (-), and slashes (/) – no underscores! Otherwise, cross-referencing won’t work properly.

  • Paragraph breaks are simply indicated by one or more empty lines. No need for \newline or anything else. This applies to elements other than text such as figures, math blocks etc. If the figure/math block/etc is part of the paragraph, don’t leave blank spaces before or after1.

  • Please use Capital Case for all section headings, for example, Plan the Study.

  • Our consensus for writing in a list is mentioned below. For details, visit here.

    • Use - to denote lists.
    • If the items in the list are complete sentences, begin the first word in each item with a capital-case letter and end the item with period.
    • If the items are single words and phrases, begin the first word in each item with a lower-case letter and end with a comma. Use “and” (or “or”, depending on the context of the list) after the next-to-last item, and use a period after the last item in the list.
    • If the items are phrases or clauses with punctuations in them, put a semicolon at the end of each item. Put “and” (or “or”) after the next-to-last item in the list and period for the last item. The items are not capitalized.

  • For indentation, use four spaces before your paragraph, code chunk, or equation. This will be very helpful when you have an item in an itemized list which contains more than one paragraph, equation, or code chunk.

  • Name all code chunks according to the above guideline about cross-references. For code chunks that take long time to run, use cache=TRUE to prevent the chunk to be executed again unless the code in the chunk has been altered. More detail can be found here.

  • Use the package styler to make the formatting of your code consistent. To do this, run the function styler::style_file() for your module’s Rmarkdown file. Do not set the option tidy = "styler" to your chunk code to prevent caching issues. The details of the package can be found here.

  • Use "" instead of ’’ for quotes.

  • Use underscore _ instead of dot . to name variables.

B.2 Embedding Files

To embed a file in your module, first put it in any subdirectory of the data folder of the repo. For example, the repo currently contains the file data/caliRain.csv. You can then use the file anywhere in your module, e.g.,

head(read.csv("data/caliRain.csv"))
##                     STATION PRECIP ALTITUDE LATITUDE DISTANCE SHADOW
## 1 Eureka                     39.57       43     40.8        1      1
## 2 RedBluff                   23.27      341     40.2       97      2
## 3 Thermal                    18.20     4152     33.8       70      2
## 4 FortBragg                  37.48       74     39.4        1      1
## 5 SodaSprings                49.26     6752     39.3      150      1
## 6 SanFrancisco               21.82       52     37.8        5      1

In order to let users download the file, you can simply provide the link using regular Markdown syntax. In other words, [download link](data/caliRain.csv) will render as download link.

Note: This method works because somewhere in the project we make a call to knitr::include_graphics("data/arbitrary/file.ext"), which has the effect of adding the data folder to the bookdown output directory. In previous attempts we tried explicitly adding the data folder to the output via dir.create(). However, this requires that the output directory be supplied in advance, whereas in general it can be set on-the-fly via the output_dir argument to bookdown::render_book().

B.3 Math

  • Always use bold font like \(\XX\)2 or \(\aal\) for anything that isn’t a scalar. In particular, please use \bm{} command in math mode to make things bold, and note that bold letters and symbols have standard macros as explained in index.Rmd. Please use them!

  • If applicable distinguish between vectors and matrices (or collections of vectors) with lower and upper case, like \(\yy\) and \(\YY\) or \(\tth\) and \(\TTh\).

  • If the math equations are part of sentences, end them with suitable punctuation. If the formula is a derivation with multiple steps, only put punctuation at the final step.

  • If an equation is to be written in a new line, use two dollar signs to start and finish the equation. For example, consider observations \(\XX = (\rv X N)\) such that \[ \begin{aligned} X_i \mid \mu_i & \ind \N(\mu_i, \sigma_i^2) \\ \mu_i & \iid \N(0, \tau^2). \end{aligned} \tag{B.1} \]

  • Generally, a colon should not be used to set off an equation, even when it is a displayed equation. Typically an equation is the object in a sentence. Use a colon on occasion for emphasis, but make sure it fits grammatically. Examples can be found here. The same rules apply for code chunks.

  • Use \(j^{th}\) and \((i,j)^{th}\).

B.3.1 Commonly-Used Math and Stats Expressions

  • Sequences of random variables: \(X_1, \ldots, X_N\). In fact since these are so common, I’ve created a macro for it: \(\rv Y 5\) and \(\rv [m,0] Z {m,N_m}\).

  • For multi-line equations with alignment, use aligned environment as in (B.1).

  • The “d” in integrals: \[ \ud X_t = \mu(X_t) \ud t + \ud B_t \qquad \iff \qquad X_t = \mu t + \int_0^t \mu(X_t) \ud t + B_t. \]

  • Conditioning: \(p(y \mid x)\).

  • Independence: \(Y \amalg X\).

  • Probability: \(\Pr(Y \le y)\).

  • Derivatives and partials: These are quite time-consuming to typeset so I’ve created some macros for them: \[ \der{x} f(x), \qquad \fdel[3]{x} {g(x, y)}, \qquad \hess{\tth}\ell(\tth \mid \XX). \] The last of these is used for Hessian matrices.

  • Independent/IID/Normal: Please see (B.1).

  • Variance/Covariance/Correlation: \(\var(X), \cov(X), \cor(X)\).

  • The \(p\)-value and the \(F\), \(t\) or chi-square tests.

  1. An exception to this is possibly within an indented region. There you may need to leave a blank space before/after math block…I’m not 100% sure…↩︎

  2. LaTeX purists might prefer to use \mathbf{} for roman letters instead of \boldsymbol{} as I have defined via the \bm{} macro in preamble.html. Observe the difference: \(\mathbf{x}\) vs \(\boldsymbol{x}\) and \(\mathbf{X}\) vs \(\boldsymbol{X}\). For pure LaTeX, the \bm{} command in the bm package automatically picks the right one for you. Eventually, I’ll figure out how to use this package for the e-book, in which case if you consistently use \bm{} for bold there will be very little for me to change!↩︎