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.

BinCountOptions

Bases: NamedTuple

Automatic and allowed dashboard bin counts for one data selection.

event_bin_options

event_bin_options(source: dict[str, DataFrame] | str | Path | list[str | Path], *, column: str, labels: list[str] | None = None, exclude_events: list[int] | None = None, outlier_threshold: float = 3.5) -> BinCountOptions

Return automatic and sensible editable bin counts for an event metric.

The maximum is derived from the current pooled in-range sample: more bins than observations normally add no statistical resolution. If NumPy's automatic rule itself chooses more, that exact automatic count remains selectable. The renderer ceiling remains the absolute upper bound.

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

def event_bin_options(
    source: dict[str, pd.DataFrame] | str | Path | list[str | Path],
    *,
    column: str,
    labels: list[str] | None = None,
    exclude_events: list[int] | None = None,
    outlier_threshold: float = 3.5,
) -> BinCountOptions:
    """Return automatic and sensible editable bin counts for an event metric.

    The maximum is derived from the current pooled in-range sample: more bins
    than observations normally add no statistical resolution. If NumPy's
    automatic rule itself chooses more, that exact automatic count remains
    selectable. The renderer ceiling remains the absolute upper bound.
    """
    if exclude_events is None:
        exclude_events = list(_DEFAULT_EXCLUDE_EVENTS)
    all_event_data = _ensure_event_data(source)
    if labels is None:
        event_data = all_event_data
    else:
        event_data = {
            key: frame
            for key, frame in all_event_data.items()
            if key in labels or any(key.endswith(f"/{wanted}") for wanted in labels)
        }
    if not event_data:
        raise ValueError(f"No event data found for labels={labels}.")
    prepared = _prepare_event_arrays(event_data, column, exclude_events, outlier_threshold)
    automatic = len(resolve_bin_edges(prepared.clipped_all)) - 1
    maximum = min(MAX_BINS, max(automatic, len(prepared.clipped_all), 1))
    return BinCountOptions(automatic=automatic, minimum=1, maximum=maximum)

auto_bin_count

auto_bin_count(source: dict[str, DataFrame] | str | Path | list[str | Path], *, column: str, labels: list[str] | None = None, exclude_events: list[int] | None = None, outlier_threshold: float = 3.5) -> int

Return the bin count plot_event_* would choose with bins="auto".

Runs the same preparation the plotting functions do — the same event exclusions, the same outlier clipping, the same pooled range — so callers that want to offer an editable bin count can seed it with the number the figure would otherwise have used, instead of an arbitrary default that would silently rebin the plot on first render.

Parameters:

Name	Type	Description	Default
source	dict[str, pd.DataFrame], str/Path, or list of str/Path	As for :func:plot_event_timing.	required
column	str	The value column to bin, e.g. "event_time_s" or "rss_end_mb".	required
labels	list[str] or None	Restrict to these run labels.	None
exclude_events	list[int] or None	Event numbers to exclude. Defaults to [0].	None
outlier_threshold	float	MAD-based modified Z-score threshold for range clipping.	3.5

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

