@uwdata/mosaic-plot 0.5.0

package/src/interactors/util/brush.js

@@ -0,0 +1,45 @@
+import {
+  brush as d3_brush, brushX as d3_brushX, brushY as d3_brushY
+} from 'd3';
+
+function wrap(brush) {
+  const brushOn = brush.on;
+  let enabled = true;
+
+  function silence(callback) {
+    enabled = false;
+    callback();
+    enabled = true;
+  }
+
+  brush.reset = (...args) => {
+    silence(() => brush.clear(...args));
+  };
+
+  brush.moveSilent = (...args) => {
+    silence(() => brush.move(...args));
+  };
+
+  brush.on = (...args) => {
+    if (args.length > 1 && args[1]) {
+      // wrap callback to respect enabled flag
+      const callback = args[1];
+      args[1] = (...event) => enabled && callback(...event);
+    }
+    return brushOn(...args);
+  };
+
+  return brush;
+}
+
+export function brush() {
+  return wrap(d3_brush());
+}
+
+export function brushX() {
+  return wrap(d3_brushX());
+}
+
+export function brushY() {
+  return wrap(d3_brushY());
+}

package/src/interactors/util/close-to.js

@@ -0,0 +1,9 @@
+const EPS = 1e-12;
+
+export function closeTo(a, b) {
+  return a === b || (
+    a && b &&
+    Math.abs(a[0] - b[0]) < EPS &&
+    Math.abs(a[1] - b[1]) < EPS
+  ) || false;
+}

package/src/interactors/util/get-field.js

@@ -0,0 +1,4 @@
+export function getField(mark, channels) {
+  const field = mark.channelField(channels)?.field;
+  return field?.basis || field;
+}

package/src/interactors/util/invert.js

@@ -0,0 +1,3 @@
+export function invert(value, scale, pixelSize = 1) {
+  return scale.invert(pixelSize * Math.floor(value / pixelSize));
+}

package/src/interactors/util/patchScreenCTM.js

@@ -0,0 +1,13 @@
+/**
+ * Patch the getScreenCTM method to memoize the last non-null
+ * result seen. This will let the method continue to function
+ * even after the node is removed from the DOM.
+ */
+export function patchScreenCTM() {
+  const node = this;
+  const getScreenCTM = node.getScreenCTM;
+  let memo;
+  node.getScreenCTM = () => {
+    return node.isConnected ? (memo = getScreenCTM.call(node)) : memo;
+  };
+}

package/src/interactors/util/sanitize-styles.js

@@ -0,0 +1,9 @@
+import { toKebabCase } from './to-kebab-case.js';
+
+export function sanitizeStyles(styles) {
+  const s = {};
+  for (const name in styles) {
+    s[toKebabCase(name)] = styles[name];
+  }
+  return s;
+}

package/src/interactors/util/to-kebab-case.js

@@ -0,0 +1,9 @@
+export function toKebabCase(cc) {
+  const lc = cc.toLowerCase();
+  const n = cc.length;
+  let kc = '';
+  for (let i = 0; i < n; ++i) {
+    kc += (cc[i] !== lc[i] ? '-' : '') + lc[i];
+  }
+  return kc;
+}

package/src/legend.js

