Linear Scale-Up Model

This module contains tools for applying a linear scale-up to an intervention

class vivarium_public_health.treatment.scale_up.LinearScaleUp(treatment)[source]

Apply a linear scale-up to intervention coverage over a configured time period.

This component linearly interpolates an intervention’s exposure parameter between a start value and an end value over a specified date range. Before the start date, the start value is used; after the end date, the end value is used. Endpoint values can be sourced from artifact data or from scalar parameters in the configuration.

For example, for an intervention called treatment the configuration could look like this:

configuration:
    treatment_scale_up:
        date:
            start: "2020-01-01"
            end: "2020-12-31"
        value:
            start: 0.0
            end: 0.9

Parameters:: treatment (str)

CONFIGURATION_DEFAULTS: dict[str, Any] = {'treatment': {'date': {'end': '2020-12-31', 'start': '2020-01-01'}, 'value': {'end': 'data', 'start': 'data'}}}: A dictionary containing the defaults for any configurations managed by this component. An empty dictionary indicates no managed configurations. Components will look for a data_sources block in this dictionary to build lookup tables automatically.

property configuration_defaults: dict[str, Any]

Provides default configuration values for this component.

Configuration structure:

{treatment_name}_scale_up:
    date:
        start: str
            Start date for the scale-up period in ISO format
            (``"YYYY-MM-DD"``). Default is ``"2020-01-01"``.
        end: str
            End date for the scale-up period in ISO format.
            Default is ``"2020-12-31"``.
    value:
        start: str or float
            Value at the start of scale-up. Can be ``"data"``
            to load from artifact, or a numeric value.
            Default is ``"data"``.
        end: str or float
            Value at the end of scale-up. Can be ``"data"``
            to load from artifact, or a numeric value.
            Default is ``"data"``.

The scale-up linearly interpolates between start and end values over the specified date range. Outside this range, values are clamped to the nearest endpoint value.

property configuration_key: str

setup(builder)[source]

Set up the component by loading dates, values, and registering the modifier.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None

get_is_intervention_scenario(builder)[source]

Determine whether the current simulation is an intervention scenario.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: bool
Returns:: True if the configured intervention scenario is not "baseline".

get_clock(builder)[source]

Return the simulation clock callable.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: Callable[[], Timestamp | datetime]
Returns:: A callable that returns the current simulation time.

get_scale_up_dates(builder)[source]

Load the scale-up start and end dates from the configuration.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: tuple[Timestamp, Timestamp]
Returns:: A tuple of (start_date, end_date) as pandas.Timestamp objects.

get_scale_up_values(builder)[source]

Get the values at the start and end of the scale-up period.

Parameters:: builder (Builder) – Interface to access simulation managers.
Return type:: tuple[LookupTable, LookupTable]
Returns:: A tuple of lookup tables returning the values at the start and end of the scale-up period.

get_required_pipelines(builder)[source]

Return any additional pipelines required by subclasses.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: dict[str, Pipeline]
Returns:: A dictionary mapping pipeline names to Pipeline objects. The base implementation returns an empty dictionary.

register_intervention_modifiers(builder)[source]

Register the coverage effect modifier on the treatment’s exposure pipeline.

Parameters:: builder (Builder) – Access point for utilizing framework interfaces during setup.
Return type:: None

coverage_effect(idx, target)[source]

Modify the treatment’s exposure parameters based on the current scale-up progress.

Compute the linear interpolation progress between the scale-up start and end dates, then apply apply_scale_up() to adjust the target values.

Parameters:

idx (Index) – Index of the simulants to modify.
target (Series) – Current exposure parameter values for the given simulants.

Return type:

Series

Returns:

The modified exposure parameter values.

get_endpoint_value_from_data(builder, endpoint_type)[source]

Get the value at the start or end of the scale-up period from data.

Parameters:

builder (Builder) – Interface to access simulation managers.
endpoint_type (str) – The type of endpoint to get the value for. Allowed values are “start” and “end”.

Return type:

LookupTable

Returns:

A lookup table returning the value at the start or end of the scale-up period.

apply_scale_up(idx, target, scale_up_progress)[source]

Apply the linearly interpolated scale-up adjustment to the target values.

The adjustment is computed as:

adjustment = progress * (end_value - start_value)

and is added to the current target values.

Parameters:

idx (Index) – Index of the simulants to modify.
target (Series) – Current target values.
scale_up_progress (float) – A float between 0.0 and 1.0 representing how far through the scale-up period the simulation has progressed.

Return type:

Series

Returns:

The target values with the scale-up adjustment applied.