k4bench.analysis.plots.event

k4bench.analysis.plots.event

Per-event timing and memory plots.

Both public functions delegate to the shared _plot_event_metric implementation, which differs only in which DataFrame column and axis labels are used.

plot_event_timing

plot_event_timing(source: dict[str, DataFrame] | str | Path | list[str | Path], *, labels: list[str] | None = None, baseline_label: str | None = None, show: str = 'both', bins: int | str = 'auto', alpha: float = 0.7, figsize: tuple[float, float] | None = None, outlier_threshold: float = 3.5, exclude_events: list[int] | None = None, palette: list[str] | None = None) -> Figure

Plot per-event timing distributions for one or more runs.

Single run: histogram with μ ± SEM and σ ± SE(σ) shown as an annotation. Multiple runs: overlaid histograms and, with show="both", bin-by-bin and per-event ratio panels for every non-baseline run against the reference.

Parameters:

Name	Type	Description	Default
source	dict[str, pd.DataFrame], str/Path, or list of str/Path	Pre-loaded dict from :func:~k4bench.analysis.loader.load_event_timing, a single log-dir path, or a list of log-dir paths.	required
labels	list[str] or None	Restrict to these run labels.	None
baseline_label	str or None	Reference run for the ratio panel (multi-run only).	None
show	('both', 'distribution', 'sequence')	Which panels to display.	"both"
bins	int or str	Bin specification for histograms.	'auto'
alpha	float	Histogram opacity (default: 0.7).	0.7
figsize	(width, height) or None	Figure size in inches (converted to pixels at 96 dpi).	None
outlier_threshold	float	MAD-based modified Z-score threshold for x-range clipping.	3.5
exclude_events	list[int] or None	Event numbers to exclude. Defaults to [0].	None

Returns:

Type	Description
Figure

Source code in k4bench/analysis/plots/event.py

def plot_event_timing(
    source: dict[str, pd.DataFrame] | str | Path | list[str | Path],
    *,
    labels: list[str] | None = None,
    baseline_label: str | None = None,
    show: str = "both",
    bins: int | str = "auto",
    alpha: float = 0.7,
    figsize: tuple[float, float] | None = None,
    outlier_threshold: float = 3.5,
    exclude_events: list[int] | None = None,
    palette: list[str] | None = None,
) -> go.Figure:
    """Plot per-event timing distributions for one or more runs.

    Single run: histogram with μ ± SEM and σ ± SE(σ) shown as an annotation.
    Multiple runs: overlaid histograms and, with ``show="both"``, bin-by-bin
    and per-event ratio panels for every non-baseline run against the reference.

    Parameters
    ----------
    source : dict[str, pd.DataFrame], str/Path, or list of str/Path
        Pre-loaded dict from :func:`~k4bench.analysis.loader.load_event_timing`,
        a single log-dir path, or a list of log-dir paths.
    labels : list[str] or None
        Restrict to these run labels.
    baseline_label : str or None
        Reference run for the ratio panel (multi-run only).
    show : {"both", "distribution", "sequence"}
        Which panels to display.
    bins : int or str
        Bin specification for histograms.
    alpha : float
        Histogram opacity (default: 0.7).
    figsize : (width, height) or None
        Figure size in inches (converted to pixels at 96 dpi).
    outlier_threshold : float
        MAD-based modified Z-score threshold for x-range clipping.
    exclude_events : list[int] or None
        Event numbers to exclude.  Defaults to ``[0]``.

    Returns
    -------
    plotly.graph_objects.Figure
    """
    return _plot_event_metric(
        source,
        column="event_time_s",
        xlabel="Event time (s)",
        yseq_label="Event time (s)",
        stat_prefix="μ",
        stat_unit="s",
        warn_name="plot_event_timing",
        warn_unit="s",
        labels=labels,
        baseline_label=baseline_label,
        show=show,
        bins=bins,
        alpha=alpha,
        figsize=figsize,
        outlier_threshold=outlier_threshold,
        exclude_events=exclude_events,
        palette=palette,
    )

plot_event_memory

plot_event_memory(source: dict[str, DataFrame] | str | Path | list[str | Path], *, labels: list[str] | None = None, baseline_label: str | None = None, show: str = 'both', bins: int | str = 'auto', alpha: float = 0.7, figsize: tuple[float, float] | None = None, outlier_threshold: float = 3.5, exclude_events: list[int] | None = None, palette: list[str] | None = None) -> Figure

Plot per-event memory (RSS) distributions for one or more runs.

Distribution panel shows a histogram of peak RSS per event. Sequence panel shows peak RSS vs event number.

Parameters:

Name	Type	Description	Default
source	dict[str, pd.DataFrame], str/Path, or list of str/Path	Pre-loaded dict from :func:~k4bench.analysis.loader.load_event_timing, a single log-dir path, or a list of log-dir paths.	required
labels	list[str] or None	Restrict to these run labels.	None
baseline_label	str or None	Reference run for the ratio panel (multi-run only).	None
show	('both', 'distribution', 'sequence')	Which panels to display.	"both"
bins	int or str	Bin specification for histograms.	'auto'
alpha	float	Histogram opacity (default: 0.7).	0.7
figsize	(width, height) or None	Figure size in inches (converted to pixels at 96 dpi).	None
outlier_threshold	float	MAD-based modified Z-score threshold for x-range clipping.	3.5
exclude_events	list[int] or None	Event numbers to exclude. Defaults to [0].	None

Returns:

Type	Description
Figure

Source code in k4bench/analysis/plots/event.py

def plot_event_memory(
    source: dict[str, pd.DataFrame] | str | Path | list[str | Path],
    *,
    labels: list[str] | None = None,
    baseline_label: str | None = None,
    show: str = "both",
    bins: int | str = "auto",
    alpha: float = 0.7,
    figsize: tuple[float, float] | None = None,
    outlier_threshold: float = 3.5,
    exclude_events: list[int] | None = None,
    palette: list[str] | None = None,
) -> go.Figure:
    """Plot per-event memory (RSS) distributions for one or more runs.

    Distribution panel shows a histogram of peak RSS per event.
    Sequence panel shows peak RSS vs event number.

    Parameters
    ----------
    source : dict[str, pd.DataFrame], str/Path, or list of str/Path
        Pre-loaded dict from :func:`~k4bench.analysis.loader.load_event_timing`,
        a single log-dir path, or a list of log-dir paths.
    labels : list[str] or None
        Restrict to these run labels.
    baseline_label : str or None
        Reference run for the ratio panel (multi-run only).
    show : {"both", "distribution", "sequence"}
        Which panels to display.
    bins : int or str
        Bin specification for histograms.
    alpha : float
        Histogram opacity (default: 0.7).
    figsize : (width, height) or None
        Figure size in inches (converted to pixels at 96 dpi).
    outlier_threshold : float
        MAD-based modified Z-score threshold for x-range clipping.
    exclude_events : list[int] or None
        Event numbers to exclude.  Defaults to ``[0]``.

    Returns
    -------
    plotly.graph_objects.Figure
    """
    return _plot_event_metric(
        source,
        column="rss_end_mb",
        xlabel="Peak RSS per event (MB)",
        yseq_label="Peak RSS (MB)",
        stat_prefix="μ<sub>RSS</sub>",
        stat_unit="MB",
        warn_name="plot_event_memory",
        warn_unit="MB",
        labels=labels,
        baseline_label=baseline_label,
        show=show,
        bins=bins,
        alpha=alpha,
        figsize=figsize,
        outlier_threshold=outlier_threshold,
        exclude_events=exclude_events,
        palette=palette,
    )