@@ -0,0 +1,64 @@
+import { Toggle } from './interactors/Toggle.js';
+
+export class Legend {
+  constructor(channel, options) {
+    const { as, ...rest } = options;
+    this.channel = channel;
+    this.options = { label: null, ...rest };
+    this.selection = as;
+
+    this.element = document.createElement('div');
+    this.element.setAttribute('class', 'legend');
+    this.element.value = this;
+  }
+
+  setPlot(plot) {
+    const { channel, selection } = this;
+    const mark = findMark(plot, channel);
+    if (this.selection && mark) {
+      this.handler = new Toggle(mark, { selection, channels: [channel] });
+      this.selection.addEventListener('value', () => this.update());
+    }
+  }
+
+  init(svg) {
+    const { channel, options, handler } = this;
+    const scale = svg.scale(channel);
+    const opt = scale.type === 'ordinal'
+      ? options
+      : { marginTop: 1, tickSize: 2, height: 28, ...options };
+    this.legend = svg.legend(channel, opt);
+
+    if (handler) {
+      handler.init(this.legend, ':scope > div', el => [el.__data__]);
+      this.update();
+    }
+
+    this.element.replaceChildren(this.legend);
+    return this.element;
+  }
+
+  update() {
+    if (!this.legend) return;
+    const { value } = this.selection;
+    const curr = value && value.length ? new Set(value.map(v => v[0])) : null;
+    const nodes = this.legend.querySelectorAll(':scope > div');
+    for (const node of nodes) {
+      const selected = curr ? curr.has(node.__data__) : true;
+      node.style.opacity = selected ? 1 : 0.2;
+    }
+  }
+}
+
+function findMark({ marks }, channel) {
+  const channels = channel === 'color' ? ['fill', 'stroke']
+    : channel === 'opacity' ? ['opacity', 'fillOpacity', 'strokeOpacity']
+    : null;
+  if (channels == null) return null;
+  for (let i = marks.length - 1; i > -1; --i) {
+    if (marks[i].channelField(channels)) {
+      return marks[i];
+    }
+  }
+  return null;
+}

package/src/marks/ConnectedMark.js

@@ -0,0 +1,66 @@
+import { Query, argmax, argmin, max, min, sql } from '@uwdata/mosaic-sql';
+import { binField } from './util/bin-field.js';
+import { filteredExtent } from './util/extent.js';
+import { Mark } from './Mark.js';
+
+export class ConnectedMark extends Mark {
+  constructor(type, source, encodings) {
+    const dim = type.endsWith('X') ? 'y' : type.endsWith('Y') ? 'x' : null;
+    const req = { [dim]: ['count', 'min', 'max'] };
+
+    super(type, source, encodings, req);
+    this.dim = dim;
+  }
+
+  query(filter = []) {
+    const { plot, dim, source, stats } = this;
+    const { optimize = true } = source.options || {};
+    const q = super.query(filter);
+
+    if (optimize && dim) {
+      const { field, as } = this.channelField(dim);
+
+      // TODO: handle stacked data
+      const { column } = field;
+      const { count, max, min } = stats[column];
+      const size = dim === 'x' ? plot.innerWidth() : plot.innerHeight();
+
+      const [lo, hi] = filteredExtent(filter, column) || [min, max];
+      const scale = (hi - lo) / (max - min);
+      if (count * scale > size * 4) {
+        const dd = binField(this, dim, as);
+        const val = this.channelField(dim === 'x' ? 'y' : 'x').as;
+        const cols = q.select().map(c => c.as).filter(c => c !== as && c !== val);
+        return m4(q, dd, as, val, lo, hi, size, cols);
+      }
+
+      q.orderby(as);
+    }
+
+    return q;
+  }
+}
+
+/**
+ * M4 is an optimization for value-preserving time-series aggregation
+ * (http://www.vldb.org/pvldb/vol7/p797-jugel.pdf). This implementation uses
+ * an efficient version with a single scan and the aggregate function
+ * argmin and argmax, following https://arxiv.org/pdf/2306.03714.pdf.
+ */
+function m4(input, bx, x, y, lo, hi, width, cols = []) {
+  const bins = sql`FLOOR(${width / (hi - lo)}::DOUBLE * (${bx} - ${+lo}::DOUBLE))::INTEGER`;
+
+  const q = (sel) => Query
+    .from(input)
+    .select(sel)
+    .groupby(bins, cols);
+
+  return Query
+    .union(
+      q([{ [x]: min(x), [y]: argmin(y, x) }, ...cols]),
+      q([{ [x]: max(x), [y]: argmax(y, x) }, ...cols]),
+      q([{ [x]: argmin(x, y), [y]: min(y) }, ...cols]),
+      q([{ [x]: argmax(x, y), [y]: max(y) }, ...cols])
+    )
+    .orderby(cols, x);
+}

package/src/marks/ContourMark.js

