B Formatting Guidelines

B.1 General

  • Use R Markdown syntax. Of note, paragraph breaks are simply indicated by one ore 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 after9.

B.2 Programming Conventions

  • 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). Also, please provide links to these packages and libraries the first time you use them, as above.

  • For R naming conventions, I suggest you more or less follow the tidyverse style guide. In particular, you should use snake_case for just about everything except classes, which should be in PascalCase. Do not use dot.case in this project, and there are good reasons for avoiding this whenever possible elsewhere too.

B.3 Citations

For external websites it’s sufficient to provide a link as I’ve done in this document. For journal articles, textbooks, conference proceedings etc. it’s good practice to provide the complete citation information (in addition to a link to the resource if it can be obtained legally for free). For such references please use BibTeX with a module specific bibliography file my_module_references.bib. Here’s an example with the textbook for this class (Gelman et al. 2013). Please see how to add multple .bib files to index.Rmd here.

B.4 Numbering

  • To refer to figures/tables/sections, the standard academic style is e.g., “Figure 2”, “Section 2.5”, etc. In other words, capital letter, no bold/italics, and hyperlink for the number. See relevant bookdown chapter for how to do this!

B.5 Math

  • Please do take a look at the LaTeX guides above, as it is easy to do this right and very annoying to redo if you do it wrong.

  • One extremely useful LaTeX feature is the ability to define macros for commonly used commands. I strongly encourage you to use macros whenever possible. Not only does this save a considerable amount of typing, but also often an enormous amount of search-replacing. For example, suppose I have a canonical transformation function which I’ll be using throughout the document, but I’m not quite sure how to typeset it yet. So I define the LaTeX macro \ctran and use it. If later I want to redefine how \ctran is typeset that’s an extremely easy fix.

  • Another useful LaTeX trick is to use simple patterns to define macros for common things. For example, I always define bold letter names (which you should use for anything that isn’t a scalar) as \xx \YY, etc., and bold symbol names as \aal for \(\boldsymbol{\alpha}\), \TTh for \(\boldsymbol{\Theta}\), etc.

  • As a rule-of-thumb, avoid defining one-letter macros. The worst LaTeX mistake I’ve ever made is to define \(\beta\) as\b in everything LaTeX document I wrote before 2015. Now suppose I want to replace \(\beta\) by \(\gamma\) as a symbol for the quantity of interest. Then either I have an extremely confusing macro \newcommand{\b}{\gamma}, or the most annoying search-replace ever (\begin{xyz} anyone?). Sometimes I do use one letter capital macros, e.g., \newcommand{\N}{\mathcal{N}} for the normal distribution, but these are much easier to search-replace.

  • For this project, LaTeX is rendered to HTML via Mathjax, and thus the macros must be defined a bit differently than in regular LaTeX. All LaTeX macros must be defined in preamble.html.

  • Always use bold font like \(\XX\)10 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 above. 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\).

  • Equations are part of sentences, so use punctuation in them, e.g., for 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} \]

B.5.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-consumming 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)\).

B.6 Basic Formatting Tests

Test math macros: \(\var(\xx)\), \(\alpha_\xx\), \(\xx \ind \N(0, \sigma_{\tx{pool}})\).

Test figure:

plot(1:25, pch = 1:25)
Test figure.

Figure B.1: Test figure.

The reference to Figure B.1 is implemented correctly.

Test math equation

\[\begin{equation} f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k} \tag{B.2} \end{equation}\]

The reference to equation (B.2) is implemented correctly.

References

Gelman, Andrew, John B Carlin, Hal S Stern, David B Dunson, Aki Vehtari, and Donald B Rubin. 2013. Bayesian Data Analysis. CRC press. http://www.stat.columbia.edu/~gelman/book/.

  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 automagically 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!↩︎