@uwdata/mosaic-plot 0.5.0

package/src/marks/Grid2DMark.js

@@ -0,0 +1,191 @@
+import { Query, count, gt, isBetween, lt, lte, sql, sum } from '@uwdata/mosaic-sql';
+import { Transient } from '../symbols.js';
+import { binField } from './util/bin-field.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 { Mark } from './Mark.js';
+
+export class Grid2DMark extends Mark {
+  constructor(type, source, options) {
+    const {
+      bandwidth = 20,
+      binType = 'linear',
+      binWidth = 2,
+      binPad = 1,
+      ...channels
+    } = options;
+
+    const densityMap = createDensityMap(channels);
+    super(type, source, channels, xyext);
+    this.densityMap = densityMap;
+
+    handleParam(this, 'bandwidth', bandwidth, () => {
+      return this.grids ? this.convolve().update() : null;
+    });
+    handleParam(this, 'binWidth', binWidth);
+    handleParam(this, 'binType', binType);
+    handleParam(this, 'binPad', binPad);
+  }
+
+  setPlot(plot, index) {
+    const update = () => { if (this.stats) this.requestUpdate(); };
+    plot.addAttributeListener('domainX', update);
+    plot.addAttributeListener('domainY', update);
+    return super.setPlot(plot, index);
+  }
+
+  get filterIndexable() {
+    const xdom = this.plot.getAttribute('xDomain');
+    const ydom = this.plot.getAttribute('yDomain');
+    return xdom && ydom && !xdom[Transient] && !ydom[Transient];
+  }
+
+  query(filter = []) {
+    const { plot, binType, binPad, 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);
+
+    // 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 q = Query
+      .from(source.table)
+      .where(filter.concat(bounds));
+
+    const groupby = this.groupby = [];
+    let agg = count();
+    for (const c of channels) {
+      if (Object.hasOwn(c, 'field')) {
+        const { as, channel, field } = c;
+        if (field.aggregate) {
+          agg = field;
+          densityMap[channel] = true;
+        } else if (channel === 'weight') {
+          agg = sum(field);
+        } else if (channel !== 'x' && channel !== 'y') {
+          q.select({ [as]: field });
+          groupby.push(as);
+        }
+      }
+    }
+
+    return binType === 'linear'
+      ? binLinear2d(q, x, y, agg, nx, groupby)
+      : bin2d(q, x, y, agg, nx, groupby);
+  }
+
+  binDimensions() {
+    const { plot, binWidth } = this;
+    return [
+      Math.round(plot.innerWidth() / binWidth),
+      Math.round(plot.innerHeight() / binWidth)
+    ];
+  }
+
+  queryResult(data) {
+    const [nx, ny] = this.bins;
+    this.grids = grid2d(nx, ny, data, this.groupby);
+    return this.convolve();
+  }
+
+  convolve() {
+    const { bandwidth, bins, grids, plot } = this;
+
+    if (bandwidth <= 0) {
+      this.kde = this.grids.map(({ key, grid }) => {
+        return (grid.key = key, grid);
+      });
+    } else {
+      const w = plot.innerWidth();
+      const h = plot.innerHeight();
+      const [nx, ny] = bins;
+      const neg = grids.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(({ key, grid }) => {
+        const k = dericheConv2d(configX, configY, grid, bins);
+        return (k.key = key, k);
+      });
+    }
+    return this;
+  }
+
+  plotSpecs() {
+    throw new Error('Unimplemented. Use a Grid2D mark subclass.');
+  }
+}
+
+function createDensityMap(channels) {
+  const densityMap = {};
+  for (const key in channels) {
+    if (channels[key] === 'density') {
+      delete channels[key];
+      densityMap[key] = true;
+    }
+  }
+  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 bin2d(q, xp, yp, value, xn, groupby) {
+  return q
+    .select({
+      index: sql`FLOOR(${xp})::INTEGER + FLOOR(${yp})::INTEGER * ${xn}`,
+      value
+    })
+    .groupby('index', groupby);
+}
+
+function binLinear2d(q, xp, yp, value, xn, groupby) {
+  const w = value.column ? `* ${value.column}` : '';
+  const subq = (i, w) => q.clone().select({ xp, yp, i, w });
+
+  // grid[xu + yu * xn] += (xv - xp) * (yv - yp) * wi;
+  const a = subq(
+    sql`FLOOR(xp)::INTEGER + FLOOR(yp)::INTEGER * ${xn}`,
+    sql`(FLOOR(xp)::INTEGER + 1 - xp) * (FLOOR(yp)::INTEGER + 1 - yp)${w}`
+  );
+
+  // grid[xu + yv * xn] += (xv - xp) * (yp - yu) * wi;
+  const b = subq(
+    sql`FLOOR(xp)::INTEGER + (FLOOR(yp)::INTEGER + 1) * ${xn}`,
+    sql`(FLOOR(xp)::INTEGER + 1 - xp) * (yp - FLOOR(yp)::INTEGER)${w}`
+  );
+
+  // grid[xv + yu * xn] += (xp - xu) * (yv - yp) * wi;
+  const c = subq(
+    sql`FLOOR(xp)::INTEGER + 1 + FLOOR(yp)::INTEGER * ${xn}`,
+    sql`(xp - FLOOR(xp)::INTEGER) * (FLOOR(yp)::INTEGER + 1 - yp)${w}`
+  );
+
+  // grid[xv + yv * xn] += (xp - xu) * (yp - yu) * wi;
+  const d = subq(
+    sql`FLOOR(xp)::INTEGER + 1 + (FLOOR(yp)::INTEGER + 1) * ${xn}`,
+    sql`(xp - FLOOR(xp)::INTEGER) * (yp - FLOOR(yp)::INTEGER)${w}`
+  );
+
+  return Query
+    .from(Query.unionAll(a, b, c, d))
+    .select({ index: 'i', value: sum('w') }, groupby)
+    .groupby('index', groupby)
+    .having(gt('value', 0));
+}

package/src/marks/HexbinMark.js

@@ -0,0 +1,88 @@
+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';
+
+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;
+  }
+
+  get filterIndexable() {
+    const xdom = this.plot.getAttribute('xDomain');
+    const ydom = this.plot.getAttribute('yDomain');
+    return xdom && ydom && !xdom[Transient] && !ydom[Transient];
+  }
+
+  query(filter = []) {
+    if (this.hasOwnData()) return null;
+    const { plot, binWidth, channels, source } = this;
+
+    // get x / y extents, may update plot domainX / domainY
+    const [x1, x2] = extentX(this, filter);
+    const [y1, y2] = extentY(this, filter);
+
+    // Adjust screen-space coordinates by top/left
+    // margins as this is what Observable Plot does.
+    // TODO use zero margins when faceted?
+    const ox = 0.5 - plot.getAttribute('marginLeft');
+    const oy = 0 - plot.getAttribute('marginTop');
+    const dx = `${binWidth}::DOUBLE`;
+    const dy = `${binWidth * (1.5 / Math.sqrt(3))}::DOUBLE`;
+    const xr = `${plot.innerWidth() / (x2 - x1)}::DOUBLE`;
+    const yr = `${plot.innerHeight() / (y2 - y1)}::DOUBLE`;
+
+    // Extract channel information, update top-level query
+    // and extract dependent columns for aggregates
+    let x, y;
+    const aggr = new Set;
+    const cols = {};
+    for (const c of channels) {
+      if (c.channel === 'orderby') {
+        q.orderby(c.value); // TODO revisit once groupby is added
+      } else if (c.channel === 'x') {
+        x = c;
+      } else if (c.channel === 'y') {
+        y = c;
+      } else if (Object.hasOwn(c, 'field')) {
+        cols[c.as] = c.field;
+        if (c.field.aggregate) {
+          c.field.columns.forEach(col => aggr.add(col));
+        }
+      }
+    }
+
+    // Top-level query; we add a hex binning subquery below
+    // Maps binned screen space coordinates back to data
+    // values to ensure we get correct data-driven scales
+    const q = Query.select({
+      [x.as]: sql`${x1}::DOUBLE + ((x + 0.5 * (y & 1)) * ${dx} + ${ox})::DOUBLE / ${xr}`,
+      [y.as]: sql`${y2}::DOUBLE - (y * ${dy} + ${oy})::DOUBLE / ${yr}`,
+      ...cols
+    }).groupby('x', 'y');
+
+    // Map x/y channels to screen space
+    const xx = `${xr} * (${x.field} - ${x1}::DOUBLE)`;
+    const yy = `${yr} * (${y2}::DOUBLE - ${y.field})`;
+
+    // Perform hex binning of x/y coordinates
+    // TODO add groupby dims
+    const hex = Query
+      .select({
+        py: sql`(${yy} - ${oy}) / ${dy}`,
+        pj: sql`ROUND(py)::INTEGER`,
+        px: sql`(${xx} - ${ox}) / ${dx} - 0.5 * (pj & 1)`,
+        pi: sql`ROUND(px)::INTEGER`,
+        tt: sql`ABS(py-pj) * 3 > 1 AND (px-pi)**2 + (py-pj)**2 > (px - pi - 0.5 * CASE WHEN px < pi THEN -1 ELSE 1 END)**2 + (py - pj - CASE WHEN py < pj THEN -1 ELSE 1 END)**2`,
+        x: sql`CASE WHEN tt THEN (pi + (CASE WHEN px < pi THEN -0.5 ELSE 0.5 END) + (CASE WHEN pj & 1 <> 0 THEN 0.5 ELSE -0.5 END))::INTEGER ELSE pi END`,
+        y: sql`CASE WHEN tt THEN (pj + CASE WHEN py < pj THEN -1 ELSE 1 END)::INTEGER ELSE pj END`
+      })
+      .select(Array.from(aggr))
+      .from(source.table)
+      .where(isNotNull(x.field), isNotNull(y.field), filter)
+
+    return q.from(hex);
+  }
+}

