analysis.resource_occupancy_over_time

analysis.resource_occupancy_over_time(
    event_log,
    *,
    every_x_time_units=1,
    warm_up=0,
    limit_duration=None,
    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',
)

Compute how many units of each resource step were busy at regular snapshots.

Unlike queue_size_over_time (built on reshape_for_animations, “most recent event per entity wins”), resource occupancy is interval containment - a different question. This computes it exactly via a +1/-1 sweep over resource_use_intervals’s bouts rather than a per-snapshot membership scan: +1 at each bout’s start, -1 at its end, sorted and cumulatively summed, then looked up onto the snapshot grid with searchsorted.

Parameters

Name Type Description Default
event_log pandas.DataFrame Long-format event log, e.g. the output of TrialLogger.to_dataframe(). required
every_x_time_units float Time granularity for snapshots. 1
warm_up float Start of the analysis window. See resource_use_intervals. 0
limit_duration float End of the analysis window. None (default) uses the latest time seen anywhere in the trial - not per run, so every run shares the same grid. None
entity_col_name str 'entity_id'
time_col_name str 'entity_id'
event_type_col_name str 'entity_id'
event_col_name str 'entity_id'
resource_col_name str Column names forwarded to resource_use_intervals. 'resource_id'
run_col_name str or None Column identifying which run each row belongs to. See event_durations. "auto"

Returns

Name Type Description
pandas.DataFrame Columns run_number, event (the step - the start event’s name), snapshot_time, count. One row per step per snapshot per run, including snapshots where nothing was in use - a genuine zero, not a missing row, matching queue_size_over_time’s convention. Empty (no rows, correct columns) if the log has no resource_use bouts at all.

Raises

Name Type Description
ValueError If every_x_time_units is not positive.

Notes

Unclosed resource use (an entity still holding a resource when the window ends) is always treated as occupied through to the window end - dropping it would understate occupancy exactly when it matters most, the same reasoning as resource_use_intervals’s unclosed="censor" default. This function always uses that behaviour; there is no unclosed parameter.

A bout is occupied on the half-open interval [start, end) - a unit freed exactly at a snapshot time is not counted as busy there. Paired with plot_resource_utilisation_over_time’s line_shape="hv" traces, this draws a resource as busy right up to, and not including, the instant it is freed.

See Also

resource_use_intervals : The underlying per-bout intervals this sweeps over. queue_size_over_time : The equivalent computation for a queue rather than a resource.

Back to top