API Reference

API Reference

The Python surface of Guidepost. For conceptual guides see Getting Started, Configuration, and Selecting and Exporting Data.

from guidepost import Guidepost, Trailmark

class Guidepost

The interactive visualization widget. Construct it, give it a DataFrame, configure the encoding, display it in a notebook, and read back the selection.

Constructor

Guidepost(
    records=None,             # pandas DataFrame to load immediately (optional)
    list_columns=None,        # list[str]: columns whose cells hold multiple values
    list_delimiter=',',       # str: separator for splitting delimited list cells
    categorical_columns=None, # list[str]: force these columns to be categorical
)

Argument	Type	Description
records	pd.DataFrame	If given, loaded immediately (equivalent to setting gp.records = df).
list_columns	list[str]	Columns whose cells contain multiple values (lists, stringified lists, or delimited strings). Parsed and exploded. See Data Requirements and Type Detection.
list_delimiter	str	Separator used to split delimited-string list cells (e.g. "a,b,c"). Default ','.
categorical_columns	list[str]	Columns to classify as categorical even if numeric — for identifiers the name heuristic misses, or to override an unwanted auto-classification.

suppress_warnings is a plain attribute (default False), not a constructor argument. To silence the load report, set gp.suppress_warnings = True before calling load_data.

Properties

Property	Type	Description
records	—	Setter accepts a pd.DataFrame and loads it (calls load_data). The getter returns the internal serialized form, not your DataFrame — use selection/retrieve_selected_data to get data back.
vis_configs	dict	The column-to-role mapping (x, y, color, color_agg, categorical, facet_by). Assigning it re-renders the widget. See Configuration.
selection	Selection	The current selection as a wrapper object; the DataFrame is on .dataframe. See Selecting and Exporting Data.
suppress_warnings	bool	Set to True to silence the data-load report.

Methods

load_data(in_df)

Validates, cleans, classifies, and loads a DataFrame, returning the serialized payload and refreshing the widget if displayed. Prints a report of any dropped/converted columns unless suppress_warnings is True. Takes only the DataFrame — there is no suppress_warnings parameter; set the attribute instead.

gp.load_data(df)            # or: gp.records = df
gp.suppress_warnings = True
gp.load_data(df)            # quiet

See Data Requirements and Type Detection for the validation rules.

retrieve_selected_data()

Returns the currently-selected rows as a pd.DataFrame (original columns; the internal gp_idx column is stripped). Returns an empty DataFrame when nothing is selected; raises ValueError if no data has been loaded yet.

df = gp.retrieve_selected_data()

gp.selection.dataframe is the property-style equivalent. See Selecting and Exporting Data.

class Selection

A thin wrapper returned by gp.selection. Its only attribute is:

• dataframe — the pd.DataFrame of selected rows (same content as retrieve_selected_data()).

The wrapper exists so future selection metadata can be added without changing the gp.selection access pattern.

---

class Trailmark

A lightweight companion widget that loads a DataFrame and surfaces summary statistics only — it does not provide the interactive heatmap, brushing, or selection/export of Guidepost. Useful for a quick look at column types and distributions.

from guidepost import Trailmark

tm = Trailmark()
tm.records = df              # validates, computes summary stats

Member	Description
records (setter)	Accepts a pd.DataFrame; runs validation and computes per-column summary statistics.
load_data(in_df)	Validates/cleans the DataFrame and returns the summary-statistics dict.
vis_configs	A small dict of dataset metadata (row/column counts, type counts).
suppress_warnings	Set True to silence load warnings.

Trailmark shares the same validation and type-detection logic as Guidepost (see Data Requirements and Type Detection) but stops at summary stats.

---

Next: Selecting and Exporting Data · FAQ and Troubleshooting · Home