FAQ and Troubleshooting

FAQ and Troubleshooting

Common questions and edge cases. See also Data Requirements and Type Detection and Configuration.

Loading data

A column disappeared after loading. Columns that are entirely NaN/None are dropped, and columns with raw array/ndarray cells are dropped unless you declare them as list_columns. The load report lists exactly what was removed (unless gp.suppress_warnings = True). See Data Requirements and Type Detection.

My data has some nulls — are those rows dropped? No. Rows with nulls are kept; nulls are skipped per-axis at render time. The per-column null counts are reported, and the config dropdowns label such columns name (N missing).

A numeric column is being treated as a label (or vice-versa). Numeric columns with ID-like names (JOB_ID, *_GENID, bare id/uid/uuid) are classified categorical; small-integer or low-cardinality numerics become ordinal. To force categorical, pass categorical_columns=[...]. See the detection rules in Data Requirements and Type Detection.

My YYYYMMDD integer column shows up as a number, not a date (or vice-versa). Integer columns encoding YYYYMMDD (e.g. 20241231) are auto-converted to datetimes when every value is a valid calendar date in 19000101–21001231. If even one value falls outside that range or isn't a real date, the whole column stays numeric. To keep such a column categorical instead, list it in categorical_columns.

"Your dataframe is very large…" warning. Guidepost warns above 250,000 rows. Aggregation still works but interactions may lag; consider subsampling toward < 200k rows:

gp.records = df.sample(n=150_000, random_state=42)

Configuration & views

The bar chart says "Categorical: n/a". No categorical variable is mapped (or the synthetic "no grouping" column fills that role). Pick a real categorical column in the categorical dropdown, or set it in vis_configs. See Configuration.

Only one group / panel appears. That happens when facet_by is the synthetic n/a column — i.e. your data lacks a second categorical column. Provide a real grouping column to split into multiple panels. See Understanding the Views.

Some categories or facet groups are missing from the chart. High-cardinality categorical x-axes are capped (a red "Showing top N of M categories" note appears), the categorical bar chart shows only the top 10, and very large numbers of facet groups are limited to the largest, with a note. Filter your input DataFrame to focus on the rest. (List x-axes keep all values via grouping — see Main Summary View Heatmap.)

A facet panel says "There are too few datapoints in this category." That group doesn't have enough rows to build a grid. Filter it out of the source DataFrame if you don't need it.

Selection & export

retrieve_selected_data() / gp.selection.dataframe is empty. Nothing is currently selected. Brush the histograms or heatmap, pin columns/cells, or brush the color legend first. Remember selections are per panel — see Selecting and Exporting Data.

Calling retrieve_selected_data() raised ValueError. No data has been loaded yet. Call load_data() (or set gp.records) first.

My selection doesn't carry across facet groups. By design. Selections apply to the panel you act in; build them up across panels and the exported DataFrame is the combined set. Only configuration changes apply to all panels at once.

Node-list (list column) specifics

My node names aren't grouped/ordered the way I expect. When list values look like structured hardware names (e.g. Cray x1008c0s0b1n1), Guidepost orders them by that structure. If names don't parse uniformly, it falls back to ordering by co-occurrence instead. Mixed conventions reduce to the co-occurrence fallback. See Main Summary View Heatmap.

Datetime comparisons look off by a timezone. Datetime handling is UTC-based end to end. Make sure your input datetimes are UTC-aware or naive-UTC to avoid surprises.

---

See also: API Reference · Getting Started · Home