@uwdata/mosaic-plot 0.7.1 → 0.8.0

package/src/marks/Density2DMark.js

@@ -26,46 +26,61 @@ export class Density2DMark extends Grid2DMark {
     const deltaY = (y1 - y0) / (ny - pad);
     const offset = pad ? 0 : 0.5;
     this.data = points(
-      this.kde, bins, x0, y0, deltaX, deltaY,
+      this.grids, bins, x0, y0, deltaX, deltaY,
       scaleX.invert, scaleY.invert, offset
     );
     return this;
   }
 
   plotSpecs() {
-    const { type, channels, densityMap, data } = this;
+    const { type, channels, densityMap, data: { numRows: length, columns } } = 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);
+        ? columns[channel] // use generated x/y data fields
+        : channelOption(c, columns);
     }
     for (const channel in densityMap) {
       if (densityMap[channel]) {
-        options[channel] = 'density';
+        options[channel] = columns.density;
       }
     }
-    return [{ type, data, options }];
+    return [{ type, data: { length }, options }];
   }
 }
 
-function points(kde, bins, x0, y0, deltaX, deltaY, invertX, invertY, offset) {
+function points(data, bins, x0, y0, deltaX, deltaY, invertX, invertY, offset) {
   const scale = 1 / (deltaX * deltaY);
   const [nx, ny] = bins;
-  const data = [];
-  for (const cell of kde) {
-    const grid = cell.density;
+  const batch = nx * ny;
+  const numRows = batch * data.numRows;
+
+  const x = new Float64Array(numRows);
+  const y = new Float64Array(numRows);
+  const density = new Float64Array(numRows);
+  const columns = { x, y, density };
+  const { density: grids, ...rest } = data.columns;
+  for (const name in rest) {
+    columns[name] = new rest[name].constructor(numRows);
+  }
+
+  let r = 0;
+  for (let row = 0; row < data.numRows; ++row) {
+    // copy repeated values in batch
+    for (const name in rest) {
+      columns[name].fill(rest[name][row], r, r + batch);
+    }
+    // copy individual grid values
+    const grid = grids[row];
     for (let k = 0, j = 0; j < ny; ++j) {
-      for (let i = 0; i < nx; ++i, ++k) {
-        data.push({
-          ...cell,
-          x: invertX(x0 + (i + offset) * deltaX),
-          y: invertY(y0 + (j + offset) * deltaY),
-          density: grid[k] * scale
-        });
+      for (let i = 0; i < nx; ++i, ++r, ++k) {
+        x[r] = invertX(x0 + (i + offset) * deltaX);
+        y[r] = invertY(y0 + (j + offset) * deltaY);
+        density[r] = grid[k] * scale;
       }
     }
   }
-  return data;
+
+  return { numRows, columns };
 }

package/src/marks/GeoMark.js

@@ -18,16 +18,15 @@ export class GeoMark extends Mark {
   }
 
   queryResult(data) {
-    super.queryResult(data);
+    super.queryResult(data); // map to columns, set this.data
 
-    // parse GeoJSON strings to JSON objects
+    // look for an explicit geometry field
     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]);
-        }
-      });
+    if (geom) {
+      const { columns } = this.data;
+      if (typeof columns[geom][0] === 'string') {
+        columns[geom] = columns[geom].map(s => JSON.parse(s));
+      }
     }
 
     return this;

package/src/marks/Grid2DMark.js

@@ -1,3 +1,4 @@
+import { interpolatorBarycentric, interpolateNearest, interpolatorRandomWalk } from '@observablehq/plot';
 import { Query, count, isBetween, lt, lte, neq, sql, sum } from '@uwdata/mosaic-sql';
 import { Transient } from '../symbols.js';
 import { binExpr } from './util/bin-expr.js';
@@ -5,9 +6,7 @@ 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 { toDataColumns } from './util/to-data-columns.js';
 import { Mark } from './Mark.js';
 
 export const DENSITY = 'density';
