Configuration

Configuration

The vis_configs mapping tells Guidepost which DataFrame columns fill which roles in the chart. You can set it from Python, or change any role from the dropdown menus inside the widget. This page covers both, plus the aggregation options.

See also: Data Requirements and Type Detection (how columns are classified) and Understanding the Views (what each role drives on screen).

The vis_configs dictionary

gp.vis_configs = {
    'x':          'start_time',
    'y':          'queue_wait',
    'color':      'nodes_requested',
    'color_agg':  'avg',
    'categorical':'user',
    'facet_by':   'partition'
}

Assigning vis_configs re-renders the visualization immediately if it is already displayed.

Field	Role	Accepts	Notes
x	Heatmap x-axis	numeric, datetime, or a list column	Binned into columns. Datetime → time axis; list → exploded values with smart ordering; high-cardinality categoricals are capped (see below).
y	Heatmap y-axis	numeric	Binned into rows. Auto log scale when the range spans many orders of magnitude.
color	Cell fill	numeric	Aggregated per cell by color_agg.
color_agg	Aggregation for color	see next section	Determines what the cell color encodes.
categorical	Categorical bar chart / filter	categorical (string/object)	Top 10 values shown; hover to filter, click to pin. See Histograms Bar Chart and Legend.
facet_by	Top-level grouping	categorical (string/object)	One panel of charts per distinct value.

If facet_by is omitted and the data lacks a second categorical column, a synthetic "no grouping" column is used and shown as n/a in the dropdowns, producing a single group.

color_agg aggregations

color_agg selects how the color column is aggregated within each heatmap cell. Accepted values:

Value	Meaning
'avg'	Mean (aliases: 'mean', 'average')
'median'	Median (alias: 'med')
'min'	Minimum
'max'	Maximum
'sum'	Sum
'count'	Number of records in the cell

An unrecognized value falls back to 'avg'. Each cell also always carries its own count, min, max, avg, median, and std internally, which the framing histograms and tooltips use.

Configuring from inside the widget

You don't have to touch vis_configs in Python — every role has a dropdown rendered above the charts. Changing any dropdown recomputes scales, redraws the histograms, recomputes the heatmap, applies to all facet groups at once, and persists the choice back to the Python model.

Dropdown behavior worth knowing:

• Columns are grouped by classification in each dropdown, under these headers (empty groups are hidden): Temporal, Quantitative, Ordinal, Categorical, List. This makes it easy to pick, say, only datetime columns for x. (Classification comes from the semantic types in Data Requirements and Type Detection.)
• Columns with missing values are labeled name (N missing) so you can see data completeness while choosing.
• The synthetic no-grouping column appears as n/a — pick it to explicitly run with a single group / no categorical.
• The collapsed dropdown shows the selected option as Classification > name.

Smart defaults: on first load (or when you swap in a new dataset), Guidepost auto-selects reasonable roles. If a saved configuration references a column that no longer exists, it resets to those smart defaults rather than erroring.

---

Next: Understanding the Views · Main Summary View Heatmap · Selecting and Exporting Data