:py:mod:`metacast.event_handling` ================================= .. py:module:: metacast.event_handling .. autoapi-nested-parse:: Creation: Author: Martin Grunnill Date: 2024-02-09 Description: Submodules ---------- .. toctree:: :titlesonly: :maxdepth: 1 event_queue/index.rst events/index.rst Package Contents ---------------- Classes ~~~~~~~ .. autoapisummary:: metacast.event_handling.BaseEvent metacast.event_handling.ValueFactorProportionChangeEvent metacast.event_handling.TransferEvent metacast.event_handling.ChangeParametersEvent metacast.event_handling.ParametersEqualSubPopEvent metacast.event_handling.EventQueue .. py:class:: BaseEvent(name, times) Base parent event. Parameters & Attributes ----------------------- name : str Name given to event. times : floats/ints, ranges or list/tuple/set of floats/ints Times at which event occurs. .. method:: process() Method for carrying out event. .. method:: 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:' .. method:: 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:' .. py:method:: process() Method for carrying out event. :rtype: Nothing .. py:class:: ValueFactorProportionChangeEvent(name, times, value=None, factor=None, proportion=None) Bases: :py:obj:`BaseEvent` Parent event for events that involve changing a value or values. Parameters & Attributes ----------------------- name : str Name given to event. times : floats/ints, ranges or list/tuple/set of floats/ints Times at which event occurs. value : foat/int, mutually exclusive with factor and proportion. Value that overrides original value(s). proportion : foat/int, mutually exclusive with value and factor. Proportion the multiplies original value(s). Must be between 0 and 1. factor : foat/int, mutually exclusive with value and proportion. Factor the multiplies original value(s). .. method:: process() Method for carrying out event. .. method:: make_event_a_nullevent() Changes method into a do null event (do nothing event). .. method:: undo_make_event_a_nullevent() Changes method from a do null event (do nothing event). .. py:property:: proportion .. py:property:: factor .. py:property:: value .. py:class:: TransferEvent(name, times, value=None, factor=None, proportion=None, from_index=None, to_index=None) Bases: :py:obj:`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 ----------------------- name : str Name given to event. times : floats/ints, ranges or list/tuple/set of floats/ints Times at which event occurs. value : foat/int, optional but mutually exclusive with factor and proportion. Value that overrides original parameter value(s). proportion : foat/int, optional but mutually exclusive with value and factor. Proportion the multiplies original parameter value(s). Must be between 0 and 1. factor : foat/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. .. method:: process() Process event by transferring amount between state variables .. method:: make_event_a_nullevent() Changes method into a do null event (do nothing event). .. py:method:: 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). :param solution_at_t: State variable values at time t. :type solution_at_t: numpy.array :param time: Time at t. :type time: float :param return_total_effected: If true total number transferred is returned. :type return_total_effected: bool, default is True :rtype: If return_total_effected is True, total number transferred is returned. .. py:class:: ChangeParametersEvent(name, times, changing_parameters, value=None, factor=None, proportion=None) Bases: :py:obj:`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 ----------------------- name : str Name given to event. times : floats/ints, ranges or list/tuple/set of floats/ints Times at which event occurs. changing_parameters : list-like of strings Parameters whose values will be changed. value : foat/int, optional but mutually exclusive with factor and proportion. Value that overrides original parameter value(s). proportion : foat/int, optional but mutually exclusive with value and factor. Proportion the multiplies original parameter value(s). Must be between 0 and 1. factor : foat/int, optional but mutually exclusive with value and proportion. Factor the multiplies original parameter value(s). .. method:: process() Process event by change parameter values for parameters listed in self.changing_parameters. .. method:: make_event_a_nullevent() Changes method into a do null event (do nothing event). .. py:method:: 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). :param model_object: Object used to define and simulate model. :type model_object: object :param parameters_attribute: Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints). :type parameters_attribute: string :param parameters: Parameters being used by model. :type parameters: dict {str : floats/ints} :returns: **parameters** -- Parameters being used by model after the values of those is list self.changing_parameters is changed. :rtype: dict {str : floats/ints} .. py:class:: ParametersEqualSubPopEvent(name, times, changing_parameters, subpopulation_index) Bases: :py:obj:`BaseEvent` Change parameters to be equal to the sum of a subpopulation. Parameters & Attributes ----------------------- name : str Name given to event. times : floats/ints, ranges or list/tuple/set of floats/ints Times at which event occurs. changing_parameters : list-like of strings Parameters whose values will be changed. subpopulation_index : list-like of ints Index of subpopulation the sum of which will change self.changing_parameters to. .. method:: process() Process event by changing parameters to be equal to the sum of a subpopulation. .. method:: make_event_a_nullevent() Changes method into a do null event (do nothing event). .. py:method:: process(model_object, parameters_attribute, parameters, solution_at_t) Process event by changing parameters to be equal to the sum of a subpopulation. :param model_object: Object used to define and simulate model. :type model_object: object :param parameters_attribute: Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints). :type parameters_attribute: string :param parameters: Parameters being used by model. :type parameters: dict {str : floats/ints} :param solution_at_t: State variable values at time t. :type solution_at_t: numpy.array :rtype: Nothing .. py:class:: 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. :param events: Events to go into event queue. :type events: list(either event_handling.BaseEvent or subclass of event_handling.BaseEvent) .. method:: reset_event_queue() Resets event queue to state at initialisation. .. method:: change_event_proportion(event_names, proportion) Change proportion attribute value of events in event_names. .. method:: change_event_factor(event_names, factor) Change factor attribute value of events in event_names. .. method:: change_event_value(event_names, value) Change value attribute value of events in event_names. .. method:: make_events_nullevents(event_names) Turns events into nullevents (do nothing events). .. method:: get_event_names() Return list of event names. .. method:: events_at_same_time() Returns a dictionary of events occurring at same time. Keys are time values are lists of event names. .. method:: 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. .. py:method:: reset_event_queue() Resets event queue to state at initialisation. :rtype: Nothing .. py:method:: _event_names_checker(event_names) .. py:method:: change_event_proportion(event_names, proportion) Change proportion attribute value of events in event_names. :param event_names: Name of event(s). If 'all' is entered attribute is changed for all events. :type event_names: list-like of strings or single string :param proportion: Value for which proportion attribute is changed to. :type proportion: float/int between 0 and 1 :rtype: Nothing .. py:method:: change_event_factor(event_names, factor) Change factor attribute value of events in event_names. :param event_names: Name of event(s). If 'all' is entered attribute is changed for all events. :type event_names: list-like of strings or single string :param factor: Value for which factor attribute is changed to. :type factor: int/float :rtype: Nothing .. py:method:: change_event_value(event_names, value) Change value attribute value of events in event_names. :param event_names: Name of event(s). If 'all' is entered attribute is changed for all events. :type event_names: list-like of strings or single string :param value: Value for which value attribute is changed to. :type value: int/float :rtype: Nothing .. py:method:: make_events_nullevents(event_names) Turns events into nullevents (do nothing events). :param event_names: Name of event(s). If 'all' is entered all events are made nullevents. :type event_names: list-like of strings or single string :rtype: Nothing .. py:method:: get_event_names() Return list of event names. :returns: Event names. :rtype: List of strings .. py:method:: 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. :rtype: dictionary .. py:method:: 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. :param model_object: Object used to define and simulate model. :type model_object: object :param run_attribute: Name of model_objects method that simulates model. Must return either a numpy array of pandas.DataFrame. :type run_attribute: string :param y0: Intial values of state varibles. :type y0: numpy.array :param end_time: End time of simulations. :type end_time: float/int :param parameters_attribute: Attribute of model_object that sets parameters (must accept dictionary where keys are strings and values are floats/ints). :type parameters_attribute: string :param parameters: Parameters being used by model. :type parameters: dict {str : floats/ints} :param start_time: Start time of simulations. :type start_time: float/int, default 0 :param simulation_step: Time steps used in simulations. :type simulation_step: float/int, default 1 :param full_output: If true an info_dict is returned outlining full_output information given from running of model between events. :type full_output: bool, default False :param return_param_changes: If true dictionary outlining parameters value changes made by events. :type return_param_changes: bool, default is False :param kwargs_to_pass_to_func: Key word arguments to pass to run_attribute method. :type kwargs_to_pass_to_func: **kwargs :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.