metacast.event_handling

Creation:

Author: Martin Grunnill Date: 2024-02-09

Description:

Submodules

• metacast.event_handling.event_queue
• metacast.event_handling.events

Package Contents

Classes

BaseEvent	Base parent event.
ValueFactorProportionChangeEvent	Parent event for events that involve changing a value or values.
TransferEvent	Transfers values between state variables.
ChangeParametersEvent	Event for changing parameter values.
ParametersEqualSubPopEvent	Change parameters to be equal to the sum of a subpopulation.
EventQueue	An event queue for processing events from lowest to the highest time. User defined method simulates model between events.

class metacast.event_handling.BaseEvent(name, times)

Base parent event.

Parameters & Attributes

namestr

Name given to event.

timesfloats/ints, ranges or list/tuple/set of floats/ints

Times at which event occurs.

process()

Method for carrying out event.

make_event_a_nullevent()

Changes method into a do null event (do nothing event). Child classes process method should start with ‘if self._do_nothing:

super().process()

else:’ or ‘if self._do_nothing:

pass

else:’

undo_make_event_a_nullevent()

Changes method from a do null event (do nothing event). Child classes process method should start with ‘if self._do_nothing:

super().process()

else:’ or ‘if self._do_nothing:

pass

else:’

process()

Method for carrying out event.

Return type:

Nothing

class metacast.event_handling.ValueFactorProportionChangeEvent(name, times, value=None, factor=None, proportion=None)

Bases: BaseEvent

Parent event for events that involve changing a value or values.

Parameters & Attributes

namestr

Name given to event.

timesfloats/ints, ranges or list/tuple/set of floats/ints

Times at which event occurs.

valuefoat/int, mutually exclusive with factor and proportion.

Value that overrides original value(s).

proportionfoat/int, mutually exclusive with value and factor.

Proportion the multiplies original value(s). Must be between 0 and 1.

factorfoat/int, mutually exclusive with value and proportion.

Factor the multiplies original value(s).

process()

Method for carrying out event.

make_event_a_nullevent()

Changes method into a do null event (do nothing event).

undo_make_event_a_nullevent()

Changes method from a do null event (do nothing event).

property proportion

property factor

property value

class metacast.event_handling.TransferEvent(name, times, value=None, factor=None, proportion=None, from_index=None, to_index=None)

Bases: ValueFactorProportionChangeEvent

Transfers values between state variables.

Note if value, factor and proportion are all None event is a null event (do nothing event).

Parameters & Attributes

namestr

Name given to event.

timesfloats/ints, ranges or list/tuple/set of floats/ints

Times at which event occurs.

valuefoat/int, optional but mutually exclusive with factor and proportion.

Value that overrides original parameter value(s).

proportionfoat/int, optional but mutually exclusive with value and factor.

Proportion the multiplies original parameter value(s). Must be between 0 and 1.

factorfoat/int, optional but mutually exclusive with value and proportion.

Factor the multiplies original parameter value(s).

from_index: list-like of ints

Indexes of stat variables from which transfers take place.

to_index: list-like of ints

Indexes of stat variables to which transfers take place.

process()

Process event by transferring amount between state variables

make_event_a_nullevent()

Changes method into a do null event (do nothing event).

process(solution_at_t, time, return_total_effected=True)

Process event by transferring amount between state variables. Note if value, factor and proportion are all None event is a null event (do nothing event).

Parameters:

• solution_at_t (numpy.array) – State variable values at time t.

• time (float) – Time at t.

• return_total_effected (bool, default is True) – If true total number transferred is returned.

Return type:

If return_total_effected is True, total number transferred is returned.

class metacast.event_handling.ChangeParametersEvent(name, times, changing_parameters, value=None, factor=None, proportion=None)

Bases: ValueFactorProportionChangeEvent

Event for changing parameter values. Note if value, factor and proportion are all None event is a null event (do nothing event).

Parameters & Attributes

namestr

Name given to event.

timesfloats/ints, ranges or list/tuple/set of floats/ints

Times at which event occurs.

changing_parameterslist-like of strings

Parameters whose values will be changed.

valuefoat/int, optional but mutually exclusive with factor and proportion.

Value that overrides original parameter value(s).

proportionfoat/int, optional but mutually exclusive with value and factor.

Proportion the multiplies original parameter value(s). Must be between 0 and 1.

factorfoat/int, optional but mutually exclusive with value and proportion.

Factor the multiplies original parameter value(s).

process()

Process event by change parameter values for parameters listed in self.changing_parameters.

make_event_a_nullevent()

Changes method into a do null event (do nothing event).

process(model_object, parameters_attribute, parameters)

Process event by change parameter values for parameters listed in self.changing_parameters. Note if value, factor and proportion are all None event is a null event (do nothing event).

Parameters:

• model_object (object) – Object used to define and simulate model.

• parameters_attribute (string) – Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints).

