interactive

module src.interactive

Interactive visualization module using Plotly.

This module generates interactive HTML figures from study quality measurements, suitable for embedding in static web reports.

Global Variables

• METRIC_DIRECTIONS
• FORMAT_COLORS
• METRIC_LABELS
• PLOTLY_MARKERS

---

function plot_quality_vs_param

plot_quality_vs_param(
    stats: DataFrame,
    x_param: str,
    metric: str,
    title: str | None = None
) → Figure

Create interactive quality metric vs parameter plot.

Args:

• stats: Statistics DataFrame from compute_statistics
• x_param: Parameter for x-axis (grouping column or _mean statistic)
• metric: Quality metric to plot (e.g., ‘ssimulacra2’)
• title: Optional custom title

Returns: Plotly Figure object

---

function plot_rate_distortion

plot_rate_distortion(
    stats: DataFrame,
    metric: str,
    grouping_param: str | None,
    title: str | None = None,
    primary_param: str | None = None
) → Figure

Create interactive rate-distortion plot (quality vs bits per pixel).

Args:

• stats: Statistics DataFrame from compute_statistics
• metric: Quality metric (e.g., ‘ssimulacra2’)
• grouping_param: Parameter to group lines by (e.g., ‘format’)
• title: Optional custom title
• primary_param: Primary sweep parameter to sort points by (e.g., ‘quality’, ‘speed’). When provided, points within each group are connected in the order of this parameter rather than by bits_per_pixel, giving a meaningful line for non-monotonic sweeps such as speed or effort settings.

Returns: Plotly Figure object

---

function plot_bits_per_pixel

plot_bits_per_pixel(
    stats: DataFrame,
    x_param: str,
    title: str | None = None
) → Figure

Create interactive bits per pixel plot with percentile bands.

Args:

• stats: Statistics DataFrame
• x_param: Parameter for x-axis
• title: Optional custom title

Returns: Plotly Figure object

---

function plot_encoding_time_per_pixel

plot_encoding_time_per_pixel(
    stats: DataFrame,
    x_param: str,
    title: str | None = None
) → Figure

Create interactive encoding time per pixel plot with percentile bands.

Automatically uses logarithmic scale if the dynamic range is large (>10x).

Args:

• stats: Statistics DataFrame
• x_param: Parameter for x-axis
• title: Optional custom title

Returns: Plotly Figure object

---

function plot_efficiency

plot_efficiency(
    stats: DataFrame,
    x_param: str,
    efficiency_metric: str,
    title: str | None = None
) → Figure

Create interactive efficiency metric plot.

Args:

• stats: Statistics DataFrame
• x_param: Parameter for x-axis
• efficiency_metric: Efficiency metric name
• title: Optional custom title

Returns: Plotly Figure object

---

function figure_to_html_fragment

figure_to_html_fragment(fig: Figure) → str

Convert a Plotly figure to an HTML fragment (no plotly.js included).

The fragment contains the

and

Args:

• fig: Plotly Figure object

Returns: HTML string fragment

---

function generate_study_figures

generate_study_figures(
    quality_json_path: str | Path,
    study_config_path: Path | None = None
) → dict[str, Figure]

Generate all interactive figures for a study.

This is the main entry point that mirrors analyze_study() but produces Plotly figures instead of saving matplotlib images.

Axis resolution uses the same shared helper (:func:~src.analysis.resolve_axis_parameters) as the static SVG analysis so that the interactive report matches exactly.

Args:

• quality_json_path: Path to quality.json file
• study_config_path: Optional path to the study configuration JSON file. analysis.x_axis / analysis.group_by are read from it when present.

Returns: Dictionary mapping figure names to Plotly Figure objects