plots.plot_resource_utilisation_over_time
plots.plot_resource_utilisation_over_time(
event_log,
*,
every_x_time_units=1,
warm_up=0,
limit_duration=None,
as_proportion=False,
show_all_runs=True,
shared_y_axis=True,
highlight_bands=None,
scenario=None,
resource_map=None,
event_position_df=None,
resource_capacities=None,
capacity=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',
)Plot how many units of each resource step were in use over time, across runs.
Thin wrapper over vidigi.analysis.resource_occupancy_over_time: this function only takes the per-snapshot mean across runs (when as_proportion=True, also resolving capacity) and builds the figure.
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 | Time at which the plotted window begins. See vidigi.analysis.resource_use_intervals. |
0 |
| limit_duration | float | End of the plotted window. None (default) uses the latest time seen anywhere in the trial. |
None |
| as_proportion | bool | If True, each step’s count is divided by its resolved capacity (see scenario/resource_map/event_position_df/resource_capacities/ capacity below), so the y-axis is a proportion in use rather than a raw count. Requires a capacity to be resolvable for every step plotted - unlike plot_resource_utilisation, there is no fallback, since a partially-NaN proportion plot is more misleading than an error naming the problem. |
False |
| show_all_runs | bool | If True, plots every run with semi-transparent lines and overlays the mean trajectory. If False, only the mean trajectory is plotted. | True |
| shared_y_axis | bool | If True (and more than one step is plotted), every facet shares a y-axis range. If False, each is scaled independently. | True |
| highlight_bands | list of dict | Shaded threshold zones drawn behind the chart - see plot_duration_distribution’s parameter of the same name for the dict shape. Spans every facet when more than one step is plotted. |
None |
| scenario | Capacity resolution, used only when as_proportion=True - see vidigi.analysis._resolve_resource_capacities for the four routes. |
None |
|
| resource_map | Capacity resolution, used only when as_proportion=True - see vidigi.analysis._resolve_resource_capacities for the four routes. |
None |
|
| event_position_df | Capacity resolution, used only when as_proportion=True - see vidigi.analysis._resolve_resource_capacities for the four routes. |
None |
|
| resource_capacities | Capacity resolution, used only when as_proportion=True - see vidigi.analysis._resolve_resource_capacities for the four routes. |
None |
|
| capacity | Capacity resolution, used only when as_proportion=True - see vidigi.analysis._resolve_resource_capacities for the four routes. |
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 or None | Column names forwarded to vidigi.analysis.resource_occupancy_over_time. |
'resource_id' |
| run_col_name | str or None | Column names forwarded to vidigi.analysis.resource_occupancy_over_time. |
'resource_id' |
Returns
| Name | Type | Description |
|---|---|---|
| plotly.graph_objects.Figure |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If no resource_use/resource_use_end pairs were found to plot; if (with as_proportion=True) a step being plotted has no resolvable capacity; or if a highlight_bands entry has neither lower nor upper set, or lower >= upper. |
Notes
Traces use line_shape="hv" - occupancy is a step function (a bout is occupied on the half-open interval [start, end)), and linear interpolation between snapshots would draw fractional resource counts that never existed.
See Also
vidigi.analysis.resource_occupancy_over_time : The underlying per-run, per-snapshot counts. plot_resource_utilisation : The same data pooled per group instead of over time.
Examples
>>> plot_resource_utilisation_over_time(
... trial.to_dataframe(), every_x_time_units=5, limit_duration=500
... )
<plotly.graph_objs._figure.Figure>