Merge branch 'main' into make-latex-docs-possible

# Conflicts:
#	docs/conf.py

.flake8

@@ -2,6 +2,7 @@
 exclude =
     .git,
     .venv,
+    venv,
     __pycache__,
     build,
     docs,

.github/workflows/docs.yaml

@@ -29,9 +29,12 @@ jobs:
         sudo apt-get update && sudo apt-get upgrade && sudo apt-get install pandoc texlive texlive-publishers texlive-science texlive-luatex latexmk
 
     - uses: actions/checkout@v3
-      with:
-        lfs: 'true'
-    - run: git lfs pull
+    - run: |
+        curl -LJO "https://media.tuhh.de/mls/software/conflowgen/docs/data/prepared_dbs/demo_poc.sqlite"
+        curl -LJO "https://media.tuhh.de/mls/software/conflowgen/docs/data/prepared_dbs/demo_deham_cta.sqlite"
+        mkdir -p docs/notebooks/data/prepared_dbs
+        mv demo_poc.sqlite docs/notebooks/data/prepared_dbs/
+        mv demo_deham_cta.sqlite docs/notebooks/data/prepared_dbs/
 
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v4

.github/workflows/installation-from-remote.yaml

@@ -3,6 +3,8 @@ name: Install from repository
 on:
   schedule:
     - cron: '42 23 * * 3'  # every Wednesday at 23:42
+  pull_request:
+    types: [opened, reopened, edited, synchronize]
 
 jobs:
   build-conda-on-windows:
@@ -21,15 +23,18 @@ jobs:
       with:
         auto-update-conda: true
         auto-activate-base: true
-        activate-environment: ""
+        activate-environment: true
+        python-version: '3.10'
 
     - name: Install ConFlowGen
       run: |
+        conda info
         conda create -n test-install-conflowgen -c conda-forge conflowgen pytest
 
     - name: Run tests
       run: |
         conda activate test-install-conflowgen
+        conda install pillow=9.0.0
         python -m pytest --pyargs conflowgen
 
   build-conda-on-linux:
@@ -54,6 +59,7 @@ jobs:
       run: |
         conda init bash
         eval "$(conda shell.bash hook)"
+        conda info
         conda activate base
         conda create -n test-install-conflowgen -c conda-forge conflowgen pytest
 
@@ -86,6 +92,7 @@ jobs:
     - name: Install ConFlowGen
       run: |
         python -m pip install conflowgen pytest
+        python -m pip show --verbose conflowgen
 
     - name: Run tests
       run: |

.github/workflows/unittests.yaml

@@ -20,11 +20,10 @@ jobs:
       uses: fkirc/skip-duplicate-actions@v5
 
     - uses: actions/checkout@v2
-      with:
-        lfs: 'true'
     - run: |
-        git lfs fetch -p -I '**/notebooks/data/prepared_dbs/demo_poc.sqlite'
-        git lfs checkout
+        curl -LJO "https://media.tuhh.de/mls/software/conflowgen/docs/data/prepared_dbs/demo_poc.sqlite"
+        mkdir -p docs/notebooks/data/prepared_dbs
+        mv demo_poc.sqlite docs/notebooks/data/prepared_dbs/
 
     - name: Set up Python 3.10
       uses: actions/setup-python@v4

.gitignore

@@ -62,3 +62,4 @@ examples/Python_Script/databases/
 
 # Ignore local changes as they happen with every execution. If something changes, the commit must be forced.
 docs/notebooks/data/prepared_dbs/demo_poc.sqlite
+conflowgen/data/tools/

.pylintrc

@@ -185,18 +185,17 @@ function-naming-style=snake_case
 #function-rgx=
 
 # Good variable names which should always be accepted, separated by a comma.
-good-names=i,
-           j,
-           k,
-           ex,
-           Run,
-           _,
-           df,
-           ax,
-           x,
-           xs,
-           mu,
-           gs
+good-names=i,  # typical counter variable
+           j,  # typical counter variable
+           k,  # typical counter variable
+           _,  # typical discard result indicator
+           df,  # pandas DataFrame
+           ax,  # matplotlib axis
+           gs,  # matplotlib gridspec
+           x,  # one element on the x axis
+           xs,  # collection of elements on the x axis
+           mu,  # mu of, e.g., a normal distribution
+           sd,  # standard deviation of, e.g., a normal distribution
 
 # Good variable names regexes, separated by a comma. If names match any regex,
 # they will always be accepted
@@ -547,5 +546,5 @@ preferred-modules=
 
 # Exceptions that will emit a warning when being caught. Defaults to
 # "BaseException, Exception".
-overgeneral-exceptions=BaseException,
-                       Exception
+overgeneral-exceptions=builtins.BaseException,
+                       builtins.Exception

Contributing.md

