Write each symbol through a shared macro file, and write the macro everywhere the symbol appears. A group that writes the same quantity in raw LaTeX in one document and with a macro in another ends up with two notations for one quantity. Changing a convention then means editing every document by hand. Before you write any symbol, search the group's shared macro file for the concept it names. If a macro names the concept, use it. If none does, add one to the shared file before you use the symbol, so the next document finds it. ::: {#exm-use-shared-macro} ## Using a shared macro This example compares the source you type, so both versions appear as code. > ❌ Source: `Let $\beta_1$ be the slope and write the sum as $\sum_{i=1}^n$.` > > ✅ Source: `Let $\coef{1}$ be the slope and write the sum as $\sumin$.` The ❌ version writes the slope and the sum in raw LaTeX. The ✅ version names each concept once, in the shared file. When the group changes how it prints a coefficient or a sum, every document that uses the macro changes with it. ::: The same rule covers these quantities: - transposes - hats on estimates - expectations - variances - probabilities - vectors A quantity that has a macro keeps the same symbol in every document. Name a macro for what the symbol means, not for the letter it prints. A macro such as `\vdelta` or `\hbeta` only spells a Greek letter, so it names no concept, and changing the symbol for that concept still means editing every use. Outside a passage that discusses the notation itself, do not write a Greek letter in a math expression, either as a raw command such as `\delta` or inside a letter-named macro such as `\vdelta`. The only exception is a one-off symbol that fits no semantic category, and the rule for Latin letters below says when that applies. ::: {#exm-semantic-macro-name} ## Naming a macro for its meaning > ❌ Source: `The error at layer $\ell$ is $\vdelta^{(\ell)}$, and the step size is $\eta$.` > > ✅ Source: `The error at layer $\ell$ is $\backerr^{(\ell)}$, and the step size is $\learnrate$.` Both versions print the same symbols. In the ✅ version, a reader of the source sees what each symbol stands for, and a group that changes the symbol for the step size changes one line in the shared file. ::: A passage about the notation itself, such as a table that lists each symbol and what it means, may write the letters directly. The same reasoning applies to decorators. A hat, a tilde or a bar says how a symbol is drawn, not what it means. A hat can mark an estimate, a [fitted value](#def-fitted-value) or a Fourier transform, so `\hat` names no concept either. Write the macro that names the role instead, such as `\est{}` for an estimate, and keep `\hat` for passages that discuss the notation itself. New math follows this now; existing hats are converted in separate sweeps. ::: {#exm-semantic-decorator} ## Naming a decorator for its meaning > ❌ Source: `The estimate $\hat{\mean}$ is close to $\mean$.` > > ✅ Source: `The estimate $\est{\mean}$ is close to $\mean$.` Both versions print the same hat. If the group later marks estimates some other way, only the definition of `\est` changes. ::: Font commands follow the same rule. `\mathscr`, `\mathcal`, `\mathbb` and `\mathbf` say how a letter is drawn, not what it stands for, so a raw `\mathbb{R}` or `\mathscr{A}` leaves the reader of the source guessing at the concept and leaves the group editing every use to change the symbol. Write the macro that names the concept. Name the macro for the set, such as `\reals` for the real numbers, not for the font, as `\bbR` would be. A document that reaches for a font command directly has found a concept with no macro yet: add the macro to the shared file, then use it. As with Greek letters, a passage that discusses the notation itself may write the font command directly. ::: {#exm-semantic-font} ## Naming a set for its meaning > ❌ Source: `The function maps $\mathbb{R}$ to $\mathbb{R}$.` > > ✅ Source: `The function maps $\reals$ to $\reals$.` Both versions print the same symbol. If the group changes how it writes the real numbers, only the definition of `\reals` changes. ::: Latin letters follow the same rule, with the same single exception for letters of either alphabet. Outside a passage that discusses the notation itself, do not write a literal Latin or Greek letter in a math expression. The exception is a one-off symbol that fits no semantic category. The shared macros already name outcome variables, covariates and generic parameters, so a one-off should almost never be needed. When a symbol has a category but no macro, add the macro to the shared file first. New macros always go in the group's shared macros repository, never in a repository that applies them, unless that repository explicitly overrides the default meaning of one specific macro. Latin letters with a fixed role show the rule. In a regression or prediction model, use these macros: - `\outvar` for the outcome variable, instead of a bare `y`; - `\eoutvar` for a predicted outcome; - `\predvar` for a predictor, instead of a bare `x`; - `\resid` for a residual, the observed minus the predicted outcome; - `\prederr` for a prediction error, the predicted minus the observed outcome. For an observation used to fit the model, the residual is the negative of the prediction error. Write `\resid` for the observed minus the predicted outcome and `\prederr` for the predicted minus the observed outcome, never one for the other. For an estimate of a parameter, `\erf{\eparam}` is the estimation error, the estimate minus the true value; it prints $\varepsilon$, the symbol the shared macros use for an error. These macros need a version of the shared macros that includes them, so update a repository's copy before using them there. The outcome, predictor and residual macros also have random-variable and vector forms, such as `\Outvar`, `\voutvar` and `\vresid`. ::: {#exm-semantic-latin-letter} ## Naming a variable for its role > ❌ Source: `The residual is $e_i = y_i - \hat{y}_i$.` > > ✅ Source: `The residual is $\resid_i = \outvar_i - \eoutvar_i$.` The ✅ version prints the residual as $r$, the symbol the shared macros use for it; the other letters are the same in both. In the ✅ version, a reader of the source can tell which letter is the outcome and which is the residual. ::: Once a quantity has a name and a macro, write the macro instead of the expression that defines it. Each equation then stays short, and a reader sees which quantity it is about. ::: {#exm-named-quantity} ## Writing a named quantity by its name > ❌ Source: `The gradient of the mean squared error is $\frac{2}{n} \tp{\design} \paren{\design\vcoef - \vy}$.` > > ✅ Source: `The gradient of the mean squared error is $\frac{2}{n} \tp{\design} \vprederr$.` The macro `\vprederr` prints the vector of prediction errors. The document defines it once, where the model is introduced, as `\vprederr = \design\vcoef - \vy`. The ✅ version has one fewer level of brackets, and it names the quantity the gradient depends on. ::: Delimiters follow the same rule. Manual sizing commands, such as `\big` and `\left` with `\right`, say how a bracket is drawn, not what it groups. The shared macros `\paren{}`, `\sb{}`, `\cb{}`, `\set{}` and `\abs{}` size themselves to their contents, so write them instead of a hand-sized pair. Arrows such as `\leftarrow` are not delimiters. ::: {#exm-semantic-delimiter} ## Letting the macro size the bracket > ❌ Source: `The mean is $\E{\left( X - \mu \right)^2}$.` > > ✅ Source: `The mean is $\E{\paren{X - \mu}^2}$.` Both versions print the same expression. In the ✅ version, the macro sizes the bracket, and a group that changes how brackets are drawn edits one definition in the shared file. ::: Macros are for the author, not the reader. Reader-facing text, such as a lecture, a handout or a notation section, describes the symbols that a macro prints and what they mean, and never names the macro that produced them. List every symbol that the reader encounters in the document's notation table, with its meaning. ::: {#exm-describe-symbol-not-macro} ## Describing the symbol, not the macro > ❌ Source: `The macro \avgfitf prints the average fit, so write $\avgfitf{x}$ for it.` > > ✅ Source: `The average fit at $x$ is written $\avgfitf{x}$.` The ✅ version tells the reader what the symbol means. The reader never sees the macro name, and the symbol has its own row in the notation table. :::