@uwdata/mosaic-core 0.8.0 → 0.10.0

package/src/util/selection-types.ts

@@ -0,0 +1,137 @@
+import { SQLExpression } from '@uwdata/mosaic-sql';
+import { MosaicClient } from '../MosaicClient.js';
+
+/**
+ * Selection clause metadata to guide possible query optimizations.
+ * Sub-interfaces provide more information about the specifics of a
+ * given selection based on the selection type.
+ */
+export interface ClauseMetadata {
+  /**
+   * The selection type, such as `'point'`, `'interval'`, or `'match'`.
+   */
+  type: string;
+}
+
+/**
+ * Selection clause metadata indicating selection of one or more discrete
+ * point values, typically based on equality or is distinctiveness checks.
+ */
+export interface PointMetadata extends ClauseMetadata {
+  type: 'point';
+}
+
+/** Text search matching methods. */
+export type MatchMethod =
+  | 'contains'
+  | 'prefix'
+  | 'suffix'
+  | 'regexp'
+  | (string & {});
+
+/**
+ * Selection clause metadata indicating text search matching.
+ */
+export interface MatchMetadata extends ClauseMetadata {
+  type: MatchMethod;
+  /** The text search matching method used. */
+  method?: 'contains' | 'prefix' | 'suffix' | 'regexp' | (string & {});
+}
+
+/** Quantitative scale types. */
+export type ScaleType =
+  | 'identity'
+  | 'linear'
+  | 'log'
+  | 'sqrt'
+  | 'pow'
+  | 'symlog'
+  | 'time'
+  | 'utc';
+
+/** A data value interval extent. */
+export type Extent = [number, number] | [Date, Date];
+
+/**
+ * Descriptor for a scale that maps a data domain to screen pixels.
+ */
+export interface Scale {
+  /** The scale type, such as `'linear'`, `'log'`, etc. */
+  type: ScaleType;
+  /** The scale domain, as an array of start and end data values. */
+  domain: Extent;
+  /**
+   * 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;
+}
+
+/** A binning method name. */
+export type BinMethod = 'floor' | 'ceil' | 'round';
+
+/**
+ * Selection clause metadata for one or more selected intervals. This
+ * metadata can be used to determine appropriate data-space binning
+ * schemes that correspond to pixel-level bins in screen space.
+ */
+export interface IntervalMetadata extends ClauseMetadata {
+  type: 'interval';
+  /**
+   * The interactive pixel size used by the generating component.
+   * Values larger than one indicate intervals that "snap-to" values
+   * greater than a single pixel. If unspecified, assumed to be `1`.
+   */
+  pixelSize?: number;
+  /**
+   * An array of one or more scale descriptors that describe the
+   * mapping from data values to screen pixels.
+   */
+  scales?: Scale[];
+  /**
+   * A hint for the binning method to use when discretizing the
+   * interval domain. If unspecified, the default is `'floor'`.
+   */
+  bin?: BinMethod
+}
+
+/**
+ * A selection clause representing filtering criteria
+ * to apply within a Mosiac Selection.
+ */
+export interface SelectionClause {
+  /**
+   * A unique identifier (according to object equality) for the source
+   * component that generated this clause. In many cases, this is a
+   * reference to the originating component itself.
+   */
+  source: any;
+  /**
+   * A set of Mosaic clients associated with this clause that should not
+   * be updated when this clause is applied in a cross-filtering context.
+   */
+  clients?: Set<MosaicClient>;
+  /**
+   * A selected value associated with this clause. For example, for a 1D
+   * interval selection clause the value may be a [lo, hi] array.
+   */
+  value: any;
+  /**
+   * A predicate SQL expression suitable for use in a query WHERE clause.
+   * The predicate should apply filtering criteria consistent with this
+   * clause's *value* property.
+   */
+  predicate: SQLExpression | null;
+  /**
+   * Optional clause metadata that varies based on the selection type.
+   * The metadata can be used to optimize selection queries, for example
+   * by creating pre-aggregated data cubes when applicable.
+   */
+  meta?: ClauseMetadata;
+}

package/src/util/to-data-columns.js

@@ -0,0 +1,71 @@
+import { convertArrowColumn, isArrowTable } from './convert-arrow.js';
+
+/**
+ * @typedef {Array | Int8Array | Uint8Array | Uint8ClampedArray
+ *  | Int16Array | Uint16Array | Int32Array | Uint32Array
+ *  | Float32Array | Float64Array
+ * } Arrayish - an Array or TypedArray
+ */
+
+/**
+ * @typedef {
+ *  | { numRows: number, columns: Record<string,Arrayish> }
+ *  | { numRows: number, values: Arrayish; }
+ * } DataColumns
+*/
+
+/**
+ * Convert input data to a set of column arrays.
+ * @param {any} data The input data.
+ * @returns {DataColumns} An object with named column arrays.
+ */
+export function toDataColumns(data) {
+  return isArrowTable(data)
+    ? arrowToColumns(data)
+    : arrayToColumns(data);
+}
+
+/**
+ * Convert an Arrow table to a set of column arrays.
+ * @param {import('apache-arrow').Table} data An Apache Arrow Table.
+ * @returns {DataColumns} An object with named column arrays.
+ */
+function arrowToColumns(data) {
+  const { numRows, numCols, schema: { fields } } = data;
+  const columns = {};
+
+  for (let col = 0; col < numCols; ++col) {
+    const name = fields[col].name;
+    if (columns[name]) {
+      console.warn(`Redundant column name "${name}". Skipping...`);
+    } else {
+      columns[name] = convertArrowColumn(data.getChildAt(col));
+    }
+  }
+
+  return { numRows, columns };
+}
+
+/**
+ * Convert an array of values to a set of column arrays.
+ * If the array values are objects, build out named columns.
+ * We use the keys of the first object as the column names.
+ * Otherwise, use a special "values" array.
+ * @param {object[]} data An array of data objects.
+ * @returns {DataColumns} An object with named column arrays.
+ */
+function arrayToColumns(data) {
+  const numRows = data.length;
+  if (typeof data[0] === 'object') {
+    const names = numRows ? Object.keys(data[0]) : [];
+    const columns = {};
+    if (names.length > 0) {
+      names.forEach(name => {
+        columns[name] = data.map(d => d[name]);
+      });
+    }
+    return { numRows, columns };
+  } else {
+    return { numRows, values: data };
+  }
+}

package/src/FilterGroup.js

@@ -1,70 +0,0 @@
-import { DataCubeIndexer } from './DataCubeIndexer.js';
-
-export class FilterGroup {
-  /**
-   * @param {import('./Coordinator.js').Coordinator} coordinator The Mosaic coordinator.
-   * @param {*} selection The shared filter selection.
-   * @param {*} index Boolean flag or options hash for data cube indexer.
-   *  Falsy values disable indexing.
-   */
-  constructor(coordinator, selection, index = true) {
-    /** @type import('./Coordinator.js').Coordinator */
-    this.mc = coordinator;
-    this.selection = selection;
-    this.clients = new Set();
-    this.indexer = index
-      ? new DataCubeIndexer(this.mc, { ...index, selection })
-      : null;
-
-    const { value, activate } = this.handlers = {
-      value: () => this.update(),
-      activate: clause => this.indexer?.index(this.clients, clause)
-    };
-    selection.addEventListener('value', value);
-    selection.addEventListener('activate', activate);
-  }
-
-  finalize() {
-    const { value, activate } = this.handlers;
-    this.selection.removeEventListener('value', value);
-    this.selection.removeEventListener('activate', activate);
-  }
-
-  reset() {
-    this.indexer?.reset();
-  }
-
-  add(client) {
-    (this.clients = new Set(this.clients)).add(client);
-    return this;
-  }
-
-  remove(client) {
-    if (this.clients.has(client)) {
-      (this.clients = new Set(this.clients)).delete(client);
-    }
-    return this;
-  }
-
-  /**
-   * Internal method to process a selection update.
-   * The return value is passed as a selection callback value.
-   * @returns {Promise} A Promise that resolves when the update completes.
-   */
-  update() {
-    const { mc, indexer, clients, selection } = this;
-    const hasIndex = indexer?.index(clients);
-    return hasIndex
-      ? indexer.update()
-      : defaultUpdate(mc, clients, selection);
-  }
-}
-
-function defaultUpdate(mc, clients, selection) {
-  return Promise.all(Array.from(clients).map(client => {
-    const filter = selection.predicate(client);
-    if (filter != null) {
-      return mc.updateClient(client, client.query(filter));
-    }
-  }));
-}