@uwdata/mosaic-spec 0.7.0 → 0.8.0

package/src/spec/Spec.ts

@@ -0,0 +1,63 @@
+import { DataDefinition } from './Data.js';
+import { ParamDefinition } from './Param.js';
+import { HConcat } from './HConcat.js';
+import { VConcat } from './VConcat.js';
+import { HSpace } from './HSpace.js';
+import { VSpace } from './VSpace.js';
+import { Menu, Search, Slider, Table } from './Input.js';
+import { Plot } from './Plot.js';
+import { PlotMark } from './PlotMark.js';
+import { Legend } from './PlotLegend.js';
+import { PlotAttributes } from './PlotAttribute.js';
+
+/** Specification metadata. */
+export interface Meta extends Record<string, any> {
+  /** The specification title. */
+  title?: string;
+  /** A description of the specification content.  */
+  description?: string;
+  /** Credits or other acknowledgements. */
+  credit?: string;
+}
+
+/** Configuration options. */
+export interface Config extends Record<string, any> {
+  extensions?: string | string[];
+}
+
+/** Top-level dataset definitions. */
+export type Data = Record<string, DataDefinition>;
+
+/** Top-level Param and Selection definitions. */
+export type Params = Record<string, ParamDefinition>;
+
+/** Top-level specification properties. */
+export interface SpecHead {
+  /** Specification metadata. */
+  meta?: Meta;
+  /** Configuration options. */
+  config?: Config;
+  /** Dataset definitions. */
+  data?: Data;
+  /** Param and Selection definitions. */
+  params?: Params;
+  /** A default set of attributes to apply to all plot components. */
+  plotDefaults?: PlotAttributes;
+}
+
+/** A specifcation component such as a plot, input widget, or layout. */
+export type Component =
+  | HConcat
+  | VConcat
+  | HSpace
+  | VSpace
+  | Menu
+  | Search
+  | Slider
+  | Table
+  | Plot
+  | PlotMark
+  | Legend;
+
+/** A declarative Mosaic specification. */
+export type Spec = SpecHead & Component;

package/src/spec/Transform.ts

