API

Domain datatypes

namedtuple ContainerFlowAdjustedToVehicleType(unchanged, train, barge, truck, deep_sea_vessel, feeder)[source]

During the automatic assignment of containers to outbound journeys, sometimes a container cannot be assigned to the previously randomly selected vehicle. This happens, e.g., during the ramp-down phase when no vessels arrive and thus transshipment is impossible. However, in the end trucks can still be generated to empty the container yard. This data structure holds how much volume had to be re-assigned.

Fields:

  1.  unchanged (float) – The container volume (e.g., counted in boxes or TEU) that was assigned a vehicle of the pre-defined vehicle type

  2.  train (float) – The container volume (e.g., counted in boxes or TEU) that was re-assigned to be transported by train

  3.  barge (float) – The container volume (e.g., counted in boxes or TEU) that was re-assigned to be transported by barge

  4.  truck (float) – The container volume (e.g., counted in boxes or TEU) that was re-assigned to be transported by truck

  5.  deep_sea_vessel (float) – The container volume (e.g., counted in boxes or TEU) that was re-assigned to be transported by deep sea vessel

  6.  feeder (float) – The container volume (e.g., counted in boxes or TEU) that was re-assigned to be transported by feeder

enum ContainerLength(value)[source]

The container length is one of the most important factors of how much space a container occupies. Here, the most common container sizes (neglecting height) are represented.

Valid values are as follows:

twenty_feet = <ContainerLength.twenty_feet: 20>

A twenty-foot container

forty_feet = <ContainerLength.forty_feet: 40>

A forty-foot container

forty_five_feet = <ContainerLength.forty_five_feet: 45>

A forty-five-foot container

other = <ContainerLength.other: -1>

Any other length usually does not fit into the standardized slots and handling processes.

The Enum and its members also have the following methods:

classmethod get_teu_factor(container_length)[source]

Each container occupies a certain amount of space when stored. This required space is measured in TEU.

Note

CONTAINER_LENGTH_TO_OCCUPIED_TEU = {ContainerLength.forty_feet: 2, ContainerLength.forty_five_feet: 2.25, ContainerLength.other: 2.5, ContainerLength.twenty_feet: 1}

This is the translation table to specify the occupied storage space in TEU. For 20’, 40’, and 45’, the typical values are picked. The TEU factor for the value ‘other’ is chosen to be rather large because it is assumed to be difficult to find a proper storage position.

Parameters:

container_length (ContainerLength) – The length of the container

Returns:

The TEU factor of the container

Return type:

float

classmethod cast_element_type(text)[source]
Parameters:

text (str) – The text to parse

Returns:

The container length enum name if the cast was successful, None otherwise.

Return type:

ContainerLength | None

namedtuple ContainersTransportedByTruck(inbound, outbound)[source]

Represents the containers moved by trucks.

Fields:

  1.  inbound (float) – The number of containers moved on the inbound journey

  2.  outbound (float) – The number of containers moved on the outbound journey

namedtuple ContainerVolumeByVehicleType(teu, containers)[source]

Several KPIs at container terminals can be both expressed in boxes per hour and TEU per hour (or a different time range).

Fields:

  1.  teu (Dict[ModeOfTransport, float]) – The container volume expressed in TEU

  2.  containers (Optional[Dict[ModeOfTransport, float]]) – The container volume expressed in number of boxes

namedtuple ContainerVolumeFromOriginToDestination(containers, teu)[source]

Several KPIs at container terminals can be both expressed in boxes per hour and TEU per hour (or a different time range).

