Skip to main content

​
Overview

The visualize_results module generates a comprehensive suite of publication-ready plots from evaluation results, including error analysis, confidence validation, runtime comparison, resource usage, and before/after signal overlays.

​
Functions

​
generate_plots

generate_plots(
    results_csv: str = RESULTS_CSV,
    plots_dir: str = PLOTS_DIR,
)
Generate all evaluation plots from results CSV.
​
results_csv
str
default:"evaluation/results/results.csv"
Path to the results CSV generated by run_batch.
​
plots_dir
str
default:"evaluation/plots"
Output directory for generated plots.
Output Files:
  1. error_vs_offset.png - Grouped bar chart of MAE per true offset
  2. confidence_vs_error.png - Scatter plot with regression lines
  3. audio_video_diff_histogram.png - Distribution of cross-method differences
  4. runtime_comparison.png - Mean runtime per method
  5. error_distribution_boxplot.png - Boxplots with individual points
  6. resource_usage.png - CPU and memory usage comparison
  7. before_after/*.png - Motion signal overlays per test case
  8. timelines/*.png - Sync timeline diagrams per test case

​
Plot Functions

​
plot_error_vs_offset

plot_error_vs_offset(df: pd.DataFrame, output_dir: str)
Grouped bar chart of MAE per true offset, split by method.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where the plot will be saved.
Output: error_vs_offset.png

​
plot_confidence_vs_error

plot_confidence_vs_error(df: pd.DataFrame, output_dir: str)
Scatter plot of confidence vs absolute error with regression line per method.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where the plot will be saved.
Output: confidence_vs_error.png Features:
  • Scatter points colored by method
  • Linear regression line per method
  • Pearson correlation coefficient annotations

​
plot_audio_video_diff_histogram

plot_audio_video_diff_histogram(df: pd.DataFrame, output_dir: str)
Histogram of |audio_estimate − video_estimate| per test case.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where the plot will be saved.
Output: audio_video_diff_histogram.png Features:
  • Vertical lines for mean and median differences
  • Legend showing numerical values

​
plot_runtime_comparison

plot_runtime_comparison(df: pd.DataFrame, output_dir: str)
Bar chart of mean runtime per method with standard deviation error bars.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where the plot will be saved.
Output: runtime_comparison.png Features:
  • Error bars showing standard deviation
  • Value labels on bars

​
plot_error_distribution

plot_error_distribution(df: pd.DataFrame, output_dir: str)
Side-by-side boxplots of absolute error grouped by true offset and method.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where the plot will be saved.
Output: error_distribution_boxplot.png Features:
  • Boxplots with median lines
  • Individual data points overlaid with jitter
  • No outlier markers (all points shown)

​
plot_resource_usage

plot_resource_usage(df: pd.DataFrame, output_dir: str)
Dual bar chart comparing peak CPU% and peak memory between methods.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where the plot will be saved.
Output: resource_usage.png Features:
  • Two subplots: CPU and memory
  • Error bars showing standard deviation
  • Value labels formatted appropriately

​
plot_motion_before_after

plot_motion_before_after(
    df: pd.DataFrame,
    output_dir: str,
    diagnostics_dir: str = DIAGNOSTICS_DIR,
)
For each NPZ in diagnostics, plot the original and synthetic motion signals before and after alignment.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where plots will be saved.
​
diagnostics_dir
str
default:"evaluation/diagnostics"
Directory containing NPZ diagnostic files from run_batch.
Output: before_after/*.png (one per test case) Features:
  • Two subplots per case: before and after alignment
  • Time-aligned x-axes
  • Color-coded signals

​
plot_sync_timelines

plot_sync_timelines(df: pd.DataFrame, output_dir: str)
For each video_id, produce a timeline diagram showing original and synthetic bars with offset arrows.
​
df
pd.DataFrame
Results dataframe.
​
output_dir
str
Directory where timelines will be saved.
Output: timelines/*.png (one per test case) Features:
  • Horizontal bars for original and synthetic videos
  • Arrows showing true offset (solid) and estimated offsets (dashed)
  • Annotations for padding/trimming actions
  • Zero reference line

​
Helper Functions

​
_apply_style

_apply_style()
Apply a clean, publication-ready matplotlib style. Style Features:
  • Sans-serif font family
  • Light gray background (#FAFAFA)
  • Grid with dashed lines
  • No top/right spines
  • Consistent sizing

​
Usage Example

import logging
from evaluation.visualize_results import generate_plots

logging.basicConfig(level=logging.INFO)

# Generate all plots
generate_plots(
    results_csv="evaluation/results/results.csv",
    plots_dir="evaluation/plots",
)

​
CLI Usage

python -m evaluation.visualize_results
Generates all plots using default paths.

​
Configuration

​
Default Paths

BASE_DIR = os.path.dirname(os.path.abspath(__file__))
RESULTS_CSV = os.path.join(BASE_DIR, "results", "results.csv")
PLOTS_DIR = os.path.join(BASE_DIR, "plots")
DIAGNOSTICS_DIR = os.path.join(BASE_DIR, "diagnostics")

​
Styling Constants

COLORS = {"audio": "#2196F3", "visual": "#FF9800"}
DPI = 300
FIGSIZE_WIDE = (10, 5)
FIGSIZE_SQUARE = (7, 6)

​
Matplotlib Backend

matplotlib.use("Agg")  # Non-interactive backend for script execution

​
1. Error vs Offset

Grouped bar chart comparing audio and visual MAE across different offset magnitudes. Useful for identifying which offsets are more challenging for each method.

​
2. Confidence vs Error

Scatter plot with regression lines showing the relationship between confidence scores and synchronization errors. Negative correlation indicates confidence is a useful quality indicator.

​
3. Audio-Video Difference Histogram

Distribution of differences between audio and visual estimates. Narrow distribution indicates good cross-method agreement.

​
4. Runtime Comparison

Direct comparison of mean execution time between audio and visual methods, with error bars showing variability.

​
5. Error Distribution Boxplot

Comprehensive view of error distributions across all offsets, showing median, quartiles, and individual data points.

​
6. Resource Usage

Side-by-side comparison of CPU and memory consumption, helping identify computational bottlenecks.

​
7. Motion Before/After

Per-case visualization of motion signals before and after alignment, demonstrating the visual sync algorithm’s effectiveness.

​
8. Sync Timelines

Timeline diagrams showing video bars, true offset, and estimated offsets as arrows. Provides intuitive visualization of synchronization results.

​
Notes

  • High Resolution: All plots saved at 300 DPI for publication quality.
  • Color Consistency: Audio = blue (#2196F3), Visual = orange (#FF9800) across all plots.
  • Batch Output: Generates dozens of plots in a single run for comprehensive analysis.
  • Non-Interactive: Uses Agg backend, safe for headless/script execution.
  • Graceful Degradation: Skips plots gracefully if required data is missing (e.g., resource metrics, diagnostics).

Build docs developers (and LLMs) love

Get started for freeTalk to us