@@ -0,0 +1,394 @@
+import { ParamRef } from './Param.js';
+
+/** A field argument to a data transform. */
+export type TransformField = string | ParamRef;
+
+/** Window transform options. */
+export interface WindowOptions {
+  orderby?: TransformField | TransformField[];
+  partitionby?: TransformField | TransformField[];
+  rows?: (number | null)[] | ParamRef;
+  range?: (number | null)[] | ParamRef;
+}
+
+/** Aggregate transform options. */
+export interface AggregateOptions {
+  distinct?: boolean;
+}
+
+/** A transform argument. */
+type Arg = string | number | boolean;
+
+/** A zero argument transform signature. */
+type Arg0 = null | [];
+
+/** A single argument transform signature. */
+type Arg1 = Arg | [Arg];
+
+/**
+ * A two argument transform signature; both arguments are required.
+ */
+type Arg2 = [Arg, Arg];
+
+/**
+ * A two argument transform signature; the second argument is optional.
+ */
+type Arg2Opt = Arg | [Arg, Arg?];
+
+/**
+ * A three argument transform signature; the
+ * second and third arguments are optional.
+ */
+type Arg3Opt = Arg | [Arg, Arg?, Arg?];
+
+/** Bin transform options. */
+export interface BinOptions {
+  /**
+   * 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.
+   */
+  steps?: number;
+  /**
+   * The minimum allowed bin step size (default `0`).
+   * For example, a setting of `1` will prevent step sizes less than 1.
+   */
+  minstep?: number;
+  /**
+   * A flag requesting "nice" human-friendly step sizes (default `true`).
+   */
+  nice?: true;
+  /**
+   * Offset for computed bins (default `0`). For example, a value of `1` will
+   * result in using the next consecutive bin boundary.
+   */
+  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 {
+  /**
+   * Transform a Date value to a month boundary for cyclic comparison.
+   * Year values are collapsed to enable comparison over months only.
+   */
+  dateMonth: Arg1;
+}
+
+/* A dateMonthDay transform. */
+export interface DateMonthDay {
+  /**
+   * Transform a Date value to a month and day boundary for cyclic comparison.
+   * Year values are collapsed to enable comparison over months and days only.
+   */
+  dateMonthDay: Arg1;
+}
+
+/* A dateDay transform. */
+export interface DateDay {
+  /**
+   * Transform a Date value to a day of the month for cyclic comparison.
+   * Year and month values are collapsed to enable comparison over days only.
+   */
+  dateDay: Arg1;
+}
+
+/* A centroid transform. */
+export interface Centroid {
+  /**
+   * Compute the 2D centroid of geometry-typed data.
+   * This transform requires the DuckDB `spatial` extension.
+   */
+  centroid: Arg1;
+}
+
+/* A centroidX transform. */
+export interface CentroidX {
+  /**
+   * Compute the centroid x-coordinate of geometry-typed data.
+   * This transform requires the DuckDB `spatial` extension.
+   */
+  centroidX: Arg1;
+}
+
+/* A centroidY transform. */
+export interface CentroidY {
+  /**
+   * Compute the centroid y-coordinate of geometry-typed data.
+   * This transform requires the DuckDB `spatial` extension.
+   */
+  centroidY: Arg1;
+}
+
+/* A geojson transform. */
+export interface GeoJSON {
+  /**
+   * Compute a GeoJSON-formatted string from geometry-typed data.
+   * This transform requires the DuckDB `spatial` extension.
+   */
+  geojson: Arg1;
+}
+
+/* An argmax aggregate transform. */
+export interface Argmax extends AggregateOptions, WindowOptions {
+  /**
+   * Find a value of the first column that maximizes the second column.
+   */
+  argmax: Arg2;
+}
+
+/* An argmin aggregate transform. */
+export interface Argmin extends AggregateOptions, WindowOptions {
+  /**
+   * Find a value of the first column that minimizes the second column.
+   */
+  argmin: Arg2;
+}
+
+/* An avg (average, or mean) aggregate transform. */
+export interface Avg extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the average (mean) value of the given column.
+   */
+  avg: Arg1;
+}
+
+/* A count aggregate transform. */
+export interface Count extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the count of records in an aggregation group.
+   */
+  count: Arg0 | Arg1;
+}
+
+/* A first aggregate transform. */
+export interface First extends AggregateOptions, WindowOptions {
+  /**
+   * Return the first column value found in an aggregation group.
+   */
+  first: Arg1;
+}
+
+/* A last aggregate transform. */
+export interface Last extends AggregateOptions, WindowOptions {
+  /**
+   * Return the last column value found in an aggregation group.
+   */
+  last: Arg1;
+}
+
+/* A max aggregate transform. */
+export interface Max extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the maximum value of the given column.
+   */
+  max: Arg1;
+}
+
+/* A min aggregate transform. */
+export interface Min extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the minimum value of the given column.
+   */
+  min: Arg1;
+}
+
+/* A median aggregate transform. */
+export interface Median extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the median value of the given column.
+   */
+  median: Arg1;
+}
+
+/* A mode aggregate transform. */
+export interface Mode extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the mode value of the given column.
+   */
+  mode: Arg1;
+}
+
+/* A product aggregate transform. */
+export interface Product extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the product of the given column.
+   */
+  product: Arg1;
+}
+
+/* A quantile aggregate transform. */
+export interface Quantile extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the quantile value of the given column at the provided
+   * probability threshold. For example, 0.5 is the median.
+   */
+  quantile: Arg2;
+}
+
+/* A sum aggregate transform. */
+export interface Sum extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sum of the given column.
+   */
+  sum: Arg1;
+}
+
+/* A row_number window transform. */
+export interface RowNumber extends WindowOptions {
+  /**
+   * Compute the 1-based row number over an ordered window partition.
+   */
+  row_number: Arg0;
+}
+
+/* A rank window transform. */
+export interface Rank extends WindowOptions {
+  /**
+   * Compute the row rank over an ordered window partition.
+   * Sorting ties result in gaps in the rank numbers ([1, 1, 3, ...]).
+   */
+  rank: Arg0;
+}
+
+/* A dense_rank window transform. */
+export interface DenseRank extends WindowOptions {
+  /**
+   * Compute the dense row rank (no gaps) over an ordered window partition.
+   * Sorting ties do not result in gaps in the rank numbers ( [1, 1, 2, ...]).
+   */
+  dense_rank: Arg0;
+}
+
+/* A percent_rank window transform. */
+export interface PercentRank extends WindowOptions {
+  /**
+   * Compute the percetange rank over an ordered window partition.
+   */
+  percent_rank: Arg0;
+}
+
+/* A cume_dist window transform. */
+export interface CumeDist extends WindowOptions {
+  /**
+   * Compute the cumulative distribution value over an ordered window
+   * partition. Equals the number of partition rows preceding or peer with
+   * the current row, divided by the total number of partition rows.
+   */
+  cume_dist: Arg0;
+}
+
+/* An ntile window transform. */
+export interface NTile extends WindowOptions {
+  /**
+   * Compute an n-tile integer ranging from 1 to the provided argument
+   * (num_buckets), dividing the partition as equally as possible.
+   */
+  ntile: Arg1;
+}
+
+/* A lag window transform. */
+export interface Lag extends WindowOptions {
+  /**
+   * Compute lagging values in a column. Returns the value at the row that is
+   * `offset` (second argument, default `1`) rows before the current row within
+   * the window frame. If there is no such row, instead return `default` (third
+   * argument, default `null`). Both offset and default are evaluated with
+   * respect to the current row.
+   */
+  lag: Arg3Opt;
+}
+
+/* A lead window transform. */
+export interface Lead extends WindowOptions {
+  /**
+   * Compute leading values in a column. Returns the value at the row that is
+   * `offset` (second argument, default `1`) rows after the current row within
+   * the window frame. If there is no such row, instead return `default` (third
+   * argument, default `null`). Both offset and default are evaluated with
+   * respect to the current row.
+   */
+  lag: Arg3Opt;
+}
+
+/* A first_value window transform. */
+export interface FirstValue extends WindowOptions {
+  /**
+   * Get the first value of the given column in the current window frame.
+   */
+  first_value: Arg1;
+}
+
+/* A last_value window transform. */
+export interface LastValue extends WindowOptions {
+  /**
+   * Get the last value of the given column in the current window frame.
+   */
+  last_value: Arg1;
+}
+
+/* An nth_value window transform. */
+export interface NthValue extends WindowOptions {
+  /**
+   * Get the nth value of the given column in the current window frame,
+   * counting from one. The second argument is the offset for the nth row.
+   */
+  nth_value: Arg2Opt;
+}
+
+/** A data transform that maps one column value to another. */
+export type ColumnTransform =
+  | Bin
+  | DateMonth
+  | DateMonthDay
+  | DateDay
+  | Centroid
+  | CentroidX
+  | CentroidY
+  | GeoJSON;
+
+/** An aggregate transform that combines multiple values. */
+export type AggregateTransform =
+  | Argmax
+  | Argmin
+  | Avg
+  | Count
+  | Max
+  | Min
+  | First
+  | Last
+  | Max
+  | Min
+  | Median
+  | Mode
+  | Product
+  | Quantile
+  | Sum;
+
+/* A window transform that operates over a sorted domain. */
+export type WindowTransform =
+  | RowNumber
+  | Rank
+  | DenseRank
+  | PercentRank
+  | CumeDist
+  | NTile
+  | Rank
+  | Lag
+  | Lead
+  | FirstValue
+  | LastValue
+  | NthValue;
+
+/** A data transform. */
+export type Transform =
+  | ColumnTransform
+  | AggregateTransform
+  | WindowTransform;