Fields:

  1.  containers (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – The container volume expressed in number of boxes

  2.  teu (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – The container volume expressed in TEU

namedtuple HinterlandModalSplit(train_capacity, barge_capacity, truck_capacity)[source]

This tuple keeps track of how much of the capacity that is either coming from or is destined to the hinterland is transported and by which vehicle type.

Fields:

  1.  train_capacity (float) – Alias for field number 0

  2.  barge_capacity (float) – Alias for field number 1

  3.  truck_capacity (float) – Alias for field number 2

enum ModeOfTransport(value)[source]

The mode of transport describes the vehicle type of the vehicle which either drops off or picks up a container.

Valid values are as follows:

truck = <ModeOfTransport.truck: 'truck'>

An external truck is sent by a freight forwarder

train = <ModeOfTransport.train: 'train'>

A freight train is sent by a train operating company

feeder = <ModeOfTransport.feeder: 'feeder'>

A feeder vessel is a rather small vessel sent by a ship operator and moves in the region

deep_sea_vessel = <ModeOfTransport.deep_sea_vessel: 'deep_sea_vessel'>

A deep sea vessel is a rather large vessel sent by a ship operator and moves between distant regions, e.g. continents.

barge = <ModeOfTransport.barge: 'barge'>

A barge is sent by an inland shipping operator

The Enum and its members also have the following methods:

classmethod get_scheduled_vehicles()[source]
Returns:

A list of vehicles that follow a schedule

Return type:

List[ModeOfTransport]

classmethod get_unscheduled_vehicles()[source]
Returns:

A list of vehicles that are created as they are needed to transport a container

Return type:

List[ModeOfTransport]

namedtuple OutboundUsedAndMaximumCapacity(used, maximum)[source]

This tuple keeps track of how much each vehicle type transports on the outbound journey and what the maximum capacity is.

Fields:

  1.  used (ContainerVolumeByVehicleType) – The container volume that is actually transported, summarized by vehicle type.

  2.  maximum (ContainerVolumeByVehicleType) – The container volume that could be transported if all capacities had been used, summarized by vehicle type.

namedtuple RequiredAndMaximumCapacityComparison(currently_planned, maximum, exceeded)[source]

This is a tuple that maintains three separate values for a given vehicle type. First, the currently planned capacity is recorded. Second, the maximum capacity is noted. If more capacity is requested than available, the exceeded flag is true, otherwise false.

Fields:

  1.  currently_planned (float) – The required vehicle capacity to transport all containers on their outbound journey based on the current modal split.

  2.  maximum (float) – The total available vehicle capacity according to current schedules.

  3.  exceeded (bool) – This indicates whether more vehicles are required than currently available. If so, the modal split or the schedules might need to be adjusted.

enum StorageRequirement(value)[source]

A container is stored in different areas of the yard depending on its requirements.

Valid values are as follows:

empty = <StorageRequirement.empty: 'empty'>

An empty container is stored in an empty container yard.

standard = <StorageRequirement.standard: 'standard'>

A standard container is stored in the full container yard and makes up most of the containers passing through a container terminal.

reefer = <StorageRequirement.reefer: 'reefer'>

A reefer container requires electricity (i.e., a reefer plug) to keep the inner temperature on a low level.

dangerous_goods = <StorageRequirement.dangerous_goods: 'dangerous_goods'>

A dangerous goods container needs a specially prepared storage area so they do not constitute a major hazard to health and environment. These are also sometimes referred to as IMO containers.

The Enum and its members also have the following methods:

classmethod get_full_containers()[source]

All containers that are not empty containers are also referred to as full containers.

Return type:

Collection[StorageRequirement]

namedtuple TransshipmentAndHinterlandSplit(transshipment_capacity, hinterland_capacity)[source]

This tuple keeps track of how much of the capacity is transshipment (i.e., dropped off and picked up by a vessel) and how much is hinterland (i.e., either dropped off or picked up by a vehicle that is not a vessel, e.g., a train or a truck).

Fields:

  1.  transshipment_capacity (float) – Alias for field number 0

  2.  hinterland_capacity (float) – Alias for field number 1

namedtuple UsedYardCapacityOverTime(teu, containers)[source]

Represents yard capacity in TEU and number of boxes.

Fields:

  1.  teu (Dict[datetime, float]) – The yard capacity expressed in TEU

  2.  containers (Dict[datetime, int]) – The yard capacity expressed in number of boxes

namedtuple VehicleIdentifier(mode_of_transport, service_name, vehicle_name, vehicle_arrival_time)[source]

A vehicle identifier is a composition of the vehicle type, its service name, and the actual vehicle name

Fields:

  1.  mode_of_transport (ModeOfTransport) – The vehicle type, e.g., ‘deep_sea_vessel’ or ‘truck’.

  2.  service_name (Optional[str]) – The service name, such as the name of the container service the vessel operates in. Not set for trucks.

  3.  vehicle_name (Optional[str]) – The name of the vehicle if given.

  4.  vehicle_arrival_time (datetime) – The time of arrival of the vehicle at the terminal.

Setting up ConFlowGen

class DatabaseChooser(sqlite_databases_directory=None)[source]

This is a stateful library. For the purpose of reproducibility, the current input distributions are all stored in the database, likewise the generated vehicles etc. Thus, different scenarios can be stored in different SQLite databases.

Parameters:

sqlite_databases_directory (str | None) – The DatabaseChooser opens one directory. All databases are saved to and load from this directory. It defaults to <project root>/data/databases/.

close_current_connection()[source]

Close current connection, e.g., as a preparatory step to create a new SQLite database.

Return type:

None

create_new_sqlite_database(file_name, overwrite=False, **seeder_options)[source]

All required tables are created and all input distributions are seeded with default values. These can be simply overwritten by the use-case specific distributions with the help of the API, e.g. the ContainerLengthDistributionManager, StorageRequirementDistributionManager, ModeOfTransportDistributionManager, TruckArrivalDistributionManager, or similar. By default, no schedules and no vehicles exist.

Parameters:

  • file_name (str) – The file name of an SQLite database that will reside in <project root>/data/databases/

  • overwrite (bool) – Whether to overwrite an existing database

  • **seeder_options – In case the database is seeded with default values, some variations exist that the user can choose from. The following options exist:

Keyword Arguments:

assume_tas (bool) – If a truck appointment system (TAS) is assumed, the corresponding truck arrival distribution is picked.

Return type:

None

list_all_sqlite_databases()[source]
Returns:

A list of all SQLite databases in the opened directory

Return type:

List[str]

load_existing_sqlite_database(file_name)[source]
Parameters:

file_name (str) – The file name of an SQLite database in the opened directory

Return type:

None

setup_logger(logging_directory=None, format_string=None)[source]

This sets up the default logger with the name ‘conflowgen’. Several classes and functions use the same logger to inform the user about the current progress. This is just a convenience function, you can easily set up your own logger that uses the same name. See e.g. https://docs.python.org/3/howto/logging.html#configuring-logging for how to set up your own logger.

Parameters:

  • logging_directory (str | None) – The path of the directory where to store logging files. Defaults to <project root>/data/logs/.

  • format_string (str | None) – The format string to use. See e.g. https://docs.python.org/3/library/logging.html#logrecord-attributes for how to create your own format string. Defaults to %(asctime)s - %(name)s - %(levelname)s - %(message)s.

Returns:

The set-up logger instance.

Return type:

Logger

Setting input data

With the following classes, the schedules, input values and input distributions are set. These are all required for generating the synthetic data.

class ContainerFlowGenerationManager[source]

This manager provides the interface to set the properties (i.e., not the distributions that are handled elsewhere) and trigger the synthetic container flow generation. If not provided, default values are used automatically.

container_flow_data_exists()[source]

When an existing database is opened, pre-existing container flow data could already be stored inside. Invoking ContainerFlowGenerationManager.generate() again would reset that stored data. You might want to skip that set and just re-use the data already stored in the database.

Returns:

Whether container flow data exists in the database.

Return type:

bool

generate(overwrite=True)[source]

Generate the synthetic container flow according to all the information stored in the database so far. This triggers a multistep procedure of generating vehicles and the containers which are delivered or picked up by the vehicles. This process is described in the Section Data Generation Process. The invocation of this method overwrites any already existent data in the database. Consider checking for ContainerFlowGenerationManager.container_flow_data_exists() and skip invoking this method.

Parameters:

overwrite (bool) – Whether to overwrite existing container flow data. Defaults to True.

Return type:

None

get_properties()[source]
Returns:

The properties of the container flow.

Return type:

Dict[str, str | date | float | int]

set_properties(start_date, end_date, name=None, transportation_buffer=None)[source]
Parameters:

  • start_date (date) – The earliest day any scheduled vehicle arrives. Trucks that drop off containers might arrive earlier though.

  • end_date (date) – The latest day any scheduled vehicle arrives. Trucks that pick up containers might arrive later though.

  • name (str | None) – The name of the generated synthetic container flow which helps to distinguish different scenarios.

  • transportation_buffer (float | None) – Determines how many percent more of the inbound journey capacity is used at most to transport containers on the outbound journey.

Return type:

None

class ContainerLengthDistributionManager[source]

This manager provides the interface to set and get the container length distribution.

The default distribution is presented in the section Container Length Distribution.

get_container_length_distribution()[source]
Returns:

The distribution of container lengths. Each length is assigned its frequency of showing up.

Return type:

Dict[ContainerLength, float]

set_container_length_distribution(container_lengths)[source]

Set the assumed global distribution of container lengths. This is applied to all vehicles that arrive at the terminal.

Parameters:

container_lengths (Dict[ContainerLength, float]) – The distribution of container lengths and their corresponding frequency.

Return type:

None

class StorageRequirementDistributionManager[source]

This is the interface to set and get the storage requirement distribution. It determines how many containers are selected to have a certain StorageRequirement.

get_storage_requirement_distribution()[source]
Returns:

The distribution of storage requirements based on the length of the container.

Return type:

Dict[ContainerLength, Dict[StorageRequirement, float]]

set_storage_requirement_distribution(storage_requirements)[source]

Set the assumed global distribution of container storage requirements. This is applied to all containers passing through the terminal.

Parameters:

storage_requirements (Dict[ContainerLength, Dict[StorageRequirement, float]]) – The distribution of storage requirements depending on the container length.

Return type:

None

class ContainerWeightDistributionManager[source]

This is the interface to set and get the container weight distribution. With the help of this distribution, the weight of each container is drawn. The default distribution is presented in the section Container Weight Distribution.

get_container_weight_distribution()[source]
Returns:

The distribution of container weights. Each length is assigned its frequency of showing up.

Return type:

Dict[ContainerLength, Dict[int, float]]

set_container_weight_distribution(container_weights)[source]

Set the assumed global distribution of container weights.

Parameters:

container_weights (Dict[ContainerLength, Dict[int, float]]) – The distribution of container weights for the respective container lengths.

Return type:

None

class ModeOfTransportDistributionManager[source]

This is the interface to set and get the distribution that controls from which vehicle containers are transshipped to which other type of vehicle.

get_mode_of_transport_distribution()[source]
Returns:

The distribution of mode of transports dependent on the vehicle the container is delivered by. If a container is delivered by a vehicle of type <first-key>, the floating point number describes the fraction that the container is later picked up by vehicle of type <second-key>.

Return type:

Dict[ModeOfTransport, Dict[ModeOfTransport, float]]

set_mode_of_transport_distribution(distribution)[source]
Parameters:

distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – If a container is delivered by a vehicle of type <first-key>, the floating point number describes the fraction that the container is later picked up by vehicle of type <second-key>.

Return type:

None

class ContainerDwellTimeDistributionManager[source]

This is the interface to set and get the distribution that controls how long the container remains in the yard before it is loaded onto a vehicle and leaves again.

static get_average_container_dwell_time(start_date, end_date)[source]

Uses ModeOfTransportDistributionManager to calculate the expected average container dwell time based on the scheduled container flow.

Parameters:

  • start_date (date) – The earliest day to consider for scheduled vehicles

  • end_date (date) – The latest day to consider for scheduled vehicles

Returns:

Weighted average of all container dwell times based on inbound and outbound vehicle capacities

Return type:

float

get_container_dwell_time_distribution()[source]
Returns:

The container dwell time distribution depends on the vehicle the container is delivered by, picked up by, and the storage requirement.

Return type:

Dict[ModeOfTransport, Dict[ModeOfTransport, Dict[StorageRequirement, ContinuousDistribution]]]

set_container_dwell_time_distribution(distribution)[source]

The container dwell time distribution depends on the vehicle the container is delivered by, picked up by, and the storage requirement.

A distribution is described by the following parameters:

  • distribution_name (str) - The name of the distribution.

  • average (float) - The expected mean

  • minimum (float) - The lower bound

  • maximum (float) - The upper bound

Currently, the distributions ‘lognormal’ and ‘uniform’ are supported.

Parameters:

distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, Dict[StorageRequirement, Dict[str, Any]]]]) –