@@ -0,0 +1,89 @@
+import { contours, max } from 'd3';
+import { handleParam } from './util/handle-param.js';
+import { Grid2DMark } from './Grid2DMark.js';
+import { channelOption } from './Mark.js';
+
+export class ContourMark extends Grid2DMark {
+  constructor(source, options) {
+    const { thresholds = 10, ...channels } = options;
+    super('geo', source, channels);
+    handleParam(this, 'thresholds', thresholds, () => {
+      return this.grids ? this.contours().update() : null
+    });
+  }
+
+  convolve() {
+    return super.convolve().contours();
+  }
+
+  contours() {
+    const { bins, densityMap, kde, thresholds, groupby, plot } = this;
+
+    let tz = thresholds;
+    if (!Array.isArray(tz)) {
+      const scale = max(kde.map(k => max(k)));
+      tz = Array.from({length: tz - 1}, (_, i) => (scale * (i + 1)) / tz);
+    }
+
+    if (densityMap.fill || densityMap.stroke) {
+      if (this.plot.getAttribute('colorScale') !== 'log') {
+        this.plot.setAttribute('colorZero', true);
+      }
+    }
+
+    // transform contours into data space coordinates
+    // so we play nice with scale domains & axes
+    const [nx, ny] = bins;
+    const [x0, x1] = plot.getAttribute('xDomain');
+    const [y0, y1] = plot.getAttribute('yDomain');
+    const sx = (x1 - x0) / nx;
+    const sy = (y1 - y0) / ny;
+    const xo = +x0;
+    const yo = +y0;
+    const x = v => xo + v * sx;
+    const y = v => yo + v * sy;
+    const contour = contours().size(bins);
+
+    // generate contours
+    this.data = kde.flatMap(k => tz.map(t => {
+      const c = transform(contour.contour(k, t), x, y);
+      groupby.forEach((name, i) => c[name] = k.key[i]);
+      c.density = t;
+      return c;
+    }));
+
+    return this;
+  }
+
+  plotSpecs() {
+    const { type, channels, densityMap, data } = this;
+    const options = {};
+    for (const c of channels) {
+      const { channel } = c;
+      if (channel !== 'x' && channel !== 'y') {
+        options[channel] = channelOption(c);
+      }
+    }
+    if (densityMap.fill) options.fill = 'density';
+    if (densityMap.stroke) options.stroke = 'density';
+    return [{ type, data, options }];
+  }
+}
+
+function transform(geometry, x, y) {
+  function transformPolygon(coordinates) {
+    coordinates.forEach(transformRing);
+  }
+
+  function transformRing(coordinates) {
+    coordinates.forEach(transformPoint);
+  }
+
+  function transformPoint(coordinates) {
+    coordinates[0] = x(coordinates[0]);
+    coordinates[1] = y(coordinates[1]);
+  }
+
+  geometry.coordinates.forEach(transformPolygon);
+  return geometry;
+}

package/src/marks/DenseLineMark.js