package/src/spec/VConcat.ts

@@ -0,0 +1,9 @@
+import { Component } from './Spec.js';
+
+/** A vconcat component. */
+export interface VConcat {
+  /**
+   * Vertically concatenate components in a column layout.
+   */
+  vconcat: Component[];
+}

package/src/spec/VSpace.ts

@@ -0,0 +1,9 @@
+/** A vspace component. */
+export interface VSpace {
+  /**
+   * Vertical space to place between components.
+   * Number values indicate screen pixels.
+   * String values may use CSS units (em, pt, px, etc).
+   */
+  vspace: number | string;
+}

package/src/spec/interactors/Highlight.ts

@@ -0,0 +1,38 @@
+import { ParamRef } from '../Param.js';
+
+/** A highlight interactor. */
+export interface Highlight {
+  /**
+   * Highlight selected marks by deemphasizing the others.
+   */
+  select: 'highlight';
+  /**
+   * The input selection. Unselected marks are deemphasized.
+   */
+  by: ParamRef;
+  /**
+   * The overall opacity of deemphasized marks.
+   * By default the opacity is set to 0.2.
+   */
+  opacity?: number;
+  /**
+   * The fill opacity of deemphasized marks.
+   * By default the fill opacity is unchanged.
+   */
+  fillOpacity?: number;
+  /**
+   * The stroke opacity of deemphasized marks.
+   * By default the stroke opacity is unchanged.
+   */
+  strokeOpacity?: number;
+  /**
+   * The fill color of deemphasized marks.
+   * By default the fill is unchanged.
+   */
+  fill?: string;
+  /**
+   * The stroke color of deemphasized marks.
+   * By default the stroke is unchanged.
+   */
+  stroke?: string;
+}

package/src/spec/interactors/Interval1D.ts

