Framework Utility Functions

Collection of utility functions shared by the vivarium framework.

vivarium.engine.framework.utilities.from_yearly(value, time_step)[source]

Rescales a yearly rate to the size of a time step.

Return type:

Union[ndarray[Any, dtype[number[NBitBase]]], Series, DataFrame, float, int]

Parameters:

value (ndarray[Any, dtype[number[NBitBase]]] | Series | DataFrame | float | int)
time_step (Timedelta | timedelta)

vivarium.engine.framework.utilities.to_yearly(value, time_step)[source]

Converts a time-step-scaled rate back to a yearly rate.

Return type:

Union[ndarray[Any, dtype[number[NBitBase]]], Series, DataFrame, float, int]

Parameters:

value (ndarray[Any, dtype[number[NBitBase]]] | Series | DataFrame | float | int)
time_step (Timedelta | timedelta)

vivarium.engine.framework.utilities.rate_to_probability(rate, time_scaling_factor=1.0, rate_conversion_type='linear')[source]

Converts a rate to a probability.

Return type:

ndarray[Any, dtype[number[NBitBase]]]

Parameters:

rate (Sequence[float] | ndarray[Any, dtype[number[NBitBase]]] | Series | DataFrame | float | int) – The rate to convert to a probability.
time_scaling_factor (float | int) – The time factor in to scale the rates by. This is usually the time step.
rate_conversion_type (Literal['linear', 'exponential']) – The type of conversion to use. Default is “linear” for a simple multiplcation of rate and time_scaling_factor. The other option is “exponential” which should be used for continuous time event driven models.

Returns:

An array of floats representing the probability of the converted rates.

Raises:

ValueError – If an unsupported rate conversion type is provided.

Notes

Beware machine-specific floating point issues. We have encountered underflow when using the exponential conversion for rates greater than ~30,000. To avoid this, we cap the rate at 250 when using the exponential conversion since exp(-250) is effectively zero for practical purposes.

vivarium.engine.framework.utilities.probability_to_rate(probability, time_scaling_factor=1.0, rate_conversion_type='linear')[source]

Converts a probability to a rate.

Return type:

ndarray[Any, dtype[number[NBitBase]]]

Parameters:

probability (Sequence[float] | ndarray[Any, dtype[number[NBitBase]]] | Series | DataFrame | float | int) – The probability to convert to a rate.
time_scaling_factor (float | int) – The time factor in to scale the probability by. This is usually the time step.
rate_conversion_type (Literal['linear', 'exponential']) – The type of conversion to use. Default is “linear” for a simple multiplcation of rate and time_scaling_factor. The other option is “exponential” which should be used for continuous time event driven models.

Returns:

An array of floats representing the rate of the converted probabilities.

Raises:

ValueError – If an unsupported rate conversion type is provided.

vivarium.engine.framework.utilities.collapse_nested_dict(d, prefix=None)[source]

Return type:

list[tuple[str, Any]]

Parameters:

d (dict[str, Any])
prefix (str | None)

vivarium.engine.framework.utilities.import_by_path(path)[source]

Imports a class or function given its absolute path.

Return type:: Callable[..., Any]
Parameters:: path (str) – Fully qualified dotted path to the object (e.g. “module.submodule.ClassName”)
Returns:: The imported class or function.

vivarium.engine.framework.utilities.handle_exceptions(func, logger, with_debugger)[source]

Drops a user into an interactive debugger if func raises an error.

Return type:

Callable[..., Any]

Parameters:

func (Callable[[...], Any])
logger (Any)
with_debugger (bool)