@uwdata/mosaic-sql 0.17.0 → 0.19.0

package/src/transforms/bin-date.ts

@@ -0,0 +1,48 @@
+import type { ExprNode } from '../ast/node.js';
+import type { ExprValue } from '../types.js';
+import { dateBin } from '../functions/datetime.js';
+import { interval } from '../functions/interval.js';
+import { add } from '../functions/operators.js';
+import { timeInterval, type DateTimeValue, type TimeUnit } from './util/time-interval.js';
+
+export interface BinDateOptions {
+  /**
+   * A string indicating a time interval unit,
+   * such as 'year', 'day', or 'hour'.
+   */
+  interval?: TimeUnit;
+  /**
+   * The number of time interval steps to take, such as 2 years or 3 months.
+   */
+  step?: number;
+  /**
+   * The number of bin steps (default 0) by which to offset the result.
+   */
+  offset?: number;
+  /**
+   * The desired number of binning steps. This value is a hint,
+   * it does not guarantee an exact number of steps.
+   */
+  steps?: number;
+}
+
+/**
+ * Return a SQL expression for date/time bins.
+ * @param field The column or expression to bin.
+ * @param extent The min/max extent over which to bin.
+ * @param options Datetime binning options.
+ */
+export function binDate(
+  field: ExprValue,
+  extent: [DateTimeValue, DateTimeValue],
+  options: BinDateOptions = {}
+): ExprNode {
+  const { offset = 0 } = options;
+
+  // use interval if provided, otherwise determine from extent
+  const { unit, step = 1 } = options.interval
+    ? { unit: options.interval, step: options.step }
+    : timeInterval(extent[0], extent[1], options.steps || 40);
+  const bin = dateBin(field, unit, step);
+  return offset ? add(bin, interval(unit, offset * step)) : bin;
+}

package/src/transforms/bin-histogram.ts

@@ -0,0 +1,61 @@
+import type { ExprNode } from '../ast/node.js';
+import type { ExprValue } from '../types.js';
+import { float64 } from '../functions/cast.js';
+import { floor } from '../functions/numeric.js';
+import { add, div, mul, sub } from '../functions/operators.js';
+import { binSpec } from './util/bin-step.js';
+import { Scale, scaleTransform } from './scales.js';
+
+export interface BinHistogramOptions {
+  /** An exact binning step to use. */
+  step?: number;
+  /**
+   * The desired number of binning steps. This value is a hint,
+   * it does not guarantee an exact number of steps.
+   */
+  steps?: number;
+  /**
+   * A minimum binning step value. No generated
+   * step can be less than this value.
+   */
+  minstep?: number;
+  /**
+   * A boolean flag (default true) indicating if bin extents should be
+   * snapped to "nice" numbers such as multiples of 5 or 10.
+   */
+  nice?: boolean;
+  /**
+   * The number of bin steps (default 0) by which to offset the result.
+   */
+  offset?: number;
+}
+
+/**
+ * Return a SQL expression for histogram bins.
+ * @param field The column or expression to bin.
+ * @param extent The min/max extent over which to bin.
+ * @param options Binning options.
+ * @param transform Scale transforms to apply to create
+ *  (potentially non-linear) binning intervals.
+ * @returns The resulting SQL expression
+ */
+export function binHistogram(
+  field: ExprValue,
+  extent: [number, number],
+  options: BinHistogramOptions = {},
+  transform: Scale<number> = scaleTransform({ type: 'linear' })!
+): ExprNode {
+  const [min, max] = extent;
+  const { offset = 0 } = options;
+  const { apply, sqlApply, sqlInvert } = transform;
+  const b = binSpec(apply(min), apply(max), options);
+  const col = sqlApply(field);
+  const alpha = (b.max - b.min) / b.steps;
+
+  let expr = b.min === 0 ? col : sub(col, b.min);
+  if (alpha !== 1) expr = div(expr, float64(alpha));
+  expr = floor(offset ? add(offset, expr) : expr);
+  if (alpha !== 1) expr = mul(alpha, expr);
+  if (b.min !== 0) expr = add(b.min, expr);
+  return sqlInvert(expr);
+}

package/src/transforms/{bin-linear-1d.js → bin-linear-1d.ts}

@@ -1,7 +1,6 @@
-/**
- * @import { SelectQuery } from '../ast/query.js'
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprNode } from '../ast/node.js';
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
 import { Query } from '../ast/query.js';
 import { sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
@@ -10,14 +9,20 @@ import { add, mul, neq, sub } from '../functions/operators.js';
 
 /**
  * Perform linear binning in one dimension.
- * @param {SelectQuery} query The base query to bin.
- * @param {ExprValue} x The expression to bin.
- * @param {ExprValue} [weight] The expression to weight by.
- * @param {string[]} [groupby] Group by expressions.
- * @returns {Query}
+ * @param  query The base query to bin.
+ * @param x The expression to bin.
+ * @param weight The expression to weight by.
+ * @param groupby Group by expressions.
  */
