suboptimumg.loganalysis.track_builder#

Build QSS-compatible Track objects from processed lap DataFrames.

suboptimumg.loganalysis.track_builder.build_comparison_df(lapsim_results, track, lap_df, log_columns=None, dist_col='LapDist')[source]#

Merge QSS results and resampled log data into one DataFrame.

The result is indexed by distance and contains both qss.* columns and the original log column names side by side.

Parameters:

  • lapsim_results (LapsimResults)

  • track (Track)

  • lap_df (pd.DataFrame)

  • log_columns (list[str] | None)

  • dist_col (str)

Return type:

pd.DataFrame

suboptimumg.loganalysis.track_builder.build_qss_track(lap_df, dx=0.1, curvature_col='body.curvature', velocity_col='groundSpeed', pos_n_col='posN', pos_e_col='posE', dist_col='LapDist', cutoff_freq=0.18, max_radius=300.0, show_plots=False)[source]#

Build a QSS-compatible Track from a trimmed lap DataFrame.

Pipeline: resample to uniform dx -> FFT spatial low-pass on curvature -> convert to absolute radius -> fit B-spline on XY -> construct Track.

Parameters:

  • lap_df (DataFrame) – Single-lap DataFrame from split_laps() (must have dist_col, curvature_col, velocity_col, position cols).

  • dx (float) – Distance step in meters (default 0.1).

  • cutoff_freq (float) – Spatial frequency cutoff for curvature filter (1/m).

  • max_radius (float) – Radius clamp for near-straight segments.

  • show_plots (bool) – If True, display verification plots.

  • curvature_col (str)

  • velocity_col (str)

  • pos_n_col (str)

  • pos_e_col (str)

  • dist_col (str)

Return type:

Track

suboptimumg.loganalysis.track_builder.filter_curvature_spatial(distance, curvature, cutoff_freq=0.18)[source]#

FFT low-pass filter on curvature in the spatial-frequency domain.

Parameters:

  • distance (ndarray) – Uniform distance grid (m).

  • curvature (ndarray) – Curvature (1/m) on the same grid.

  • cutoff_freq (float) – Cutoff spatial frequency in 1/m.

Returns:

Filtered curvature array (same length).

Return type:

ndarray

suboptimumg.loganalysis.track_builder.plot_comparison_trace(laps, variable='groundSpeed', qss_df=None, baseline='fastest', dist_col='LapDist', vel_col='groundSpeed', units='m/s', dx=0.1)[source]#

Multi-lap comparison trace with cumulative time-delta subplot.

Parameters:

  • laps (dict[label, DataFrame]) – Trimmed lap DataFrames from split_laps().

  • variable (str) – Column to plot on the top subplot (log-world name).

  • qss_df (DataFrame or None) – If provided, the QSS series is included. Column names are auto-resolved via LOG_TO_QSS.

  • baseline (str or int) – Reference for time delta. "fastest" picks the lap with the shortest LapTime. "first" / "last" use positional order. "qss" uses the QSS as baseline. An explicit key selects that lap.

  • vel_col (str) – Velocity column used for time-delta computation (log-world name, auto-resolved for QSS).

  • dist_col (str)

  • units (str)

  • dx (float)

Return type:

Figure

suboptimumg.loganalysis.track_builder.plot_heatmap(baseline_df, comparison_df, variable='groundSpeed', baseline_label='Baseline', comparison_label='Comparison', pos_cols=('posN', 'posE'), dist_col='LapDist', units='m/s', dx=0.1)[source]#

3-panel 2D track heatmap comparing any two DataFrames.

Works for lap-vs-lap or lap-vs-QSS. Column names are auto-resolved via LOG_TO_QSS so the caller always uses log-world names (e.g. "groundSpeed").

Parameters:

  • baseline_df (DataFrame) – Any two lap DataFrames, or a lap and a qss_df.

  • comparison_df (DataFrame) – Any two lap DataFrames, or a lap and a qss_df.

  • variable (str) – Column to compare (log-world name).

  • pos_cols ((north_col, east_col)) – Position columns (log-world names).

  • units (str) – Label for colorbars and hover.

  • dx (float) – Resample step when the two DataFrames are on different grids.

  • baseline_label (str)

  • comparison_label (str)

  • dist_col (str)

Return type:

Figure

suboptimumg.loganalysis.track_builder.plot_velocity_heatmap(comp_df, track, log_vel_col='groundSpeed', qss_vel_col='qss.velocity')[source]#

3-panel velocity heatmap (IRL vs QSS).

Thin wrapper around plot_heatmap() for backward compatibility.

Parameters:

  • comp_df (DataFrame)

  • track (Track)

  • log_vel_col (str)

  • qss_vel_col (str)

Return type:

Figure

suboptimumg.loganalysis.track_builder.plot_velocity_trace(comp_df, log_vel_col='groundSpeed', qss_vel_col='qss.velocity')[source]#

F1-style velocity trace (IRL vs QSS).

Thin wrapper around plot_comparison_trace() for backward compatibility.

Parameters:

  • comp_df (DataFrame)

  • log_vel_col (str)

  • qss_vel_col (str)

Return type:

Figure

suboptimumg.loganalysis.track_builder.qss_results_to_dataframe(lapsim_results, track)[source]#

Convert QSS lapsim output arrays into a distance-indexed DataFrame.

Columns use a qss. prefix so they sit cleanly alongside log columns in a merged comparison DataFrame. Includes position columns (qss.posN, qss.posE) from the track.

Parameters:
Return type:

pd.DataFrame

suboptimumg.loganalysis.track_builder.resample_lap_to_distance(lap_df, dx=0.1, curvature_col='body.curvature', velocity_col='groundSpeed', pos_n_col='posN', pos_e_col='posE', dist_col='LapDist')[source]#

Resample a trimmed lap DataFrame to a uniform distance grid.

Parameters:

  • lap_df (DataFrame) – A single-lap DataFrame produced by split_laps(), which must contain dist_col, curvature_col, velocity_col, pos_n_col, and pos_e_col.

  • dx (float) – Distance step in meters.

  • curvature_col (str)

  • velocity_col (str)

  • pos_n_col (str)

  • pos_e_col (str)

  • dist_col (str)

Returns:

Keys: distance, velocity, curvature, x_m, y_m.

Return type:

dict

suboptimumg.loganalysis.track_builder.resample_log_to_distance(lap_df, distance_grid, columns=None, dist_col='LapDist')[source]#

Resample selected log columns onto a QSS distance grid.

Uses linear interpolation via numpy.interp().

Parameters:

  • lap_df (DataFrame) – Trimmed single-lap DataFrame.

  • distance_grid (ndarray) – Target distance array (from a built Track).

  • columns (list[str] or None) – Columns to resample. If None, uses all non-None values from QSS_TO_LOG.

  • dist_col (str) – Distance column in lap_df.

Return type:

DataFrame