Return type:

None

class PortCallManager[source]

This manager provides the interface to create schedules for services that periodically call the container terminal, e.g., ships of any size and trains. This explicitly does not cover the trucks which arrive according to a probability distribution set at TruckArrivalDistributionManager.

add_vehicle(vehicle_type, service_name, vehicle_arrives_at, vehicle_arrives_at_time, average_vehicle_capacity, average_moved_capacity, next_destinations=None, vehicle_arrives_every_k_days=None)[source]

Add the schedule of a ship of any size or a train. The concrete vehicle instances are automatically generated when ContainerFlowGenerationManager.generate() is invoked.

Parameters:

  • vehicle_type (ModeOfTransport) – One of ModeOfTransport.deep_sea_vessel, ModeOfTransport.feeder, ModeOfTransport.barge, or ModeOfTransport.train

  • service_name (str) – The name of the service, i.e., the shipping line or rail freight line

  • vehicle_arrives_at (date) – A date the service would arrive at the terminal. This can, e.g., point at the week day for weekly services. In any case, this is combined with the parameter vehicle_arrives_every_k_days and only arrivals within the time scope between start_date and end_date are considered.

  • vehicle_arrives_at_time (time) – A time of the day (between 00:00 and 23:59).

  • average_vehicle_capacity (int) – Number of TEU that can be transported with the vehicle at most. The number of moved containers can never exceed this number, no matter what the value for the transportation_buffer is set to.

  • average_moved_capacity (int) –

    The average moved capacity describes the number of TEU which the vehicle delivers to the terminal on its inbound journey. When summing up the TEU factors of each of the loaded containers on the inbound journey, this value is never exceeded but closely approximated. For the outbound journey, the containers are assigned depending on the distribution kept in ModeOfTransportDistributionManager. The maximum number of containers in TEU on the outbound journey of the vehicle is bound by

    \[min( \text{average_moved_capacity} \cdot \text{transportation_buffer},\text{average_vehicle_capacity} )\]

    If you have calibrated the aforementioned distribution accordingly, the actual number of containers on the outbound journey in TEU should be on average the same as on the inbound journey. In that case, the vehicle moves average_moved_capacity number of containers in TEU on its inbound journey and the same number of containers in TEU again on its outbound journey.

  • next_destinations (List[Tuple[str, float]] | None) – Pairs of destination and frequency of the destination being chosen.

  • vehicle_arrives_every_k_days (int | None) – Defaults to weekly services (arrival every 7 days). Other frequencies are possible as well. In the special case of -1, only a single arrival is scheduled for day vehicle_arrives_at as long as the specified date lies within start_date and end_date. This arrival is only part of the generated container flow if that arrival lies between start_date and end_date.

Return type:

None

has_schedule(service_name, vehicle_type)[source]
Parameters:

  • service_name (str) – The name of the service which moves to a schedule that is sought for.

  • vehicle_type (ModeOfTransport) – The mode of transport to restrict the search to.

Returns:

Whether the requested schedule already exist in the database.

Return type:

bool

class TruckArrivalDistributionManager[source]

This manager provides the interface to set and get the weekly arrival rates of trucks. When the truck arrival time is drawn from this distribution, first a slice for the minimum and maximum dwell time is created and the arrival time of the truck is drawn from that period. All other vehicles are created based on the schedule they adhere to with the help of the PortCallManager

get_truck_arrival_distribution()[source]

Each key represents the hour in the week and each value represents the probability of a truck to arrive between that hour and the start of the next time slot (the successor is the nearest key larger than the current key).

Returns:

The truck arrival distribution.

Return type:

Dict[int, float]

set_truck_arrival_distribution(distribution)[source]
Parameters:

distribution (Dict[float, float]) – The truck arrival distribution. Each key represents the hour in the week and each value represents the probability of a truck to arrive between that hour and the start of the next time slot (the successor is the nearest key larger than the current key).

Return type:

None

Generating previews

class ContainerFlowByVehicleTypePreview(start_date, end_date, transportation_buffer)[source]

This preview tells the user how many containers are planned to be transshipped between which types of vehicles.

The preview 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 ContainerFlowByVehicleTypePreviewReport. The preview is intended to provide a first estimate before running the expensive ContainerFlowGenerationManager.generate() method. The preview does not consider all restrictions (such as container dwell times in combination with the schedules) into consideration, thus later deviations might exist.

Parameters:

  • start_date (date) – The earliest day to consider when checking the vehicles that move according to schedules

  • end_date (date) – The latest day to consider when checking the vehicles that move according to schedules

  • transportation_buffer (float) – The fraction of how much more a vehicle takes with it on an outbound journey compared to an inbound journey as long as the total vehicle capacity is not exceeded.

get_inbound_to_outbound_flow()[source]

The estimated flow of containers from vehicles on their inbound journey to vehicles on their outbound journey based on the mode of transport distribution.

Returns:

A flow from vehicle type A to vehicle type B estimated in TEU.

Return type:

Dict[ModeOfTransport, Dict[ModeOfTransport, float]]

hypothesize_with_mode_of_transport_distribution(mode_of_transport_distribution)[source]

This allows to see the effect of different mode of transport distributions on this preview.

Parameters:

mode_of_transport_distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – A mode of transport distribution to try out

class ContainerFlowByVehicleTypePreviewReport[source]

This preview report takes the data structure as generated by ContainerFlowByVehicleTypePreview 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 ContainerFlowByVehicleTypePreviewReport.

get_report_as_graph(**kwargs)[source]

The container flow is represented by a Sankey diagram.

Returns:

The plotly figure of the Sankey diagram.

Return type:

Figure

Note

At the time of writing, plotly comes with some shortcomings.

However, it seems to be the best available library for plotting Sankey diagrams that can be visualized, e.g., in a Jupyter Notebook.

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

logger = <Logger conflowgen (WARNING)>

Each report can log to the console

class InboundAndOutboundVehicleCapacityPreview(start_date, end_date, transportation_buffer)[source]

This preview examines how much the inbound vehicles deliver to the terminal and how it is redistributed to the outbound journeys of the other vehicles according to the mode of transport distribution. This pre-checks whether the transport capacity of the vehicles will be exceeded. In such case, the input schedules and distributions should be further refined before generating a container flow.

The preview 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 InboundAndOutboundVehicleCapacityPreviewReport. The preview is intended to provide a first estimate before running the expensive ContainerFlowGenerationManager.generate() method. The preview does not consider all restrictions (such as container dwell times in combination with the schedules) into consideration, thus later deviations might exist.