@@ -0,0 +1,146 @@
+import { Query, and, count, isNull, isBetween, sql, sum } from '@uwdata/mosaic-sql';
+import { binField, bin1d } from './util/bin-field.js';
+import { extentX, extentY } from './util/extent.js';
+import { handleParam } from './util/handle-param.js';
+import { RasterMark } from './RasterMark.js';
+
+export class DenseLineMark extends RasterMark {
+  constructor(source, options) {
+    const { normalize = true, ...rest } = options;
+    super(source, { bandwidth: 0, ...rest });
+    handleParam(this, 'normalize', normalize);
+  }
+
+  query(filter = []) {
+    const { plot, channels, normalize, source } = this;
+    const [x0, x1] = extentX(this, filter);
+    const [y0, y1] = extentY(this, filter);
+    const [nx, ny] = this.bins = this.binDimensions(this);
+    const bx = binField(this, 'x');
+    const by = binField(this, 'y');
+    const rx = !!plot.getAttribute('xReverse');
+    const ry = !!plot.getAttribute('yReverse');
+    const x = bin1d(bx, x0, x1, nx, rx, this.binPad);
+    const y = bin1d(by, y0, y1, ny, ry, this.binPad);
+
+    const q = Query
+      .from(source.table)
+      .where(stripXY(this, filter));
+
+    const groupby = this.groupby = [];
+    const z = [];
+    for (const c of channels) {
+      if (Object.hasOwn(c, 'field')) {
+        const { channel, field } = c;
+        if (channel === 'z') {
+          q.select({ [channel]: field });
+          z.push('z');
+        } else if (channel !== 'x' && channel !== 'y') {
+          q.select({ [channel]: field });
+          groupby.push(channel);
+        }
+      }
+    }
+
+    return lineDensity(q, x, y, z, nx, ny, groupby, normalize);
+  }
+}
+
+// strip x, y fields from filter predicate
+// to prevent improper clipping of line segments
+// TODO: improve, perhaps with supporting query utilities
+function stripXY(mark, filter) {
+  if (Array.isArray(filter) && !filter.length) return filter;
+
+  const xc = mark.channelField('x').field.column;
+  const yc = mark.channelField('y').field.column;
+  const test = p => p.op !== 'BETWEEN'
+    || p.field.column !== xc && p.field.column !== yc;
+  const filterAnd = p => p.op === 'AND'
+    ? and(p.children.filter(c => test(c)))
+    : p;
+
+  return Array.isArray(filter)
+    ? filter.filter(p => test(p)).map(p => filterAnd(p))
+    : filterAnd(filter);
+}
+
+function lineDensity(
+  q, x, y, z, xn, yn,
+  groupby = [], normalize = true
+) {
+  // select x, y points binned to the grid
+  q.select({
+    x: sql`FLOOR(${x})::INTEGER`,
+    y: sql`FLOOR(${y})::INTEGER`
+  });
+
+  // select line segment end point pairs
+  const groups = groupby.concat(z);
+  const pairPart = groups.length ? `PARTITION BY ${groups.join(', ')} ` : '';
+  const pairs = Query
+    .from(q)
+    .select(groups, {
+      x0: 'x',
+      y0: 'y',
+      dx: sql`(lead(x) OVER sw - x)`,
+      dy: sql`(lead(y) OVER sw - y)`
+    })
+    .window({ sw: sql`${pairPart}ORDER BY x ASC` })
+    .qualify(and(
+      sql`(x0 < ${xn} OR x0 + dx < ${xn})`,
+      sql`(y0 < ${yn} OR y0 + dy < ${yn})`,
+      sql`(x0 > 0 OR x0 + dx > 0)`,
+      sql`(y0 > 0 OR y0 + dy > 0)`
+    ));
+
+  // indices to join against for rasterization
+  // generate the maximum number of indices needed
+  const num = Query
+    .select({ x: sql`GREATEST(MAX(ABS(dx)), MAX(ABS(dy)))` })
+    .from('pairs');
+  const indices = Query.select({ i: sql`UNNEST(range((${num})))::INTEGER` });
+
+  // rasterize line segments
+  const raster = Query.unionAll(
+    Query
+      .select(groups, {
+        x: sql`x0 + i`,
+        y: sql`y0 + ROUND(i * dy / dx::FLOAT)::INTEGER`
+      })
+      .from('pairs', 'indices')
+      .where(sql`ABS(dy) <= ABS(dx) AND i < ABS(dx)`),
+    Query
+      .select(groups, {
+        x: sql`x0 + ROUND(SIGN(dy) * i * dx / dy::FLOAT)::INTEGER`,
+        y: sql`y0 + SIGN(dy) * i`
+      })
+      .from('pairs', 'indices')
+      .where(sql`ABS(dy) > ABS(dx) AND i < ABS(dy)`),
+    Query
+      .select(groups, { x: 'x0', y: 'y0' })
+      .from('pairs')
+      .where(isNull('dx'))
+  );
+
+  // filter raster, normalize columns for each series
+  const pointPart = ['x'].concat(groups).join(', ');
+  const points = Query
+    .from('raster')
+    .select(groups, 'x', 'y',
+      normalize
+        ? { w: sql`1.0 / COUNT(*) OVER (PARTITION BY ${pointPart})` }
+        : null
+    )
+    .where(and(isBetween('x', [0, xn]), isBetween('y', [0, yn])));
+
+  // sum normalized, rasterized series into output grids
+  return Query
+    .with({ pairs, indices, raster, points })
+    .from('points')
+    .select(groupby, {
+      index: sql`x + y * ${xn}::INTEGER`,
+      value: normalize ? sum('w') : count()
+    })
+    .groupby('index', groupby);
+}

