Graph

Compiles and renders interactive Vega-Lite visualizations in the console, combining high-level builders for rapid data exploration with custom declarative chart definitions.

The Graph service bridges Expression Lab with the client-side Vega-Lite runtime. It transforms JSON payloads and structured language arrays into reactive charts, offering both turnkey builders for common visualizations and direct access to the raw Vega-Lite compiler.

• Vega-Lite compiler access: Compiles custom declarative specifications through Graph.render().
• Turnkey chart builders: Generates complete visualizations in a single call, including bar, line, area, scatter, heatmap, histogram, and timeline charts.
• Offline geographic mapping: Produces choropleths using bundled World and US TopoJSON datasets without external network requests or CSP issues, with built-in resolution for ISO country codes and US state abbreviations.
• Responsive container sizing: Scales chart dimensions to fit the console panel (width: "container").

---

How Graphs Work

Every Graph method includes validation, sensible defaults, and managed rendering:

• Flexible inputs: Accepts object literals, associative arrays, or raw JSON strings.
• Built-in defaults: Injects the Vega-Lite $schema and responsive width (width: "container") if omitted.
• Execution limits: Each chart generation counts toward expression execution limits and timeouts.
• Interactive & batch execution: Renders live visualizations in the interactive console, or pools them during batch routines until revealed via show[...].

Scripting with Visualizations

Charts can be generated alongside database queries or data processing routines inside prog[...] blocks:

prog[
  set['details', Database.table_details('posts')],
  show[
      Graph.bars(var['details']['indexes'], {
        x: 'Key_name',
        y: 'Cardinality',
        horizontal: true,
        title: 'Posts Table Index Cardinality',
        color_value: Graph.COLOR_BLUE
      })
  ]
]

---

Constants & Visual Tokens

The Graph class provides visual constants for colors, palettes, and TopoJSON geographic layers. When accessed using the scripting syntax, class constants resolve as properties on the Graph object instance (such as Graph.COLOR_BLUE or Graph.SCHEME_VIRIDIS).

Schema & Container Layout

Constant	Value	Description
DEFAULT_SCHEMA	'https://vega.github.io/schema/vega-lite/v6.json'	Default schema definition injected when $schema is omitted.
DEFAULT_WIDTH	'container'	Instructs the visualization container to expand across available viewport width.

Geographic TopoJSON Assets

Constant	Value	Description
COUNTRIES	'countries-110m.json'	Bundled TopoJSON dataset for world countries (1:110m resolution).
LAND	'land-110m.json'	Bundled TopoJSON dataset for continental landmass boundaries (1:110m resolution).
USA_STATES	'states-10m.json'	Bundled TopoJSON dataset for United States features (1:10m resolution).

Color Palette

Constant	Hex Value	Semantic Usage
COLOR_BLUE	'#3858e9'	Primary accent for default marks across single-series visualizations.
COLOR_RED	'#e53935'	Error thresholds, warning boundaries, and critical indicators.
COLOR_GREEN	'#43a047'	Positive metrics, success states, and growth indicators.
COLOR_PURPLE	'#8e24aa'	Categorical accents and secondary distributions.
COLOR_ORANGE	'#fb8c00'	Moderate warning thresholds and notice highlights.
COLOR_CYAN	'#00acc1'	Neutral continuous series and network metrics.
COLOR_GRAY	'#78909c'	Baseline boundaries, background markers, and reference tracks.
COLOR_DARK	'#263238'	High-contrast markers and dark outline rules.

Continuous & Categorical Schemes

Constant	Identifier	Color Type	Colors	Description
SCHEME_BLUES	'blues'	Sequential		Single-hue gradient ranging from light to dark blue.
SCHEME_REDS	'reds'	Sequential		Single-hue gradient ranging from light to deep red.
SCHEME_GREENS	'greens'	Sequential		Single-hue gradient ranging from light to forest green.
SCHEME_PURPLES	'purples'	Sequential		Single-hue gradient ranging from lavender to deep purple.
SCHEME_ORANGES	'oranges'	Sequential		Single-hue gradient ranging from peach to dark orange.
SCHEME_VIRIDIS	'viridis'	Perceptual		Multi-hue uniform gradient (purple to teal to yellow).
SCHEME_INFERNO	'inferno'	Perceptual		High-contrast heat gradient (black to red to yellow).
SCHEME_MAGMA	'magma'	Perceptual		Multi-hue gradient (dark violet to pink to white).
SCHEME_CATEGORY10	'category10'	Discrete		Ten distinct categorical hues for nominal dimensions.
SCHEME_TABLEAU10	'tableau10'	Discrete		Ten balanced hues for multi-series lines, slices, and groups.

