@uwdata/mosaic-plot 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-plot",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "A Mosaic-powered plotting framework based on Observable Plot.",
   "keywords": [
     "data",
@@ -29,10 +29,10 @@
   },
   "dependencies": {
     "@observablehq/plot": "^0.6.13",
-    "@uwdata/mosaic-core": "^0.5.0",
-    "@uwdata/mosaic-sql": "^0.5.0",
+    "@uwdata/mosaic-core": "^0.6.1",
+    "@uwdata/mosaic-sql": "^0.6.0",
     "d3": "^7.8.5",
     "isoformat": "^0.2.1"
   },
-  "gitHead": "92886dddfb126c1439924c5a0189e4639c3519a7"
+  "gitHead": "9e788e6dc5241fa1c54967a25fd9599f97da1a41"
 }

package/src/index.js

@@ -11,7 +11,7 @@ export { Density2DMark } from './marks/Density2DMark.js';
 export { GeoMark } from './marks/GeoMark.js';
 export { Grid2DMark } from './marks/Grid2DMark.js';
 export { HexbinMark } from './marks/HexbinMark.js';
-export { RasterMark } from './marks/RasterMark.js';
+export { RasterMark, HeatmapMark } from './marks/RasterMark.js';
 export { RasterTileMark } from './marks/RasterTileMark.js';
 export { RegressionMark } from './marks/RegressionMark.js';
 

package/src/marks/ConnectedMark.js

@@ -1,13 +1,12 @@
 import { Query, argmax, argmin, max, min, sql } from '@uwdata/mosaic-sql';
-import { binField } from './util/bin-field.js';
+import { binExpr } from './util/bin-expr.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'] };
-
+    const req = { [dim]: ['min', 'max'] };
     super(type, source, encodings, req);
     this.dim = dim;
   }
@@ -16,28 +15,28 @@ export class ConnectedMark extends Mark {
     const { plot, dim, source, stats } = this;
     const { optimize = true } = source.options || {};
     const q = super.query(filter);
+    if (!dim) return q;
 
-    if (optimize && dim) {
-      const { field, as } = this.channelField(dim);
+    const ortho = dim === 'x' ? 'y' : 'x';
+    const value = this.channelField(ortho)?.as;
+    const { field, as } = this.channelField(dim);
+    const { type } = stats[field.column];
+    const isContinuous = type === 'date' || type === 'number';
 
-      // TODO: handle stacked data
+    if (optimize && isContinuous && value) {
+      // TODO: handle stacked data!
       const { column } = field;
-      const { count, max, min } = stats[column];
+      const { 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);
+      const [expr] = binExpr(this, dim, size, [lo, hi], 1, as);
+      const cols = q.select()
+        .map(c => c.as)
+        .filter(c => c !== as && c !== value);
+      return m4(q, expr, as, value, cols);
+    } else {
+      return q.orderby(field);
     }
-
-    return q;
   }
 }
 