package/src/marks/Density1DMark.js

@@ -0,0 +1,104 @@
+import { Query, gt, isBetween, sql, sum } from '@uwdata/mosaic-sql';
+import { Transient } from '../symbols.js';
+import { binField, bin1d } from './util/bin-field.js';
+import { dericheConfig, dericheConv1d } from './util/density.js';
+import { extentX, extentY, xext, yext } from './util/extent.js';
+import { grid1d } from './util/grid.js';
+import { handleParam } from './util/handle-param.js';
+import { Mark, channelOption, markQuery } from './Mark.js';
+
+export class Density1DMark extends Mark {
+  constructor(type, source, options) {
+    const { bins = 1024, bandwidth = 20, ...channels } = options;
+    const dim = type.endsWith('X') ? 'y' : 'x';
+
+    super(type, source, channels, dim === 'x' ? xext : yext);
+    this.dim = dim;
+
+    handleParam(this, 'bins', bins);
+    handleParam(this, 'bandwidth', bandwidth, () => {
+      return this.grid ? this.convolve().update() : null
+    });
+  }
+
+  get filterIndexable() {
+    const name = this.dim === 'x' ? 'xDomain' : 'yDomain';
+    const dom = this.plot.getAttribute(name);
+    return dom && !dom[Transient];
+  }
+
+  query(filter = []) {
+    if (this.hasOwnData()) throw new Error('Density1DMark requires a data source');
+    const { bins, channels, dim, source: { table } } = this;
+    const [lo, hi] = this.extent = (dim === 'x' ? extentX : extentY)(this, filter);
+    const bx = binField(this, dim);
+    return binLinear1d(
+      markQuery(channels, table, [dim])
+        .where(filter.concat(isBetween(bx, [lo, hi]))),
+      bin1d(bx, lo, hi, bins),
+      this.channelField('weight') ? 'weight' : null
+    );
+  }
+
+  queryResult(data) {
+    this.grid = grid1d(this.bins, data);
+    return this.convolve();
+  }
+
+  convolve() {
+    const { bins, bandwidth, dim, grid, plot, extent: [lo, hi] } = this;
+
+    // perform smoothing
+    const neg = grid.some(v => v < 0);
+    const size = dim === 'x' ? plot.innerWidth() : plot.innerHeight();
+    const config = dericheConfig(bandwidth * (bins - 1) / size, neg);
+    const result = dericheConv1d(config, grid, bins);
+
+    // map smoothed grid values to sample data points
+    const points = this.data = [];
+    const v = dim === 'x' ? 'y' : 'x';
+    const b = this.channelField(dim).as;
+    const b0 = +lo;
+    const delta = (hi - b0) / (bins - 1);
+    const scale = 1 / delta;
+    for (let i = 0; i < bins; ++i) {
+      points.push({
+        [b]: b0 + i * delta,
+        [v]: result[i] * scale
+      });
+    }
+
+    return this;
+  }
+
+  plotSpecs() {
+    const { type, data, channels, dim } = this;
+    const options = dim === 'x' ? { y: 'y' } : { x: 'x' };
+    for (const c of channels) {
+      options[c.channel] = channelOption(c);
+    }
+    return [{ type, data, options }];
+  }
+}
+
+function binLinear1d(q, p, value) {
+  const w = value ? `* ${value}` : '';
+
+  const u = q.clone().select({
+    p,
+    i: sql`FLOOR(p)::INTEGER`,
+    w: sql`(FLOOR(p) + 1 - p)${w}`
+  });
+
+  const v = q.clone().select({
+    p,
+    i: sql`FLOOR(p)::INTEGER + 1`,
+    w: sql`(p - FLOOR(p))${w}`
+  });
+
+  return Query
+    .from(Query.unionAll(u, v))
+    .select({ index: 'i', value: sum('w') })
+    .groupby('index')
+    .having(gt('value', 0));
+}

