:py:mod:`starling_sim.basemodel.output.kpis` ============================================ .. py:module:: starling_sim.basemodel.output.kpis Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: starling_sim.basemodel.output.kpis.KPI starling_sim.basemodel.output.kpis.MoveKPI starling_sim.basemodel.output.kpis.WaitKPI starling_sim.basemodel.output.kpis.GetVehicleKPI starling_sim.basemodel.output.kpis.SuccessKPI starling_sim.basemodel.output.kpis.StaffOperationKPI starling_sim.basemodel.output.kpis.OccupationKPI starling_sim.basemodel.output.kpis.StationOccupationKPI starling_sim.basemodel.output.kpis.VehicleOccupationKPI starling_sim.basemodel.output.kpis.ChargeKPI starling_sim.basemodel.output.kpis.PublicTransportChargeKPI starling_sim.basemodel.output.kpis.ServiceKPI starling_sim.basemodel.output.kpis.TransferKPI starling_sim.basemodel.output.kpis.DestinationReachedKPI starling_sim.basemodel.output.kpis.LeaveSimulationKPI Functions ~~~~~~~~~ .. autoapisummary:: starling_sim.basemodel.output.kpis.get_route_id_of_trip starling_sim.basemodel.output.kpis.get_direction_of_trip starling_sim.basemodel.output.kpis.get_route_short_name_of_trip starling_sim.basemodel.output.kpis.get_stop_id_of_event .. py:class:: KPI(export_keys: list = None) Bases: :py:obj:`abc.ABC` Generic structure of a KPI class Its sub-classes compute and update specific indicator from given events .. py:property:: export_keys .. py:attribute:: PROFILE_COMPATIBILITY :value: True .. py:attribute:: KEY_ID :value: 'agentId' .. py:method:: _init_keys() .. py:method:: new_indicator_dict() Evaluate indicators starting values :return: dict with keys in self.keys .. py:method:: setup(kpi_output, simulation_model) Setup method called during simulation setup. After calling this method, the `keys` attribute should be set. :param kpi_output: parent KpiOutput :param simulation_model: .. py:method:: _indicators_setup(simulation_model) Setup attributes that need the simulation model to be initialised. .. py:method:: evaluate_for_agent(agent) Evaluate KPI indicators for the given agent. Indicators are evaluated by browsing the agent's events in chronological and updating values according to the KPI description. :param agent: Traced agent .. py:method:: reset_for_agent(agent) Reset indicators of the KPI in preparation of a new evaluation. :param agent: .. py:method:: end_of_events() Execute certain actions when the event list evaluation has ended. .. py:method:: end_of_profile_range() Add a new row with indicators of current interval and jump to the next one. .. py:method:: new_kpi_row() Add a new row to the output table. Indicators are reset after their data has been added to a row. .. py:method:: is_in_later_profile(timestamp) Test if time profiling is enabled and if the given timestamp is in a later profile interval. :param timestamp: :return: boolean indicating if timestamp in a later profile interval .. py:method:: update_from_event(event: starling_sim.basemodel.trace.events.Event) Update indicators based on the event contents. If event is in a later profile interval, jump to the right interval before processing the event. :param event: Event instance .. py:method:: add_proportioned_indicators(event) .. py:method:: evaluate_indicators_on_profile_range(event, current_timestamp, duration_on_range) :abstractmethod: Evaluate and update KPI indicators for the given event on the specified time interval. :param event: :param current_timestamp: :param duration_on_range: :return: .. py:method:: _update(event) :abstractmethod: Update the kpi values according to the event content and the agent. :param event: processed event :return: .. py:class:: MoveKPI(**kwargs) Bases: :py:obj:`KPI` This KPI evaluates the distance and spent time for each one of the simulation modes .. py:attribute:: SUFFIX_KEY_DISTANCE :value: '{mode}Distance' .. py:attribute:: SUFFIX_KEY_TIME :value: '{mode}Time' .. py:method:: _indicators_setup(simulation_model) Setup attributes that need the simulation model to be initialised. .. py:method:: _init_keys() .. py:method:: _update(event) Update the kpi values according to the event content and the agent. :param event: processed event :return: .. py:method:: evaluate_indicators_on_profile_range(event, current_timestamp, duration_on_range) Evaluate and update KPI indicators for the given event on the specified time interval. :param event: :param current_timestamp: :param duration_on_range: :return: .. py:class:: WaitKPI(export_keys: list = None) Bases: :py:obj:`KPI` This KPI evaluates the time spent waiting .. py:attribute:: KEY_WAIT :value: 'waitTime' .. py:method:: _update(event) Update the kpi values according to the event content and the agent. :param event: processed event :return: .. py:method:: evaluate_indicators_on_profile_range(event, current_timestamp, duration_on_range) Evaluate and update KPI indicators for the given event on the specified time interval. :param event: :param current_timestamp: :param duration_on_range: :return: .. py:class:: GetVehicleKPI(export_keys: list = None) Bases: :py:obj:`KPI` This KPI evaluates the number of vehicle uses .. py:attribute:: KEY_GET_VEHICLE :value: 'nbGetVehicle' .. py:method:: _update(event) Add a new use for each GetVehicleEvent :param event: .. py:class:: SuccessKPI(export_keys: list = None) Bases: :py:obj:`KPI` This KPI evaluates the number of failed/successful requests .. py:attribute:: KEY_FAILED_GET :value: 'nbFailedGet' .. py:attribute:: KEY_SUCCESS_GET :value: 'nbSuccessGet' .. py:attribute:: KEY_FAILED_PUT :value: 'nbFailedPut' .. py:attribute:: KEY_SUCCESS_PUT :value: 'nbSuccessPut' .. py:attribute:: KEY_FAILED_REQUEST :value: 'nbFailedRequest' .. py:attribute:: KEY_SUCCESS_REQUEST :value: 'nbSuccessRequest' .. py:method:: _init_keys() .. py:method:: _update(event) Add request events according to their success :param event: .. py:class:: StaffOperationKPI(export_keys: list = None) Bases: :py:obj:`KPI` This KPI evaluates the number of staff operations .. py:attribute:: KEY_FAILED_GET_STAFF :value: 'nbFailedGetStaff' .. py:attribute:: KEY_SUCCESS_GET_STAFF :value: 'nbSuccessGetStaff' .. py:attribute:: KEY_FAILED_PUT_STAFF :value: 'nbFailedPutStaff' .. py:attribute:: KEY_SUCCESS_PUT_STAFF :value: 'nbSuccessPutStaff' .. py:method:: _init_keys() .. py:method:: _update(event) Add operations to the total :param event: .. py:class:: OccupationKPI(**kwargs) Bases: :py:obj:`KPI` This KPI evaluates the empty and full time and distance and the stock relative time/distance .. py:attribute:: KEY_EMPTY_TIME :value: 'emptyTime' .. py:attribute:: KEY_EMPTY_DISTANCE :value: 'emptyDistance' .. py:attribute:: KEY_FULL_TIME :value: 'fullTime' .. py:attribute:: KEY_FULL_DISTANCE :value: 'fullDistance' .. py:attribute:: KEY_STOCK_TIME :value: 'stockTime' .. py:attribute:: KEY_STOCK_DISTANCE :value: 'stockDistance' .. py:attribute:: KEY_MAX_STOCK :value: 'maxStock' .. py:method:: _init_keys() .. py:method:: reset_for_agent(agent) Reset indicators of the KPI in preparation of a new evaluation. :param agent: .. py:method:: get_capacity(element) Get the capacity of the agent, according to its type. :param element: :return: agent's capacity .. py:method:: get_initial_stock(element) Get the initial stock of the agent, according to its type. :param element: :return: agent's initial stock .. py:method:: end_of_profile_range() Add a new row with indicators of current interval and jump to the next one. .. py:method:: update_timestamp(timestamp) .. py:method:: add_to_stock(value, timestamp) Update the full and empty time and distance counts, according to the previous stock value, then updates the stock and time. :param value: stock change (negative for stock loss) :param timestamp: timestamp of the stock change event .. py:method:: _update(event) Update the stock and time counts from traced events :param event: .. py:class:: StationOccupationKPI(**kwargs) Bases: :py:obj:`OccupationKPI` This KPI evaluates the time spent in the empty and full states (of a station), and the stock relative time spent in the station .. py:method:: _init_keys() .. py:method:: new_indicator_dict() Evaluate indicators starting values :return: dict with keys in self.keys .. py:method:: get_capacity(element) Get the capacity of the agent, according to its type. :param element: :return: agent's capacity .. py:method:: get_initial_stock(element) Get the initial stock of the agent, according to its type. :param element: :return: agent's initial stock .. py:method:: _update(event) Update the stock and time counts from request events :param event: .. py:class:: VehicleOccupationKPI(**kwargs) Bases: :py:obj:`OccupationKPI` This KPI evaluates the time and distance in the empty and full states (of vehicle), and a passenger relative distance and time. .. py:method:: reset_for_agent(agent) Reset indicators of the KPI in preparation of a new evaluation. :param agent: .. py:method:: end_of_profile_range() Add a new row with indicators of current interval and jump to the next one. .. py:method:: get_capacity(element) Get the capacity of the agent, according to its type. :param element: :return: agent's capacity .. py:method:: get_initial_stock(element) Get the initial stock of the agent, according to its type. :param element: :return: agent's initial stock .. py:method:: _update(event) Update the stock and time/distance counts from get/leave vehicle and move events :param event: .. py:method:: evaluate_indicators_on_profile_range(event, current_timestamp, duration_on_range) Evaluate and update KPI indicators for the given event on the specified time interval. :param event: :param current_timestamp: :param duration_on_range: :return: .. py:class:: ChargeKPI(non_empty_only=True, **kwargs) Bases: :py:obj:`KPI` This KPI evaluates the trips's boards and un-boards .. py:attribute:: PROFILE_COMPATIBILITY :value: False .. py:attribute:: KEY_TRIP_ID :value: 'tripId' .. py:attribute:: KEY_TIME :value: 'time' .. py:attribute:: KEY_STOP_ID :value: 'stopId' .. py:attribute:: KEY_BOARD_TYPE :value: 'boardType' .. py:attribute:: KEY_VALUE :value: 'value' .. py:method:: new_indicator_dict() Evaluate indicators starting values :return: dict with keys in self.keys .. py:method:: _init_keys() .. py:method:: end_of_events() Execute certain actions when the event list evaluation has ended. .. py:method:: _update(event) Add stop information to the list :param event: .. py:method:: update_stop_information(event) Update the indicator with the information common to dropoffs and pickups. :param event: .. py:class:: PublicTransportChargeKPI(**kwargs) Bases: :py:obj:`ChargeKPI` This KPI evaluates the public transport trips's boards and un-boards .. py:attribute:: KEY_ROUTE_ID :value: 'routeId' .. py:attribute:: KEY_TRIP_DIRECTION :value: 'tripDirection' .. py:method:: _init_keys() .. py:method:: _indicators_setup(simulation_model) Setup attributes that need the simulation model to be initialised. .. py:method:: update_stop_information(event) Update the indicator with the information common to dropoffs and pickups. :param event: .. py:class:: ServiceKPI(**kwargs) Bases: :py:obj:`KPI` This KPI describes the service time of a vehicle. .. py:attribute:: KEY_SERVICE_DURATION :value: 'serviceDuration' .. py:method:: reset_for_agent(agent) Reset indicators of the KPI in preparation of a new evaluation. :param agent: .. py:method:: end_of_profile_range() Add a new row with indicators of current interval and jump to the next one. .. py:method:: update_indicator(timestamp) .. py:method:: _update(event) Update the kpi values according to the event content and the agent. :param event: processed event :return: .. py:method:: start_service(timestamp) .. py:method:: close_service(timestamp) .. py:class:: TransferKPI(**kwargs) Bases: :py:obj:`KPI` This KPI lists the transfers realised by a user, with additional information such as walk distance and duration, wait duration, from/to trip/stop .. py:attribute:: PROFILE_COMPATIBILITY :value: False .. py:attribute:: KEY_WALK_DIST :value: 'walkDistance' .. py:attribute:: KEY_WALK_DURATION :value: 'walkDuration' .. py:attribute:: KEY_WAIT_TIME :value: 'waitTime' .. py:attribute:: KEY_FROM_ROUTE :value: 'fromRoute' .. py:attribute:: KEY_FROM_TRIP :value: 'fromTrip' .. py:attribute:: KEY_FROM_STOP :value: 'fromStop' .. py:attribute:: KEY_TO_ROUTE :value: 'toRoute' .. py:attribute:: KEY_TO_TRIP :value: 'toTrip' .. py:attribute:: KEY_TO_STOP :value: 'toStop' .. py:method:: _indicators_setup(simulation_model) Setup attributes that need the simulation model to be initialised. .. py:method:: _init_keys() .. py:method:: end_of_events() Execute certain actions when the event list evaluation has ended. .. py:method:: new_indicator_dict() Evaluate indicators starting values :return: dict with keys in self.keys .. py:method:: _update(event) Update the kpi values according to the event content and the agent. :param event: processed event :return: .. py:method:: reset_variables() .. py:method:: write_variables() .. py:class:: DestinationReachedKPI(export_keys: list = None) Bases: :py:obj:`KPI` This KPI evaluates the destination reach time .. py:attribute:: KEY_DESTINATION_REACHED :value: 'destinationReachedTime' .. py:method:: new_indicator_dict() Evaluate indicators starting values :return: dict with keys in self.keys .. py:method:: _update(event) Add total wait duration of the request :param event: .. py:class:: LeaveSimulationKPI(export_keys: list = None) Bases: :py:obj:`KPI` This KPI evaluates the cause of the simulation leave. .. py:attribute:: KEY_LEAVE_SIMULATION :value: 'leaveSimulation' .. py:method:: new_indicator_dict() Evaluate indicators starting values :return: dict with keys in self.keys .. py:method:: _update(event) Add the cause of the LeaveSimulationEvent. :param event: .. py:function:: get_route_id_of_trip(trips, trip_id, event) .. py:function:: get_direction_of_trip(trips, trip_id) .. py:function:: get_route_short_name_of_trip(trips, routes, trip_id) .. py:function:: get_stop_id_of_event(event)