analysis.resource_utilisation

analysis.resource_utilisation(
    event_log,
    *,
    by='step',
    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',
)

Summarise resource use into busy time, mean-in-use and utilisation, per run.

Always one row per run per group - aggregating across runs (a mean, a confidence interval) is the plotting layer’s job, exactly as replication_means/mean_confidence_interval do for durations.

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 row summarises. - "step": one row per (run, step) - step is the start event’s name, e.g. "treatment_begins". Capacity comes from whichever capacity route was given for that step. - "resource": one row per (run, resource_id) - one physical unit. Capacity is always 1 (the unit itself); no capacity route needs to be given at all, and none of the capacity arguments below are used. This assumes resource_id is unique across the whole log, not just within one step - if two different resource pools each number their own units from 1 (e.g. two independent vidigi.resources.VidigiStore instances), their busy time is silently summed as if it were one unit, and utilisation can read above 1 with no error, only the generic over-capacity warning below. Give each pool a distinct label= (see vidigi.resources.VidigiStore) and use its unique_id if you plan to use by="resource" - this mode also warns directly whenever it finds two bouts for the same resource_id genuinely overlapping in time, which is impossible for one physical unit and a sharper signal of this exact collision than the over-capacity warning alone. - "run": one row per run, pooling every step/unit together. capacity is the sum of every step’s resolved capacity (NaN if any step’s capacity is unresolved) - the maximum number of resource-things that could have been busy at once, treating every unit of every step as equally countable. If more than one distinct step is pooled, a warning is raised: this is a blended figure across (typically different) resource types, e.g. doctors and beds summed together, which is rarely the number a capacity-planning question is actually asking - prefer by="step" unless a single blended load figure is genuinely what is wanted. "step"
scenario Capacity resolution - see _resolve_resource_capacities for the four routes and their precedence order. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. None
resource_map Capacity resolution - see _resolve_resource_capacities for the four routes and their precedence order. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. None
event_position_df Capacity resolution - see _resolve_resource_capacities for the four routes and their precedence order. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. None
resource_capacities Capacity resolution - see _resolve_resource_capacities for the four routes and their precedence order. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. None
capacity Capacity resolution - see _resolve_resource_capacities for the four routes and their precedence order. All optional; with none given, utilisation is NaN throughout and only busy_time/mean_in_use are meaningful. 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 resource_use_intervals - see that function. 'event_type'
event_col_name str Forwarded to resource_use_intervals - see that function. 'event_type'
resource_col_name str Forwarded to resource_use_intervals - see that function. 'event_type'
run_col_name str Forwarded to resource_use_intervals - see that function. 'event_type'

Returns

Name Type Description
pandas.DataFrame Columns depend on by ("event", "resource_id", or nothing extra), plus run_number, busy_time, mean_in_use, capacity, utilisation. A (run, group) combination that appears in some run but not others is filled with a genuine busy_time of 0, not omitted - the same “real zero” convention as queue_size_over_time.

See Also

resource_use_intervals : The underlying per-bout intervals this aggregates. mean_confidence_interval : A confidence interval over one group’s utilisation (or mean_in_use) column, filtered to that group, across runs - already one value per run, so no replication_means reduction step is needed first, unlike the event_durations -> replication_means route.

Back to top