@@ -28,21 +27,47 @@ export class Grid2DMark extends Mark {
     super(type, source, channels, xyext);
     this.densityMap = densityMap;
 
-    handleParam(this, 'bandwidth', bandwidth, () => {
+    /** @type {number} */
+    this.bandwidth = handleParam(bandwidth, value => {
+      this.bandwidth = value;
       return this.grids ? this.convolve().update() : null;
     });
-    handleParam(this, 'pixelSize', pixelSize);
-    handleParam(this, 'interpolate', interpolate);
-    handleParam(this, 'pad', pad);
-    handleParam(this, 'width', width);
-    handleParam(this, 'height', height);
+
+    /** @type {string} */
+    this.interpolate = handleParam(interpolate, value => {
+      return (this.interpolate = value, this.requestUpdate());
+    });
+
+    /** @type {number} */
+    this.pixelSize = handleParam(pixelSize, value => {
+      return (this.pixelSize = value, this.requestUpdate());
+    });
+
+    /** @type {number} */
+    this.pad = handleParam(pad, value => {
+      return (this.pad = value, this.requestUpdate());
+    });
+
+    /** @type {number|undefined} */
+    this.width = handleParam(width, value => {
+      return (this.width = value, this.requestUpdate());
+    });
+
+    /** @type {number|undefined} */
+    this.height = handleParam(height, value => {
+      return (this.height = value, this.requestUpdate());
+    });
   }
 
+  /**
+   * @param {import('../plot.js').Plot} plot The plot.
+   * @param {number} index 
+   */
   setPlot(plot, index) {
     const update = () => { if (this.hasFieldInfo()) this.requestUpdate(); };
-    plot.addAttributeListener('domainX', update);
-    plot.addAttributeListener('domainY', update);
-    return super.setPlot(plot, index);
+    plot.addAttributeListener('xDomain', update);
+    plot.addAttributeListener('yDomain', update);
+    super.setPlot(plot, index);
   }
 
   get filterIndexable() {
@@ -55,7 +80,7 @@ export class Grid2DMark extends Mark {
     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 [nx, ny] = this.bins = this.binDimensions();
     const [x, bx] = binExpr(this, 'x', nx, [x0, x1], pad);
     const [y, by] = binExpr(this, 'y', ny, [y0, y1], pad);
 
@@ -115,6 +140,9 @@ export class Grid2DMark extends Mark {
     }
   }
 
+  /**
+   * @returns {[number, number]} The bin dimensions.
+   */
   binDimensions() {
     const { plot, pixelSize, width, height } = this;
     return [
@@ -126,47 +154,49 @@ export class Grid2DMark extends Mark {
   queryResult(data) {
     const [w, h] = this.bins;
     const interp = maybeInterpolate(this.interpolate);
-    this.grids = grid2d(w, h, data, this.aggr, this.groupby, interp);
+    const { columns } = toDataColumns(data);
+    this.grids0 = grid2d(w, h, columns.index, columns, this.aggr, this.groupby, interp);
     return this.convolve();
   }
 
   convolve() {
-    const { aggr, bandwidth, bins, grids, plot } = this;
+    const { aggr, bandwidth, bins, grids0, plot } = this;
 
     // no smoothing as default fallback
-    this.kde = this.grids;
+    this.grids = grids0;
 
     if (bandwidth > 0) {
       // determine which grid to smooth
-      const gridProp = aggr.length === 1 ? aggr[0]
+      const prop = aggr.length === 1 ? aggr[0]
         : aggr.includes(DENSITY) ? DENSITY
         : null;
 
       // bail if no compatible grid found
-      if (!gridProp) {
+      if (!prop) {
         console.warn('No compatible grid found for smoothing.');
         return this;
       }
+      const g = grids0.columns[prop];
 
       // apply smoothing, bandwidth uses units of screen pixels
       const w = plot.innerWidth();
       const h = plot.innerHeight();
       const [nx, ny] = bins;
-      const neg = grids.some(cell => cell[gridProp].some(v => v < 0));
+      const neg = g.some(grid => grid.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(grid => {
-        const density = dericheConv2d(configX, configY, grid[gridProp], bins);
-        return { ...grid, [gridProp]: density };
-      });
+      this.grids = {
+        numRows: grids0.numRows,
+        columns: {
+          ...grids0.columns,
+          // @ts-ignore
+          [prop]: g.map(grid => dericheConv2d(configX, configY, grid, bins))
+        }
+      };
     }
 
     return this;
   }
-
-  plotSpecs() {
-    throw new Error('Unimplemented. Use a Grid2D mark subclass.');
-  }
 }
 
 /**
@@ -185,7 +215,7 @@ function createDensityMap(channels) {
 
 function maybeInterpolate(interpolate = 'none') {
   if (typeof interpolate === 'function') return interpolate;
-  switch (`${interpolate}`.toLowerCase()) {
+  switch (interpolate.toLowerCase()) {
     case 'none':
     case 'linear':
       return undefined; // no special interpolation need

package/src/marks/HexbinMark.js

@@ -2,12 +2,17 @@ import { Query, isNotNull, sql } from '@uwdata/mosaic-sql';
 import { Transient } from '../symbols.js';
 import { extentX, extentY, xyext } from './util/extent.js';
 import { Mark } from './Mark.js';
+import { handleParam } from './util/handle-param.js';
 
 export class HexbinMark extends Mark {
   constructor(source, options) {
     const { type = 'hexagon', binWidth = 20, ...channels } = options;
     super(type, source, { r: binWidth / 2, clip: true, ...channels }, xyext);
-    this.binWidth = binWidth;
+
+    /** @type {number} */
+    this.binWidth = handleParam(binWidth, value => {
+      return (this.binWidth = value, this.requestUpdate());
+    });
   }
 
   get filterIndexable() {
@@ -39,9 +44,10 @@ export class HexbinMark extends Mark {
     let x, y;
     const aggr = new Set;
     const cols = {};
+    let orderby;
     for (const c of channels) {
       if (c.channel === 'orderby') {
-        q.orderby(c.value); // TODO revisit once groupby is added
+        orderby = c.value; // TODO revisit once groupby is added
       } else if (c.channel === 'x') {
         x = c;
       } else if (c.channel === 'y') {
@@ -63,6 +69,8 @@ export class HexbinMark extends Mark {
       ...cols
     }).groupby('x', 'y');
 
+    if (orderby) q.orderby(orderby);
+
     // Map x/y channels to screen space
     const xx = `${xr} * (${x.field} - ${x1}::DOUBLE)`;
     const yy = `${yr} * (${y2}::DOUBLE - ${y.field})`;

package/src/marks/Mark.js

@@ -3,10 +3,11 @@ import { Query, Ref, column, isParamLike } from '@uwdata/mosaic-sql';
 import { isColor } from './util/is-color.js';
 import { isConstantOption } from './util/is-constant-option.js';
 import { isSymbol } from './util/is-symbol.js';
-import { toDataArray } from './util/to-data-array.js';
+import { toDataColumns } from './util/to-data-columns.js';
 import { Transform } from '../symbols.js';
 
 const isColorChannel = channel => channel === 'stroke' || channel === 'fill';
+const isOpacityChannel = channel => /opacity$/i.test(channel);
 const isSymbolChannel = channel => channel === 'symbol';
 const isFieldObject = (channel, field) => {
   return channel !== 'sort' && channel !== 'tip'
@@ -31,7 +32,7 @@ export class Mark extends MosaicClient {
 
     this.source = source;
     if (isDataArray(this.source)) {
-      this.data = this.source;
+      this.data = toDataColumns(this.source);
     }
 
     const channels = this.channels = [];
@@ -63,12 +64,15 @@ export class Mark extends MosaicClient {
         }
       } else if (isParamLike(entry)) {
         if (Array.isArray(entry.columns)) {
+          // we currently duck-type to having a columns array
+          // as a check that this is SQLExpression-compatible
           channels.push(fieldEntry(channel, entry));
           params.add(entry);
         } else {
           const c = valueEntry(channel, entry.value);
           channels.push(c);
           entry.addEventListener('value', value => {
+            // update immediately, the value is simply passed to Plot
             c.value = value;
             return this.update();
           });
@@ -85,6 +89,10 @@ export class Mark extends MosaicClient {
     }
   }
 
+  /**
+   * @param {import('../plot.js').Plot} plot The plot.
+   * @param {number} index 
+   */
   setPlot(plot, index) {
     this.plot = plot;
     this.index = index;
@@ -104,7 +112,7 @@ export class Mark extends MosaicClient {
     return this.channels.find(c => c.channel === channel);
   }
 
-  channelField(channel, { exact } = {}) {
+  channelField(channel, { exact = false } = {}) {
     const c = exact
       ? this.channel(channel)
       : this.channels.find(c => c.channel.startsWith(channel));
@@ -140,6 +148,11 @@ export class Mark extends MosaicClient {
     return this;
   }
 
+  /**
+   * Return a query specifying the data needed by this Mark client.
+   * @param {*} [filter] The filtering criteria to apply in the query.
+   * @returns {*} The client query
+   */
   query(filter = []) {
     if (this.hasOwnData()) return null;
     const { channels, source: { table } } = this;
@@ -151,8 +164,11 @@ export class Mark extends MosaicClient {
     return this;
   }
 
+  /**
+   * Provide query result data to the mark.
+   */
   queryResult(data) {
-    this.data = toDataArray(data);
+    this.data = toDataColumns(data);
     return this;
   }
 
@@ -160,16 +176,29 @@ export class Mark extends MosaicClient {
     return this.plot.update(this);
   }
 
+  /**
+   * Generate an array of Plot mark specifications.
+   * @returns {object[]}
+   */
   plotSpecs() {
-    const { type, data, detail, channels } = this;
+    const { type, detail, channels } = this;
+    // @ts-ignore
+    const { numRows: length, values, columns } = this.data || {};
+
+    // populate plot specification options
     const options = {};
     const side = {};
     for (const c of channels) {
       const obj = detail.has(c.channel) ? side : options;
-      obj[c.channel] = channelOption(c)
+      obj[c.channel] = channelOption(c, columns);
     }
     if (detail.size) options.channels = side;
-    return [{ type, data, options }];
+
+    // if provided raw source values (not objects) pass as-is
+    // otherwise we pass columnar data directy in the options
+    const data = values ?? (this.data ? { length } : null);
+    const spec = [{ type, data, options }];
+    return spec;
   }
 }
 
@@ -178,14 +207,17 @@ export class Mark extends MosaicClient {
  * Checks if a constant value or a data field is needed.
  * Also avoids misinterpretation of data values as color names.
  * @param {*} c a visual encoding channel spec
+ * @param {object} columns named data column arrays
  * @returns the Plot channel option
  */
-export function channelOption(c) {
+export function channelOption(c, columns) {
   // use a scale override for color channels to sidestep
   // https://github.com/observablehq/plot/issues/1593
+  const value = columns?.[c.as] ?? c.as;
   return Object.hasOwn(c, 'value') ? c.value
-    : isColorChannel(c.channel) ? { value: c.as, scale: 'color' }
-    : c.as;
+    : isColorChannel(c.channel) ? { value, scale: 'color' }
+    : isOpacityChannel(c.channel) ? { value, scale: 'opacity' }
+    : value;
 }
 
 /**
@@ -196,7 +228,7 @@ export function channelOption(c) {
  * @param {*} table the table to query.
  * @param {*} skip an optional array of channels to skip.
  *  Mark subclasses can skip channels that require special handling.
- * @returns a Query instance
+ * @returns {Query} a Query instance
  */
 export function markQuery(channels, table, skip = []) {
   const q = Query.from({ source: table });

package/src/marks/RasterMark.js

@@ -20,6 +20,7 @@ import { Fixed, Transient } from '../symbols.js';
 export class RasterMark extends Grid2DMark {
   constructor(source, options) {
     super('image', source, options);
+    this.image = null;
   }
 
   setPlot(plot, index) {
@@ -33,37 +34,45 @@ export class RasterMark extends Grid2DMark {
   }
 
   rasterize() {
-    const { bins, kde } = this;
+    const { bins, grids } = this;
     const [ w, h ] = bins;
+    const { numRows, columns } = grids;
 
     // raster data
     const { canvas, ctx, img } = imageData(this, w, h);
 
     // color + opacity encodings
     const { alpha, alphaProp, color, colorProp } = rasterEncoding(this);
+    const alphaData = columns[alphaProp] ?? [];
+    const colorData = columns[colorProp] ?? [];
 
     // generate rasters
-    this.data = kde.map(cell => {
-      color?.(img.data, w, h, cell[colorProp]);
-      alpha?.(img.data, w, h, cell[alphaProp]);
-      ctx.putImageData(img, 0, 0);
-      return { src: canvas.toDataURL() };
-    });
+    this.data = {
+      numRows,
+      columns: {
+        src: Array.from({ length: numRows }, (_, i) => {
+          color?.(img.data, w, h, colorData[i]);
+          alpha?.(img.data, w, h, alphaData[i]);
+          ctx.putImageData(img, 0, 0);
+          return canvas.toDataURL();
+        })
+      }
+    };
 
     return this;
   }
 
   plotSpecs() {
-    const { type, plot, data } = this;
+    const { type, plot, data: { numRows: length, columns } } = this;
     const options = {
-      src: 'src',
+      src: columns.src,
       width: plot.innerWidth(),
       height: plot.innerHeight(),
       preserveAspectRatio: 'none',
       imageRendering: this.channel('imageRendering')?.value,
       frameAnchor: 'middle'
     };
-    return [{ type, data, options }];
+    return [{ type, data: { length }, options }];
   }
 }
 
@@ -86,6 +95,7 @@ export class HeatmapMark extends RasterMark {
 /**
  * Utility method to generate color and alpha encoding helpers.
  * The returned methods can write directly to a pixel raster.
+ * @param {RasterMark} mark
  */
 export function rasterEncoding(mark) {
   const { aggr, densityMap, groupby, plot } = mark;
@@ -132,18 +142,24 @@ export function rasterEncoding(mark) {
   return { alphaProp, colorProp, alpha, color };
 }
 
+/**
+ * Generate an opacity rasterizer for a bitmap alpha channel.
+ * @param {RasterMark} mark The mark instance
+ * @param {string} prop The data property name
+ * @returns A bitmap rasterizer function.
+ */
 function alphaScale(mark, prop) {
-  const { plot, kde: grids } = mark;
+  const { plot, grids } = mark;
 
   // determine scale domain
   const domainAttr = plot.getAttribute('opacityDomain');
   const domainFixed = domainAttr === Fixed;
   const domainTransient = domainAttr?.[Transient];
   const domain = (!domainFixed && !domainTransient && domainAttr)
-    || gridDomainContinuous(grids, prop);
-  if (domainFixed || domainTransient) {
-    if (domainTransient) domain[Transient] = true;
-    plot.setAttribute('colorDomain', domain);
+    || gridDomainContinuous(grids.columns[prop]);
+  if (domainFixed || domainTransient || !domainAttr) {
+    if (!domainFixed) domain[Transient] = true;
+    plot.setAttribute('opacityDomain', domain);
   }
 
   // generate opacity scale
@@ -163,22 +179,29 @@ function alphaScale(mark, prop) {
   return alphaScheme(s);
 }
 
+/**
+ * Generate an color rasterizer for bitmap r, g, b channels.
+ * @param {RasterMark} mark The mark instance
+ * @param {string} prop
+ * @returns A bitmap rasterizer function.
+ */
 function colorScale(mark, prop) {
-  const { plot, kde: grids } = mark;
-  const flat = !grids[0][prop]?.map; // not array-like
-  const discrete = flat || Array.isArray(grids[0][prop]);
+  const { plot, grids } = mark;
+  const data = grids.columns[prop];
+  const flat = !data[0]?.map; // not array-like
+  const discrete = flat || Array.isArray(data[0]);
 
   // determine scale domain
   const domainAttr = plot.getAttribute('colorDomain');
   const domainFixed = domainAttr === Fixed;
   const domainTransient = domainAttr?.[Transient];
   const domain = (!domainFixed && !domainTransient && domainAttr) || (
-    flat ? grids.map(cell => cell[prop]).sort(ascending)
-      : discrete ? gridDomainDiscrete(grids, prop)
-      : gridDomainContinuous(grids, prop)
+    flat ? data.sort(ascending)
+      : discrete ? gridDomainDiscrete(data)
+      : gridDomainContinuous(data)
   );
-  if (domainFixed || domainTransient) {
-    if (domainTransient) domain[Transient] = true;
+  if (domainFixed || domainTransient || !domainAttr) {
+    if (!domainFixed) domain[Transient] = true;
     plot.setAttribute('colorDomain', domain);
   }
 
@@ -234,6 +257,15 @@ function inferScaleType(type) {
   return type;
 }
 
+/**
+ * Retrieve canvas image data for a 2D raster bitmap.
+ * The resulting data is cached in the mark.image property.
+ * If the canvas dimensions change, a new canvas is created.
+ * @param {RasterMark} mark The mark instance
+ * @param {number} w The canvas width.
+ * @param {number} h The canvas height.
+ * @returns An object with a canvas, context, image data, and dimensions.
+ */
 export function imageData(mark, w, h) {
   if (!mark.image || mark.image.w !== w || mark.image.h !== h) {
     const canvas = createCanvas(w, h);