viz

nomad.stop_detection.viz.animate_stop_dashboard(data, stops=None, interval=100, ping_color='black', ping_cmap=None, stop_cmap='Reds', ping_size=6, base_geometry=None, base_geom_color='#2c353c', base_geom_background='#0e0e0e', data_crs=None, traj_cols=None, show_path=False, show_stop_overlays=False, figsize=(10, 8), ax_map=None, ax_barcode=None, **kwargs)[source]

Animate pings over space with a synchronized time barcode below.

nomad.stop_detection.viz.clip_spatial_outliers(data, lower_quantile=0.01, upper_quantile=0.99, traj_cols=None, **kwargs)[source]

Remove spatial outliers using quantile-based clipping.

Parameters:

  • data (pandas.DataFrame or GeoDataFrame) – Data with spatial columns.

  • lower_quantile (float, default 0.01) – Lower quantile threshold (0-1).

  • upper_quantile (float, default 0.99) – Upper quantile threshold (0-1).

  • traj_cols (dict, optional) – Column mappings.

  • **kwargs (dict) – Additional column mappings (e.g., latitude=’lat’).

Returns:

Data with spatial outliers removed.

Return type:

DataFrame or GeoDataFrame

nomad.stop_detection.viz.h3_cell_to_polygon(cell)[source]

Return shapely Polygon for H3 cell (lon/lat).

nomad.stop_detection.viz.plot_circles(data, ax, radius=None, diameter=None, color=None, edgecolor=None, cmap=None, alpha=0.75, linewidth=None, base_geometry=None, base_geom_color='#2c353c', base_geom_background='#0e0e0e', data_crs=None, traj_cols=None, **kwargs)[source]

Plot buffered circles. Automatically projects geographic coordinates to Mercator.

Parameters:

  • data (pandas.DataFrame or GeoDataFrame) – Data with spatial columns.

  • ax (matplotlib.axes.Axes) – Axis to draw on.

  • radius (float or str, optional) – Circle radius in meters (scalar or column name).

  • diameter (float or str, optional) – Circle diameter in meters (scalar or column name).

  • color (color, str, or None, default None) – Face color. None = edge-only. ‘cluster’ requires cmap.

  • edgecolor (color, str, or None, default None) – Edge color. ‘cluster’ requires cmap.

  • cmap (str or Colormap, optional) – Colormap when coloring by integer column (e.g., ‘cluster’).

  • alpha (float, default 0.75) – Opacity.

  • linewidth (float, optional) – Edge width (auto: 2 if edge-only, 0.5 otherwise).

  • base_geometry (GeoDataFrame, optional) – Base layer underneath.

  • base_geom_color (str or column, default '#2c353c') – Base geometry color.

  • base_geom_background (color, default '#0e0e0e') – Axes background color.

  • data_crs (str or CRS, optional) – Data CRS.

  • traj_cols (dict, optional) – Column mappings.

  • **kwargs (dict) – Additional column mappings.

Return type:

matplotlib collection

nomad.stop_detection.viz.plot_hexagons(data, ax, h3_resolution=None, color=None, edgecolor=None, cmap=None, alpha=0.8, linewidth=0.75, stagger=True, base_geometry=None, base_geom_color='#2c353c', base_geom_background='#0e0e0e', data_crs=None, traj_cols=None, **kwargs)[source]

Plot H3 hexagons.

Parameters:

  • data (pandas.DataFrame or GeoDataFrame) – Data with spatial columns or location_id/h3_cell column.

  • ax (matplotlib.axes.Axes) – Axis to draw on.

  • h3_resolution (int, optional) – H3 resolution. If None, expects location_id column with H3 cells.

  • color (color, str, or None, default None) – Face color. ‘cluster’ requires cmap.

  • edgecolor (color, str, or None, default None) – Edge color. ‘cluster’ requires cmap.

  • cmap (str or Colormap, optional) – Colormap for integer columns.

  • alpha (float, default 0.8) – Opacity.

  • linewidth (float, default 0.75) – Edge width.

  • stagger (bool, default True) – Stagger duplicate hexagons concentrically.

  • base_geometry (GeoDataFrame, optional) – Base layer underneath.

  • base_geom_color (str or column, default '#2c353c') – Base geometry color.

  • base_geom_background (color, default '#0e0e0e') – Axes background.

  • data_crs (str or CRS, optional) – Target CRS (default EPSG:4326).

  • traj_cols (dict, optional) – Column mappings.

  • **kwargs (dict) – Additional column mappings.