@@ -66,7 +66,7 @@ Linux users invoke `make html` instead.
 The landing page of the documentation is created at `<project-root>/docs/_build/html/index.html`.
 It is advised to use a strict approach by using the additional argument `SPHINXOPTS="-W --keep-going`
 (see the corresponding
-[GitHub CI pipeline](https://github.com/1kastner/conflowgen/blob/main/.github/workflows/docs.yaml#L38)
+[GitHub CI pipeline](https://github.com/1kastner/conflowgen/blob/main/.github/workflows/docs.yaml)
 for reference).
 The invocation should be equivalent to `python -m sphinx -W --keep-going ./docs ./docs/_build`.
 

conflowgen/__init__.py

@@ -25,6 +25,10 @@
     VehicleCapacityUtilizationOnOutboundJourneyPreviewReport
 from conflowgen.previews.modal_split_preview import ModalSplitPreview
 from conflowgen.previews.modal_split_preview_report import ModalSplitPreviewReport
+from conflowgen.previews.truck_gate_throughput_preview import TruckGateThroughputPreview
+from conflowgen.previews.truck_gate_throughput_preview_report import TruckGateThroughputPreviewReport
+from conflowgen.previews.quay_side_throughput_preview import QuaySideThroughputPreview
+from conflowgen.previews.quay_side_throughput_preview_report import QuaySideThroughputPreviewReport
 
 # Analyses and their reports
 from conflowgen.analyses.inbound_and_outbound_vehicle_capacity_analysis import \
@@ -61,6 +65,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
 
@@ -85,11 +92,13 @@
 from conflowgen.previews.inbound_and_outbound_vehicle_capacity_preview import OutboundUsedAndMaximumCapacity
 from conflowgen.analyses.container_flow_adjustment_by_vehicle_type_analysis_summary import \
     ContainerFlowAdjustedToVehicleType
-from conflowgen.descriptive_datatypes import TransshipmentAndHinterlandSplit, ContainerVolumeFromOriginToDestination
+from conflowgen.descriptive_datatypes import TransshipmentAndHinterlandSplit
+from conflowgen.descriptive_datatypes import ContainerVolumeFromOriginToDestination
 from conflowgen.descriptive_datatypes import HinterlandModalSplit
-from conflowgen.analyses.inbound_to_outbound_vehicle_capacity_utilization_analysis import \
-    VehicleIdentifier
+from conflowgen.descriptive_datatypes import UsedYardCapacityOverTime
+from conflowgen.descriptive_datatypes import VehicleIdentifier
 from conflowgen.descriptive_datatypes import ContainerVolumeByVehicleType
+from conflowgen.descriptive_datatypes import ContainersTransportedByTruck
 
 # Add metadata constants
 from .metadata import __version__

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

@@ -16,6 +16,9 @@ class ContainerDwellTimeAnalysisReport(AbstractReportWithMatplotlib):
     """
     This analysis report takes the data structure as generated by :class:`.ContainerDwellTimeAnalysis`
     and creates a comprehensible representation for the user, either as text or as a graph.
+    The visual and table are expected to approximately look like in the
+    `example ContainerDwellTimeAnalysisReport \
+    <notebooks/analyses.ipynb#Container-Dwell-Time-Analysis-Report>`_.
     """
 
     report_description = """
@@ -52,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).
@@ -121,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
         """
@@ -160,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_report.py

@@ -15,6 +15,9 @@ class ContainerFlowAdjustmentByVehicleTypeAnalysisReport(AbstractReportWithPlotl
     This analysis report takes the data structure as generated by
     :class:`.ContainerFlowAdjustmentByVehicleTypeAnalysis` and creates a comprehensible representation for the
     user, either as text or as a graph.
+    The visual and table are expected to approximately look like in the
+    `example ContainerFlowAdjustmentByVehicleTypeAnalysisReport \
+    <notebooks/analyses.ipynb#Container-Flow-Adjustment-By-Vehicle-Type-Analysis-Report>`_.
     """
 
     report_description = """
@@ -125,21 +128,21 @@ def get_report_as_graph(self, **kwargs) -> plotly.graph_objs.Figure:
             data=[
                 plotly.graph_objs.Sankey(
                     arrangement='perpendicular',
-                    node=dict(
-                        pad=15,
-                        thickness=20,
-                        line=dict(
-                            color="black",
-                            width=0.5
-                        ),
-                        label=initial_labels + adjusted_labels,
-                        color="dimgray",
-                    ),
-                    link=dict(
-                        source=source_ids_with_duplication,
-                        target=target_ids_with_duplication,
-                        value=value
-                    )
+                    node={
+                        'pad': 15,
+                        'thickness': 20,
+                        'line': {
+                            'color': "black",
+                            'width': 0.5
+                        },
+                        'label': initial_labels + adjusted_labels,
+                        'color': "dimgray",
+                    },
+                    link={
+                        'source': source_ids_with_duplication,
+                        'target': target_ids_with_duplication,
+                        'value': value
+                    }
                 )
             ]
         )

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