@uwdata/mosaic-spec 0.8.0 → 0.9.0

package/src/spec/marks/ErrorBar.ts

@@ -0,0 +1,91 @@
+import { ParamRef } from '../Param.js';
+import {
+  ChannelValue, ChannelValueSpec, MarkData, MarkOptions, MarkerOptions
+} from './Marks.js';
+
+/** Options for errorbar marks. */
+interface ErrorBarOptions extends MarkOptions, MarkerOptions {
+  /**
+   * The confidence interval in (0, 1); defaults to 0.95.
+   */
+  ci?: number | ParamRef;
+
+  /**
+   * An optional ordinal channel for grouping data, producing an independent
+   * error bar for each group. If not specified, it defaults to **stroke** if
+   * a channel.
+   */
+  z?: ChannelValue;
+}
+
+/** Options for the errorbarX mark. */
+export interface ErrorBarXOptions extends ErrorBarOptions {
+  /**
+   * The dependent variable horizontal position channel, typically bound to the
+   * *x* scale.
+   */
+  x: ChannelValueSpec;
+
+  /**
+   * The independent variable vertical position channel, typically bound to
+   * the *y* scale; defaults to the zero-based index of the data [0, 1, 2, …].
+   */
+  y?: ChannelValueSpec;
+}
+
+/** The errorbarX mark. */
+export interface ErrorBarX extends MarkData, ErrorBarXOptions {
+  /**
+   * A mark that draws error bars for a calculated parametric confidence
+   * interval for a dependent variable (*x*), potentially grouped by an
+   * independent variable (*y*).
+   *
+   * This mark aggregates raw values to produce a [parametric confidence
+   * interval][1] of the mean, assuming a normal distribution. To instead
+   * visualize pre-computeted interval values or custom aggregations, use
+   * a **ruleY** mark with specified **x1** and **x2** channels.
+   *
+   * Multiple error bars can be produced by specifying a **z** or **stroke**
+   * channel. Set the **marker** option to `'tick'` to add small perpendicular
+   * lines at the start and end of the error interval.
+   *
+   * [1]: https://en.wikipedia.org/wiki/Normal_distribution#Confidence_intervals
+   */
+  mark: 'errorbarX';
+}
+
+/** Options for the errorbarY mark. */
+export interface ErrorBarYOptions extends ErrorBarOptions {
+  /**
+   * The independent variable horizontal position channel, typically bound to
+   * the *x* scale; defaults to the zero-based index of the data [0, 1, 2, …].
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The dependent variable vertical position channel, typically bound to the
+   * *y* scale.
+   */
+  y: ChannelValueSpec;
+}
+
+/** The errorbarY mark. */
+export interface ErrorBarY extends MarkData, ErrorBarYOptions {
+  /**
+   * A mark that draws error bars for a calculated parametric confidence
+   * interval for a dependent variable (*y*), potentially grouped by an
+   * independent variable (*x*).
+   *
+   * This mark aggregates raw values to produce a [parametric confidence
+   * interval][1] of the mean, assuming a normal distribution. To instead
+   * visualize pre-computeted interval values or custom aggregations, use
+   * a **ruleX** mark with specified **y1** and **y2** channels.
+   *
+   * Multiple error bars can be produced by specifying a **z** or **stroke**
+   * channel. Set the **marker** option to `'tick'` to add small perpendicular
+   * lines at the start and end of the error interval.
+   *
+   * [1]: https://en.wikipedia.org/wiki/Normal_distribution#Confidence_intervals
+   */
+  mark: 'errorbarY';
+}

package/src/spec/marks/Marks.ts

@@ -194,6 +194,18 @@ export type SortOrder =
 /** The pointer mode for the tip; corresponds to pointerX, pointerY, and pointer. */
 export type TipPointer = 'x' | 'y' | 'xy';
 
+/** Selection filters to apply internally to mark data. */
+export type SelectFilter =
+  | 'first'
+  | 'last'
+  | 'maxX'
+  | 'maxY'
+  | 'minX'
+  | 'minY'
+  | 'nearest'
+  | 'nearestX'
+  | 'nearestY';
+
 export interface MarkData {
   /**
    * The data source for the mark.
@@ -215,10 +227,24 @@ export interface MarkOptions {
    * channel values; only truthy values are retained.
    *
    * Note that filtering only affects the rendered mark index, not the
-   * associated channel values, and thus has no effect on imputed scale domains.
+   * associated channel values, and has no effect on imputed scale domains.
    */
   filter?: ChannelValue;
 
+  /**
+   * Applies a filter transform after data is loaded to highlight selected
+   * values only. For example, `first` and `last` select the first or last
+   * values of series only (using the *z* channel to separate series).
+   * Meanwhile, `nearestX` and `nearestY` select the point nearest to the
+   * pointer along the *x* or *y* channel dimension. Unlike Mosaic selections,
+   * a mark level *select* is internal to the mark only, and does not populate
+   * a param or selection value to be shared across clients.
+   *
+   * Note that filtering only affects the rendered mark index, not the
+   * associated channel values, and has no effect on imputed scale domains.
+   */
+  select?: SelectFilter;
+
   /**
    * Applies a transform to reverse the order of the mark’s index, say for
    * reverse input order.

package/src/spec/marks/Text.ts

@@ -19,6 +19,11 @@ export interface TextOptions extends MarkOptions, TextStyles {
    */
   y?: ChannelValueSpec;
 
+  /**
+   * An optional ordinal channel for grouping data into series.
+   */
+  z?: ChannelValue;
+
   /**
    * The text contents channel, possibly with line breaks (\n, \r\n, or \r). If
    * not specified, defaults to the zero-based index [0, 1, 2, …].

package/LICENSE

@@ -1,47 +0,0 @@
-BSD 3-Clause License
-
-Copyright (c) 2023, UW Interactive Data Lab
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
----
-
-Portions of this software are derived from Observable Plot, which is released
-under the ISC license.
-
-Copyright 2020-2023 Observable, Inc.
-
-Permission to use, copy, modify, and/or distribute this software for any purpose
-with or without fee is hereby granted, provided that the above copyright notice
-and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
-REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
-FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
-INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
-OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
-THIS SOFTWARE.