Appearance

Selection ​

A Selection is a specialized Param that manages a collection of Boolean-valued predicates that can be used to interactively filter a data source.

Selections apply a resolution strategy to merge clauses into client-specific predicates:

  • The single strategy simply includes only the most recent clause.
  • The union strategy performs disjunction, combining all predicates via Boolean OR.
  • The intersect strategy performs conjunction via Boolean AND.

In addition, selections can be cross-filtered, so that they affect views other than the one currently being interacted with. The strategies above are modified to omit clauses where the clients set includes the input argument to the predicate() function.

By default, a selection without any clauses selects all records. To instead select no records, set the empty option to true.

A Selection can include the clauses of one or more upstream selections. New clauses or activations published to those selections will be relayed to any selections that include them. Beyond these relays, the selections act independently and so may apply different resolution strategies.

isSelection ​

isSelection(value)

Returns true if the input value is a Selection, false otherwise.

Selection.intersect ​

Selection.intersect(options)

Create a new Selection instance with an intersect (conjunction) resolution strategy.

The options object may include:

  • A Boolean cross flag (default false) indicating cross-filtered resolution. If true, selection clauses will not be applied to the clients they are associated with.
  • An empty flag (default false) indicates whether a selection without any clauses should not select an empty set with no records (true) or select all records (false).
  • An include option (default []) indicating one or more selections whose clauses should be included as part of this selection. The option value can be either a single Selection instance or an array of Selection instances.

Selection.union ​

Selection.union(options)

Create a new Selection instance with a union (disjunction) resolution strategy.

The options object may include:

  • A Boolean cross flag (default false) indicating cross-filtered resolution. If true, selection clauses will not be applied to the clients they are associated with.
  • An empty flag (default false) indicates whether a selection without any clauses should not select an empty set with no records (true) or select all records (false).
  • An include option (default []) indicating one or more selections whose clauses should be included as part of this selection. The option value can be either a single Selection instance or an array of Selection instances.

Selection.single ​

Selection.single(options)

Create a new Selection instance with a singular resolution strategy that keeps only the most recent selection clause.

The options object may include:

  • A Boolean cross flag (default false) indicating cross-filtered resolution. If true, selection clauses will not be applied to the clients they are associated with.
  • An empty flag (default false) indicates whether a selection without any clauses should not select an empty set with no records (true) or select all records (false).
  • An include option (default []) indicating one or more selections whose clauses should be included as part of this selection. The option value can be either a single Selection instance or an array of Selection instances.

Selection.crossfilter ​

Selection.crossfilter()

Create a new Selection instance with a cross-filtered intersect resolution strategy. This is a convenience method for Selection.intersect({ cross: true }).

clone ​

selection.clone()

Create a cloned copy of this Selection instance.

remove ​

selection.remove(source)

Create a clone of this Selection with clauses corresponding to the provided source removed.

active ​

selection.active

Property getter for the current active (most recently updated) selection clause.

value ​

selection.value

The value corresponding to the current active selection clause. Selections override the Param.value property to return the active clause value, making selections compatible where standard params are expected.

valueFor ​

selection.valueFor(source)

The value corresponding to a given clause source. Returns undefined if this selection does not include a clause from this source.

clauses ​

selection.clauses

The current array of selection clauses.

activate ​

selection.activate(clause)

Emit an activate event with the given selection clause.

These activate events provide a clause indicative of likely future updates. For example, a brush interactor may trigger an activation event when the cursor enters a brushable region, providing an example clause prior to any actual updates. Activation events can be used to implement optimizations such as prefetching.

update ​

selection.update(clause)

Update the selection with a new selection clause. A clause is an object consisting of:

  • the source component (such as a client or interactor) providing the clause,
  • a set of clients associated with the clause, indicating the clients that should be skipped in the case of cross-filtering,
  • a query predicate (e.g, the range predicate column BETWEEN 0 AND 1),
  • a corresponding value (e.g., the range array [0,1]), and
  • an optional schema providing clause metadata.

Upon update, any prior clause with the same source is removed and the new, most recent clause (called the active clause) is added.

predicate ​

selection.predicate(client)

Return a selection query predicate for the given Mosaic client. The resulting predicate can be used as part of a SQL WHERE clause.

addEventListener ​

selection.addEventListener(type, callback)

Add an event listener callback function for the specified event type. Selections support both "value" and "activate" type events.

removeEventListener ​

selection.removeEventListener(type, callback)

Remove an event listener callback function for the specified event type.

pending ​

selection.pending(type)

Returns a promise that resolves when any pending updates complete for the event of the given type currently being processed. The Promise will resolve immediately if the queue for the given event type is empty.