---

Low-Level Specification Bridge

Graph.render()

Renders an arbitrary Vega-Lite v6 specification payload directly in the console visualization panel.

Graph.render(
  array|object|string:payload,
  string:title = 'Graph'
): void

Parameters

• payload (array|object|string, required): An associative array, object literal, or valid JSON string containing the complete Vega-Lite specification.
• title (string, optional): Header label for the output tab. Defaults to 'Graph'. If left as default, the title declared inside the specification (payload.title or payload.description) takes precedence.

Normalization & Error Behavior

1. String Input: Parsed via json_decode(). Throws \InvalidArgumentException if string is empty or contains malformed JSON syntax.
2. Object Input: Converted recursively to an associative array to isolate the engine from unexpected host references.
3. Array Input: Validated to ensure the root payload is an associative map rather than an indexed sequential list.
4. Default Injection: If missing, $schema receives DEFAULT_SCHEMA and width receives DEFAULT_WIDTH.

Example

Graph.render({
  '$schema': 'https://vega.github.io/schema/vega-lite/v6.json',
  title: 'Storage by Asset Type',
  data: {
    values: [
      { asset: 'Images', megabytes: 340 },
      { asset: 'Videos', megabytes: 820 },
      { asset: 'Documents', megabytes: 110 }
    ]
  },
  mark: { type: 'bar', color: Graph.COLOR_BLUE },
  encoding: {
    x: { field: 'asset', type: 'nominal', axis: { title: 'Asset Category' } },
    y: { field: 'megabytes', type: 'quantitative', axis: { title: 'Size (MB)' } }
  }
}, 'Storage Breakdown')

---

High-Level Chart Builders

Graph.bars()

Compiles and renders a bar chart from tabular collections or associative key-value dictionaries.

Graph.bars(
  mixed:data,
  array:options = []
): void

Parameters

• data (mixed, required): Array of associative records (such as [{ role: 'Editor', count: 12 }]) or a key-value dictionary (such as { Draft: 14, Published: 89 }).
• options (array, optional): Configuration settings.

Options Dictionary

Key	Type	Default	Description
title	string	'Bar Chart'	Visualization title and tab label.
x	string	Auto-detected	Field mapped to horizontal coordinates.
y	string	Auto-detected	Field mapped to vertical coordinates.
color	string	null	Record field used for categorical color partitioning.
color_value	string	Graph.COLOR_BLUE	Fixed hex color applied to all bars when color is omitted.
horizontal	bool	false	When true, inverts axes to render horizontal bars.
sort	string|array	null	Custom order definition for categorical dimension.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	360	Pixel height of the visualization area.

Examples

Vertical Category Breakdown

Graph.bars([
  { role: 'Administrator', users: 4 },
  { role: 'Editor', users: 12 },
  { role: 'Author', users: 28 },
  { role: 'Contributor', users: 45 },
  { role: 'Subscriber', users: 190 }
], {
  title: 'Active Users by Role',
  color_value: Graph.COLOR_PURPLE
})

Horizontal Layout from Key-Value Map

Graph.bars({
  'Draft': 14,
  'Pending': 6,
  'Private': 3,
  'Published': 89
}, {
  title: 'Post Inventory by Status',
  horizontal: true,
  color_value: Graph.COLOR_BLUE
})

---

Graph.lines()

Renders continuous trend lines and multi-series time comparisons.

Graph.lines(
  mixed:data,
  array:options = []
): void

Options Dictionary

Key	Type	Default	Description
title	string	'Line Chart'	Visualization title.
x	string	Auto-detected	Field mapped to horizontal coordinates.
y	string	Auto-detected	Field mapped to vertical coordinates.
color	string	null	Field used for multi-series color grouping.
color_value	string	Graph.COLOR_BLUE	Fixed hex color for single series.
points	bool	true	Renders discrete circular vertex markers along paths.
sort	string|array	null	Sorting specification for horizontal coordinate axis.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	360	Pixel height of the visualization area.

Example

Graph.lines([
  { month: '2026-01', volume: 1420 },
  { month: '2026-02', volume: 1890 },
  { month: '2026-03', volume: 2400 },
  { month: '2026-04', volume: 2180 },
  { month: '2026-05', volume: 3050 },
  { month: '2026-06', volume: 3820 }
], {
  title: 'Monthly Network Throughput',
  color_value: Graph.COLOR_GREEN
})

---

Graph.pie()

Renders proportional arc segments for composition analysis, with optional inner cutout hole for donut charts.

