plots.plot_resource_utilisation

plots.plot_resource_utilisation(
    event_log,
    *,
    by='step',
    metric='utilisation',
    kind='bar',
    error_bars='ci',
    ci_level=0.95,
    show_runs=True,
    highlight_bands=None,
    sort_by=None,
    scenario=None,
    resource_map=None,
    event_position_df=None,
    resource_capacities=None,
    capacity=None,
    warm_up=0,
    limit_duration=None,
    unclosed='censor',
    entity_col_name='entity_id',
    time_col_name='time',
    event_type_col_name='event_type',
    event_col_name='event',
    resource_col_name='resource_id',
    run_col_name='auto',
)

Plot a bar chart of resource utilisation, one bar per group, across runs.

Thin wrapper over vidigi.analysis.resource_utilisation: that function already returns one row per run per group, so this only takes the mean across runs, builds error bars from the same per-run values, and draws the figure - no replication_means reduction step is needed first.

Parameters

Name Type Description Default
event_log pandas.DataFrame Long-format event log, e.g. the output of TrialLogger.to_dataframe(). required
by (step, resource, run) What each bar summarises. See vidigi.analysis.resource_utilisation. by="run" draws a single bar labelled “All resources”. "step"
metric (busy_time, mean_in_use, utilisation) Which column of vidigi.analysis.resource_utilisation’s output is the bar height. If metric="utilisation" and no capacity was resolved for any group (every value NaN), this falls back to "mean_in_use" instead - which needs no capacity - with a warning and a note in the title, rather than drawing an all-NaN chart. "busy_time"
kind (bar, box, violin) Chart type. "bar" draws one bar per group (the default, unchanged). "box"/"violin" draw the full per-run distribution for each group instead of collapsing it to a mean - error_bars is not valid with either (the box/violin already shows the spread). "bar"
error_bars (ci, sd, se, range, iqr) The spread drawn as an error bar around each bar, computed over the per-run values for that group. Only valid with kind="bar". See vidigi.plots.plot_metric_bar for the full explanation of each. "ci" requires the optional scipy dependency (pip install vidigi[stats]). "ci"
ci_level float Confidence level used when error_bars="ci". 0.95
show_runs bool If True, overlays each run’s individual value. For kind="bar", a semi-transparent point on top of the bar; for kind="box"/"violin", the trace’s own points (boxpoints="all"/points="all"). True
highlight_bands list of dict Shaded threshold zones drawn behind the chart - see vidigi.plots.plot_duration_distribution’s parameter of the same name for the dict shape. Valid with any kind. None
sort_by value If "value", bars are ordered by descending metric value (NaN last) rather than by group value. "value"
scenario Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource", whose capacity is always 1. None
resource_map Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource", whose capacity is always 1. None
event_position_df Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource", whose capacity is always 1. None
resource_capacities Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource", whose capacity is always 1. None
capacity Capacity resolution - see vidigi.analysis._resolve_resource_capacities for the four routes. Unused when by="resource", whose capacity is always 1. None
warm_up float 0
limit_duration float 0
unclosed float 0
entity_col_name float 0
time_col_name float 0
event_type_col_name str Forwarded to vidigi.analysis.resource_utilisation. 'event_type'
event_col_name str Forwarded to vidigi.analysis.resource_utilisation. 'event_type'
resource_col_name str Forwarded to vidigi.analysis.resource_utilisation. 'event_type'
run_col_name str Forwarded to vidigi.analysis.resource_utilisation. 'event_type'

Returns

Name Type Description
plotly.graph_objects.Figure

Raises

Name Type Description
ValueError If by, metric, kind, error_bars or sort_by is not one of the supported values; if error_bars is set with kind != "bar"; if no resource_use/resource_use_end pairs were found to plot; or if a highlight_bands entry has neither lower nor upper set, or lower >= upper.

Notes

A dashed line is drawn at y=1.0 when the plotted metric is (or falls back to being) "utilisation" - a value above it is never valid for this definition (mean number busy / capacity) and is diagnostic of a mis-resolved capacity or overlapping resource_use intervals.

See Also

vidigi.analysis.resource_utilisation : The underlying per-run, per-group summary. plot_resource_utilisation_over_time : The same data, resolved over time instead of per group.

Examples

>>> plot_resource_utilisation(
...     trial.to_dataframe(), by="step", resource_capacities={"treatment_begins": 3}
... )
<plotly.graph_objs._figure.Figure>
Back to top