Selecting and Exporting Data

Selecting and Exporting Data

The whole point of Guidepost is to go from a visual pattern to the actual records behind it. This page explains what counts as a selection, how to read the export counter, and how to pull the selected rows back into Python as a DataFrame.

What counts as a selection

Within each facet panel, Guidepost tracks three independent selection streams and exports their union — a record is selected if any stream picks it:

1. Box brush — a rectangular region of the grid, set by the heatmap's 2D-brush mode or by the x/y framing histogram brushes. See Main Summary View Heatmap and Histograms Bar Chart and Legend.
2. Pins — columns pinned in column-pin mode, or individual cells pinned in cell-pin mode.
3. Color band — a range brushed on the color legend: cells whose aggregated color falls in that range, regardless of x/y.

Selected records are highlighted in orange on the heatmap, and the legend header shows a live count: "No. of Records Selected for Export: N" (it flashes orange when the count changes).

Selections span panels, not facets

Selections are per panel: brushing in one facet group does not mirror into the others. You can, however, build a selection across several panels at once — the exported DataFrame is the combined set of everything selected, across all panels.

Retrieving your selection in Python

After making a selection in the widget, pull it back into a pandas DataFrame. Two equivalent entry points:

# Method form:
df = gp.retrieve_selected_data()

# Property form (returns a Selection wrapper; the DataFrame is on .dataframe):
df = gp.selection.dataframe

Both return the selected rows from your original dataset (the internal gp_idx tracking column is stripped out). With nothing selected you get an empty DataFrame; calling before any data is loaded raises a ValueError.

df = gp.selection.dataframe
print(f"Selected {len(df)} records")
df.head()

Why gp.selection is an object. gp.selection returns a small Selection wrapper whose .dataframe attribute holds the DataFrame. The indirection leaves room to attach more selection metadata in the future without changing how you access the data. If you prefer a bare DataFrame, use gp.retrieve_selected_data().

Typical workflow

from guidepost import Guidepost
import pandas as pd

gp = Guidepost(records=pd.read_parquet("jobs.parquet"))
gp.vis_configs = {
    'x': 'start_time', 'y': 'queue_wait', 'color': 'nodes_requested',
    'color_agg': 'avg', 'categorical': 'user', 'facet_by': 'partition'
}
gp   # display, then brush/pin in the widget

# ...after selecting in the UI:
selected = gp.selection.dataframe
selected.to_parquet("selected_jobs.parquet")

The values update each time you read them, reflecting the current selection in the widget.

---

Next: API Reference · Understanding the Views · FAQ and Troubleshooting