Graph.pie(
  mixed:data,
  array:options = []
): void

Options Dictionary

Key	Type	Default	Description
title	string	'Pie Chart' / 'Donut Chart'	Visualization title.
category	string	Auto-detected	Field containing slice categorical labels.
value	string	Auto-detected	Field containing slice numeric magnitudes.
donut	bool	false	Renders a central cutout hole when true.
inner_radius	int	65	Pixel radius of inner cutout hole when donut is active.
scheme	string	Graph.SCHEME_TABLEAU10	Vega-Lite color palette for categorical slices.
height	int	360	Pixel height of the visualization area.

Example

Graph.pie([
  { device: 'Mobile', share: 58 },
  { device: 'Desktop', share: 34 },
  { device: 'Tablet', share: 8 }
], {
  title: 'Client Traffic Share by Form Factor',
  donut: true,
  inner_radius: 75
})

---

Graph.worldmap()

Renders a two-layer offline choropleth world map projected onto an Equal Earth projection

Graph.worldmap(
  mixed:data,
  array:options = []
): void

Automatic Country Code Resolution

The method resolves country identifiers into standard TopoJSON numeric geometry IDs (id):

• ISO 3166-1 Alpha-2: 'US', 'ES', 'DE', 'FR', 'JP'. Output from IPLookup.to_country() binds directly into this method.
• ISO 3166-1 Alpha-3: 'USA', 'ESP', 'DEU', 'FRA', 'JPN'.
• Standard Country Names: 'United States', 'Germany', 'Spain'.
• Numeric TopoJSON IDs: '840', '724', '276'.

Options Dictionary

Key	Type	Default	Description
title	string	'World Map'	Visualization title.
key	string	Auto-detected	Field holding country codes or names.
value	string	Auto-detected	Field holding quantitative heat values.
label	string	null	Optional metadata field included in hover tooltips.
scheme	string	Graph.SCHEME_BLUES	Sequential color gradient scheme.
projection	string	'equalEarth'	Cartographic projection algorithm.
legend_title	string	Field Name	Custom title for the continuous color scale legend.
height	int	480	Pixel height of the map viewport.

Example

Graph.worldmap({
  'US': 1940,
  'ES': 820,
  'DE': 1150,
  'BR': 670,
  'JP': 930,
  'AU': 450,
  'CA': 610,
  'FR': 780
}, {
  title: 'Global Request Ingestion by Origin',
  scheme: Graph.SCHEME_BLUES
})

---

Graph.usa()

Renders a two-layer offline choropleth map of the United States using an Albers USA projection.

Graph.usa(
  mixed:data,
  array:options = []
): void

State Code Resolution

Normalizes state references to 2-digit FIPS strings:

• Postal Codes: 'CA', 'TX', 'NY', 'FL', 'WA'.
• State Names: 'California', 'Texas', 'New York'.
• FIPS Identifiers: '06', '48', '36', 6, 48.

Options Dictionary

Key	Type	Default	Description
title	string	'US State Map'	Visualization title.
key	string	Auto-detected	Field holding state postal codes, names, or FIPS.
value	string	Auto-detected	Field holding metric values.
label	string	null	Optional extra dimension displayed in tooltips.
scheme	string	Graph.SCHEME_BLUES	Sequential color scheme.
projection	string	'albersUsa'	Cartographic projection algorithm.
legend_title	string	Field Name	Custom legend title.
height	int	450	Pixel height of the viewport.

Example

Graph.usa({
  'CA': 1420,
  'TX': 980,
  'NY': 1150,
  'FL': 870,
  'IL': 520,
  'WA': 610,
  'CO': 430,
  'MA': 560
}, {
  title: 'Traffic Density across United States',
  scheme: Graph.SCHEME_PURPLES
})

---

Graph.boxplot()

Renders box-and-whisker distribution charts displaying medians, interquartile ranges (Q1–Q3), and min-max boundaries across categorical dimensions.

Graph.boxplot(
  mixed:data,
  array:options = []
): void

Options Dictionary

Key	Type	Default	Description
title	string	'Boxplot'	Visualization title.
x	string	Auto-detected	Categorical dimension mapped to horizontal axis.
y	string	Auto-detected	Quantitative metric mapped to vertical axis.
color	string	null	Dimension used for discrete group color encoding.
color_value	string	Graph.COLOR_BLUE	Fill color for single-series boxes.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	360	Pixel height of the visualization area.

Example