@@ -47,13 +46,13 @@ export class ConnectedMark extends Mark {
  * 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`;
+function m4(input, bin, x, y, cols = []) {
+  const pixel = sql`FLOOR(${bin})::INTEGER`;
 
   const q = (sel) => Query
     .from(input)
     .select(sel)
-    .groupby(bins, cols);
+    .groupby(pixel, cols);
 
   return Query
     .union(

package/src/marks/ContourMark.js

@@ -1,4 +1,5 @@
-import { contours, max } from 'd3';
+import { contours } from 'd3';
+import { gridDomainContinuous } from './util/grid.js';
 import { handleParam } from './util/handle-param.js';
 import { Grid2DMark } from './Grid2DMark.js';
 import { channelOption } from './Mark.js';
@@ -6,7 +7,12 @@ import { channelOption } from './Mark.js';
 export class ContourMark extends Grid2DMark {
   constructor(source, options) {
     const { thresholds = 10, ...channels } = options;
-    super('geo', source, channels);
+    super('geo', source, {
+      bandwidth: 20,
+      interpolate: 'linear',
+      pixelSize: 2,
+      ...channels
+    });
     handleParam(this, 'thresholds', thresholds, () => {
       return this.grids ? this.contours().update() : null
     });
@@ -17,12 +23,12 @@ export class ContourMark extends Grid2DMark {
   }
 
   contours() {
-    const { bins, densityMap, kde, thresholds, groupby, plot } = this;
+    const { bins, densityMap, kde, thresholds, 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);
+      const [, hi] = gridDomainContinuous(kde, 'density');
+      tz = Array.from({length: tz - 1}, (_, i) => (hi * (i + 1)) / tz);
     }
 
     if (densityMap.fill || densityMap.stroke) {
@@ -45,11 +51,11 @@ export class ContourMark extends Grid2DMark {
     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;
+    this.data = kde.flatMap(cell => tz.map(t => {
+      return Object.assign(
+        transform(contour.contour(cell.density, t), x, y),
+        { ...cell, density: t }
+      );
     }));
 
     return this;

package/src/marks/DenseLineMark.js

@@ -1,5 +1,5 @@
 import { Query, and, count, isNull, isBetween, sql, sum } from '@uwdata/mosaic-sql';
-import { binField, bin1d } from './util/bin-field.js';
+import { binExpr } from './util/bin-expr.js';
 import { extentX, extentY } from './util/extent.js';
 import { handleParam } from './util/handle-param.js';
 import { RasterMark } from './RasterMark.js';
@@ -7,26 +7,21 @@ import { RasterMark } from './RasterMark.js';
 export class DenseLineMark extends RasterMark {
   constructor(source, options) {
     const { normalize = true, ...rest } = options;
-    super(source, { bandwidth: 0, ...rest });
+    super(source, 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 { channels, normalize, source, binPad } = this;
     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 [x] = binExpr(this, 'x', nx, extentX(this, filter), binPad);
+    const [y] = binExpr(this, 'y', ny, extentY(this, filter), binPad);
 
     const q = Query
       .from(source.table)
       .where(stripXY(this, filter));
 
+    this.aggr = ['density'];
     const groupby = this.groupby = [];
     const z = [];
     for (const c of channels) {
@@ -132,7 +127,7 @@ function lineDensity(
         ? { w: sql`1.0 / COUNT(*) OVER (PARTITION BY ${pointPart})` }
         : null
     )
-    .where(and(isBetween('x', [0, xn]), isBetween('y', [0, yn])));
+    .where(and(isBetween('x', [0, xn], true), isBetween('y', [0, yn], true)));
 
   // sum normalized, rasterized series into output grids
   return Query
@@ -140,7 +135,7 @@ function lineDensity(
     .from('points')
     .select(groupby, {
       index: sql`x + y * ${xn}::INTEGER`,
-      value: normalize ? sum('w') : count()
+      density: normalize ? sum('w') : count()
     })
     .groupby('index', groupby);
 }

package/src/marks/Density1DMark.js

@@ -1,6 +1,6 @@
 import { Query, gt, isBetween, sql, sum } from '@uwdata/mosaic-sql';
 import { Transient } from '../symbols.js';
-import { binField, bin1d } from './util/bin-field.js';
+import { binExpr } from './util/bin-expr.js';
 import { dericheConfig, dericheConv1d } from './util/density.js';
 import { extentX, extentY, xext, yext } from './util/extent.js';
 import { grid1d } from './util/grid.js';
@@ -30,14 +30,12 @@ export class Density1DMark extends Mark {
   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
-    );
+    const extent = this.extent = (dim === 'x' ? extentX : extentY)(this, filter);
+    const [x, bx] = binExpr(this, dim, bins, extent);
+    const q = markQuery(channels, table, [dim])
+      .where(filter.concat(isBetween(bx, extent)));
+    const v = this.channelField('weight') ? 'weight' : null;
+    return binLinear1d(q, x, v);
   }
 
   queryResult(data) {
@@ -81,8 +79,8 @@ export class Density1DMark extends Mark {
   }
 }
 
-function binLinear1d(q, p, value) {
-  const w = value ? `* ${value}` : '';
+function binLinear1d(q, p, density) {
+  const w = density ? `* ${density}` : '';
 
   const u = q.clone().select({
     p,
@@ -98,7 +96,7 @@ function binLinear1d(q, p, value) {
 
   return Query
     .from(Query.unionAll(u, v))
-    .select({ index: 'i', value: sum('w') })
+    .select({ index: 'i', density: sum('w') })
     .groupby('index')
-    .having(gt('value', 0));
+    .having(gt('density', 0));
 }

package/src/marks/Density2DMark.js

@@ -1,37 +1,37 @@
-import { handleParam } from './util/handle-param.js';
+import { channelScale } from './util/channel-scale.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);
+    const { type = 'dot', ...channels } = options;
+    super(type, source, {
+      bandwidth: 20,
+      interpolate: 'linear',
+      pad: 0,
+      pixelSize: 2,
+      ...channels
+    });
   }
 
   convolve() {
     super.convolve();
-    const { bins, binPad, extentX, extentY } = this;
+    const { bins, pad, 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);
+    const scaleX = channelScale(this, 'x');
+    const scaleY = channelScale(this, 'y');
+    const [x0, x1] = extentX.map(v => scaleX.apply(v));
+    const [y0, y1] = extentY.map(v => scaleY.apply(v));
+    const deltaX = (x1 - x0) / (nx - pad);
+    const deltaY = (y1 - y0) / (ny - pad);
+    const offset = pad ? 0 : 0.5;
+    this.data = points(
+      this.kde, bins, x0, y0, deltaX, deltaY,
+      scaleX.invert, scaleY.invert, 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 = {};
@@ -50,16 +50,18 @@ export class Density2DMark extends Grid2DMark {
   }
 }
 
-function points(kde, bins, x0, y0, deltaX, deltaY, offset) {
+function points(kde, bins, x0, y0, deltaX, deltaY, invertX, invertY, offset) {
   const scale = 1 / (deltaX * deltaY);
   const [nx, ny] = bins;
   const data = [];
-  for (const grid of kde) {
+  for (const cell of kde) {
+    const grid = cell.density;
     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,
+          ...cell,
+          x: invertX(x0 + (i + offset) * deltaX),
+          y: invertY(y0 + (j + offset) * deltaY),
           density: grid[k] * scale
         });
       }

package/src/marks/Grid2DMark.js

@@ -1,19 +1,26 @@
-import { Query, count, gt, isBetween, lt, lte, sql, sum } from '@uwdata/mosaic-sql';
+import { Query, count, isBetween, lt, lte, neq, sql, sum } from '@uwdata/mosaic-sql';
 import { Transient } from '../symbols.js';
-import { binField } from './util/bin-field.js';
+import { binExpr } from './util/bin-expr.js';
 import { dericheConfig, dericheConv2d } from './util/density.js';
 import { extentX, extentY, xyext } from './util/extent.js';
 import { grid2d } from './util/grid.js';
 import { handleParam } from './util/handle-param.js';
+import {
+  interpolateNearest, interpolatorBarycentric, interpolatorRandomWalk
+} from './util/interpolate.js';
 import { Mark } from './Mark.js';
 
+export const DENSITY = 'density';
+
 export class Grid2DMark extends Mark {
   constructor(type, source, options) {
     const {
-      bandwidth = 20,
-      binType = 'linear',
-      binWidth = 2,
-      binPad = 1,
+      bandwidth = 0,
+      interpolate = 'none',
+      pixelSize = 1,
+      pad = 1,
+      width,
+      height,
       ...channels
     } = options;
 
@@ -24,9 +31,11 @@ export class Grid2DMark extends Mark {
     handleParam(this, 'bandwidth', bandwidth, () => {
       return this.grids ? this.convolve().update() : null;
     });
-    handleParam(this, 'binWidth', binWidth);
-    handleParam(this, 'binType', binType);
-    handleParam(this, 'binPad', binPad);
+    handleParam(this, 'pixelSize', pixelSize);
+    handleParam(this, 'interpolate', interpolate);
+    handleParam(this, 'pad', pad);
+    handleParam(this, 'width', width);
+    handleParam(this, 'height', height);
   }
 
   setPlot(plot, index) {
@@ -43,82 +52,115 @@ export class Grid2DMark extends Mark {
   }
 
   query(filter = []) {
-    const { plot, binType, binPad, channels, densityMap, source } = this;
+    const { interpolate, pad, channels, densityMap, source } = this;
     const [x0, x1] = this.extentX = extentX(this, filter);
     const [y0, y1] = this.extentY = 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 [x, bx] = binExpr(this, 'x', nx, [x0, x1], pad);
+    const [y, by] = binExpr(this, 'y', ny, [y0, y1], pad);
 
     // with padded bins, include the entire domain extent
     // if the bins are flush, exclude the extent max
-    const bounds = binPad
-      ? [isBetween(bx, [x0, x1]), isBetween(by, [y0, y1])]
-      : [lte(x0, bx), lt(bx, x1), lte(y0, by), lt(by, y1)];
+    const bounds = pad
+      ? [isBetween(bx, [+x0, +x1]), isBetween(by, [+y0, +y1])]
+      : [lte(+x0, bx), lt(bx, +x1), lte(+y0, by), lt(by, +y1)];
 
     const q = Query
       .from(source.table)
       .where(filter.concat(bounds));
 
     const groupby = this.groupby = [];
-    let agg = count();
+    const aggrMap = {};
     for (const c of channels) {
       if (Object.hasOwn(c, 'field')) {
         const { as, channel, field } = c;
         if (field.aggregate) {
-          agg = field;
+          // include custom aggregate
+          aggrMap[channel] = field;
           densityMap[channel] = true;
         } else if (channel === 'weight') {
-          agg = sum(field);
+          // compute weighted density
+          aggrMap[DENSITY] = sum(field);
         } else if (channel !== 'x' && channel !== 'y') {
+          // add groupby field
           q.select({ [as]: field });
           groupby.push(as);
         }
       }
     }
+    const aggr = this.aggr = Object.keys(aggrMap);
+
+    // check for incompatible encodings
+    if (aggrMap.density && aggr.length > 1) {
+      throw new Error('Weight option can not be used with custom aggregates.');
+    }
+
+    // if no aggregates, default to count density
+    if (!aggr.length) {
+      aggr.push(DENSITY);
+      aggrMap.density = count();
+    }
 
-    return binType === 'linear'
-      ? binLinear2d(q, x, y, agg, nx, groupby)
-      : bin2d(q, x, y, agg, nx, groupby);
+    // generate grid binning query
+    if (interpolate === 'linear') {
+      if (aggr.length > 1) {
+        throw new Error('Linear binning not applicable to multiple aggregates.');
+      }
+      if (!aggrMap.density) {
+        throw new Error('Linear binning not applicable to custom aggregates.');
+      }
+      return binLinear2d(q, x, y, aggrMap[DENSITY], nx, groupby);
+    } else {
+      return bin2d(q, x, y, aggrMap, nx, groupby);
+    }
   }
 
   binDimensions() {
-    const { plot, binWidth } = this;
+    const { plot, pixelSize, width, height } = this;
     return [
-      Math.round(plot.innerWidth() / binWidth),
-      Math.round(plot.innerHeight() / binWidth)
+      width ?? Math.round(plot.innerWidth() / pixelSize),
+      height ?? Math.round(plot.innerHeight() / pixelSize)
     ];
   }
 
   queryResult(data) {
-    const [nx, ny] = this.bins;
-    this.grids = grid2d(nx, ny, data, this.groupby);
+    const [w, h] = this.bins;
+    const interp = maybeInterpolate(this.interpolate);
+    this.grids = grid2d(w, h, data, this.aggr, this.groupby, interp);
     return this.convolve();
   }
 
   convolve() {
-    const { bandwidth, bins, grids, plot } = this;
+    const { aggr, bandwidth, bins, grids, plot } = this;
 
-    if (bandwidth <= 0) {
-      this.kde = this.grids.map(({ key, grid }) => {
-        return (grid.key = key, grid);
-      });
-    } else {
+    // no smoothing as default fallback
+    this.kde = this.grids;
+
+    if (bandwidth > 0) {
+      // determine which grid to smooth
+      const gridProp = aggr.length === 1 ? aggr[0]
+        : aggr.includes(DENSITY) ? DENSITY
+        : null;
+
+      // bail if no compatible grid found
+      if (!gridProp) {
+        console.warn('No compatible grid found for smoothing.');
+        return this;
+      }
+
+      // apply smoothing, bandwidth uses units of screen pixels
       const w = plot.innerWidth();
       const h = plot.innerHeight();
       const [nx, ny] = bins;
-      const neg = grids.some(({ grid }) => grid.some(v => v < 0));
+      const neg = grids.some(cell => cell[gridProp].some(v => v < 0));
       const configX = dericheConfig(bandwidth * (nx - 1) / w, neg);
       const configY = dericheConfig(bandwidth * (ny - 1) / h, neg);
-      this.kde = this.grids.map(({ key, grid }) => {
-        const k = dericheConv2d(configX, configY, grid, bins);
-        return (k.key = key, k);
+      this.kde = this.grids.map(grid => {
+        const density = dericheConv2d(configX, configY, grid[gridProp], bins);
+        return { ...grid, [gridProp]: density };
       });
     }
+
     return this;
   }
 
@@ -127,6 +169,9 @@ export class Grid2DMark extends Mark {
   }
 }
 
+/**
+ * Extract channels that explicitly encode computed densities.
+ */
 function createDensityMap(channels) {
   const densityMap = {};
   for (const key in channels) {
@@ -138,25 +183,33 @@ function createDensityMap(channels) {
   return densityMap;
 }
 
-function bin1d(x, x0, x1, n, reverse, pad) {
-  const d = (n - pad) / (x1 - x0);
-  const f = d !== 1 ? ` * ${d}::DOUBLE` : '';
-  return reverse
-    ? sql`(${x1} - ${x}::DOUBLE)${f}`
-    : sql`(${x}::DOUBLE - ${x0})${f}`;
+function maybeInterpolate(interpolate = 'none') {
+  if (typeof interpolate === 'function') return interpolate;
+  switch (`${interpolate}`.toLowerCase()) {
+    case 'none':
+    case 'linear':
+      return undefined; // no special interpolation need
+    case 'nearest':
+      return interpolateNearest;
+    case 'barycentric':
+      return interpolatorBarycentric();
+    case 'random-walk':
+      return interpolatorRandomWalk();
+  }
+  throw new Error(`invalid interpolate: ${interpolate}`);
 }
 
-function bin2d(q, xp, yp, value, xn, groupby) {
+function bin2d(q, xp, yp, aggs, xn, groupby) {
   return q
     .select({
       index: sql`FLOOR(${xp})::INTEGER + FLOOR(${yp})::INTEGER * ${xn}`,
-      value
+      ...aggs
     })
     .groupby('index', groupby);
 }
 
-function binLinear2d(q, xp, yp, value, xn, groupby) {
-  const w = value.column ? `* ${value.column}` : '';
+function binLinear2d(q, xp, yp, density, xn, groupby) {
+  const w = density?.column ? `* ${density.column}` : '';
   const subq = (i, w) => q.clone().select({ xp, yp, i, w });
 
   // grid[xu + yu * xn] += (xv - xp) * (yv - yp) * wi;
@@ -185,7 +238,7 @@ function binLinear2d(q, xp, yp, value, xn, groupby) {
 
   return Query
     .from(Query.unionAll(a, b, c, d))
-    .select({ index: 'i', value: sum('w') }, groupby)
+    .select({ index: 'i', density: sum('w') }, groupby)
     .groupby('index', groupby)
-    .having(gt('value', 0));
+    .having(neq('density', 0));
 }