-export function binLinear1d(query, x, weight = undefined, groupby = []) {
-  const w = weight ? (x => mul(x, weight)) : (x => x);
+export function binLinear1d(
+  query: SelectQuery,
+  x: ExprValue,
+  weight: ExprValue | undefined = undefined,
+  groupby: string[] = []
+) {
+  const w = weight
+    ? ((x: ExprNode) => mul(x, weight))
+    : ((x: ExprNode) => x);
   const p0 = floor(x);
   const p1 = add(p0, 1);
   return Query

package/src/transforms/{bin-linear-2d.js → bin-linear-2d.ts}

@@ -1,22 +1,12 @@
-/**
- * @import { SelectQuery } from '../ast/query.js'
- * @import { ExprValue } from '../types.js'
- */
+import type { ExprNode } from '../ast/node.js';
+import type { SelectQuery } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
 import { Query } from '../ast/query.js';
 import { sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
 import { floor } from '../functions/numeric.js';
 import { add, mul, neq, sub } from '../functions/operators.js';
-
-/**
- * Identity function.
- * @template T
- * @param {T} x
- * @returns {T}
- */
-function identity(x) {
-  return x;
-}
+import { identity } from '../util/identity.js';
 
 /**
  * Compute densities over a 2D domain using linear binning. The weight of
@@ -24,30 +14,28 @@ function identity(x) {
  * a better base for subsequent kernel density estimation. This method takes
  * expressions for the (non-truncated) x and y bin values; these expressions
  * should be in units of grid indices, but can contain fractional components.
- * @param {SelectQuery} q The input query. The FROM and WHERE clauses should
+ * @param q The input query. The FROM and WHERE clauses should
  *  be added to the query separately, before this method is invoked.
- * @param {ExprValue} xp The x grid bin expression
- * @param {ExprValue} yp The y grid bin expression
- * @param {ExprValue | undefined} weight Point weights.
- * @param {number} xn The number of x grid bins.
- * @param {string[]} [groupby] Group by expressions.
- * @returns {SelectQuery} A linear binning query for bin `index` and
- *  aggregate `density` columns, in addition to any group by expressions.
+ * @param xp The x grid bin expression
+ * @param yp The y grid bin expression
+ * @param weight Point weights.
+ * @param xn The number of x grid bins.
+ * @param groupby Group by expressions.
+ * @returns A linear binning query for bin `index` and aggregate `density`
+ *  columns, in addition to any group by expressions.
  */
-export function binLinear2d(q, xp, yp, weight, xn, groupby = []) {
-
-  const w = weight ? x => mul(x, weight) : identity;
+export function binLinear2d(
+  q: SelectQuery,
+  xp: ExprValue,
+  yp: ExprValue,
+  weight: ExprValue | undefined,
+  xn: number,
+  groupby: string[] = []
+) {
+  const w = weight ? (x: ExprNode) => mul(x, weight) : identity;
 
-  /**
-   * @param {ExprValue} i
-   * @param {ExprValue} w
-   */
-  const subq = (i, w) => q.clone().select({ xp, yp, i, w });
-  /**
-   * @param {ExprValue} x
-   * @param {ExprValue} y
-   */
-  const index = (x, y) => add(x, mul(y, xn));
+  const subq = (i: ExprValue, w: ExprValue) => q.clone().select({ xp, yp, i, w });
+  const index = (x: ExprValue, y: ExprValue) => add(x, mul(y, xn));
 
   const xu = int32(floor(xp));
   const yu = int32(floor(yp));

package/src/transforms/{filter-query.js → filter-query.ts}

@@ -1,22 +1,18 @@
-/**
- * @import { Query } from '../ast/query.js'
- * @import { TableRefNode } from '../ast/table-ref.js'
- * @import { FilterExpr } from '../types.js'
- */
-import { isSelectQuery } from '../ast/query.js';
-import { isTableRef } from '../ast/table-ref.js';
+import type { FilterExpr } from '../types.js';
+import { isSelectQuery, type Query } from '../ast/query.js';
+import { isTableRef, type TableRefNode } from '../ast/table-ref.js';
 import { deepClone } from '../visit/clone.js';
 import { walk } from '../visit/walk.js';
 
 /**
  * Returns a generator function that clones the given query and adds
  * a WHERE clause for the specified table reference.
- * @param {Query} query The query to clone and extend.
- * @param {TableRefNode} tableRef The table to filter.
- * @returns {(filter: FilterExpr) => Query} The generator function.
+ * @param query The query to clone and extend.
+ * @param tableRef The table to filter.
+ * @returns The generator function.
  */
-export function filterQuery(query, tableRef) {
-  return (filter) => {
+export function filterQuery(query: Query, tableRef: TableRefNode) {
+  return (filter: FilterExpr) => {
     const clone = deepClone(query);
     walk(clone, (node) => {
       if (
@@ -32,12 +28,12 @@ export function filterQuery(query, tableRef) {
   };
 }
 
-function arrayEquals(a, b) {
+function arrayEquals(a: unknown[], b: unknown[]) {
   if (a === b) return true;
   if (a == null || b == null) return false;
   if (a.length !== b.length) return false;
 
-  for (var i = 0; i < a.length; ++i) {
+  for (let i = 0; i < a.length; ++i) {
     if (a[i] !== b[i]) return false;
   }
   return true;

package/src/transforms/{line-density.js → line-density.ts}

@@ -1,8 +1,5 @@
-/**
- * @import { SelectQuery } from '../ast/query.js'
- * @import { ExprValue } from '../types.js'
- */
-import { Query } from '../ast/query.js';
+import type { ExprValue } from '../types.js';
+import { Query, type SelectQuery } from '../ast/query.js';
 import { count, max, sum } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
 import { abs, floor, greatest, round, sign } from '../functions/numeric.js';
@@ -18,24 +15,29 @@ import { over } from '../util/ast.js';
  * pairs, perform line rasterization in-database, normalize arc lengths,
  * and then sum results for all line series to produce a density map.
  * Based on Moritz and Fisher's work: https://arxiv.org/abs/1808.06019
- * @param {SelectQuery} q The base query over the data.
- * @param {ExprValue} x Bin expression for x dimension.
+ * @param q The base query over the data.
+ * @param x Bin expression for x dimension.
  *  Provides gridded x coordinates, potentially with a fractional component.
- * @param {ExprValue} y Bin expression for x dimension.
+ * @param y Bin expression for x dimension.
  *  Provides gridded y coordinates, potentially with a fractional component.
- * @param {string[]} z Group by columns that segment data into individual line
+ * @param z Group by columns that segment data into individual line
  *  series. An empty array indicates there is only a single line series.
- * @param {number} xn The number of grid bins for the x dimension.
- * @param {number} yn The number of grid bins for the y dimension.
- * @param {string[]} [groupby] Additional group by expressions. Separate
+ * @param xn The number of grid bins for the x dimension.
+ * @param yn The number of grid bins for the y dimension.
+ * @param groupby Additional group by expressions. Separate
  *  line density maps are created for each of these groups.
- * @param {boolean} [normalize=true] Flag toggling approximate arc-length
- *  normalization to improve accuracy and reduce artifacts (default `true`).
- * @returns {SelectQuery}
+ * @param normalize Flag toggling approximate arc-length normalization to
+ *  improve accuracy and reduce artifacts (default `true`).
  */
 export function lineDensity(
-  q, x, y, z, xn, yn,
-  groupby = [], normalize = true
+  q: SelectQuery,
+  x: ExprValue,
+  y: ExprValue,
+  z: string[],
+  xn: number,
+  yn: number,
+  groupby: string[] = [],
+  normalize: boolean = true
 ) {
   // select x, y points binned to the grid
   q.select({

package/src/transforms/{m4.js → m4.ts}

@@ -1,7 +1,5 @@
-/**
- * @import { ExprNode } from '../ast/node.js'
- * @import { ExprValue, FromExpr } from '../types.js'
- */
+import type { ExprValue, FromExpr, SelectExpr } from '../types.js';
+import type { ColumnRefNode } from '../ast/column-ref.js';
 import { Query, isQuery } from '../ast/query.js';
 import { argmax, argmin, max, min } from '../functions/aggregate.js';
 import { int32 } from '../functions/cast.js';
@@ -15,16 +13,21 @@ import { floor } from '../functions/numeric.js';
  * argmin and argmax, following https://arxiv.org/pdf/2306.03714.pdf.
  * This method can bin along either the *x* or *y* dimension, as determined
  * by the caller-provided *bin* expression.
- * @param {FromExpr} input The base query or table.
- * @param {ExprValue} bin An expression that maps
+ * @param input The base query or table.
+ * @param bin An expression that maps
  *  time-series values to fractional pixel positions.
- * @param {string} x The x dimension column name.
- * @param {string} y The y dimension column name.
- * @param {ExprNode[]} [groups] Additional
- *  groupby columns, for example for faceted charts.
- * @returns {Query} The resulting M4 query.
+ * @param x The x dimension column name.
+ * @param y The y dimension column name.
+ * @param groups Additional groupby columns, for example for faceted charts.
+ * @returns The resulting M4 query.
  */
-export function m4(input, bin, x, y, groups = []) {
+export function m4(
+  input: FromExpr,
+  bin: ExprValue,
+  x: string,
+  y: string,
+  groups: ColumnRefNode[] = []
+) {
   const pixel = int32(floor(bin));
 
   // Below, we treat input as a CTE when it is a query. In this case,
@@ -32,10 +35,10 @@ export function m4(input, bin, x, y, groups = []) {
   const useCTE = isQuery(input);
   const from = useCTE ? 'input' : input;
   const query = useCTE
-    ? Query.with(cte(/** @type {string} */(from), input, true))
+    ? Query.with(cte(String(from), input, true))
     : Query;
 
-  const q = (sel) => Query
+  const q = (sel: SelectExpr) => Query
     .from(from)
     .select(sel)
     .groupby(pixel, groups);

package/src/transforms/{scales.js → scales.ts}

@@ -1,13 +1,55 @@
+import type { ExprValue } from '../types.js';
 import { LiteralNode } from '../ast/literal.js';
+import { ExprNode } from '../ast/node.js';
 import { epoch_ms } from '../functions/datetime.js';
 import { literal } from '../functions/literal.js';
 import { abs, exp, ln, log, sign, sqrt } from '../functions/numeric.js';
 import { add, div, mul, pow, sub } from '../functions/operators.js';
 import { asNode } from '../util/ast.js';
+import { identity } from '../util/identity.js';
+import { DateTimeValue } from './util/time-interval.js';
 
-const identity = x => x;
+export interface ScaleTransform<T> {
+  apply: (value: T) => number;
+  invert: (value: number) => T;
+  sqlApply: (value: ExprValue) => ExprNode;
+  sqlInvert: (value: ExprNode) => ExprNode;
+}
+
+export type ScaleType =
+  | 'identity'
+  | 'linear'
+  | 'log'
+  | 'symlog'
+  | 'sqrt'
+  | 'pow'
+  | 'time'
+  | 'utc'
+  ;
+
+export type ScaleDomain = [number, number] | [Date, Date];
+
+export interface ScaleOptions {
+  /** The scale type, such as `'linear'`, `'log'`, etc. */
+  type: ScaleType;
+  /** The scale domain, as an array of start and end data values. */
+  domain?: ScaleDomain;
+  /**
+   * The scale range, as an array of start and end screen pixels.
+   * The range may be omitted for *identity* scales.
+   */
+  range?: [number, number];
+  /** The base of the logarithm. For `'log'` scales only. */
+  base?: number;
+  /** The constant parameter. For `'symlog'` scales only. */
+  constant?: number;
+  /** The exponent parameter. For `'pow'` scales only. */
+  exponent?: number;
+}
+
+export type Scale<T> = ScaleTransform<T> & ScaleOptions;
 
-function scaleLinear() {
+function scaleLinear(): ScaleTransform<number> {
   return {
     apply: identity,
     invert: identity,
@@ -16,7 +58,7 @@ function scaleLinear() {
   };
 }
 
-function scaleLog({ base = null } = {}) {
+function scaleLog({ base = null }: {base?: number | null} = { }): ScaleTransform<number> {
   if (base == null || base === Math.E) {
     return {
       apply: Math.log,
@@ -42,7 +84,7 @@ function scaleLog({ base = null } = {}) {
   }
 }
 
-function scaleSymlog({ constant = 1 } = {}) {
+function scaleSymlog({ constant = 1 } = {}): ScaleTransform<number> {
   const _ = +constant;
   return {
     apply: x => Math.sign(x) * Math.log1p(Math.abs(x)),
@@ -52,7 +94,7 @@ function scaleSymlog({ constant = 1 } = {}) {
   };
 }
 
-function scaleSqrt() {
+function scaleSqrt(): ScaleTransform<number> {
   return {
     apply: x => Math.sign(x) * Math.sqrt(Math.abs(x)),
     invert: x => Math.sign(x) * x * x,
@@ -61,7 +103,7 @@ function scaleSqrt() {
   };
 }
 
-function scalePow({ exponent = 1 } = {}) {
+function scalePow({ exponent = 1 } = {}): ScaleTransform<number> {
   const e = +exponent;
   return {
     apply: x => Math.sign(x) * Math.pow(Math.abs(x), e),
@@ -71,12 +113,12 @@ function scalePow({ exponent = 1 } = {}) {
   };
 }
 
-function scaleTime() {
+function scaleTime(): ScaleTransform<DateTimeValue> {
   return {
-    apply: x => +x,
+    apply: x => Number(x),
     invert: x => new Date(x),
     sqlApply: c => c instanceof Date ? literal(+c)
-      : isDateLiteral(c) ? literal(+c.value)
+      : isDateLiteral(c) ? literal(Number(c.value))
       : epoch_ms(c),
     sqlInvert: identity
   };
@@ -93,16 +135,17 @@ const scales = {
   utc: scaleTime
 };
 
-export function scaleTransform(options) {
+export function scaleTransform<T>(options: ScaleOptions): Scale<T> {
   const scale = scales[options.type];
-  return scale ? { ...options, ...scale(options) } : null;
+  if (!scale) throw new Error(`Unrecognized scale type: ${options.type}`);
+  // @ts-expect-error suppress error, revisit later?
+  return { ...options, ...scale(options) };
 }
 
 /**
  * Check if a value is a date-valued literal SQL AST node.
- * @param {*} x The value to test.
- * @returns {x is LiteralNode}
+ * @param x The value to test.
  */
-function isDateLiteral(x) {
+function isDateLiteral(x: unknown): x is LiteralNode {
   return x instanceof LiteralNode && x.value instanceof Date;
 }

package/src/transforms/util/bin-step.ts

@@ -0,0 +1,100 @@
+/** Numerical binning options. */
+export interface BinOptions {
+  /**
+   * An exact binning step to use.
+   */
+  step?: number;
+  /**
+   * The desired number of binning steps. This value is a hint,
+   * it does not guarantee an exact number of steps.
+   */
+  steps?: number;
+  /**
+   * A minimum binning step value.
+   * No generated step can be less than this value.
+   */
+  minstep?: number;
+  /**
+   * A boolean flag (default true) indicating if bin extents should be snapped
+   * to "nice" numbers such as multiples of 5 or 10.
+   */
+  nice?: boolean;
+  /**
+   * A number indicating the the logarithm base to use for automatic step size
+   * determination. Defaults to base 10.
+   */
+  base?: number;
+}
+
+/**
+ * Generate a numeric binning scheme suitable for a histogram.
+ * @param min The minimum value of the extent to bin.
+ * @param max The maximum value of the extent to bin.
+ * @param options Binning scheme options.
+ */
+export function binSpec(min: number, max: number, options: BinOptions) {
+  let {
+    step,
+    steps = 25,
+  } = options;
+  const {
+    minstep = 0,
+    nice = true,
+    base
+  } = options;
+
+  if (nice !== false) {
+    // use span to determine step size
+    const span = max - min;
+    const logb = base ? Math.log(base) : Math.LN10;
+    step = step || binStep(span, steps, minstep, logb);
+
+    // adjust min/max relative to step
+    let v = Math.log(step);
+    const precision = v >= 0 ? 0 : ~~(-v / logb) + 1;
+    const eps = Math.pow(10, -precision - 1);
+    v = Math.floor(min / step + eps) * step;
+    min = min < v ? v - step : v;
+    max = Math.ceil(max / step) * step;
+    steps = Math.round((max - min) / step);
+  }
+
+  return { min, max, steps };
+}
+
+/**
+ * Determine a bin step interval.
+ * @param span The span from maximum to minimum value.
+ * @param steps The approximate number of desired bins.
+ * @param minstep The minimum acceptable bin step size.
+ * @param logb The log base for determining orders of magnitude for step
+ *  sizes. Defaults to log base 10 (`Math.LN10`). For example to use log
+ *  base 2, provide the argument `Math.LN2` instead.
+ * @returns The bin step interval (bin size).
+ */
+export function binStep(
+  span: number,
+  steps: number,
+  minstep: number = 0,
+  logb: number = Math.LN10
+) {
+  let v;
+
+  const level = Math.ceil(Math.log(steps) / logb);
+  let step = Math.max(
+    minstep,
+    Math.pow(10, Math.round(Math.log(span) / logb) - level)
+  );
+
+  // increase step size if too many bins
+  while (Math.ceil(span / step) > steps) { step *= 10; }
+
+  // decrease step size if allowed
+  const div = [5, 2];
+  for (let i = 0, n = div.length; i < n; ++i) {
+    v = step / div[i];
+    if (v >= minstep && span / v <= steps) step = v;
+  }
+
+  return step;
+}