Data Query Examples

Type definitions for the data query layer. These types define the schema for querying and aggregating experiment data, used in ML-Dash and similar data visualization interfaces.

Import

import type {
  Aggregation,
  SeriesQuery,
  AggregatedSeriesQuery,
  SeriesConfig,
  ChartQuery,
} from "@vuer-ai/vuer-viz";

Type Definitions

Aggregation

Aggregation methods for combining time series data across multiple experiment runs.

type Aggregation =
  | "mean" | "median" | "std" | "var" | "min" | "max" | "sum" | "count"
  | "Q05" | "Q10" | "Q25" | "Q50" | "Q75" | "Q90" | "Q95"
  | null

Aggregation	Formula	Description
`"mean"`	x̄ = (1/n)Σxᵢ	Arithmetic mean
`"median"`	median(x₁, …, xₙ)	Middle value (50th percentile)
`"std"`	σ = √[(1/n)Σ(xᵢ − x̄)²]	Standard deviation
`"var"`	σ² = (1/n)Σ(xᵢ − x̄)²	Variance
`"min"`	min(x₁, …, xₙ)	Minimum value
`"max"`	max(x₁, …, xₙ)	Maximum value
`"sum"`	Σxᵢ	Sum of all values
`"count"`	n	Number of values
`"Q05"`	Q₀.₀₅	5th percentile
`"Q10"`	Q₀.₁₀	10th percentile
`"Q25"`	Q₀.₂₅	25th percentile (lower quartile)
`"Q50"`	Q₀.₅₀	50th percentile (median)
`"Q75"`	Q₀.₇₅	75th percentile (upper quartile)
`"Q90"`	Q₀.₉₀	90th percentile
`"Q95"`	Q₀.₉₅	95th percentile
`null`	—	No aggregation (use raw data)

SeriesQuery

Data query interface for fetching time series from a single experiment.

interface SeriesQuery {
  /** Experiment directory prefix (used as current working directory for glob) */
  prefix?: string;
  /** X-axis key (dot-separated path in the log data) */
  xKey?: string;
  /** Single Y-axis key */
  yKey?: string;
  /** Multiple Y-axis keys (alternative to yKey) */
  yKeys?: string[];
  /** Data range for x-axis */
  xMin?: number;
  xMax?: number;
  /** Data range for y-axis */
  yMin?: number;
  yMax?: number;
}

Example:

const query: SeriesQuery = {
  prefix: "experiments/run-001",
  xKey: "step",
  yKeys: ["train.loss", "val.loss"],
  xMin: 0,
  xMax: 1000,
};

AggregatedSeriesQuery

Extends SeriesQuery with glob pattern matching and aggregation capabilities for querying multiple experiments.

interface AggregatedSeriesQuery extends SeriesQuery {
  /** Glob pattern for matching multiple experiment directories */
  glob?: string;
  /** Aggregation method for combining data across matched experiments */
  agg?: Aggregation;
  /** Sort order for selecting experiments */
  sortOrder?: SortOrder;
}

Example:

const query: AggregatedSeriesQuery = {
  prefix: "experiments",
  glob: "run-*/seed-*",
  xKey: "step",
  yKey: "reward.mean",
  agg: "mean",
  sortOrder: "mtime",
};

SeriesConfig

Series configuration for comparison plots, combining query parameters with visual styling.

interface SeriesConfig extends AggregatedSeriesQuery {
  /** Display label for the series */
  label: string;
  /** Line color */
  color?: string;
  /** Line width in pixels */
  lineWidth?: number;
  /** SVG dash array pattern (e.g., "5 5" for dashed) */
  dashArray?: string;
}

Example:

const series: SeriesConfig = {
  label: "Baseline",
  prefix: "experiments",
  glob: "baseline/seed-*",
  xKey: "step",
  yKey: "reward.mean",
  agg: "mean",
  color: "#3498db",
  lineWidth: 2,
};

ChartQuery

Complete chart configuration for comparison plots across multiple experiment sets.

interface ChartQuery {
  /** Chart title */
  title?: string;
  /** X-axis label */
  xLabel?: string;
  /** Y-axis label */
  yLabel?: string;
  /** X-axis formatter */
  xFormat?: string;
  /** Y-axis formatter */
  yFormat?: string;
  /** Y-axis range */
  yMin?: number;
  yMax?: number;
  /** Series configurations */
  series: SeriesConfig[];
}

Example:

const chartConfig: ChartQuery = {
  title: "Training Performance",
  xLabel: "Steps",
  yLabel: "Reward",
  yMin: -10,
  yMax: 1000,
  xFormat: "auto",
  yFormat: "auto",
  series: [
    {
      label: "Baseline",
      prefix: "experiments",
      glob: "baseline/seed-*",
      xKey: "step",
      yKey: "reward.mean",
      agg: "mean",
      color: "#3498db",
    },
    {
      label: "Improved",
      prefix: "experiments",
      glob: "improved/seed-*",
      xKey: "step",
      yKey: "reward.mean",
      agg: "mean",
      color: "#2ecc71",
      dashArray: "5 5",
    },
  ],
};

Usage with Data Query Functions

These types are designed to work with data query functions like getSeries() from ML-Dash:

import { getSeries } from "@vuer-ai/ml-dash";
import type { AggregatedSeriesQuery } from "@vuer-ai/vuer-viz";

const query: AggregatedSeriesQuery = {
  prefix: "experiments",
  glob: "run-*/seed-*",
  xKey: "step",
  yKey: "loss",
  agg: "mean",
};

const series = getSeries(query);

Visual Grammar - Overview of the visual grammar
Other Chart Types - Additional visualization components

Data Query Examples

Import

Type Definitions

Aggregation

SeriesQuery

AggregatedSeriesQuery

SeriesConfig

ChartQuery

Usage with Data Query Functions

Related Documentation