Parameters:

  • start_date (date) – The earliest day to consider when checking the vehicles that move according to schedules

  • end_date (date) – The latest day to consider when checking the vehicles that move according to schedules

  • transportation_buffer (float) – The fraction of how much more a vehicle takes with it on an outbound journey compared to an inbound journey as long as the total vehicle capacity is not exceeded.

get_inbound_capacity_of_vehicles()[source]

For the inbound capacity, first vehicles that adhere to a schedule are considered. Trucks, which are created depending on the outbound distribution, are created based on the assumptions of the further container flow generation process.

Return type:

ContainerVolumeByVehicleType

get_outbound_capacity_of_vehicles()[source]

For the outbound capacity, both the used outbound capacity (estimated) and the maximum outbound capacity is reported. If a vehicle type reaches the maximum outbound capacity, this means that containers need to be redistributed to other vehicle types due to a lack of capacity. The capacities are only calculated in TEU, not in containers.

Return type:

OutboundUsedAndMaximumCapacity

hypothesize_with_mode_of_transport_distribution(mode_of_transport_distribution)[source]

This allows to see the effect of different mode of transport distributions on this preview.

Parameters:

mode_of_transport_distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – A mode of transport distribution to try out

class InboundAndOutboundVehicleCapacityPreviewReport[source]

This preview report takes the data structure as generated by InboundAndOutboundVehicleCapacityPreview and creates a comprehensible representation for the user, either as text or as a graph. A similar report can be found at VehicleCapacityExceededPreviewReport. The visual and table are expected to approximately look like in the example InboundAndOutboundVehicleCapacityPreviewReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a bar chart using pandas.

Returns:

The matplotlib axis of the bar chart.

Return type:

Axis

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

class ModalSplitPreview(start_date, end_date, transportation_buffer)[source]

This preview examines the inbound and/or outbound journeys and estimates the modal split. This is separated into two different aspects. First, the transshipment share is indicated. For the hinterland, the modal split is reported.

The preview 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 ModalSplitPreviewReport. The preview is intended to provide a first estimate before running the expensive ContainerFlowGenerationManager.generate() method. The preview does not consider all restrictions (such as container dwell times in combination with the schedules) into consideration, thus later deviations might exist.

Parameters:

  • start_date (date) – The earliest day to consider when checking the vehicles that move according to schedules

  • end_date (date) – The latest day to consider when checking the vehicles that move according to schedules

  • transportation_buffer (float) – The fraction of how much more a vehicle takes with it on an outbound journey compared to an inbound journey as long as the total vehicle capacity is not exceeded.

get_modal_split_for_hinterland(inbound, outbound)[source]
Parameters:

  • inbound (bool) – Whether to account for inbound journeys

  • outbound (bool) – Whether to account for outbound journeys

Returns:

The estimated modal split for the hinterland

Return type:

HinterlandModalSplit

get_transshipment_and_hinterland_split()[source]
Returns:

The amount of containers in TEU dedicated for or coming from the hinterland versus the amount of containers in TEU that are transshipped.

Return type:

TransshipmentAndHinterlandSplit

hypothesize_with_mode_of_transport_distribution(mode_of_transport_distribution)[source]

This allows to see the effect of different mode of transport distributions on this preview.

Parameters:

mode_of_transport_distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – A mode of transport distribution to try out

class ModalSplitPreviewReport[source]

This preview report takes the data structure as generated by ModalSplitPreview 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 ModalSplitPreviewReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a set of pie charts using pandas.

Returns:

The matplotlib axes

Return type:

Axes

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

class QuaySideThroughputPreview(start_date, end_date, transportation_buffer)[source]

This preview calculates the quayside throughput based on the schedules.

The preview returns a data structure that can be used for generating reports (e.g., in text or as a figure). The preview is intended to provide an estimate of the quayside throughput for the given inputs.

Parameters:

  • start_date (date) – The earliest day to consider for scheduled vehicles

  • end_date (date) – The latest day to consider for scheduled vehicles

  • transportation_buffer (float) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

hypothesize_with_mode_of_transport_distribution(mode_of_transport_distribution)[source]

This allows to see the effect of different mode of transport distributions on this preview.

Parameters:

mode_of_transport_distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – A mode of transport distribution to try out

class QuaySideThroughputPreviewReport[source]

This preview report takes the data structure as generated by QuaySideThroughputPreview 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 QuaySideThroughputPreviewReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented in a figure. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

A reference to the figure. The actual type depends on the plotting library.

Return type:

object

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

run_all_previews(as_text=True, as_graph=False, display_text_func=None, display_in_markup_language=None, static_graphs=False, display_as_ipython_svg=False)[source]

Runs all preview analyses in sequence. This is just a convenience function to ensure that all reports are presented. The text output is logged to the logger with the name ‘conflowgen’ by default. See setup_logger() for more details.

If neither static_graphs nor display_as_ipython_svg are true, the default functionality of the respective plotting library is used.

Parameters:

  • as_text (bool) – Whether to get the reports as text and log them.

  • as_graph (bool) – Whether to display the reports as graphs (visualizations will pop up).

  • display_text_func (Callable | None) – The function to use to display the text. Defaults to logger.info().

  • display_in_markup_language (DisplayAsMarkupLanguage | str | None) – The markup language to use. Currently, the options ‘markdown’ and ‘plaintext’ exist. Defaults to DisplayAsPlainText (same as ‘plaintext’), users can provide their own approach with DisplayAsMarkupLanguage.

  • static_graphs (bool) – Whether the graphs should be static. Plotly has some nice interactive options that are currently not supported inside some websites such as the HTML version of the documentation. In such cases, the static version of the plots is used.

  • display_as_ipython_svg (bool) – Whether the graphs should be plotted with the IPython functionality. This is suitable, e.g., inside Jupyter Notebooks where a conversion to a raster image is not desirable.

Return type:

None

class VehicleCapacityExceededPreview(start_date, end_date, transportation_buffer)[source]

The preview examines the outbound traffic and checks if the intended transportation demands can be satisfied by the existing transport capacities (per vehicle type).

The preview 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 VehicleCapacityExceededPreviewReport. The preview is intended to provide a first estimate before running ContainerFlowGenerationManager.generate() which is time-consuming. The preview does not consider all restrictions (such as container dwell times in combination with the schedules) into consideration, thus later deviations might exist.

Parameters:

  • start_date (date) – The earliest day to consider when checking the vehicles that move according to schedules

  • end_date (date) – The latest day to consider when checking the vehicles that move according to schedules

  • transportation_buffer (float) – The fraction of how much more a vehicle takes with it on an outbound journey compared to an inbound journey as long as the total vehicle capacity is not exceeded.

compare()[source]

Compare the required capacity of vehicles on their outbound journey to transport all containers and the maximum capacity of the vehicles on their outbound journey. If the maximum capacity of the vehicles is exceeded, this mismatch is indicated (per vehicle type, in TEU).

Return type:

Dict[ModeOfTransport, RequiredAndMaximumCapacityComparison]

hypothesize_with_mode_of_transport_distribution(mode_of_transport_distribution)[source]

This allows to see the effect of different mode of transport distributions on this preview.

Parameters:

mode_of_transport_distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – A mode of transport distribution to try out

class VehicleCapacityUtilizationOnOutboundJourneyPreviewReport[source]

This preview report takes the data structure as generated by VehicleCapacityExceededPreview and creates a comprehensible representation for the user, either as text or as a graph. A similar report can be found at InboundAndOutboundVehicleCapacityPreviewReport. The visual and table are expected to approximately look like in the example InboundAndOutboundVehicleCapacityPreviewReport.