Return type:

matplotlib collection

nomad.stop_detection.viz.plot_pings(data, ax, color='black', cmap=None, s=6, marker='o', alpha=1, base_geometry=None, base_geom_color='#2c353c', base_geom_background='#0e0e0e', data_crs=None, traj_cols=None, edgecolor=None, linewidth=0.0, **kwargs)[source]

Plot trajectory points.

Parameters:

  • data (pandas.DataFrame or GeoDataFrame) – Data with spatial columns (x/y or lon/lat).

  • ax (matplotlib.axes.Axes) – Axis to draw on.

  • color (color or str, default 'black') – Point color. Can be color string or column name. If column name and values are integers (e.g., clusters), cmap is required to map to colors.

  • cmap (str or Colormap, optional) – Colormap when color is a column with integer values.

  • s (float or array-like, default 6) – Marker size in points².

  • marker (str, default 'o') – Marker style.

  • alpha (float, default 1) – Opacity.

  • base_geometry (GeoDataFrame, optional) – Base layer to plot underneath.

  • base_geom_color (str or column name, default '#2c353c') – Color for base geometry.

  • base_geom_background (color, default '#0e0e0e') – Axes background color.

  • data_crs (str or CRS, optional) – CRS of the data.

  • traj_cols (dict, optional) – Column name mappings.

  • **kwargs (dict) – Additional column mappings.

Return type:

matplotlib collection

nomad.stop_detection.viz.plot_stops(stops, ax, radius=None, diameter=None, cmap='Reds', edge_only=False, stagger=True, base_geometry=None, base_geom_color='#2c353c', base_geom_background='#0e0e0e', data_crs=None, traj_cols=None, **kwargs)[source]

Plot stop table (circles, hexagons, or points).

Parameters:

  • stops (pandas.DataFrame or GeoDataFrame) – Stop data.

  • ax (matplotlib.axes.Axes) – Axis to draw on.

  • radius (float or str, optional) – Circle radius in meters (scalar or column name).

  • diameter (float or str, optional) – Circle diameter in meters (scalar or column name).

  • cmap (str or Colormap, default 'Reds') – Colormap for cluster coloring.

  • edge_only (bool, default False) – If True, hollow circles/hexagons (edge-only).

  • stagger (bool, default True) – Stagger duplicate hexagons.

  • base_geometry (GeoDataFrame, optional) – Base layer underneath.

  • base_geom_color (str or column, default '#2c353c') – Base geometry color.

  • base_geom_background (color, default '#0e0e0e') – Axes background.

  • data_crs (str or CRS, optional) – Data CRS.

  • traj_cols (dict, optional) – Column mappings.

  • **kwargs (dict) – Additional column mappings.

Return type:

matplotlib collection or None

nomad.stop_detection.viz.plot_stops_barcode(stops, ax, cmap='Reds', stop_color=None, set_xlim=True, stop_alpha=0.75, traj_cols=None, **kwargs)[source]

Plot colored stop intervals as bars on ax using temporal columns and colors by cluster with cmap. If set_xlim is True, auto-sets x-axis to padded range.

nomad.stop_detection.viz.plot_time_barcode(data, ax, color='black', cmap=None, current_idx=None, set_xlim=True, lw=1)[source]

Plot a barcode of timestamps on ax. Optionally highlight current_idx in red. If set_xlim is True, auto-sets x-axis to padded timestamp range.