package/src/marks/Mark.js

@@ -0,0 +1,207 @@
+import { MosaicClient } from '@uwdata/mosaic-core';
+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 { Transform } from '../symbols.js';
+
+const isColorChannel = channel => channel === 'stroke' || channel === 'fill';
+const isSymbolChannel = channel => channel === 'symbol';
+const isFieldObject = (channel, field) => {
+  return channel !== 'sort' && channel !== 'tip'
+    && field != null && !Array.isArray(field);
+};
+const fieldEntry = (channel, field) => ({
+  channel,
+  field,
+  as: field instanceof Ref ? field.column : channel
+});
+const valueEntry = (channel, value) => ({ channel, value });
+
+export const isDataArray = source => Array.isArray(source);
+
+export class Mark extends MosaicClient {
+  constructor(type, source, encodings, reqs = {}) {
+    super(source?.options?.filterBy);
+    this.type = type;
+    this.reqs = reqs;
+
+    this.source = source;
+    if (isDataArray(this.source)) {
+      this.data = this.source;
+    }
+
+    const channels = this.channels = [];
+    const detail = this.detail = new Set;
+    const params = this.params = new Set;
+
+    const process = (channel, entry) => {
+      const type = typeof entry;
+      if (channel === 'channels') {
+        for (const name in entry) {
+          detail.add(name);
+          process(name, entry[name]);
+        }
+      } else if (type === 'function' && entry[Transform]) {
+        const enc = entry(this, channel);
+        for (const key in enc) {
+          process(key, enc[key]);
+        }
+      } else if (type === 'string') {
+        if (
+          isConstantOption(channel) ||
+          isColorChannel(channel) && isColor(entry) ||
+          isSymbolChannel(channel) && isSymbol(entry)
+        ) {
+          // interpret constants and color/symbol names as values, not fields
+          channels.push(valueEntry(channel, entry));
+        } else {
+          channels.push(fieldEntry(channel, column(entry)));
+        }
+      } else if (isParamLike(entry)) {
+        if (Array.isArray(entry.columns)) {
+          channels.push(fieldEntry(channel, entry));
+          params.add(entry);
+        } else {
+          const c = valueEntry(channel, entry.value);
+          channels.push(c);
+          entry.addEventListener('value', value => {
+            c.value = value;
+            return this.update();
+          });
+        }
+      } else if (type === 'object' && isFieldObject(channel, entry)) {
+        channels.push(fieldEntry(channel, entry));
+      } else if (entry !== undefined) {
+        channels.push(valueEntry(channel, entry));
+      }
+    };
+
+    for (const channel in encodings) {
+      process(channel, encodings[channel]);
+    }
+  }
+
+  setPlot(plot, index) {
+    this.plot = plot;
+    this.index = index;
+    plot.addParams(this, this.params);
+    if (this.source?.table) this.queryPending();
+  }
+
+  hasOwnData() {
+    return this.source == null || isDataArray(this.source);
+  }
+
+  channel(channel) {
+    return this.channels.find(c => c.channel === channel);
+  }
+
+  channelField(...channels) {
+    const list = channels.flat();
+    for (const channel of list) {
+      const c = this.channel(channel);
+      if (c?.field) return c;
+    }
+    return null;
+  }
+
+  fields() {
+    if (this.hasOwnData()) return null;
+    const { source: { table }, channels, reqs } = this;
+
+    const fields = new Map;
+    for (const { channel, field } of channels) {
+      const column = field?.column;
+      if (!column) {
+        continue; // no column to lookup
+      } else if (field.stats?.length || reqs[channel]) {
+        if (!fields.has(column)) fields.set(column, new Set);
+        const entry = fields.get(column);
+        reqs[channel]?.forEach(s => entry.add(s));
+        field.stats?.forEach(s => entry.add(s));
+      }
+    }
+    return Array.from(fields, ([column, stats]) => {
+      return { table, column, stats: Array.from(stats) };
+    });
+  }
+
+  fieldInfo(info) {
+    this.stats = info.reduce(
+      (o, d) => (o[d.column] = d, o),
+      Object.create(null)
+    );
+    return this;
+  }
+
+  query(filter = []) {
+    if (this.hasOwnData()) return null;
+    const { channels, source: { table } } = this;
+    return markQuery(channels, table).where(filter);
+  }
+
+  queryPending() {
+    this.plot.pending(this);
+    return this;
+  }
+
+  queryResult(data) {
+    this.data = toDataArray(data);
+    return this;
+  }
+
+  update() {
+    return this.plot.update(this);
+  }
+
+  plotSpecs() {
+    const { type, data, detail, channels } = this;
+    const options = {};
+    const side = {};
+    for (const c of channels) {
+      const obj = detail.has(c.channel) ? side : options;
+      obj[c.channel] = channelOption(c)
+    }
+    if (detail.size) options.channels = side;
+    return [{ type, data, options }];
+  }
+}
+
+export function channelOption(c) {
+  // use a scale override for color channels to sidestep
+  // https://github.com/observablehq/plot/issues/1593
+  return Object.hasOwn(c, 'value') ? c.value
+    : isColorChannel(c.channel) ? { value: c.as, scale: 'color' }
+    : c.as;
+}
+
+export function markQuery(channels, table, skip = []) {
+  const q = Query.from({ source: table });
+  const dims = new Set;
+  let aggr = false;
+
+  for (const c of channels) {
+    const { channel, field, as } = c;
+    if (skip.includes(channel)) continue;
+
+    if (channel === 'orderby') {
+      q.orderby(c.value);
+    } else if (field) {
+      if (field.aggregate) {
+        aggr = true;
+      } else {
+        if (dims.has(as)) continue;
+        dims.add(as);
+      }
+      q.select({ [as]: field });
+    }
+  }
+
+  if (aggr) {
+    q.groupby(Array.from(dims));
+  }
+
+  return q;
+}