get_report_as_graph(**kwargs)[source]
Returns:

The matplotlib axis of the bar chart.

Return type:

Axis

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

class TruckGateThroughputPreview(start_date, end_date, transportation_buffer)[source]

This preview shows the distribution of truck traffic throughout a given week

The preview returns a data structure that can be used for generating reports (e.g., in text or as a figure). The preview is intended to provide an estimate of the truck gate throughput for the given inputs. It does not consider all factors that may impact the actual truck gate throughput.

Parameters:

  • start_date (date) – The earliest day to consider for scheduled vehicles

  • end_date (date) – The latest day to consider for scheduled vehicles

  • transportation_buffer (float) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

hypothesize_with_mode_of_transport_distribution(mode_of_transport_distribution)[source]

This allows to see the effect of different mode of transport distributions on this preview.

Parameters:

mode_of_transport_distribution (Dict[ModeOfTransport, Dict[ModeOfTransport, float]]) – A mode of transport distribution to try out

class TruckGateThroughputPreviewReport[source]

This preview report takes the data structure as generated by TruckGateThroughputPreview 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 TruckGateThroughputPreviewReport.

get_report_as_graph(inbound=True, outbound=True, **kwargs)[source]

The report as a graph is represented in a figure. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

A reference to the figure. The actual type depends on the plotting library.

Parameters:

  • inbound (bool) –

  • outbound (bool) –

Return type:

Axes

