Data Hooks & Providers

The visual grammar system provides four separate data providers, each focused on a specific data type. Each provider transforms a simple fetch function into a stateful hook with loading and error states.

• SeriesDataProvider - Time series data
• TabularDataProvider - Tabular data
• SweepDataProvider - Hyperparameter sweep data
• GlobDataProvider - File/resource lists via glob patterns
• Example Data & Glob Patterns
• Related Documentation

SeriesDataProvider

Context provider for time series data fetching. You provide a simple async fetch function:

type FetchSeriesFunction = (query: AggregatedSeriesQuery) => Promise<LineSeries[]>

Example Usage

import { SeriesDataProvider, useSeriesData } from '@vuer-ai/vuer-viz';

async function fetchSeries(query: AggregatedSeriesQuery): Promise<LineSeries[]> {
  const response = await fetch("/api/series", {
    method: "POST",
    body: JSON.stringify(query),
  });
  return await response.json();
}

<SeriesDataProvider fetchSeries={fetchSeries}>
  <YourChart />
</SeriesDataProvider>

Using the Hook

function YourChart() {
  const useSeries = useSeriesData();
  const { series, loading, error } = useSeries({
    prefix: "experiments",
    glob: "ffn/*",
    xKey: "step",
    yKey: "reward",
    agg: "mean"
  });

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <LineChart series={series} />;
}

TabularDataProvider

Context provider for tabular data fetching:

type FetchTabularFunction = <T>(query: {
  prefix?: string;
  glob?: string;
  filters?: Record<string, any>;
}) => Promise<T[]>

Example Usage

import { TabularDataProvider, useTabularData } from '@vuer-ai/vuer-viz';

async function fetchTabular(query) {
  const response = await fetch("/api/tabular", {
    method: "POST",
    body: JSON.stringify(query),
  });
  return await response.json();
}

<TabularDataProvider fetchTabular={fetchTabular}>
  <YourChart />
</TabularDataProvider>

Using the Hook

function YourChart() {
  const useTabular = useTabularData();
  const { data, loading, error } = useTabular({
    prefix: "benchmarks",
    filters: { domain: "cheetah-run" }
  });

  return <BarChart data={data} />;
}

SweepDataProvider

Context provider for hyperparameter sweep data:

type FetchSweepFunction = <T>(query: {
  prefix?: string;
  glob?: string;
  filters?: Record<string, any>;
}) => Promise<T[]>

Example Usage

import { SweepDataProvider, useSweepData } from '@vuer-ai/vuer-viz';

async function fetchSweep(query) {
  const response = await fetch("/api/sweep", {
    method: "POST",
    body: JSON.stringify(query),
  });
  return await response.json();
}

<SweepDataProvider fetchSweep={fetchSweep}>
  <YourChart />
</SweepDataProvider>

Using the Hook

function YourChart() {
  const useSweep = useSweepData();
  const { data, loading, error } = useSweep({
    prefix: "sweeps",
    filters: { num_layers: 3 }
  });

  return <ParallelCoordinates data={data} />;
}

GlobDataProvider

Context provider for file/resource list fetching via glob patterns. Ideal for Image, Video, and Text components that need to access lists of files:

type FetchGlobFunction = <T extends GlobResult>(query: {
  prefix?: string;
  glob?: string;
  filters?: Record<string, any>;
}) => Promise<T[]>

interface GlobResult {
  prefix: string;
  src: string;
  [key: string]: any;
}

Example Usage

import { GlobDataProvider, useGlobData } from '@vuer-ai/vuer-viz';

async function fetchGlob(query) {
  const response = await fetch("/api/glob", {
    method: "POST",
    body: JSON.stringify(query),
  });
  return await response.json();
}

<GlobDataProvider fetchGlob={fetchGlob}>
  <YourComponent />
</GlobDataProvider>

Using the Hook

function ImageGallery() {
  const useGlob = useGlobData();
  const { data, loading, error } = useGlob({
    prefix: "experiments/run-1",
    glob: "images/*.png"
  });

  if (loading) return <div>Loading...</div>;

  return (
    <div>
      {data.map(item => (
        <img key={item.src} src={item.src} alt={item.prefix} />
      ))}
    </div>
  );
}

Use Cases

• Image galleries - glob: "screenshots/*.png"
• Video playback - glob: "videos/*.mp4"
• Log files - glob: "logs/*.txt"
• Model checkpoints - glob: "checkpoints/model-*.pt"

Composing Multiple Providers

You can nest providers when you need multiple data types:

<SeriesDataProvider fetchSeries={fetchSeries}>
  <TabularDataProvider fetchTabular={fetchTabular}>
    <SweepDataProvider fetchSweep={fetchSweep}>
      <GlobDataProvider fetchGlob={fetchGlob}>
        <App />
      </GlobDataProvider>
    </SweepDataProvider>
  </TabularDataProvider>
</SeriesDataProvider>

Or use only the providers you need:

<GlobDataProvider fetchGlob={fetchGlob}>
  <App />
</GlobDataProvider>

Available Hooks

Each hook has its own detailed documentation with implementation examples:

• useSeries - Time series data with aggregation across multiple runs
• useTabular - Tabular data for tables and bar charts
• useSweep - Hyperparameter sweep data for parallel coordinates
• useGlob - File/resource lists for images, videos, and text files

Related Documentation

• useSeries - Time series data with aggregation
• useTabular - Tabular data for bar charts
• useSweep - Hyperparameter sweep data
• useGlob - File and resource list queries
• Example Data & Globs - Example datasets and glob pattern matching
• Visual Grammar Overview - Understanding the visual grammar system
• Data Query Examples - Query patterns and examples
• Data Structure & Format Guide - Columnar data format specification