There are three main classes of objects in Auteur - Generation Criteria, Augmentations, and Drafts. Generation Criteria are templates that can be parameterized based on the data relationships relevant to the usage context. Each generation criterion is mapped to multiple Augmentations. For example, the data relationship x<15 can be expressed using the Threshold generation criterion as Threshold("x", 15, "leq"). This Threshold is mapped to multiple augmentations that can be used to express the specified relationship: a threshold line at x=15, changing the fill, opacity, and stroke encodings of points less than or equal 15, and so on.
To use a generation criterion, it needs to be parameterized. That is to say, we need to specify the details of the relationship. In the above example, we use the parameters "x", 15, and "leq" (less than equals). Once a generation criterion has been parameterized, a .selection(D3Selection) or .select(CSSSelector)needs to be defined. This determines the SVG elements the augmentations will be applied to.
Finally, an array of Augmentations can be generated using the .getAugs() function to convey the details of the data relationship. This list of augmentations and a target D3 visualization can be input to the Draft object, which then renders the augmentations onto the visualization. An overview of this workflow is shown below:
Generation Criteria
Auteur provides six generation criteria that serve as general templates for different types of data relationships. These six generation criteria are: Emphasis, Threshold, Range, Derived Values, Local Data, and Regression. Each generation criterion accepts a set of input parameters that determine the details of that data relationship. For example, the Threshold criterion has three parameters: the variable (data attribute), value (numerical or temporal value of the threshold), and type (less than, equals, greater than etc).
Emphasis
A single or an array of important values for a numerical (N) or categorical (C) variable.
Usage: new Emphasis(variable, value, type)
Parameters:
| variable | str, default=None Name of variable of interest. |
|---|---|
| value | str/num/date or array of str/num/date or stat, default=None Value(s) to be emphasized. |
| type | "any" or "all", default="any" If array provided for value parameter, highlights data item if variable value matches "any" or "all" of the values in the array |
.getAugs() returns: Stroke, Label, Fill, Opacity, Regression
Threshold
A threshold value for a numerical (N) or temporal (T) variable.
Usage: new Threshold(variable, value, type)
Parameters:
| variable | str, default=None Name of variable of interest. |
|---|---|
| value | num/date or stat, default=None Value to be used as threshold. |
| type | "eq" / "le" / "leq" / "ge" / "geq", default="eq" Highlights data item if variable value is "eq" (equal to), "le" (less than), "leq" (less than or equal to), "ge" (greater than) or "geq" (greater than or equal to) value parameter. |
.getAugs() returns: Line, Text, Opacity, Stroke, Fill, Label, Regression
Range
A range of values for a numerical (N) or temporal (T) variable.
Usage: new Range(variable, value, type)
Parameters:
| variable | str, default=None Name of variable of interest. |
|---|---|
| value | list of num/date or stat, default=None [min, max] value to be used as the extents of the range. |
| type | "closed" or "open", default="closed" If "closed" highlights data item if variable value is inclusive of [min, max] value parameter list. If "open" highlights data item if variable value is exclusive of [min, max] value parameter list - i.e. mathematically (min, max). |
.getAugs() returns: Rect, Text, Opacity, Stroke, Fill, Label, Regression
Derived Values
Value(s) calculated from existing numerical (N) variable(s).
Usage:
new DerivedValues(variable, value, calculation) or
new DerivedValues(variable, undefined, undefined, function)
Parameters:
| variable | str, default=None Variable to be used for calculation. If multiple variables are used, any one can be used as the initial "starting" variable. |
|---|---|
| value | num or str, default=None (optional) Adjust the initial "starting" variable by a constant num (numeric) value or another variable name str (another numeric variable) from the dataset. |
| calculation | "add" / "sub" / "mult" / "div", default="add" (optional) Adjust the initial "starting" variable by "add" (adding), "sub" (subtracting), "mult" (multiplying) or "div" (dividing) by the value parameter. |
| function | function, default=None (optional) Adjust the initial "starting" variable by applying a user defined function to the variable, the function takes a single data item (row) as input and should return a num. |
.getAugs() returns: Mark, Line
Local Data
Additional data instances not originally in data set.
Usage: new LocalData(value)
Parameters:
| value | array, default=None Array of new data instances, should resemble original data, i.e. [{variable1:value1, variable2:value2, ...}, ...]. |
|---|
.getAugs() returns: Mark
Regression
Linear least squares regression trend line of items in data set.
Usage: new Regression()
The regression generation criterion uses the standard mathematical linear least squares approach and does not require any additional user input parameters.
.getAugs() returns: Line
Selections
Selections determine the SVG elements that augmentations will be applied to. They should be defined either for each Generation Criterion or for the entire Draft object as a whole. If defined on the Generation Criterion level, multiple Generation Criteria can have different selections even when added to the same visualization. If a single selection is defined for the Draft object, this selection applies to all generation criteria added to that Draft.
.select(selector)
A css selector that defines the svg element(s) that should be considered when applying the augmentations. For example, encoding-type augmentations will only be applied to data items within the selection. Either .select() or.selection() needs to be defined.
Usage: .select("circle").select(".{CLASSNAME}")
Parameters:
| selector | str, default=None A css selector of all svg elements to be included when applying augmentations. |
|---|
.selection(selection)
A d3 selection that defines the svg element(s) that should be considered when applying the augmentations. For example, encoding-type augmentations will only be applied to data items within the selection. Either .select() or.selection() needs to be defined.
Usage: .selection(d3.selectAll("circle")).selection(d3.selectAll(".{CLASSNAME}"))
Parameters:
| selection | array, default=None A d3 selection of all svg elements to be included when applying augmentations. |
|---|
Compound Generation Criteria
To further enhance the variety and expressiveness of the library, developers can apply multiple generation criteria to the same visualization. Since each generation criterion returns multiple augmentations, combining generation criteria requires a way to merge multiple sets of augmentations on the same visualization. Each generation criterion has three methods that can be used to combine its augmentations with another generation criterion using set operations - union, intersect, and symmdiff - to express more complex data relationships.
.union(generationCriteria)
Augmentations from all provided generation criteria are applied.
Usage: .union(generationCriterion) OR.union([generationCriterion, generationCriterion, ...])
Parameters:
| generationCriteria | generationCriterion or list of generationCriteria, default=None A generation criterion or an array of generation criteria. |
|---|
.intersect(generationCriteria)
Only augmentations at the intersection of all provided generation criteria are applied (i.e. satisfies all generation criteria).
Usage: .intersect(generationCriterion) OR.intersect([generationCriterion, generationCriterion, ...])
Parameters:
| generationCriteria | generationCriterion or list of generationCriteria, default=None A generation criterion or an array of generation criteria. |
|---|
.symmdiff(generationCriteria)
The symmetric difference of augmentations for provided generation criteria (i.e. only augmentations that satisfy one of the provided generation criteria are applied).
Usage: .symmdiff(generationCriterion) OR.symmdiff([generationCriterion, generationCriterion, ...])
Parameters:
| generationCriteria | generationCriterion or list of generationCriteria, default=None A generation criterion or an array of generation criteria. |
|---|
Customization
The following functions can be used to select, filter, and customize augmentations.
.updateStyles(styles, override)
For fine-grained customization of augmentations, users can define their own styles for each augmentation returned by the .getAugs() function.
Usage: .updateStyles({augmentationName:{cssStyles}, ...})
Parameters:
| styles | object, default=None An object that contains the name of each augmentation mapped to the css styles to apply. |
|---|---|
| override | boolean, default=False If False, merges new styles with current styles. If True, replaces current styles with new styles. |
.include(inclusions)
Defines the augmentations to apply to the chart. Cannot be used with .exclude().
Usage: .include({"type": ["mark"]}).include({"name": ["line", "opacity", "regression", "label", ...]}).include({"type": ["encoding"], "name": ["line", "opacity", ...]})
Parameters:
| inclusions | object, default=None Can contain an object mapped to an array of the type(s) of augmentations to include and/or an array of the name(s) of the augmentations to include. Augmentation names are exactly identical to the documentation above. |
|---|
.exclude(exclusions)
Defines the augmentations to exclude when applying augmentations to the chart. Cannot be used with .include().
Usage: .exclude({"type": ["mark"]}).exclude({"name": ["line", "opacity", "regression", "label", ...]}).exclude({"type": ["encoding"], "name": ["line", "opacity", ...]})
Parameters:
| exclusions | object, default=None Can contain an object mapped to an array of the type(s) of augmentations to exclude and/or an array of the name(s) of the augmentations to exclude. Augmentation names are exactly identical to the documentation above. |
|---|
Stats
For those generation criteria that express data relationships about a certain value or values (i.e. Threshold, Range, and Emphasis), these values can be custom specified by the user or calculated from statistical summaries. There are a total of eight statistical summary values that are accepted input parameters.
Usage: new Emphasis(variable, "median")new Threshold(variable, "upperbound", "geq")new Range(variable, ["Q1", "Q3"])
| "min" | Minimum value of a variable. |
|---|---|
| "max" | Maximum value of a variable. |
| "mean" | Statistical average of variable. |
| "median" | Middle value of variable. |
| "Q1" | Value of 25th quartile of variable. |
| "Q3" | Value of 75th quartile of variable. |
| "lowerbound" | Q1 − 1.5 IQR, values below this lowerbound are considered outliers |
| "upperbound" | Q3 + 1.5 IQR, values below this upperbound are considered outliers |
Augmentations
Each generation criterion in Auteur is mapped to one or more augmentations that convey the corresponding data relationship. There are a total of nine augmentations provided by Auteur derived from prior works: Opacity, Stroke, Fill, Text, Label, Line, Regression, Rect, Mark. Each augmentation is associated with a type (mark or encoding). Opacity, Stroke, and Fill are encoding type augmentations that change the attributes of existing SVG elements, such as their fill color. In contrast, Text, Label, Line, Regression, Rect, and Mark are mark type augmentations that add new elements to the SVG.
It is unlikely that you will ever have to work with Augmentations directly. However, they are documented below for reference.
Opacity
Changes the opacity of existing svg items. Items relevant to the data relationship will have an opacity of 1, while all other items will have opacity of 0.25.
Type: encoding
Default styling:
{
"opacity": 1
}Stroke
Adds a stroke around all items relevant to the data relationship.
Type: encoding
Default styling:
{
"stroke": "black",
"stroke-opacity": 1,
"stroke-width": "1px"
}Fill
Changes the fill color of existing svg items. Items relevant to the data relationship will have a fill color of "red", while all other items will have unchanged fill.
Type: encoding
Default styling:
{
"fill": "#eb4034"
}Text
Adds <text> element(s) to the chart to describe relevant information about the data relationship. For Threshold generation criterion, describes value of threshold and statistic (if used). For Range generation criterion, describes value of extents of range.
Type: mark
Default styling:
{
"font-family":"sans-serif",
"font-size":11
}Label
Adds <text> element(s) to the chart to label the value of items relevant to the data relationship. Label is positioned above data item by default.
Type: mark
Default styling:
{
"font-family":"sans-serif",
"font-size":11,
"text-anchor": "middle",
}Line
Only applies to the Threshold generation criterion. Adds a <line> element to the chart to indicate the threshold value.
Type: mark
Default styling:
{
"stroke": "black",
"stroke-opacity": 1,
"stroke-width": "1px"
}Regression
Adds a <line> element to indicate the least squares regression of all items relevant to a data relationship.
Type: mark
Default styling:
{
"stroke": "black",
"stroke-opacity": 1,
"stroke-width": "1px"
}Rect
Only applies to the Range generation criterion. Adds a <rect> element to the chart to indicate the range extent.
Type: mark
Default styling:
{
"opacity": 0.1,
"fill": "black"
}Mark
A general mark type augmentation where the new elements added to the SVG are determined either by inferring from existing SVG elements or through user input. Only for the Derived Values and Local Data generation criteria. New values calculated from existing data or input by users are rendered as multiples (duplicates) of existing marks. This augmentation would thus add different SVG elements depending on the input D3 visualization.
Type: mark
Default styling:
{
"stroke-opacity": 0.25,
}Draft
After parameterizing the generation criteria and obtaining the corresponding augmentations, these augmentations can be rendered onto a D3 visualization using the Draft object. The Draft requires details about the D3 visualization, but to reduce the amount of additional effort necessary, these should already be defined during the process of authoring the visualization such as its SVG container, the D3 selection of elements mapped to the underlying data, and the xy-axis scales.
Usage: new Draft()
.layer(selector)
Defines the DOM element to which mark type augmentations will be added. Typically, this is the top-level <svg> element, but it can also be a <g> container.
Usage: .layer("svg")
Parameters:
| el | str, default=None A css selector for an svg or g element. |
|---|
.select(selector)
A css selector that defines the svg element(s) that should be considered when applying the augmentations. For example, encoding-type augmentations will only be applied to data items within the selection. Either .select() or.selection() needs to be defined.
Usage: .select("circle").select(".{CLASSNAME}")
Parameters:
| selector | str, default=None A css selector of all svg elements to be included when applying augmentations. |
|---|
.selection(selection)
A d3 selection that defines the svg element(s) that should be considered when applying the augmentations. For example, encoding-type augmentations will only be applied to data items within the selection. Either .select() or.selection() needs to be defined.
Usage: .selection(d3.selectAll("circle")).selection(d3.selectAll(".{CLASSNAME}"))
Parameters:
| selection | array, default=None A d3 selection of all svg elements to be included when applying augmentations. |
|---|
.x(variable, scaleX) (optional)
Defines the x-axis of the chart. If this is not provided, some mark-type augmentations will not be rendered.
Parameters:
| variable | str, default=None Name of the variable on the x-axis. |
|---|---|
| scaleX | function, default=None d3 scale applied to the variable on the x-axis. |
.y(variable, scaleY) (optional)
Defines the y-axis of the chart. If this is not provided, some mark-type augmentations will not be rendered.
Parameters:
| variable | str, default=None Name of the variable on the y-axis. |
|---|---|
| scaleY | function, default=None d3 scale applied to the variable on the y-axis. |
.include(inclusions) (optional)
Defines the augmentations to apply to the chart. Cannot be used with .exclude().
Usage: .include({"type": ["mark"]}).include({"name": ["line", "opacity", "regression", "label", ...]}).include({"type": ["encoding"], "name": ["line", "opacity", ...]})
Parameters:
| inclusions | object, default=None Can contain an object mapped to an array of the type(s) of augmentations to include and/or an array of the name(s) of the augmentations to include. Augmentation names are exactly identical to the documentation. |
|---|
.exclude(exclusions) (optional)
Defines the augmentations to exclude when applying augmentations to the chart. Cannot be used with .include().
Usage: .exclude({"type": ["mark"]}).exclude({"name": ["line", "opacity", "regression", "label", ...]}).exclude({"type": ["encoding"], "name": ["line", "opacity", ...]})
Parameters:
| exclusions | object, default=None Can contain an object mapped to an array of the type(s) of augmentations to exclude and/or an array of the name(s) of the augmentations to exclude. Augmentation names are exactly identical to the documentation. |
|---|
.augment(augmentations)
Applies array of augmentations to the selected svg and svg elements.
Parameters:
| augmentations | array, default=None Obtained by calling the .getAugs() function after specifying a generation criterion. Can also be obtained by creating a compound generation criterion. |
|---|