get_report_as_text(inbound=True, outbound=True, **kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

The report in text format (possibly spanning over several lines).

Parameters:

  • inbound (bool) –

  • outbound (bool) –

Return type:

str

Running analyses

class ContainerDwellTimeAnalysis(transportation_buffer=None)[source]

This analysis can be run after the synthetic data has been generated. 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 ContainerDwellTimeAnalysisReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

get_container_dwell_times(container_delivered_by_vehicle_type='all', container_picked_up_by_vehicle_type='all', storage_requirement='all', start_date=None, end_date=None)[source]

The containers are filtered according to the provided criteria. Then, the time between the arrival of the container in the yard and the departure of the container is calculated.

Parameters:
Returns:

A set of container dwell times.

Return type:

set[timedelta]

class ContainerDwellTimeAnalysisReport[source]

This analysis report takes the data structure as generated by 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.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a line graph using pandas. For the exact interpretation of the parameter, check ContainerDwellTimeAnalysis.get_container_dwell_times().

Keyword Arguments:

  • container_delivered_by_vehicle_type – One of "all", a collection of ModeOfTransport enum values (as a list, set, or similar), or a single ModeOfTransport enum value. Defaults to all.

  • container_picked_up_by_vehicle_type – One of "all", a collection of ModeOfTransport enum values (as a list, set, or similar), or a single ModeOfTransport enum value. Defaults to all.

  • storage_requirement – One of "all", a collection of StorageRequirement enum values (as a list, set, or similar), or a single StorageRequirement enum value. Defaults to all.

  • start_date (datetime) – Only include containers that arrive after the given start time. Defaults to None.

  • end_date (datetime) – Only include containers that depart before the given end time. Defaults to None.

Returns:

The matplotlib axis of the histogram

Return type:

Axis

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. For the exact interpretation of the parameter, check ContainerDwellTimeAnalysis.get_container_dwell_times().

Keyword Arguments:

  • container_delivered_by_vehicle_type – One of "all", a collection of ModeOfTransport enum values (as a list, set, or similar), or a single ModeOfTransport enum value.

  • container_picked_up_by_vehicle_type – One of "all", a collection of ModeOfTransport enum values (as a list, set, or similar), or a single ModeOfTransport enum value.

  • storage_requirement – One of "all", a collection of StorageRequirement enum values (as a list, set, or similar), or a single StorageRequirement enum value.

  • start_date (datetime) – Only include containers that arrive after the given start time. Defaults to None.

  • end_date (datetime) – Only include containers that depart before the given end time. Defaults to None.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

class ContainerFlowAdjustmentByVehicleTypeAnalysis(transportation_buffer=None)[source]

This analysis can be run after the synthetic data has been generated. 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 ContainerFlowAdjustmentByVehicleTypeAnalysisReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

static get_initial_to_adjusted_outbound_flow(start_date=None, end_date=None)[source]

When containers are generated, in order to obey the maximum dwell time, the vehicle type that is used for onward transportation might change. The initial outbound vehicle type is the vehicle type that is drawn randomly for a container at the time of generation. The adjusted vehicle type is the vehicle type that is drawn in case no vehicle of the initial outbound vehicle type is left within the maximum dwell time.

Parameters:

  • start_date (datetime | None) – Only include containers that arrive after the given start time.

  • end_date (datetime | None) – Only include containers that depart before the given end time.

Returns:

The data structure describes how often an initial outbound vehicle type had to be adjusted with which other vehicle type.

Return type:

ContainerVolumeFromOriginToDestination

class ContainerFlowAdjustmentByVehicleTypeAnalysisReport[source]

This analysis report takes the data structure as generated by 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.

get_report_as_graph(**kwargs)[source]

The container flow is represented by a Sankey diagram.

Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The plotly figure of the Sankey diagram.

Return type:

Figure

get_report_as_text(**kwargs)[source]
Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Return type:

str

logger = <Logger conflowgen (WARNING)>

Each report can log to the console

class ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysis(transportation_buffer=None)[source]

This analysis can be run after the synthetic data has been generated. 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 ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

get_vehicle_type_adjustments_per_vehicle(initial_vehicle_type='scheduled vehicles', adjusted_vehicle_type='scheduled vehicles', start_date=None, end_date=None)[source]

When containers are generated, in order to obey the maximum dwell time, the vehicle type that is used for onward transportation might change. The initial outbound vehicle type is the vehicle type that is drawn randomly for a container at the time of generation. The adjusted vehicle type is the vehicle type that is drawn in case no vehicle of the initial outbound vehicle type is left within the maximum dwell time.

Parameters:

  • initial_vehicle_type (ModeOfTransport | str | Collection) – Either "all", scheduled vehicles, a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. Only the vehicles that correspond to the provided vehicle type(s) are considered in the analysis.

  • adjusted_vehicle_type (ModeOfTransport | str | Collection) – Either "all", scheduled vehicles, a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. Only the vehicles that correspond to the provided vehicle type(s) are considered in the analysis.

  • start_date (datetime | None) – Only include containers that arrive after the given start time.

  • end_date (datetime | None) – Only include containers that depart before the given end time.

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.

Return type:

Dict[VehicleIdentifier, int]

class ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport[source]

This analysis report takes the data structure as generated by ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysis 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 ContainerFlowVehicleTypeAdjustmentPerVehicleAnalysisReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a scatter plot using pandas.

Keyword Arguments:

  • initial_vehicle_type (typing.Any) – Either "all", a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. Only the vehicles that correspond to the provided vehicle type(s) are considered in the analysis.

  • adjusted_vehicle_type (typing.Any) – Either "all", a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. Only the vehicles that correspond to the provided vehicle type(s) are considered in the analysis.

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The matplotlib figure

Return type:

Axes

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style.

Keyword Arguments:

  • initial_vehicle_type (typing.Any) – Either "all", a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. Only the vehicles that correspond to the provided vehicle type(s) are considered in the analysis.

  • adjusted_vehicle_type (typing.Any) – Either "all", a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. Only the vehicles that correspond to the provided vehicle type(s) are considered in the analysis. Defaults to {:class:.`ModeOfTransport.deep_sea_vessel`, :class:.`ModeOfTransport.feeder`, :class:.`ModeOfTransport.barge`, :class:.`ModeOfTransport.train`}

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The report in text format spanning over several lines.

Return type:

str

class ContainerFlowAdjustmentByVehicleTypeAnalysisSummary(transportation_buffer=None)[source]

This analysis summary can be run after the synthetic data has been generated. 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 ContainerFlowAdjustmentByVehicleTypeAnalysisSummaryReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

get_summary(start_date=None, end_date=None)[source]

Under certain circumstances (as explained in ContainerFlowAdjustmentByVehicleTypeAnalysis.get_initial_to_adjusted_outbound_flow()), the containers must change the vehicle they leave the yard with. Thus, the question remains how often this has been the case and which vehicles were the primary target for this redirected traffic? The capacity is expressed in TEU.

Parameters:

  • start_date (datetime | None) – The earliest arriving container that is included. Consider all containers if None.

  • end_date (datetime | None) – The latest departing container that is included. Consider all containers if None.

Return type:

ContainerFlowAdjustedToVehicleType

class ContainerFlowAdjustmentByVehicleTypeAnalysisSummaryReport[source]

This analysis report takes the data structure as generated by ContainerFlowAdjustmentByVehicleTypeAnalysisSummary 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 ContainerFlowAdjustmentByVehicleTypeAnalysisSummaryReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a pie chart.

Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time. Defaults to None.

  • end_date (datetime) – Only include containers that depart before the given end time. Defaults to None.

Returns:

The matplotlib axis of the pie chart.

Return type:

Axis

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style.

Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time. Defaults to None.

  • end_date (datetime) – Only include containers that depart before the given end time. Defaults to None.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

class ContainerFlowByVehicleTypeAnalysis(transportation_buffer=None)[source]

This analysis can be run after the synthetic data has been generated. 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 ContainerFlowByVehicleTypeAnalysisReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

static get_inbound_to_outbound_flow(start_date=None, end_date=None)[source]

This is the overview of the generated inbound to outbound container flow by vehicle type.

Parameters:

  • start_date (datetime | None) – The earliest arriving container that is included. Consider all containers if None.

  • end_date (datetime | None) – The latest departing container that is included. Consider all containers if None.

Return type:

ContainerVolumeFromOriginToDestination

class ContainerFlowByVehicleTypeAnalysisReport[source]

This analysis report takes the data structure as generated by ContainerFlowByVehicleTypeAnalysis 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 ContainerFlowByVehicleTypeAnalysisReport.

get_report_as_graph(**kwargs)[source]

The container flow is represented by a Sankey diagram.

Keyword Arguments:

unit (str) – One of “TEU”, “containers”, or “both”. Defaults to “both” if none provided.

Returns:

The plotly figure(s) of the Sankey diagram.

Return type:

Collection[Figure]

get_report_as_text(**kwargs)[source]
Keyword Arguments:

  • unit (str) – One of “teu”, “container”, or “both”. Defaults to “both” if none provided.

  • start_date (datetime) – The earliest arriving container that is included. Consider all containers if None.

  • end_date (datetime) – The latest departing container that is included. Consider all containers if None.

Returns:

The report in human-readable text format

Return type:

str

logger = <Logger conflowgen (WARNING)>

Each report can log to the console

class InboundAndOutboundVehicleCapacityAnalysis(transportation_buffer)[source]

This analysis can be run after the synthetic data has been generated. 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 InboundAndOutboundVehicleCapacityAnalysisReport.

Parameters:

transportation_buffer (float) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

static get_inbound_container_volumes_by_vehicle_type(start_date=None, end_date=None)[source]

This is the used capacity of all vehicles separated by vehicle type on their inbound journey in TEU.

Parameters:

  • start_date (datetime | None) – Only include containers that arrive after the given start time.

  • end_date (datetime | None) – Only include containers that depart before the given end time.

Return type:

ContainerVolumeByVehicleType

get_outbound_container_volume_by_vehicle_type(start_date=None, end_date=None)[source]

This is the used and the maximum capacity of all vehicles separated by vehicle type on their outbound journey in TEU. If for a vehicle type, the used capacity is very close to the maximum capacity, you might want to reconsider the mode of transport distribution. See ModeOfTransportDistributionManager for further details.

Parameters:

  • start_date (datetime | None) – Only include containers that arrive after the given start time.

  • end_date (datetime | None) – Only include containers that depart before the given end time.

Returns:

Both the used and maximum outbound capacities grouped by vehicle type.

Return type:

OutboundUsedAndMaximumCapacity

class InboundAndOutboundVehicleCapacityAnalysisReport[source]

This analysis report takes the data structure as generated by InboundAndOutboundVehicleCapacityAnalysis 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 InboundAndOutboundVehicleCapacityAnalysisReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a bar chart using pandas.

Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The matplotlib axis of the bar chart.

Return type:

Axis

get_report_as_text(**kwargs)[source]
Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The report in text format spanning over several lines.

Return type:

str

class InboundToOutboundVehicleCapacityUtilizationAnalysis(transportation_buffer)[source]

This analysis can be run after the synthetic data has been generated. 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 InboundToOutboundCapacityUtilizationAnalysisReport.

Parameters:

transportation_buffer (float) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

get_inbound_and_outbound_capacity_of_each_vehicle(vehicle_type='scheduled vehicles', start_date=None, end_date=None)[source]
Parameters:

  • vehicle_type (Any) – Either "scheduled vehicles", a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. Only the vehicles that correspond to the provided vehicle type(s) are considered in the analysis.

  • start_date (datetime | None) – Only include containers that arrive after the given start time.

  • end_date (datetime | None) – Only include containers that depart before the given end time.

Returns:

The transported containers of each vehicle on their inbound and outbound journey in TEU.

Return type:

Dict[VehicleIdentifier, Tuple[float, float]]

class InboundToOutboundVehicleCapacityUtilizationAnalysisReport[source]

This analysis report takes the data structure as generated by InboundToOutboundCapacityUtilizationAnalysis 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 InboundToOutboundVehicleCapacityUtilizationAnalysisReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a scatter plot using pandas.

Keyword Arguments:

  • plot_type (str) – Either "absolute", "relative", "absolute and relative", "over time", or "all". Defaults to “all”.

  • vehicle_type (Any) – Either "all", a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. For the exact interpretation of the parameter, check InboundToOutboundVehicleCapacityUtilizationAnalysis. Defaults to "all".

  • start_date (datetime) – Only include containers that arrive after the given start time. Defaults to None.

  • end_date (datetime) – Only include containers that depart before the given end time. Defaults to None.

Returns:

The matplotlib figure

Return type:

Figure

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style.

Keyword Arguments:

  • vehicle_type (Any) – Either "scheduled vehicles", a single vehicle of type ModeOfTransport or a whole collection of vehicle types, e.g., passed as a list or set. For the exact interpretation of the parameter, check InboundToOutboundVehicleCapacityUtilizationAnalysis.

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The report in text format spanning over several lines.

Return type:

str

class ModalSplitAnalysis[source]

This analysis can be run after the synthetic data has been generated. 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 ModalSplitAnalysisReport.

get_modal_split_for_hinterland_traffic(inbound, outbound, start_date=None, end_date=None)[source]
Parameters:

  • inbound (bool) – Whether to account for inbound journeys

  • outbound (bool) – Whether to account for outbound journeys

  • start_date (datetime | None) – Only include containers that arrive after the given start time.

  • end_date (datetime | None) – Only include containers that depart before the given end time.

Returns:

The modal split for the hinterland in TEU.

Return type:

HinterlandModalSplit

get_transshipment_and_hinterland_split(start_date=None, end_date=None)[source]
Parameters:

  • start_date (datetime | None) – Only include containers that arrive after the given start time.

  • end_date (datetime | None) – Only include containers that depart before the given end time.

Returns:

The amount of containers in TEU dedicated for or coming from the hinterland versus the amount of containers in TEU that are transshipped.

Return type:

TransshipmentAndHinterlandSplit

class ModalSplitAnalysisReport[source]

This analysis report takes the data structure as generated by ModalSplitAnalysis 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 ModalSplitAnalysisReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a set of pie charts using pandas.

Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The matplotlib axes with all pie charts.

Return type:

Axes

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style.

Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time. Defaults to None`.

  • end_date (datetime) – Only include containers that depart before the given end time. Defaults to None.

Return type:

str

class QuaySideThroughputAnalysis(transportation_buffer=None)[source]

This analysis can be run after the synthetic data has been generated. 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 QuaySideThroughputAnalysisReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

classmethod get_throughput_over_time(inbound=True, outbound=True, start_date=None, end_date=None)[source]

For each week, the containers crossing the quay are checked. Based on this, the required quay capacity in boxes can be deduced - it is the maximum of these values (based on all the assumptions, in reality an additional buffer might be reasonable to add).

The rather coarse time window is due to the fact that the discharging and loading process are not modelled. At this stage, as a simplification all containers arriving with a vessel are discharged at once and all containers departing with a vessel are loaded at once. This is smoothed by the larger time window.

Parameters:

  • inbound (bool) – Whether to check for vessels which deliver a container on their inbound journey

  • outbound (bool) – Whether to check for vessels which pick up a container on their outbound journey

  • start_date (datetime | None) – The earliest arriving container that is included. Consider all containers if None.

  • end_date (datetime | None) – The latest departing container that is included. Consider all containers if None.

Return type:

Dict[date, float]

class QuaySideThroughputAnalysisReport[source]

This analysis report takes the data structure as generated by QuaySideThroughputAnalysis 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 QuaySideThroughputAnalysisReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a line graph using pandas.

Keyword Arguments:

  • start_date (datetime) – Only include containers that arrive after the given start time.

  • end_date (datetime) – Only include containers that depart before the given end time.

Returns:

The matplotlib axis of the line chart over time.

Return type:

Axis

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style. The additional keyword arguments are passed to the analysis instance in case it accepts them.

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

run_all_analyses(as_text=True, as_graph=False, display_text_func=None, display_in_markup_language=None, static_graphs=False, display_as_ipython_svg=False, start_date=None, end_date=None)[source]

Runs all post-hoc analyses in sequence. This is just a convenience function to ensure that all reports are presented. The text output is logged to the logger with the name ‘conflowgen’ by default.. See setup_logger() for more details.

If neither static_graphs nor display_as_ipython_svg are true, the default functionality of the respective plotting library is used.

Parameters:

  • as_text (bool) – Whether to get the reports as text and log them

  • as_graph (bool) – Whether to display the reports as graphs (visualizations will pop up)

  • display_text_func (Callable | None) – The function to use to display the text. Defaults to logger.info().

  • display_in_markup_language (DisplayAsMarkupLanguage | str | None) – The markup language to use. Currently, the options ‘markdown’ and ‘plaintext’ exist. Defaults to DisplayAsPlainText (same as ‘plaintext’), users can provide their own approach with DisplayAsMarkupLanguage.

  • static_graphs (bool) – Whether the graphs should be static. Plotly has some nice interactive options that are currently not supported inside some websites such as the HTML version of the documentation. In such cases, the static version of the plots is used.

  • display_as_ipython_svg (bool) – Whether the graphs should be plotted with the IPython functionality. This is suitable, e.g., inside Jupyter Notebooks where a conversion to a raster image is not desirable.

  • start_date (datetime | None) – Only include containers that arrive after the given start time (if supported by the report).

  • end_date (datetime | None) – Only include containers that depart before the given end time (if supported by the report).

Return type:

None

class TruckGateThroughputAnalysis(transportation_buffer=None)[source]

This analysis can be run after the synthetic data has been generated. 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 TruckGateThroughputAnalysisReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

classmethod get_throughput_over_time(inbound=True, outbound=True, start_date=None, end_date=None)[source]

For each hour, the trucks entering through the truck gate are checked. Based on this, the required truck gate capacity in boxes can be deduced.

Parameters:

  • inbound (bool) – Whether to check for trucks which deliver a container on their inbound journey

  • outbound (bool) – Whether to check for trucks which pick up a container on their outbound journey

  • start_date (datetime | None) – When to start recording. Start with the earliest container if no date is provided.

  • end_date (datetime | None) – When to end recording. Stop with the latest container if no date is provided.

Return type:

Dict[datetime, float]

class TruckGateThroughputAnalysisReport[source]

This analysis report takes the data structure as generated by TruckGateThroughputAnalysis 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 TruckGateThroughputAnalysisReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a line graph using pandas.

Keyword Arguments:

  • start_date (datetime) – When to start recording

  • end_date (datetime) – When to end recording

  • inbound (bool) – Whether to check for trucks which deliver a container on their inbound journey

  • outbound (bool) – Whether to check for trucks which pick up a container on their outbound journey

  • ax (Axis) – Which matplotlib axis to plot on.

Returns:

The matplotlib axis of the plot over time.

Return type:

Axis

get_report_as_text(**kwargs)[source]
Keyword Arguments:

  • start_date (datetime) – When to start recording

  • end_date (datetime) – When to end recording

  • inbound (bool) – Whether to check for trucks which deliver a container on their inbound journey

  • outbound (bool) – Whether to check for trucks which pick up a container on their outbound journey

Returns:

The report in text format.

Return type:

str

class YardCapacityAnalysis(transportation_buffer=None)[source]

This analysis can be run after the synthetic data has been generated. 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 YardCapacityAnalysisReport.

Parameters:

transportation_buffer (Optional[float]) – The buffer, e.g. 0.2 means that 20% more containers (in TEU) can be put on a vessel compared to the amount of containers it had on its inbound journey - as long as the total vehicle capacity would not be exceeded.

get_used_yard_capacity_over_time(storage_requirement='all', smoothen_peaks=True)[source]

For each hour, the containers entering and leaving the yard are checked. Based on this, the required yard capacity in TEU can be deduced - it is simply the maximum of these values. In addition, with the parameter storage_requirement the yard capacity can be filtered, e.g., to only include standard containers, empty containers, or any other kind of subset.

Please be aware that this method slightly overestimates the required capacity if smoothen_peaks is set to false. When one container leaves the yard at the beginning of the respective time window and another container enters the yard at the end of the same time window, still the TEU equivalence of both containers is recorded as the required yard capacity for that time window. Obviously, in that case the entering container could use the slot previously used by the container which left earlier. This, however, is not true if the container enters the terminal before the other container leaves. This minor inaccuracy might be of little importance because no yard should be planned that tight. If, on the other hand, smoothen_peaks is set to true, the last time window is not recorded as occupied. This slightly underestimates the required capacity but leads to visually more appealing curves with fewer spikes.

Parameters:
Returns:

A namedtuple consisting of two dictionaries. The first dictionary represents the used yard capacity in TEU over the time. The second dictionary represents the used yard capacity in terms of the number of boxes over the time.

Return type:

UsedYardCapacityOverTime

class YardCapacityAnalysisReport[source]

This analysis report takes the data structure as generated by YardCapacityAnalysis 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 YardCapacityAnalysisReport.

get_report_as_graph(**kwargs)[source]

The report as a graph is represented as a line graph using pandas.

Keyword Arguments:

storage_requirement – Either a single storage requirement of type StorageRequirement or a whole collection of them, e.g., passed as a list or set. For the exact interpretation of the parameter, check YardCapacityAnalysis.get_used_yard_capacity_over_time().

Returns:

The matplotlib axis of the plot over time.

Return type:

Axis

get_report_as_text(**kwargs)[source]

The report as a text is represented as a table suitable for logging. It uses a human-readable formatting style.

Keyword Arguments:

storage_requirement – Either a single storage requirement of type StorageRequirement or a whole collection of them, e.g., passed as a list or set. For the exact interpretation of the parameter, check YardCapacityAnalysis.get_used_yard_capacity_over_time().

Returns:

The report in text format (possibly spanning over several lines).

Return type:

str

Using distributions

Most of the distributions in ConFlowGen are discrete distributions and are just reflected by classic Python dictionaries where the key refers to the element to be drawn and the value is the probability. In some cases, such as container dwell times, continuous distributions are required.

class ContinuousDistribution(average, minimum, maximum, unit=None)[source]
Parameters:

  • average (float) – The expected mean of the distribution.

  • minimum (float) – The minimum of the distribution. Smaller values are automatically set to zero.

  • maximum (float) – The maximum of the distribution. Larger values are automatically set to zero.

  • unit (Optional[str]) – The unit for the average, minimum, and maximum. It is used for the __repr__ implementation.

abstract classmethod from_database_entry(entry)[source]
Parameters:

entry (ContainerDwellTimeDistributionInterface) – The database entry describing a continuous distribution.

Returns:

The loaded distribution instance.

Return type:

Type[ContinuousDistribution]

get_probabilities(xs, reversed_distribution=False)[source]
Parameters:

  • xs (Sequence[float]) – Elements that are on the same scale as average, variance, minimum, and maximum

  • reversed_distribution (bool) – Whether to reverse the probabilities

Returns:

The respective probability that element x of xs is drawn from this distribution.

Return type:

ndarray

class ContainerDwellTimeDistributionInterface[source]
average_number_of_hours: float

The average number of hours is the expected mean of the distribution.

delivered_by: ModeOfTransport

The vehicle type the box is delivered by.

distribution_name: str

The distribution to use in that specific case.

maximum_number_of_hours: float

To avoid unrealistic long times, values longer than this are not drawn from the distribution.

minimum_number_of_hours: float

To avoid unrealistic short times, values shorter than this are not drawn from the distribution.

picked_up_by: ModeOfTransport

The vehicle type the box is picked up by.

storage_requirement: StorageRequirement

The storage requirement of the box.

variance: float | None

The variance is a distribution-specific parameter and helps to instantiate, e.g., normal or lognormal distributions.

Working with reports

When working with run_all_previews() or run_all_analyses(), there is some common functionality. If you wish to add another markup language besides plaintext and markdown for these two lists of reports, you can define them here and pass them as parameters to the aforementioned functions.

class DisplayAsMarkdown(display_func)[source]

With this style, the output is set in Markdown. This is, e.g., helpful when showing the output in Jupyter Notebooks.

Parameters:

display_func (Callable) – The function that is invoked to display the text

display_explanation(text)[source]
Parameters:

text (str) – The text of an explanatory text (shown in normal font, wrapped if required). Different paragraphs are separated by repeated invocations of this method.

Return type:

None

display_headline(text, level=4)[source]
Parameters:

  • text (str) – The text of the headline

  • level (int) – The level of the headline, 1 being the upmost headline. The number of levels depends on the markup language.

Return type:

None

display_verbatim(text)[source]
Parameters:

text (str) – The text of the verbatim block (shown as-is)

Return type:

None

class DisplayAsMarkupLanguage(display_func)[source]

This is the abstract class new markup language definitions can derive from.

Parameters:

display_func (Callable) – The function that is invoked to display the text

abstract display_explanation(text)[source]
Parameters:

text (str) – The text of an explanatory text (shown in normal font, wrapped if required). Different paragraphs are separated by repeated invocations of this method.

Return type:

None

abstract display_headline(text, level)[source]
Parameters:

  • text (str) – The text of the headline

  • level (int) – The level of the headline, 1 being the upmost headline. The number of levels depends on the markup language.

Return type:

None

abstract display_verbatim(text)[source]
Parameters:

text (str) – The text of the verbatim block (shown as-is)

Return type:

None

class DisplayAsPlainText(display_func)[source]

With this style, the output is simply returned in a plain manner. This is, e.g., helpful when logging the text.

Parameters:

display_func (Callable) – The function that is invoked to display the text

display_explanation(text)[source]
Parameters:

text (str) – The text of an explanatory text (shown in normal font, wrapped if required). Different paragraphs are separated by repeated invocations of this method.

Return type:

None

display_headline(text, level=-1)[source]
Parameters:

  • text (str) – The text of the headline.

  • level (int) – The level of the headline is not supported for the plaintext mode.

Return type:

None

display_verbatim(text)[source]
Parameters:

text (str) – The text of the verbatim block (shown as-is)

Return type:

None

class DataSummariesCache[source]

This class is used to cache the results of the data summaries (analyses and previews). This is useful when the same data summary is requested multiple times, e.g., when generating a report. In this case, the data summary computation is only performed once and the result is cached. The next time the same data summary is requested, the cached result is returned instead of computing the data summary again. This can significantly speed up the report generation process. To use this class, simply decorate the data summary function with the DataSummariesCache.cache_result() decorator. The cache is automatically reset when input data changes or a new database is used. This can also be done manually by calling DataSummariesCache.reset_cache().

classmethod cache_result(func)[source]

Decorator function to accept function as argument, and return cached result if available or compute and cache result.

classmethod reset_cache()[source]

Resets the cache.

Exporting data

class ExportContainerFlowManager[source]

In the SQLite databases all data is stored. This might not be the right format for further usage though. This manager provides the interface to export the container flow, excluding the input distributions etc., so that they can be read in easily for the next step, e.g., a routine in a simulation model or mathematical optimization script.

export(folder_name, path_to_export_folder=None, file_format=None, overwrite=False)[source]

This extracts the container movement data from the SQL database to a folder of choice in a tabular data format.

Parameters:

  • folder_name (str) – Name of folder that bundles the tabular data which belongs together

  • path_to_export_folder (str | None) – Path to directory where all exports are kept, defaults to <project root>/data/exports/

  • file_format (ExportFileFormat | None) – Desired tabular format, defaults to ExportFileFormat.csv.

  • overwrite (bool) – Whether to overwrite previously exported data, defaults to False

Returns:

The path to the folder where the tabular data is located

Return type:

str

enum ExportFileFormat(value)[source]

The export file format supports tables. The export function enables the user to read in the generated synthetic data into another tool, such as a software for mathematical optimization or discrete event simulation.

Valid values are as follows:

csv = <ExportFileFormat.csv: 'csv'>

Comma-separated values files are very simplistic representation but unrestricted and widely supported.

xlsx = <ExportFileFormat.xlsx: 'xlsx'>

The xlsx file format can be opened by, e.g., Microsoft Excel which might help to quickly analyse the output data. However, this file format comes with known limitations listed at https://support.microsoft.com/en-us/office/excel-specifications-and-limits-1672b34d-7043-467e-8e27-269d656771c3. On January 4th, 2022, the known maximum number of rows is 1,048,576. Thus, if, e.g., 1.1 million containers are generated, opening this xlsx file in Excel is not supported by the specifications.

xls = <ExportFileFormat.xls: 'xls'>

The xls format is the precursor of the xlsx format. This should only be used if a software demands this file format. Older versions of Excel had more restrictions on the size, e.g. Excel 2003 is known to have only supported 65,536 rows (see, e.g., http://web.archive.org/web/20140819001409/http://news.office-watch.com/t/n.aspx?articleid=1408&zoneid=9) which is less than what large terminals nowadays handle within a month. Even with a hypothetical TEU factor of 2, this only reaches 1,572,864 TEU throughput per year.