Tutorial: Your First Augmentations

FFL is designed to help authors augment formulas with a light-weight syntax and live feedback. With FFL you can add augmentations such as colors and labels to formula by writing a style-sheet-like specification. Here, we showcase some examples of basic features of FFL.

For this tutorial, you will work on the below excerpt from Gamut: A Design Probe to Understand How Data Scientists Understand Machine Learning Models by Hohman et al.

Consider a dataset $D = \{(x_i ,y_i)\}^N$ of $N$ data points, where $x_i = (x_{i1}, x_{i2},\cdots, x_{iM} )$ is a feature vector with $M$ features, and $y_i$ is the target, i.e., the response, variable. Let $x_j$ denote the $j$th variable in feature space. A typical linear regression model can then be expressed mathematically as: $$ y = \beta_0 + \beta_1 x_1 + \beta_2 x_2 + \dots + \beta_M x_M $$ This model assumes that the relationships between the target variable $y_i$ and features $x_j$ are linear and can be captured in slope terms $\beta_1$, $\beta_2$, . . . , $\beta_M$.

Structure of an FFL Specification

An FFL rule is a lot like a CSS rule—it consists of a selector and a style block. The selector "selects" parts of a formula you want to style and the style block contains a semicolon-separated list of properties specifying what augmentations to apply.

For example, $y$ { color: red } means to select all \(y\)'s in formulas and color them red. Here, $y$ is a literal selector, written as literal LaTeX surrounded with a pair of single dollar signs, and { color: red } is the style block consisting of a single property color.

Consider a dataset $D = \{(x_i ,y_i)\}^N$ of $N$ data points, where $x_i = (x_{i1}, x_{i2},\cdots,x_{iM} )$ is a feature vector with $M$ features, and $y_i$ is the target, i.e., the response, variable. Let $x_j$ denote the $j$th variable in feature space. A typical linear regression model can then be expressed mathematically as: $$ y = \beta_0 + \beta_1 x_1 + \beta_2 x_2 + \dots + \beta_M x_M $$ This model assumes that the relationships between the target variable $y_i$ and features $x_j$ are linear and can be captured in slope terms $\beta_1$, $\beta_2$, . . . ,$\beta_M$.

Selectors

So far, we have already seen literal selectors which select parts of formulas directly corresponding to its content. In addition to literal selectors, FFL also supports a few other ways of selecting elements. To see the full list of supported selectors, navigate to Selectors on the side bar.

Wildcards/Globbing

One of the core features of FFL is the ability to make cross-cutting changes. This includes the ability to select related elements with wildcard matching. Literal selectors in FFL support wildcards * and ? analogous to Unix glob patterns. In other words, ? matches a single token and * matches zero or more tokens (bounded by {…} groups).

For instance, you might have noticed that the selector $y$ didn't include subscripts. This might be fine for \(y_i\)'s but it certainly would be cumbersome to select each \(x_i\)'s one by one. Instead, the alternative is to use the wildcards to match all subscripts.

Consider a dataset $D = \{(x_i ,y_i)\}^N$ of $N$ data points, where $x_i = (x_{i1}, x_{i2},\cdots,x_{iM} )$ is a feature vector with $M$ features, and $y_i$ is the target, i.e., the response, variable. Let $x_j$ denote the $j$th variable in feature space. A typical linear regression model can then be expressed mathematically as: $$ y = \beta_0 + \beta_1 x_1 + \beta_2 x_2 + \dots + \beta_M x_M $$ This model assumes that the relationships between the target variable $y_i$ and features $x_j$ are linear and can be captured in slope terms $\beta_1$, $\beta_2$, . . . ,$\beta_M$.

CSS Classes

Oftentimes you might want to make some connections between labels and their textual descriptions. FFL doesn't directly support styling of texts, but you can mix in some simple CSS selectors (currently only class selectors are supported) alongside FFL. By default, the scope of FFL selectors are limited to formulas. To select outside of formulas, you simply prepend an asterisk * in front of a class selector to indicate its application outside of the formulas. For example, <span class="target">target</span> here is selected by the selector *.target.

Consider a dataset $D = \{(x_i ,y_i)\}^N$ of $N$ data points, where $x_i = (x_{i1}, x_{i2},\cdots,x_{iM} )$ is a feature vector with $M$ features, and $y_i$ is the target, i.e., the response, variable. Let $x_j$ denote the $j$th variable in feature space. A typical linear regression model can then be expressed mathematically as: $$ y = \beta_0 + \beta_1 x_1 + \beta_2 x_2 + \dots + \beta_M x_M $$ This model assumes that the relationships between the target variable $y_i$ and features $x_j$ are linear and can be captured in slope terms $\beta_1$, $\beta_2$, . . . ,$\beta_M$.

Style Properties

Many CSS styles work out of the box, among which the most common is color, which we have already seen above. For more on supported properties, navigate to Style Properties on the side bar. FFL also supports a few additional properties that are specific to math formulas, the primary among which is label.

Labels

Of course, colors are not the only way to grab your readers' attention. We find this common enough that adding a label to an element in FFL is as simple as adding a label property. Labels are automatically placed wherever there is room. For options to customize labels, read more at Additional Styles.

y = \beta_0 + \beta_1 x_1 + \beta_2 x_2 + \dots + \beta_M x_M

Summary

To use FFL to style formulas, you can write CSS-like style rules consisting of selectors and declaration blocks. FFL supports a variety of selectors and style properties. For more details, check out more pages on the side bar.