useTabular

Fetches tabular data for tables and bar charts.

Overview

The useTabular hook provides filtering and querying capabilities for tabular data, ideal for bar charts, tables, and other non-time-series visualizations.

Hook Interface

export type UseTabularHook = <T = any>(query: {
  prefix?: string;
  glob?: string;
  filters?: Record<string, any>;
}) => {
  data: T[];
  loading: boolean;
  error: Error | null;
};

Reference Implementation

1. Define the fetch function

The fetch function handles the data retrieval logic:

async function fetchTabular<T = any>(query: {
  prefix?: string;
  glob?: string;
  filters?: Record<string, any>;
}): Promise<T[]> {
  const response = await fetch("/api/tabular", {
    method: "POST",
    body: JSON.stringify(query),
  });
  return await response.json();
}

2. Pass to TabularDataProvider

The provider builds the internal useTabular hook using your fetch function:

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

3. Internal hook implementation

The provider internally creates the useTabular hook with loading and error states:

// Inside TabularDataProvider
function useTabular<T = any>(query: {
  prefix?: string;
  glob?: string;
  filters?: Record<string, any>;
}) {
  const [data, setData] = useState<T[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    let cancelled = false;

    async function load() {
      try {
        setLoading(true);
        setError(null);
        const result = await fetchTabular<T>(query);
        if (!cancelled) setData(result);
      } catch (err) {
        if (!cancelled) setError(err as Error);
      } finally {
        if (!cancelled) setLoading(false);
      }
    }

    load();
    return () => { cancelled = true; };
  }, [query]);

  return { data, loading, error };
}

Usage Examples

Filter by Domain

const { data } = useTabular({
  filters: { domain: "cheetah-run" }
});

Filter by Method

const { data } = useTabular({
  glob: "lff/*"
});

Combine Filters

const { data } = useTabular({
  glob: "*/no-tgt/*",
  filters: { domain: "walker-walk" }
});

Benchmark Results Example Data

Tabular benchmark data across DM Control domains and methods.

Data Structure

export interface BenchmarkResult {
  from: string;              // "lff/no-tgt/cheetah-run/seed-0"
  domain: string;            // "cheetah-run"
  model: string;             // "lff"
  "no-tgt": boolean;
  "eval.reward": number;
  "eval.success_rate"?: number;
  steps: number;
}

export const benchmarkResults: BenchmarkResult[] = [...];

Contents

• 6 domains: cheetah-run, walker-walk, hopper-stand, reacher-easy, finger-spin, cartpole-swingup
• 5 methods: mlp, ffn, ffn/no-tgt, lff, lff/no-tgt
• LFF/no-tgt performs best across all domains

Helper Functions

getNestedValue

Access nested object properties via dot notation.

function getNestedValue(obj: any, path: string): any {
  return path.split('.').reduce((acc, key) => acc?.[key], obj);
}

// Examples:
getNestedValue(run, "metrics.reward")     // run.metrics.reward
getNestedValue(run, "eval.success_rate")  // run.eval.success_rate

Custom Backend Integration

Replace the example fixtures with your own data source:

// API backend
export function useTabular<T = any>(query: {
  prefix?: string;
  glob?: string;
  filters?: Record<string, any>;
}) {
  const [data, setData] = useState<T[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);

  useEffect(() => {
    async function fetchData() {
      try {
        setLoading(true);
        const response = await fetch('/api/tabular', {
          method: 'POST',
          body: JSON.stringify(query)
        });
        const result = await response.json();
        setData(result);
      } catch (err) {
        setError(err as Error);
      } finally {
        setLoading(false);
      }
    }
    fetchData();
  }, [query]);

  return { data, loading, error };
}

Related Documentation

• Data Hooks Overview - Data providers and hook system
• Data Query Examples - Query patterns and examples
• Data Structure & Format Guide - Columnar data format specification