@@ -0,0 +1,67 @@
+import { ParamRef } from '../Param.js';
+
+/** Styles for rectangular selection brushes. */
+export interface BrushStyles {
+  /**
+   * The overall opacity of the brush rectangle.
+   */
+  opacity?: number;
+  /**
+   * The fill opacity of the brush rectangle.
+   */
+  fillOpacity?: number;
+  /**
+   * The stroke opacity of the brush rectangle.
+   */
+  strokeOpacity?: number;
+  /**
+   * The fill color of the brush rectangle.
+   */
+  fill?: string;
+  /**
+   * The stroke color of the brush rectangle.
+   */
+  stroke?: string;
+}
+
+/** Options for 1D interval interactors. */
+export interface Interval1DOptions {
+  /**
+   * The output selection. A clause of the form `field BETWEEN lo AND hi`
+   * is added for the currently selected interval [lo, hi].
+   */
+  as: ParamRef;
+  /**
+   * The name of the field (database column) over which the interval
+   * selection should be defined. If unspecified, the  channel field of the
+   * first valid prior mark definition is used.
+   */
+  field?: string;
+  /**
+   * The size of an interative pixel (default `1`). Larger pixel sizes reduce
+   * the brush resolution, which can reduce the size of data cube indexes.
+   */
+  pixelSize?: number;
+  /**
+   * A flag indicating if peer (sibling) marks are when cross-filtering
+   * (default `true`). If set, peer marks will not be filtered by this
+   * interactor's selection in cross-filtering setups.
+   */
+  peers?: boolean;
+  /**
+   * CSS styles for the brush (SVG `rect`) element.
+   */
+  brush?: BrushStyles;
+}
+
+/** An intervalX interactor. */
+export interface IntervalX extends Interval1DOptions {
+  /** Select a continuous 1D interval selection over the `x` scale domain. */
+  select: 'intervalX';
+}
+
+/** An intervalY interactor. */
+export interface IntervalY extends Interval1DOptions {
+  /** Select a continuous 1D interval selection over the `y` scale domain. */
+  select: 'intervalY';
+}

package/src/spec/interactors/Interval2D.ts

@@ -0,0 +1,48 @@
+import { ParamRef } from '../Param.js';
+import { BrushStyles } from './Interval1D.js';
+
+/** Options for 2D interval interactors. */
+export interface Interval2DOptions {
+  /**
+   * The output selection. A clause of the form
+   * `(xfield BETWEEN x1 AND x2) AND (yfield BETWEEN y1 AND y2)`
+   * is added for the currently selected intervals.
+   */
+  as: ParamRef;
+  /**
+   * The name of the field (database column) over which the `x`-component
+   * of the interval selection should be defined. If unspecified, the `x`
+   * channel field of the first valid prior mark definition is used.
+   */
+  xfield?: string;
+  /**
+   * The name of the field (database column) over which the `y`-component
+   * of the interval selection should be defined. If unspecified, the `y`
+   * channel field of the first valid prior mark definition is used.
+   */
+  yfield?: string;
+  /**
+   * The size of an interative pixel (default `1`). Larger pixel sizes reduce
+   * the brush resolution, which can reduce the size of data cube indexes.
+   */
+  pixelSize?: number;
+  /**
+   * A flag indicating if peer (sibling) marks are when cross-filtering
+   * (default `true`). If set, peer marks will not be filtered by this
+   * interactor's selection in cross-filtering setups.
+   */
+  peers?: boolean;
+  /**
+   * CSS styles for the brush (SVG `rect`) element.
+   */
+  brush?: BrushStyles;
+}
+
+/** An intervalXY interactor. */
+export interface IntervalXY extends Interval2DOptions {
+  /**
+   * Select a continuous 2D interval selection
+   * over the `x` and `y` scale domains.
+   */
+  select: 'intervalXY';
+}

package/src/spec/interactors/Nearest.ts

@@ -0,0 +1,28 @@
+import { ParamRef } from '../Param.js';
+
+/** Options for nearest interactors. */
+export interface NearestOptions {
+  /**
+   * The output selection. A clause of the form `field = value`
+   * is added for the currently nearest value.
+   */
+  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.
+   */
+  field?: string;
+}
+
+/** A nearestX interactor. */
+export interface NearestX extends NearestOptions {
+  /** Select the **x** domain value of the mark closest to the pointer. */
+  select: 'nearestX';
+}
+
+/** A nearestY interactor. */
+export interface NearestY extends NearestOptions {
+  /** Select the **y** domain value of the mark closest to the pointer. */
+  select: 'nearestY';
+}