package/src/marks/Density2DMark.js

@@ -0,0 +1,69 @@
+import { handleParam } from './util/handle-param.js';
+import { Grid2DMark } from './Grid2DMark.js';
+import { channelOption } from './Mark.js';
+
+export class Density2DMark extends Grid2DMark {
+  constructor(source, options) {
+    const { type = 'dot', binsX, binsY, ...channels } = options;
+    channels.binPad = channels.binPad ?? 0;
+    super(type, source, channels);
+    handleParam(this, 'binsX', binsX);
+    handleParam(this, 'binsY', binsY);
+  }
+
+  convolve() {
+    super.convolve();
+    const { bins, binPad, extentX, extentY } = this;
+    const [nx, ny] = bins;
+    const [x0, x1] = extentX;
+    const [y0, y1] = extentY;
+    const deltaX = (x1 - x0) / (nx - binPad);
+    const deltaY = (y1 - y0) / (ny - binPad);
+    const offset = binPad ? 0 : 0.5;
+    this.data = points(this.kde, bins, x0, y0, deltaX, deltaY, offset);
+    return this;
+  }
+
+  binDimensions() {
+    const { plot, binWidth, binsX, binsY } = this;
+    return [
+      binsX ?? Math.round(plot.innerWidth() / binWidth),
+      binsY ?? Math.round(plot.innerHeight() / binWidth)
+    ];
+  }
+
+  plotSpecs() {
+    const { type, channels, densityMap, data } = this;
+    const options = {};
+    for (const c of channels) {
+      const { channel } = c;
+      options[channel] = (channel === 'x' || channel === 'y')
+        ? channel // use generated x/y data fields
+        : channelOption(c);
+    }
+    for (const channel in densityMap) {
+      if (densityMap[channel]) {
+        options[channel] = 'density';
+      }
+    }
+    return [{ type, data, options }];
+  }
+}
+
+function points(kde, bins, x0, y0, deltaX, deltaY, offset) {
+  const scale = 1 / (deltaX * deltaY);
+  const [nx, ny] = bins;
+  const data = [];
+  for (const grid of kde) {
+    for (let k = 0, j = 0; j < ny; ++j) {
+      for (let i = 0; i < nx; ++i, ++k) {
+        data.push({
+          x: x0 + (i + offset) * deltaX,
+          y: y0 + (j + offset) * deltaY,
+          density: grid[k] * scale
+        });
+      }
+    }
+  }
+  return data;
+}

package/src/marks/GeoMark.js

@@ -0,0 +1,35 @@
+import { geojson } from '@uwdata/mosaic-sql';
+import { Mark, isDataArray } from './Mark.js';
+
+// default geometry column created by st_read
+// warning: if another "geom" column exists this default
+// will shift, for example to "geom_1" and so on.
+const DEFAULT_GEOMETRY_COLUMN = 'geom';
+
+export class GeoMark extends Mark {
+  constructor(source, encodings = {}, reqs) {
+    if (!isDataArray(source) && !encodings?.geometry) {
+      // if issuing queries and no geometry channel specified
+      // then request default geometry column as GeoJSON
+      encodings.geometry = geojson(DEFAULT_GEOMETRY_COLUMN);
+    }
+
+    super('geo', source, encodings, reqs);
+  }
+
+  queryResult(data) {
+    super.queryResult(data);
+
+    // parse GeoJSON strings to JSON objects
+    const geom = this.channelField('geometry')?.as;
+    if (geom && this.data) {
+      this.data.forEach(data => {
+        if (typeof data[geom] === 'string') {
+          data[geom] = JSON.parse(data[geom]);
+        }
+      });
+    }
+
+    return this;
+  }
+}