def auto_bin_count(
    source: dict[str, pd.DataFrame] | str | Path | list[str | Path],
    *,
    column: str,
    labels: list[str] | None = None,
    exclude_events: list[int] | None = None,
    outlier_threshold: float = 3.5,
) -> int:
    """Return the bin count ``plot_event_*`` would choose with ``bins="auto"``.

    Runs the same preparation the plotting functions do — the same event
    exclusions, the same outlier clipping, the same pooled range — so callers
    that want to offer an editable bin count can seed it with the number the
    figure would otherwise have used, instead of an arbitrary default that
    would silently rebin the plot on first render.

    Parameters
    ----------
    source : dict[str, pd.DataFrame], str/Path, or list of str/Path
        As for :func:`plot_event_timing`.
    column : str
        The value column to bin, e.g. ``"event_time_s"`` or ``"rss_end_mb"``.
    labels : list[str] or None
        Restrict to these run labels.
    exclude_events : list[int] or None
        Event numbers to exclude.  Defaults to ``[0]``.
    outlier_threshold : float
        MAD-based modified Z-score threshold for range clipping.
    """
    return event_bin_options(
        source,
        column=column,
        labels=labels,
        exclude_events=exclude_events,
        outlier_threshold=outlier_threshold,
    ).automatic

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: BinSpec = 'auto', bin_width: float | None = None, bin_origin: float | None = None, show_errors: bool = False, show_mean_lines: bool = True, 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, str, or sequence of float	Bin count, a :func:numpy.histogram_bin_edges rule name, or explicit edges covering the pooled in-range data. Edges are resolved once, so all runs and the ratio panel share exactly the same bins.	'auto'
bin_width	float or None	Fixed bin width in data units. Mutually exclusive with bins. The width and origin define a stable grid across separate figures, whereas bins="auto" derives each figure's binning from its pooled data.	None
bin_origin	float or None	Origin of the fixed-width grid. Used only with bin_width and defaults to zero.	None
show_errors	bool	Draw Poisson √N uncertainties on the bin contents.	False
show_mean_lines	bool	Draw the dashed per-run mean line on the distribution panel.	True
alpha	float	Opacity of the filled bars (default: 0.7). The step outline drawn over each histogram stays fully opaque, so lowering this fades overlapping fills without losing any distribution; alpha=0 leaves outlines only.	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: BinSpec = "auto",
    bin_width: float | None = None,
    bin_origin: float | None = None,
    show_errors: bool = False,
    show_mean_lines: bool = True,
    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, str, or sequence of float
        Bin count, a :func:`numpy.histogram_bin_edges` rule name, or explicit
        edges covering the pooled in-range data. Edges are resolved once, so all
        runs and the ratio panel share exactly the same bins.
    bin_width : float or None
        Fixed bin width in data units. Mutually exclusive with ``bins``. The
        width and origin define a stable grid across separate figures, whereas
        ``bins="auto"`` derives each figure's binning from its pooled data.
    bin_origin : float or None
        Origin of the fixed-width grid. Used only with ``bin_width`` and defaults
        to zero.
    show_errors : bool
        Draw Poisson ``√N`` uncertainties on the bin contents.
    show_mean_lines : bool
        Draw the dashed per-run mean line on the distribution panel.
    alpha : float
        Opacity of the filled bars (default: 0.7).  The step outline drawn over
        each histogram stays fully opaque, so lowering this fades overlapping
        fills without losing any distribution; ``alpha=0`` leaves outlines only.
    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,
        bin_width=bin_width,
        bin_origin=bin_origin,
        show_errors=show_errors,
        show_mean_lines=show_mean_lines,
        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: BinSpec = 'auto', bin_width: float | None = None, bin_origin: float | None = None, show_errors: bool = False, show_mean_lines: bool = True, 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, str, or sequence of float	Bin count, a :func:numpy.histogram_bin_edges rule name, or explicit edges covering the pooled in-range data. Edges are resolved once, so all runs and the ratio panel share exactly the same bins.	'auto'
bin_width	float or None	Fixed bin width in data units. Mutually exclusive with bins. The width and origin define a stable grid across separate figures, whereas bins="auto" derives each figure's binning from its pooled data.	None
bin_origin	float or None	Origin of the fixed-width grid. Used only with bin_width and defaults to zero.	None
show_errors	bool	Draw Poisson √N uncertainties on the bin contents.	False
show_mean_lines	bool	Draw the dashed per-run mean line on the distribution panel.	True
alpha	float	Opacity of the filled bars (default: 0.7). The step outline drawn over each histogram stays fully opaque, so lowering this fades overlapping fills without losing any distribution; alpha=0 leaves outlines only.	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: BinSpec = "auto",
    bin_width: float | None = None,
    bin_origin: float | None = None,
    show_errors: bool = False,
    show_mean_lines: bool = True,
    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, str, or sequence of float
        Bin count, a :func:`numpy.histogram_bin_edges` rule name, or explicit
        edges covering the pooled in-range data. Edges are resolved once, so all
        runs and the ratio panel share exactly the same bins.
    bin_width : float or None
        Fixed bin width in data units. Mutually exclusive with ``bins``. The
        width and origin define a stable grid across separate figures, whereas
        ``bins="auto"`` derives each figure's binning from its pooled data.
    bin_origin : float or None
        Origin of the fixed-width grid. Used only with ``bin_width`` and defaults
        to zero.
    show_errors : bool
        Draw Poisson ``√N`` uncertainties on the bin contents.
    show_mean_lines : bool
        Draw the dashed per-run mean line on the distribution panel.
    alpha : float
        Opacity of the filled bars (default: 0.7).  The step outline drawn over
        each histogram stays fully opaque, so lowering this fades overlapping
        fills without losing any distribution; ``alpha=0`` leaves outlines only.
    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,
        bin_width=bin_width,
        bin_origin=bin_origin,
        show_errors=show_errors,
        show_mean_lines=show_mean_lines,
        alpha=alpha,
        figsize=figsize,
        outlier_threshold=outlier_threshold,
        exclude_events=exclude_events,
        palette=palette,
    )