• parameters (dict {str : floats/ints}) – Parameters being used by model.

Returns:

parameters – Parameters being used by model after the values of those is list self.changing_parameters is changed.

Return type:

dict {str : floats/ints}

class metacast.event_handling.ParametersEqualSubPopEvent(name, times, changing_parameters, subpopulation_index)

Bases: BaseEvent

Change parameters to be equal to the sum of a subpopulation.

Parameters & Attributes

namestr

Name given to event.

timesfloats/ints, ranges or list/tuple/set of floats/ints

Times at which event occurs.

changing_parameterslist-like of strings

Parameters whose values will be changed.

subpopulation_indexlist-like of ints

Index of subpopulation the sum of which will change self.changing_parameters to.

process()

Process event by changing parameters to be equal to the sum of a subpopulation.

make_event_a_nullevent()

Changes method into a do null event (do nothing event).

process(model_object, parameters_attribute, parameters, solution_at_t)

Process event by changing parameters to be equal to the sum of a subpopulation.

Parameters:

• model_object (object) – Object used to define and simulate model.

• parameters_attribute (string) – Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints).

• parameters (dict {str : floats/ints}) – Parameters being used by model.

• solution_at_t (numpy.array) – State variable values at time t.

Return type:

Nothing

class metacast.event_handling.EventQueue(events)

An event queue for processing events from lowest to the highest time. User defined method simulates model between events.

See method run_simulation on how to customise simulating of model between events.

Parameters:

events (list(either event_handling.BaseEvent or subclass of event_handling.BaseEvent)) – Events to go into event queue.

reset_event_queue()

Resets event queue to state at initialisation.

change_event_proportion(event_names, proportion)

Change proportion attribute value of events in event_names.

change_event_factor(event_names, factor)

Change factor attribute value of events in event_names.

change_event_value(event_names, value)

Change value attribute value of events in event_names.

make_events_nullevents(event_names)

Turns events into nullevents (do nothing events).

get_event_names()

Return list of event names.

events_at_same_time()

Returns a dictionary of events occurring at same time. Keys are time values are lists of event names.

run_simulation(model_object, run_attribute, y0, end_time, parameters_attribute, parameters,

start_time=0, simulation_step=1, full_output=False, return_param_changes=False, **kwargs_to_pass_to_func)

Carries out events in queue, running simulations using user defined method between events.

reset_event_queue()

Resets event queue to state at initialisation.

Return type:

Nothing

_event_names_checker(event_names)

change_event_proportion(event_names, proportion)

Change proportion attribute value of events in event_names.

Parameters:

• event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered attribute is changed for all events.

• proportion (float/int between 0 and 1) – Value for which proportion attribute is changed to.

Return type:

Nothing

change_event_factor(event_names, factor)

Change factor attribute value of events in event_names.

Parameters:

• event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered attribute is changed for all events.

• factor (int/float) – Value for which factor attribute is changed to.

Return type:

Nothing

change_event_value(event_names, value)

Change value attribute value of events in event_names.

Parameters:

• event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered attribute is changed for all events.

• value (int/float) – Value for which value attribute is changed to.

Return type:

Nothing

make_events_nullevents(event_names)

Turns events into nullevents (do nothing events).

Parameters:

event_names (list-like of strings or single string) – Name of event(s). If ‘all’ is entered all events are made nullevents.

Return type:

Nothing

get_event_names()

Return list of event names. :returns: Event names. :rtype: List of strings

events_at_same_time()

Returns a dictionary of events occurring at same time. Keys are time values are lists of event names.

Returns:

Keys are floats/ints values are lists of strings.

Return type:

dictionary

run_simulation(model_object, run_attribute, y0, end_time, parameters_attribute, parameters, start_time=0, simulation_step=1, full_output=False, return_param_changes=False, **kwargs_to_pass_to_func)

Carries out events in queue, running simulations using user defined method between events.

Parameters:

• model_object (object) – Object used to define and simulate model.

• run_attribute (string) – Name of model_objects method that simulates model. Must return either a numpy array of pandas.DataFrame.

• y0 (numpy.array) – Intial values of state varibles.

• end_time (float/int) – End time of simulations.

• parameters_attribute (string) – Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints).

• parameters (dict {str : floats/ints}) – Parameters being used by model.

• start_time (float/int, default 0) – Start time of simulations.

• simulation_step (float/int, default 1) – Time steps used in simulations.

• full_output (bool, default False) – If true an info_dict is returned outlining full_output information given from running of model between events.

• return_param_changes (bool, default is False) – If true dictionary outlining parameters value changes made by events.

• kwargs_to_pass_to_func (**kwargs) – Key word arguments to pass to run_attribute method.

Returns:

• y (numpy.array or pandas.Dataframe) – Solution from simulating model and processing events.

• transfers_df (pandas.Dataframe) – Details of values being transferred by events between state variables.