package/src/marks/RasterMark.js

@@ -0,0 +1,121 @@
+import { scale } from '@observablehq/plot';
+import { isColor } from './util/is-color.js';
+import { createCanvas, raster, opacityMap, palette } from './util/raster.js';
+import { Grid2DMark } from './Grid2DMark.js';
+
+export class RasterMark extends Grid2DMark {
+  constructor(source, options) {
+    super('image', source, options);
+  }
+
+  setPlot(plot, index) {
+    const update = () => { if (this.stats) this.rasterize(); };
+    plot.addAttributeListener('schemeColor', update);
+    super.setPlot(plot, index);
+  }
+
+  convolve() {
+    return super.convolve().rasterize();
+  }
+
+  rasterize() {
+    const { bins, kde, groupby } = this;
+    const [ w, h ] = bins;
+
+    // raster data
+    const { canvas, ctx, img } = imageData(this, w, h);
+
+    // scale function to map densities to [0, 1]
+    const s = imageScale(this);
+
+    // gather color domain as needed
+    const idx = groupby.indexOf(this.channelField('fill')?.as);
+    const domain = idx < 0 ? [] : kde.map(({ key }) => key[idx]);
+
+    // generate raster images
+    this.data = kde.map(grid => {
+      const palette = imagePalette(this, domain, grid.key?.[idx]);
+      raster(grid, img.data, w, h, s, palette);
+      ctx.putImageData(img, 0, 0);
+      return { src: canvas.toDataURL() };
+    });
+
+    return this;
+  }
+
+  plotSpecs() {
+    const { type, plot, data } = this;
+    const options = {
+      src: 'src',
+      width: plot.innerWidth(),
+      height: plot.innerHeight(),
+      preserveAspectRatio: 'none',
+      imageRendering: this.channel('imageRendering')?.value,
+      frameAnchor: 'middle'
+    };
+    return [{ type, data, options }];
+  }
+}
+
+function imageData(mark, w, h) {
+  if (!mark.image || mark.image.w !== w || mark.image.h !== h) {
+    const canvas = createCanvas(w, h);
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    const img = ctx.getImageData(0, 0, w, h);
+    mark.image = { canvas, ctx, img, w, h };
+  }
+  return mark.image;
+}
+
+function imageScale(mark) {
+  const { densityMap, kde, plot } = mark;
+  let domain = densityMap.fill && plot.getAttribute('colorDomain');
+
+  // compute kde grid extents if no explicit domain
+  if (!domain) {
+    let lo = 0, hi = 0;
+    kde.forEach(grid => {
+      for (const v of grid) {
+        if (v < lo) lo = v;
+        if (v > hi) hi = v;
+      }
+    });
+    domain = (lo === 0 && hi === 0) ? [0, 1] : [lo, hi];
+  }
+
+  const type = plot.getAttribute('colorScale');
+  return scale({ x: { type, domain, range: [0, 1] } }).apply;
+}
+
+function imagePalette(mark, domain, value, steps = 1024) {
+  const { densityMap, plot } = mark;
+  const scheme = plot.getAttribute('colorScheme');
+
+  // initialize color to constant fill, if specified
+  const fill = mark.channel('fill');
+  let color = isColor(fill?.value) ? fill.value : undefined;
+
+  if (densityMap.fill || (scheme && !color)) {
+    if (scheme) {
+      try {
+        return palette(
+          steps,
+          scale({color: { scheme, domain: [0, 1] }}).interpolate
+        );
+      } catch (err) {
+        console.warn(err);
+      }
+    }
+  } else if (domain.length) {
+    // fill is based on data values
+    const range = plot.getAttribute('colorRange');
+    const spec = {
+      domain,
+      range,
+      scheme: scheme || (range ? undefined : 'tableau10')
+    };
+    color = scale({ color: spec }).apply(value);
+  }
+
+  return palette(steps, opacityMap(color));
+}