Graph.boxplot([
  { endpoint: '/api/posts', latency_ms: 42 },
  { endpoint: '/api/posts', latency_ms: 58 },
  { endpoint: '/api/posts', latency_ms: 120 },
  { endpoint: '/api/posts', latency_ms: 68 },
  { endpoint: '/api/posts', latency_ms: 95 },
  { endpoint: '/api/users', latency_ms: 85 },
  { endpoint: '/api/users', latency_ms: 92 },
  { endpoint: '/api/users', latency_ms: 240 },
  { endpoint: '/api/users', latency_ms: 110 },
  { endpoint: '/api/users', latency_ms: 135 }
], {
  title: 'Endpoint Latency Distribution',
  color_value: Graph.COLOR_BLUE
})

---

Graph.scatter()

Renders scatter and bubble plots for multi-dimensional correlation analysis between quantitative variables.

Graph.scatter(
  mixed:data,
  array:options = []
): void

Options Dictionary

Key	Type	Default	Description
title	string	'Scatter Plot'	Visualization title.
x	string	Auto-detected	Quantitative field for horizontal coordinates.
y	string	Auto-detected	Quantitative field for vertical coordinates.
color	string	null	Field for discrete color grouping or literal hex color code.
size	string|int|float	null	Field mapped to point area or fixed marker size in square pixels.
opacity	float	0.7	Marker fill opacity between 0.0 and 1.0.
zero	bool	false	When false, scales axes to data extents rather than forcing zero baseline.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	360	Pixel height of the visualization area.

Example

Graph.scatter([
  { queries: 6,   duration_ms: 18,  rows: 85,    status: 'ok' },
  { queries: 12,  duration_ms: 28,  rows: 240,   status: 'ok' },
  { queries: 16,  duration_ms: 35,  rows: 410,   status: 'ok' },
  { queries: 22,  duration_ms: 52,  rows: 620,   status: 'ok' },
  { queries: 32,  duration_ms: 70,  rows: 880,   status: 'ok' },
  { queries: 45,  duration_ms: 135, rows: 2800,  status: 'warning' },
  { queries: 58,  duration_ms: 145, rows: 3100,  status: 'warning' },
  { queries: 72,  duration_ms: 230, rows: 6800,  status: 'warning' },
  { queries: 90,  duration_ms: 360, rows: 12500, status: 'critical' },
  { queries: 116, duration_ms: 560, rows: 31000, status: 'critical' }
], {
  title: 'Database Queries vs Execution Duration',
  x: 'queries',
  y: 'duration_ms',
  color: 'status',
  size: 'rows',
  opacity: 0.75,
  zero: false
})

---

Graph.heatmap()

Renders a two-dimensional grid heatmap mapping categorical or ordinal coordinates to color-intensity values.

Graph.heatmap(
  mixed:data,
  array:options = []
): void

Options Dictionary

Key	Type	Default	Description
title	string	'Heatmap'	Visualization title.
x	string	Auto-detected	Field mapped to horizontal column cells.
y	string	Auto-detected	Field mapped to vertical row cells.
value	string	Auto-detected	Metric mapped to cell color intensity.
scheme	string	Graph.SCHEME_BLUES	Sequential color palette for cell heat.
stroke	string	'#ffffff'	Grid separation line color.
legend_title	string	Field Name	Custom legend title.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	360	Pixel height of the visualization area.

Example

Graph.heatmap([
    { 'day': 'Mon', 'hour': 9,  'events': 50 },
    { 'day': 'Mon', 'hour': 10, 'events': 320 },
    { 'day': 'Mon', 'hour': 11, 'events': 25 },
    { 'day': 'Mon', 'hour': 12, 'events': 250 },
    { 'day': 'Mon', 'hour': 13, 'events': 195 },
    { 'day': 'Mon', 'hour': 14, 'events': 331 },
    { 'day': 'Mon', 'hour': 15, 'events': 80 },
    { 'day': 'Tue', 'hour': 9,  'events': 190 },
    { 'day': 'Tue', 'hour': 10, 'events': 78 },
    { 'day': 'Tue', 'hour': 11, 'events': 22 },
    { 'day': 'Tue', 'hour': 12, 'events': 25 },
    { 'day': 'Tue', 'hour': 13, 'events': 250 },
    { 'day': 'Tue', 'hour': 14, 'events': 410 },
    { 'day': 'Tue', 'hour': 15, 'events': 295 },
    { 'day': 'Wed', 'hour': 9,  'events': 190 },
    { 'day': 'Wed', 'hour': 10, 'events': 46 },
    { 'day': 'Wed', 'hour': 11, 'events': 101 },
    { 'day': 'Wed', 'hour': 12, 'events': 610 },
    { 'day': 'Wed', 'hour': 13, 'events': 710 },
    { 'day': 'Wed', 'hour': 14, 'events': 155 },
    { 'day': 'Wed', 'hour': 15, 'events': 25 }
], {
    'title': 'System Events by Day and Hour',
    'x': 'hour',
    'y': 'day',
    'value': 'events',
    'height' : 180,
    'scheme': Graph.SCHEME_PURPLES
})

