@uwdata/mosaic-spec 0.8.0 → 0.10.0

package/src/ast/SelectionNode.js

@@ -2,25 +2,29 @@ import { ASTNode } from './ASTNode.js';
 import { INTERSECT, SELECTION } from '../constants.js';
 
 export class SelectionNode extends ASTNode {
-  constructor(select = INTERSECT, cross) {
+  constructor(select = INTERSECT, cross, empty) {
     super(SELECTION);
     this.select = select;
     this.cross = cross;
+    this.empty = empty;
   }
 
   instantiate(ctx) {
-    const { select, cross } = this;
-    return ctx.api.Selection[select]({ cross });
+    const { select, cross, empty } = this;
+    return ctx.api.Selection[select]({ cross, empty });
   }
 
   codegen(ctx) {
-    const { select, cross } = this;
-    const arg = cross != null ? `{ cross: ${cross} }` : '';
+    const { select, cross, empty } = this;
+    const args = [['cross', cross], ['empty', empty]]
+      .filter(a => a[1] != null)
+      .map(a => `${a[0]}: ${a[1]}`);
+    const arg = args.length ? `{ ${args.join(', ')} }` : '';
     return `${ctx.ns()}Selection.${select}(${arg})`;
   }
 
   toJSON() {
-    const { select, cross } = this;
-    return { select, cross };
+    const { select, cross, empty } = this;
+    return { select, cross, empty };
   }
 }

package/src/ast/TransformNode.js

@@ -1,5 +1,6 @@
 import { ASTNode } from './ASTNode.js';
 import { TRANSFORM } from '../constants.js';
+import { parseOptions } from './OptionsNode.js';
 
 function toArray(value) {
   return value == null ? [] : [value].flat();
@@ -17,16 +18,21 @@ export function parseTransform(spec, ctx) {
     return; // return undefined to signal no transform!
   }
 
-  const args = name === 'count' || name == null ? [] : toArray(spec[name]);
-  const options = {
-    distinct: spec.distinct,
-    orderby: toArray(spec.orderby).map(v => ctx.maybeParam(v)),
-    partitionby: toArray(spec.partitionby).map(v => ctx.maybeParam(v)),
-    rows: spec.rows ? ctx.maybeParam(spec.rows) : null,
-    range: spec.range ? ctx.maybeParam(spec.range) : null
-  };
-
-  return new TransformNode(name, args, options);
+  if (name === 'bin') {
+    const { bin, ...options } = spec;
+    const [arg] = toArray(bin);
+    return new BinTransformNode(name, arg, parseOptions(options, ctx));
+  } else {
+    const args = name === 'count' && !spec[name] ? [] : toArray(spec[name]);
+    const options = {
+      distinct: spec.distinct,
+      orderby: toArray(spec.orderby).map(v => ctx.maybeParam(v)),
+      partitionby: toArray(spec.partitionby).map(v => ctx.maybeParam(v)),
+      rows: spec.rows ? ctx.maybeParam(spec.rows) : null,
+      range: spec.range ? ctx.maybeParam(spec.range) : null
+    };
+    return new TransformNode(name, args, options);
+  }
 }
 
 export class TransformNode extends ASTNode {
@@ -112,6 +118,34 @@ export class TransformNode extends ASTNode {
   }
 }
 
+export class BinTransformNode extends ASTNode {
+  constructor(name, arg, options) {
+    super(TRANSFORM);
+    this.name = name;
+    this.arg = arg;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const { name, arg, options } = this;
+    return ctx.api[name](arg, options.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const { name, arg, options } = this;
+    const opt = options.codegen(ctx);
+    return `${ctx.ns()}${name}(`
+        + JSON.stringify(arg)
+        + (opt ? `, ${opt}` : '')
+        + ')';
+  }
+
+  toJSON() {
+    const { name, arg, options } = this;
+    return { [name]: arg, ...options.toJSON() };
+  }
+}
+
 function simplify(array) {
   return array.length === 0 ? '' : array.length === 1 ? array[0] : array;
 }

package/src/config/transforms.js

@@ -11,6 +11,8 @@ export function transformNames(overrides = []) {
     'centroidX',
     'centroidY',
     'count',
+    'covariance',
+    'covarPop',
     'dateMonth',
     'dateMonthDay',
     'dateDay',
@@ -23,7 +25,11 @@ export function transformNames(overrides = []) {
     'mode',
     'product',
     'quantile',
+    'stddev',
+    'stddevPop',
     'sum',
+    'variance',
+    'varPop',
     'row_number',
     'rank',
     'dense_rank',

package/src/spec/Input.ts

@@ -11,6 +11,11 @@ export interface Menu {
    * currently selected menu option.
    */
   as?: ParamRef;
+  /**
+   * The database column name to use within generated selection clause
+   * predicates. Defaults to the `column` property.
+   */
+  field?: string;
   /**
    * The name of a database table to use as a data source for this widget.
    * Used in conjunction with the `column` property.
@@ -33,11 +38,11 @@ export interface Menu {
   /**
    * An array of menu options, as literal values or option objects.
    * Option objects have a `value` property and an optional `label` property.
-   * If no label is provided, the (string-coerced) value is used.
+   * If no label is provided, the string-coerced value is used.
    */
-  options?: Array<any>;
+  options?: Array<any | { value: any, label?: string }>;
   /**
-   * The initial selected menu option.
+   * The initial selected menu value.
    */
   value?: any;
 }
@@ -53,6 +58,11 @@ export interface Search {
    * current text search query.
    */
   as?: ParamRef;
+  /**
+   * The database column name to use within generated selection clause
+   * predicates. Defaults to the `column` property.
+   */
+  field?: string;
   /**
    * The type of text search query to perform. One of:
    * - `"contains"` (default): the query string may appear anywhere in the text
@@ -93,6 +103,18 @@ export interface Slider {
    * currently selected slider option.
    */
   as?: ParamRef;
+  /**
+   * The database column name to use within generated selection clause
+   * predicates. Defaults to the `column` property.
+   */
+  field?: string;
+  /**
+   * The type of selection clause predicate to generate if the **as** option
+   * is a Selection. If `'point'` (the default), the selection predicate is an
+   * equality check for the slider value. If `'interval'`, the predicate checks
+   * an interval from the minimum to the current slider value.
+   */
+  select?: 'point' | 'interval';
   /**
    * The name of a database table to use as a data source for this widget.
    * Used in conjunction with the `column` property.
@@ -141,6 +163,11 @@ export interface Table {
    * A table grid widget.
    */
   input: 'table';
+  /**
+   * The output selection. A selection clause is added for each
+   * currently selected table row.
+   */
+  as?: ParamRef;
   /**
    * The name of a database table to use as a data source for this widget.
    */

package/src/spec/Param.ts

@@ -58,6 +58,13 @@ export interface Selection {
    * but not oneself (default `false`, except for `crossfilter` selections).
    */
   cross?: boolean;
+
+  /**
+   * A flag for setting an initial empty selection state. If true, a selection
+   * with no clauses corresponds to an empty selection with no records. If
+   * false, a selection with no clauses selects all values.
+   */
+  empty?: boolean;
 }
 
 /** A Param or Selection definition. */

package/src/spec/PlotAttribute.ts

@@ -1556,6 +1556,13 @@ export interface PlotAttributes {
    */
   rNice?: boolean | number| Interval | ParamRef;
 
+  /**
+   * A textual label to show on the axis or legend; if null, show no label. By
+   * default the scale label is inferred from channel definitions, possibly with
+   * an arrow (↑, →, ↓, or ←) to indicate the direction of increasing value.
+   */
+  rLabel?: string | null | ParamRef;
+
   /**
    * If true, shorthand for a transform suitable for percentages, mapping
    * proportions in [0, 1] to [0, 100].

package/src/spec/PlotMark.ts

@@ -8,6 +8,7 @@ import { DelaunayLink, DelaunayMesh, Hull, Voronoi, VoronoiMesh } from './marks/
 import { DenseLine } from './marks/DenseLine.js';
 import { Density, DensityX, DensityY } from './marks/Density.js';
 import { Circle, Dot, DotX, DotY, Hexagon } from './marks/Dot.js';
+import { ErrorBarX, ErrorBarY } from './marks/ErrorBar.js';
 import { Frame } from './marks/Frame.js';
 import { Geo, Graticule, Sphere } from './marks/Geo.js';
 import { Hexbin } from './marks/Hexbin.js';
@@ -35,6 +36,7 @@ export type PlotMark =
   | DenseLine
   | Density | DensityX | DensityY
   | Dot | DotX | DotY | Circle | Hexagon
+  | ErrorBarX | ErrorBarY
   | Frame
   | Geo | Graticule | Sphere
   | Hexbin

package/src/spec/Spec.ts

@@ -33,6 +33,13 @@ export type Params = Record<string, ParamDefinition>;
 
 /** Top-level specification properties. */
 export interface SpecHead {
+  /**
+   * A [JSON schema](http://json-schema.org/) URL for this specification,
+   * such as https://uwdata.github.io/mosaic/schema/latest.json. This property
+   * enables validation and autocomplete in editors with JSON schema support.
+   * @format uri
+   */
+  $schema?: string;
   /** Specification metadata. */
   meta?: Meta;
   /** Configuration options. */

package/src/spec/Transform.ts

@@ -41,20 +41,58 @@ type Arg2Opt = Arg | [Arg, Arg?];
  */
 type Arg3Opt = Arg | [Arg, Arg?, Arg?];
 
-/** Bin transform options. */
-export interface BinOptions {
+/** Binning interval names. */
+export type BinInterval =
+  | 'date'
+  | 'number'
+  | 'millisecond'
+  | 'second'
+  | 'minute'
+  | 'hour'
+  | 'day'
+  | 'month'
+  | 'year';
+
+/* A bin transform. */
+export interface Bin {
+  /**
+   * Bin a continuous variable into discrete intervals. The bin argument
+   * specifies a data column or expression to bin. Both numerical and
+   * temporal (date/time) values are supported.
+   */
+  bin: Arg | [Arg];
+  /**
+   * The interval bin unit to use, typically used to indicate a date/time
+   * unit for binning temporal values, such as `hour`, `day`, or `month`.
+   * If `date`, the extent of data values is used to automatically select
+   * an interval for temporal data. The value `number` enforces normal
+   * numerical binning, even over temporal data. If unspecified, defaults
+   * to `number` for numerical data and `date` for temporal data.
+   */
+  interval?: BinInterval;
+  /**
+   * The step size to use between bins. When binning numerical values (or
+   * interval type `number`), this setting specifies the numerical step size.
+   * For data/time intervals, this indicates the number of steps of that unit,
+   * such as hours, days, or years.
+   */
+  step?: number;
   /**
    * The target number of binning steps to use. To accommodate human-friendly
-   * bin boundaries, the actual number of bins may diverge from this exact number.
+   * ("nice") bin boundaries, the actual number of bins may diverge from this
+   * exact value. This option is ignored when **step** is specified.
    */
   steps?: number;
   /**
-   * The minimum allowed bin step size (default `0`).
-   * For example, a setting of `1` will prevent step sizes less than 1.
+   * The minimum allowed bin step size (default `0`) when performing numerical
+   * binning. For example, a setting of `1` prevents step sizes less than 1.
+   * This option is ignored when **step** is specified.
    */
   minstep?: number;
   /**
-   * A flag requesting "nice" human-friendly step sizes (default `true`).
+   * A flag (default `true`) requesting "nice" human-friendly end points and
+   * step sizes when performing numerical binning. When **step** is specified,
+   * this option affects the binning end points (e.g., origin) only.
    */
   nice?: true;
   /**
@@ -64,15 +102,6 @@ export interface BinOptions {
   offset?: number;
 }
 
-/* A bin transform. */
-export interface Bin {
-  /**
-   * Bin a continuous variable into discrete intervals. This transform accepts
-   * a data column to bin over as well as an optional bin options object.
-   */
-  bin: Arg | [Arg] | [Arg, BinOptions];
-}
-
 /* A dateMonth transform. */
 export interface DateMonth {
   /**
@@ -168,6 +197,22 @@ export interface Count extends AggregateOptions, WindowOptions {
   count: Arg0 | Arg1;
 }
 
+/* A sample covariance aggregate transform. */
+export interface Covariance extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sample covariance of between the given columns.
+   */
+  covariance: Arg2;
+}
+
+/* A population covariance aggregate transform. */
+export interface CovarPop extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the population covariance of between the given columns.
+   */
+  covarPop: Arg2;
+}
+
 /* A first aggregate transform. */
 export interface First extends AggregateOptions, WindowOptions {
   /**
@@ -233,6 +278,22 @@ export interface Quantile extends AggregateOptions, WindowOptions {
   quantile: Arg2;
 }
 
+/* A sample standard deviation aggregate transform. */
+export interface Stddev extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sum of the given column.
+   */
+  stddev: Arg1;
+}
+
+/* A population standard deviation aggregate transform. */
+export interface StddevPop extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sum of the given column.
+   */
+  stddevPop: Arg1;
+}
+
 /* A sum aggregate transform. */
 export interface Sum extends AggregateOptions, WindowOptions {
   /**
@@ -241,6 +302,22 @@ export interface Sum extends AggregateOptions, WindowOptions {
   sum: Arg1;
 }
 
+/* A sample variance aggregate transform. */
+export interface Variance extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sample variance of the given column.
+   */
+  variance: Arg1;
+}
+
+/* A population variance aggregate transform. */
+export interface VarPop extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the population variance of the given column.
+   */
+  varPop: Arg1;
+}
+
 /* A row_number window transform. */
 export interface RowNumber extends WindowOptions {
   /**
@@ -370,7 +447,11 @@ export type AggregateTransform =
   | Mode
   | Product
   | Quantile
-  | Sum;
+  | Stddev
+  | StddevPop
+  | Sum
+  | Variance
+  | VarPop;
 
 /* A window transform that operates over a sorted domain. */
 export type WindowTransform =

package/src/spec/interactors/Nearest.ts

@@ -8,21 +8,41 @@ export interface NearestOptions {
    */
   as: ParamRef;
   /**
-   * The name of the field (database column) over which the nearest
-   * selection should be defined. If unspecified, the  channel field of the
-   * first valid prior mark definition is used.
+   * The encoding channels whose domain values should be selected. For example,
+   * a setting of `['color']` selects the data value backing the color channel,
+   * whereas `['x', 'z']` selects both x and z channel domain values. If
+   * unspecified, the selected channels default to match the current pointer
+   * settings: a `nearestX` interactor selects the `['x']` channels, while
+   * a `nearest` interactor selects the `['x', 'y']` channels.
    */
-  field?: string;
+  channels?: string[];
+  /**
+   * The fields (database column names) to use in generated selection clause
+   * predicates. If unspecified, the fields backing the selected *channels*
+   * in the first valid prior mark definition are used by default.
+   */
+  fields?: string[];
+  /**
+   * The maximum radius of a nearest selection (default 40). Marks with (x, y)
+   * coordinates outside this radius will not be selected as nearest points.
+   */
+  maxRadius?: number;
+}
+
+/** A nearest interactor. */
+export interface Nearest extends NearestOptions {
+  /** Select values from the mark closest to the pointer. */
+  select: 'nearest';
 }
 
 /** A nearestX interactor. */
 export interface NearestX extends NearestOptions {
-  /** Select the **x** domain value of the mark closest to the pointer. */
+  /** Select values from the mark closest to the pointer *x* location. */
   select: 'nearestX';
 }
 
 /** A nearestY interactor. */
 export interface NearestY extends NearestOptions {
-  /** Select the **y** domain value of the mark closest to the pointer. */
+  /** Select values from the mark closest to the pointer *y* location. */
   select: 'nearestY';
 }

package/src/spec/interactors/Toggle.ts

@@ -46,6 +46,15 @@ export interface ToggleY extends ToggleOptions {
   select: 'toggleY';
 }
 
+/** A toggleZ interactor. */
+export interface ToggleZ extends ToggleOptions {
+  /**
+   * Select individal values in the `z` scale domain.
+   * Clicking or touching a mark toggles its selection status.
+   */
+  select: 'toggleZ';
+}
+
 /** A toggleColor interactor. */
 export interface ToggleColor extends ToggleOptions {
   /**

package/src/spec/marks/Dot.ts

@@ -19,6 +19,11 @@ export interface DotOptions extends MarkOptions {
    */
   y?: ChannelValueSpec;
 
+  /**
+   * An optional ordinal channel for grouping data into series.
+   */
+  z?: ChannelValue;
+
   /**
    * The radius of dots; either a channel or constant. When a number, it is
    * interpreted as a constant radius in pixels. Otherwise it is interpreted as

package/src/spec/marks/ErrorBar.ts

@@ -0,0 +1,91 @@
+import { ParamRef } from '../Param.js';
+import {
+  ChannelValue, ChannelValueSpec, MarkData, MarkOptions, MarkerOptions
+} from './Marks.js';
+
+/** Options for errorbar marks. */
+interface ErrorBarOptions extends MarkOptions, MarkerOptions {
+  /**
+   * The confidence interval in (0, 1); defaults to 0.95.
+   */
+  ci?: number | ParamRef;
+
+  /**
+   * An optional ordinal channel for grouping data, producing an independent
+   * error bar for each group. If not specified, it defaults to **stroke** if
+   * a channel.
+   */
+  z?: ChannelValue;
+}
+
+/** Options for the errorbarX mark. */
+export interface ErrorBarXOptions extends ErrorBarOptions {
+  /**
+   * The dependent variable horizontal position channel, typically bound to the
+   * *x* scale.
+   */
+  x: ChannelValueSpec;
+
+  /**
+   * The independent variable vertical position channel, typically bound to
+   * the *y* scale; defaults to the zero-based index of the data [0, 1, 2, …].
+   */
+  y?: ChannelValueSpec;
+}
+
+/** The errorbarX mark. */
+export interface ErrorBarX extends MarkData, ErrorBarXOptions {
+  /**
+   * A mark that draws error bars for a calculated parametric confidence
+   * interval for a dependent variable (*x*), potentially grouped by an
+   * independent variable (*y*).
+   *
+   * This mark aggregates raw values to produce a [parametric confidence
+   * interval][1] of the mean, assuming a normal distribution. To instead
+   * visualize pre-computeted interval values or custom aggregations, use
+   * a **ruleY** mark with specified **x1** and **x2** channels.
+   *
+   * Multiple error bars can be produced by specifying a **z** or **stroke**
+   * channel. Set the **marker** option to `'tick'` to add small perpendicular
+   * lines at the start and end of the error interval.
+   *
+   * [1]: https://en.wikipedia.org/wiki/Normal_distribution#Confidence_intervals
+   */
+  mark: 'errorbarX';
+}
+
+/** Options for the errorbarY mark. */
+export interface ErrorBarYOptions extends ErrorBarOptions {
+  /**
+   * The independent variable horizontal position channel, typically bound to
+   * the *x* scale; defaults to the zero-based index of the data [0, 1, 2, …].
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The dependent variable vertical position channel, typically bound to the
+   * *y* scale.
+   */
+  y: ChannelValueSpec;
+}
+
+/** The errorbarY mark. */
+export interface ErrorBarY extends MarkData, ErrorBarYOptions {
+  /**
+   * A mark that draws error bars for a calculated parametric confidence
+   * interval for a dependent variable (*y*), potentially grouped by an
+   * independent variable (*x*).
+   *
+   * This mark aggregates raw values to produce a [parametric confidence
+   * interval][1] of the mean, assuming a normal distribution. To instead
+   * visualize pre-computeted interval values or custom aggregations, use
+   * a **ruleX** mark with specified **y1** and **y2** channels.
+   *
+   * Multiple error bars can be produced by specifying a **z** or **stroke**
+   * channel. Set the **marker** option to `'tick'` to add small perpendicular
+   * lines at the start and end of the error interval.
+   *
+   * [1]: https://en.wikipedia.org/wiki/Normal_distribution#Confidence_intervals
+   */
+  mark: 'errorbarY';
+}

package/src/spec/marks/Marks.ts

@@ -194,6 +194,18 @@ export type SortOrder =
 /** The pointer mode for the tip; corresponds to pointerX, pointerY, and pointer. */
 export type TipPointer = 'x' | 'y' | 'xy';
 
+/** Selection filters to apply internally to mark data. */
+export type SelectFilter =
+  | 'first'
+  | 'last'
+  | 'maxX'
+  | 'maxY'
+  | 'minX'
+  | 'minY'
+  | 'nearest'
+  | 'nearestX'
+  | 'nearestY';
+
 export interface MarkData {
   /**
    * The data source for the mark.
@@ -215,10 +227,24 @@ export interface MarkOptions {
    * channel values; only truthy values are retained.
    *
    * Note that filtering only affects the rendered mark index, not the
-   * associated channel values, and thus has no effect on imputed scale domains.
+   * associated channel values, and has no effect on imputed scale domains.
    */
   filter?: ChannelValue;
 
+  /**
+   * Applies a filter transform after data is loaded to highlight selected
+   * values only. For example, `first` and `last` select the first or last
+   * values of series only (using the *z* channel to separate series).
+   * Meanwhile, `nearestX` and `nearestY` select the point nearest to the
+   * pointer along the *x* or *y* channel dimension. Unlike Mosaic selections,
+   * a mark level *select* is internal to the mark only, and does not populate
+   * a param or selection value to be shared across clients.
+   *
+   * Note that filtering only affects the rendered mark index, not the
+   * associated channel values, and has no effect on imputed scale domains.
+   */
+  select?: SelectFilter;
+
   /**
    * Applies a transform to reverse the order of the mark’s index, say for
    * reverse input order.

package/src/spec/marks/Text.ts

@@ -19,6 +19,11 @@ export interface TextOptions extends MarkOptions, TextStyles {
    */
   y?: ChannelValueSpec;
 
+  /**
+   * An optional ordinal channel for grouping data into series.
+   */
+  z?: ChannelValue;
+
   /**
    * The text contents channel, possibly with line breaks (\n, \r\n, or \r). If
    * not specified, defaults to the zero-based index [0, 1, 2, …].