Implement DataSummariesCache (#183)

conflowgen/__init__.py

@@ -63,6 +63,9 @@
 from conflowgen.analyses.container_flow_vehicle_type_adjustment_per_vehicle_analysis_report import \
     ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport
 
+# Cache for analyses and previews
+from conflowgen.data_summaries.data_summaries_cache import DataSummariesCache
+
 # Specific classes for reports
 from conflowgen.reporting.output_style import DisplayAsMarkupLanguage, DisplayAsPlainText, DisplayAsMarkdown
 

conflowgen/analyses/container_dwell_time_analysis.py

@@ -7,6 +7,7 @@
 from conflowgen.domain_models.data_types.storage_requirement import StorageRequirement
 from conflowgen.domain_models.container import Container
 from conflowgen.analyses.abstract_analysis import AbstractAnalysis
+from conflowgen.data_summaries.data_summaries_cache import DataSummariesCache
 
 
 class ContainerDwellTimeAnalysis(AbstractAnalysis):
@@ -15,7 +16,7 @@ class ContainerDwellTimeAnalysis(AbstractAnalysis):
     The analysis returns a data structure that can be used for generating reports (e.g., in text or as a figure)
     as it is the case with :class:`.ContainerDwellTimeAnalysisReport`.
     """
-
+    @DataSummariesCache.cache_result
     def get_container_dwell_times(
             self,
             container_delivered_by_vehicle_type: typing.Union[
@@ -25,8 +26,7 @@ def get_container_dwell_times(
             storage_requirement: typing.Union[
                 str, typing.Collection[StorageRequirement], StorageRequirement] = "all",
             start_date: typing.Optional[datetime.datetime] = None,
-            end_date: typing.Optional[datetime.datetime] = None,
-            use_cache: bool = True
+            end_date: typing.Optional[datetime.datetime] = None
     ) -> set[datetime.timedelta]:
         """
         The containers are filtered according to the provided criteria.
@@ -50,8 +50,6 @@ def get_container_dwell_times(
                 Only include containers that arrive after the given start time.
             end_date:
                 Only include containers that depart before the given end time.
-            use_cache:
-                Use internally cached values. Please set this to false if data are altered between analysis runs.
 
         Returns:
             A set of container dwell times.
@@ -77,8 +75,8 @@ def get_container_dwell_times(
 
         container: Container
         for container in selected_containers:
-            container_enters_yard = container.get_arrival_time(use_cache=use_cache)
-            container_leaves_yard = container.get_departure_time(use_cache=use_cache)
+            container_enters_yard = container.get_arrival_time()
+            container_leaves_yard = container.get_departure_time()
             assert container_enters_yard < container_leaves_yard, "A container should enter the yard before leaving it"
             if start_date and container_enters_yard < start_date:
                 continue

conflowgen/analyses/container_dwell_time_analysis_report.py

@@ -55,9 +55,6 @@ def get_report_as_text(self, **kwargs) -> str:
                 Only include containers that arrive after the given start time. Defaults to ``None``.
             end_date (datetime.datetime):
                 Only include containers that depart before the given end time. Defaults to ``None``.
-            use_cache (bool):
-                Use internally cached values. Please set this to false if data are altered between analysis runs.
-                Defaults to ``True``.
 
         Returns:
              The report in text format (possibly spanning over several lines).
@@ -124,9 +121,6 @@ def get_report_as_graph(self, **kwargs) -> matplotlib.axis.Axis:
                 Only include containers that arrive after the given start time. Defaults to ``None``.
             end_date (datetime.datetime):
                 Only include containers that depart before the given end time. Defaults to ``None``.
-            use_cache (bool):
-                Use internally cached values. Please set this to false if data are altered between analysis runs.
-                Defaults to ``True``.
         Returns:
              The matplotlib axis of the histogram
         """
@@ -163,16 +157,14 @@ def _get_container_dwell_times(self, kwargs):
         storage_requirement = kwargs.pop("storage_requirement", "all")
         start_date = kwargs.pop("start_date", None)
         end_date = kwargs.pop("end_date", None)
-        use_cache = kwargs.pop("use_cache", True)
         assert len(kwargs) == 0, f"Keyword(s) {list(kwargs.keys())} have not been processed"
 
         container_dwell_times: set[datetime.timedelta] = self.analysis.get_container_dwell_times(
             container_delivered_by_vehicle_type=container_delivered_by_vehicle_type,
             container_picked_up_by_vehicle_type=container_picked_up_by_vehicle_type,
             storage_requirement=storage_requirement,
             start_date=start_date,
-            end_date=end_date,
-            use_cache=use_cache
+            end_date=end_date
         )
         return (
             container_delivered_by_vehicle_type, container_dwell_times, container_picked_up_by_vehicle_type,

conflowgen/analyses/container_flow_adjustment_by_vehicle_type_analysis.py

@@ -3,6 +3,7 @@
 import datetime
 import typing
 
+from conflowgen.data_summaries.data_summaries_cache import DataSummariesCache
 from conflowgen.domain_models.container import Container
 from conflowgen.domain_models.data_types.mode_of_transport import ModeOfTransport
 from conflowgen.analyses.abstract_analysis import AbstractAnalysis
@@ -17,10 +18,10 @@ class ContainerFlowAdjustmentByVehicleTypeAnalysis(AbstractAnalysis):
     """
 
     @staticmethod
+    @DataSummariesCache.cache_result
     def get_initial_to_adjusted_outbound_flow(
             start_date: typing.Optional[datetime.datetime] = None,
-            end_date: typing.Optional[datetime.datetime] = None,
-            use_cache: bool = True
+            end_date: typing.Optional[datetime.datetime] = None
     ) -> ContainerVolumeFromOriginToDestination:
         """
         When containers are generated, in order to obey the maximum dwell time, the vehicle type that is used for
@@ -33,9 +34,6 @@ def get_initial_to_adjusted_outbound_flow(
                 Only include containers that arrive after the given start time.
             end_date:
                 Only include containers that depart before the given end time.
-            use_cache:
-                Use cache instead of re-calculating the arrival and departure time of the container.
-                Defaults to ``True``.
 
         Returns:
             The data structure describes how often an initial outbound vehicle type had to be adjusted with which other
@@ -64,9 +62,9 @@ def get_initial_to_adjusted_outbound_flow(
         # Iterate over all containers and count number of containers / used teu capacity
         container: Container
         for container in Container.select():
-            if start_date and container.get_arrival_time(use_cache=use_cache) < start_date:
+            if start_date and container.get_arrival_time() < start_date:
                 continue
-            if end_date and container.get_departure_time(use_cache=use_cache) > end_date:
+            if end_date and container.get_departure_time() > end_date:
                 continue
             vehicle_type_initial = container.picked_up_by_initial
             vehicle_type_adjusted = container.picked_up_by

conflowgen/analyses/container_flow_adjustment_by_vehicle_type_analysis_summary.py

@@ -3,6 +3,7 @@
 import datetime
 import typing
 
+from conflowgen.data_summaries.data_summaries_cache import DataSummariesCache
 from conflowgen.domain_models.data_types.mode_of_transport import ModeOfTransport
 from conflowgen.analyses.container_flow_adjustment_by_vehicle_type_analysis import \
     ContainerFlowAdjustmentByVehicleTypeAnalysis
@@ -42,12 +43,11 @@ class ContainerFlowAdjustmentByVehicleTypeAnalysisSummary(ContainerFlowAdjustmen
     The analysis summary returns a data structure that can be used for generating reports (e.g., in text or as a figure)
     as it is the case with :class:`.ContainerFlowAdjustmentByVehicleTypeAnalysisSummaryReport`.
     """
-
+    @DataSummariesCache.cache_result
     def get_summary(
             self,
             start_date: typing.Optional[datetime.datetime] = None,
-            end_date: typing.Optional[datetime.datetime] = None,
-            use_cache: bool = True
+            end_date: typing.Optional[datetime.datetime] = None
     ) -> ContainerFlowAdjustedToVehicleType:
         """
         Under certain circumstances (as explained in
@@ -62,14 +62,10 @@ def get_summary(
                 The earliest arriving container that is included. Consider all containers if :obj:`None`.
             end_date:
                 The latest departing container that is included. Consider all containers if :obj:`None`.
-            use_cache:
-                Use cache instead of re-calculating the arrival and departure time of the container.
-                Defaults to ``True``.
         """
         initial_to_adjusted_outbound_flow = self.get_initial_to_adjusted_outbound_flow(
             start_date=start_date,
-            end_date=end_date,
-            use_cache=use_cache
+            end_date=end_date
         )
 
         initial_to_adjusted_outbound_flow_in_teu = initial_to_adjusted_outbound_flow.teu

conflowgen/analyses/container_flow_adjustment_by_vehicle_type_analysis_summary_report.py

@@ -43,9 +43,6 @@ def get_report_as_text(
                 Only include containers that arrive after the given start time. Defaults to ``None``.
             end_date (datetime.datetime):
                 Only include containers that depart before the given end time. Defaults to ``None``.
-            use_cache (bool):
-                Use internally cached values. Please set this to false if data are altered between analysis runs.
-                Defaults to ``True``.
 
         Returns:
              The report in text format (possibly spanning over several lines).
@@ -82,9 +79,6 @@ def get_report_as_graph(self, **kwargs) -> matplotlib.axis.Axis:
                 Only include containers that arrive after the given start time. Defaults to ``None``.
             end_date (datetime.datetime):
                 Only include containers that depart before the given end time. Defaults to ``None``.
-            use_cache (bool):
-                Use internally cached values. Please set this to false if data are altered between analysis runs.
-                Defaults to ``True``.
 
         Returns:
              The matplotlib axis of the pie chart.
@@ -117,11 +111,9 @@ def get_report_as_graph(self, **kwargs) -> matplotlib.axis.Axis:
     def _get_analysis(self, kwargs: dict) -> ContainerFlowAdjustedToVehicleType:
         start_date = kwargs.pop("start_date", None)
         end_date = kwargs.pop("end_date", None)
-        use_cache = kwargs.pop("use_cache", True)
         assert len(kwargs) == 0, f"Keyword(s) {kwargs.keys()} have not been processed"
         adjusted_to = self.analysis_summary.get_summary(
             start_date=start_date,
-            end_date=end_date,
-            use_cache=use_cache
+            end_date=end_date
         )
         return adjusted_to

conflowgen/analyses/container_flow_by_vehicle_type_analysis.py

@@ -4,6 +4,7 @@
 import datetime
 import typing
 
+from conflowgen.data_summaries.data_summaries_cache import DataSummariesCache
 from conflowgen.domain_models.container import Container
 from conflowgen.domain_models.data_types.mode_of_transport import ModeOfTransport
 from conflowgen.analyses.abstract_analysis import AbstractAnalysis
@@ -18,10 +19,10 @@ class ContainerFlowByVehicleTypeAnalysis(AbstractAnalysis):
     """
 
     @staticmethod
+    @DataSummariesCache.cache_result
     def get_inbound_to_outbound_flow(
             start_date: typing.Optional[datetime.datetime] = None,
-            end_date: typing.Optional[datetime.datetime] = None,
-            use_cache: bool = True
+            end_date: typing.Optional[datetime.datetime] = None
     ) -> ContainerVolumeFromOriginToDestination:
         """
         This is the overview of the generated inbound to outbound container flow by vehicle type.
@@ -31,8 +32,6 @@ def get_inbound_to_outbound_flow(
                 The earliest arriving container that is included. Consider all containers if :obj:`None`.
             end_date:
                 The latest departing container that is included. Consider all containers if :obj:`None`.
-            use_cache:
-                Use cache instead of re-calculating the arrival and departure time of the container.
         """
         inbound_to_outbound_flow_in_containers: typing.Dict[ModeOfTransport, typing.Dict[ModeOfTransport, float]] = {
             vehicle_type_inbound:
@@ -46,9 +45,9 @@ def get_inbound_to_outbound_flow(
 
         container: Container
         for container in Container.select():
-            if start_date and container.get_arrival_time(use_cache=use_cache) < start_date:
+            if start_date and container.get_arrival_time() < start_date:
                 continue
-            if end_date and container.get_departure_time(use_cache=use_cache) > end_date:
+            if end_date and container.get_departure_time() > end_date:
                 continue
             inbound_vehicle_type = container.delivered_by
             outbound_vehicle_type = container.picked_up_by

conflowgen/analyses/container_flow_vehicle_type_adjustment_per_vehicle_analysis.py

@@ -4,7 +4,7 @@
 import datetime
 import typing
 
-
+from conflowgen.data_summaries.data_summaries_cache import DataSummariesCache
 from conflowgen.domain_models.container import Container
 from conflowgen.domain_models.data_types.mode_of_transport import ModeOfTransport
 from conflowgen.analyses.abstract_analysis import AbstractAnalysis
@@ -17,14 +17,13 @@ class ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysis(AbstractAnalysis):
     The analysis returns a data structure that can be used for generating reports (e.g., in text or as a figure)
     as it is the case with :class:`.ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport`.
     """
-
+    @DataSummariesCache.cache_result
     def get_vehicle_type_adjustments_per_vehicle(
             self,
             initial_vehicle_type: ModeOfTransport | str | typing.Collection = "scheduled vehicles",
             adjusted_vehicle_type: ModeOfTransport | str | typing.Collection = "scheduled vehicles",
             start_date: typing.Optional[datetime.datetime] = None,
-            end_date: typing.Optional[datetime.datetime] = None,
-            use_cache: bool = True
+            end_date: typing.Optional[datetime.datetime] = None
     ) -> typing.Dict[VehicleIdentifier, int]:
         """
         When containers are generated, in order to obey the maximum dwell time, the vehicle type that is used for
@@ -45,9 +44,6 @@ def get_vehicle_type_adjustments_per_vehicle(
                 Only include containers that arrive after the given start time.
             end_date:
                 Only include containers that depart before the given end time.
-            use_cache:
-                Use cache instead of re-calculating the arrival and departure time of the container.
-                Defaults to ``True``.
         Returns:
             The data structure describes how often an initial outbound vehicle type had to be adjusted over time
             in relation to the total container flows.
@@ -73,9 +69,9 @@ def get_vehicle_type_adjustments_per_vehicle(
 
         container: Container
         for container in selected_containers:
-            if start_date and container.get_arrival_time(use_cache=use_cache) < start_date:
+            if start_date and container.get_arrival_time() < start_date:
                 continue
-            if end_date and container.get_departure_time(use_cache=use_cache) > end_date:
+            if end_date and container.get_departure_time() > end_date:
                 continue
 
             vehicle_identifier = self._get_vehicle_identifier_for_vehicle_picking_up_the_container(container)
@@ -104,14 +100,14 @@ def _get_vehicle_identifier_for_vehicle_picking_up_the_container(container: Cont
         if container.picked_up_by == ModeOfTransport.truck:
             vehicle_identifier = VehicleIdentifier(
                 mode_of_transport=ModeOfTransport.truck,
-                vehicle_arrival_time=container.get_departure_time(use_cache=True),
+                vehicle_arrival_time=container.get_departure_time(),
                 service_name=None,
                 vehicle_name=None
             )
         else:
             vehicle_identifier = VehicleIdentifier(
                 mode_of_transport=container.picked_up_by,
-                vehicle_arrival_time=container.get_departure_time(use_cache=True),
+                vehicle_arrival_time=container.get_departure_time(),
                 service_name=container.picked_up_by_large_scheduled_vehicle.schedule.service_name,
                 vehicle_name=container.picked_up_by_large_scheduled_vehicle.vehicle_name
             )