---

Graph.histogram()

Partitions continuous quantitative measurements into discrete interval bins and calculates distribution counts.

Graph.histogram(
  mixed:data,
  array:options = []
): void

Input Modes

• Numeric Scalar Array: List of raw floats or integers (such as query runtimes or latencies).
• Tabular Records: Objects containing a targeted numeric metric column.

Options Dictionary

Key	Type	Default	Description
title	string	'Histogram'	Visualization title.
field	string	Auto-detected	Numeric field to partition into bins.
bins	int	20	Target maximum bin intervals.
maxbins	int	null	Upper constraint on generated bin count.
step	float	null	Fixed interval width for bin steps.
color	string	Graph.COLOR_BLUE	Categorical color partition or fixed color code.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	360	Pixel height of the visualization area.

Example

Graph.histogram([
  12.4, 15.1, 18.3, 19.0, 21.2, 22.8, 23.1, 28.5, 34.2, 45.0,
  18.1, 21.9, 23.4, 25.0, 27.2, 31.8, 35.1, 38.5, 42.2, 49.0
], {
  title: 'Query Duration Distribution (ms)',
  bins: 8,
  color: Graph.COLOR_CYAN
})

---

Graph.area()

Renders filled area charts for cumulative volume tracking, stacked multi-series infrastructure metrics, streamgraphs, and 100% normalized proportions.

Graph.area(
  mixed:data,
  array:options = []
): void

Options Dictionary

Key	Type	Default	Description
title	string	'Area Chart'	Visualization title.
x	string	Auto-detected	Field mapped to horizontal coordinates.
y	string	Auto-detected	Field mapped to vertical coordinates.
color	string	null	Field used for multi-series color grouping.
color_value	string	Graph.COLOR_BLUE	Fixed hex color for single series.
stream	bool	false	Centers vertical stack around middle baseline to form a streamgraph.
normalize	bool	false	Scales stack to 100% relative proportions.
curve	string	'monotone'	Path interpolation mode ('monotone', 'basis', 'linear').
opacity	float	0.6	Fill opacity between 0.0 and 1.0.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	360	Pixel height of the visualization area.

Example

Graph.area([
  { date: '2026-09-01', traffic_gb: 320, tier: 'CDN Cache' },
  { date: '2026-09-01', traffic_gb: 180, tier: 'Application Server' },
  { date: '2026-09-02', traffic_gb: 410, tier: 'CDN Cache' },
  { date: '2026-09-02', traffic_gb: 240, tier: 'Application Server' },
  { date: '2026-09-03', traffic_gb: 490, tier: 'CDN Cache' },
  { date: '2026-09-03', traffic_gb: 290, tier: 'Application Server' },
  { date: '2026-09-04', traffic_gb: 380, tier: 'CDN Cache' },
  { date: '2026-09-04', traffic_gb: 220, tier: 'Application Server' }
], {
  title: 'Network Egress Volume by Tier',
  x: 'date',
  y: 'traffic_gb',
  color: 'tier'
})

---

Graph.timeline()

Renders horizontal Gantt interval timeline bars for execution profiles, request tracing, and scheduled events.

Graph.timeline(
  mixed:data,
  array:options = []
): void

Options Dictionary

Key	Type	Default	Description
title	string	'Timeline'	Visualization title.
task	string	Auto-detected	Field containing task name or lane identifier (vertical axis).
start	string	Auto-detected	Field containing start timestamp or numeric millisecond offset.
end	string	Auto-detected	Field containing end timestamp or completion offset.
color	string	Graph.COLOR_BLUE	Field for category color encoding, or fixed color code.
label_angle	int	-45	Rotation angle in degrees for axis labels.
height	int	Auto-calculated	Pixel height of the visualization area.

Example

Graph.timeline([
  { task: 'Authentication & Session', start: 0,   end: 35 },
  { task: 'Database Query Pipeline',  start: 25,  end: 95 },
  { task: 'Object Cache Lookup',      start: 40,  end: 75 },
  { task: 'Template Rendering',       start: 90,  end: 180 },
  { task: 'Output Buffer Flush',      start: 175, end: 210 }
], {
  title: 'Request Lifecycle Execution Breakdown',
  color: Graph.COLOR_BLUE
})