starling_sim.utils.utils

This module contains utils for the Starling framework.

Module Contents

Functions

json_dump(data, filepath)

Create a json file and dump the given object

json_pretty_dump(data, filepath)

Creates a json file and dumps the given object

json_load(filepath)

Loads the content of the given json file

gz_compression(filepath[, delete_source])

Compress the given file using gzip.

gz_decompression(filepath[, delete_source])

Decompress the given file using gzip.

create_file_information(filepath, mimetype[, ...])

Create a dict containing file information.

validate_against_schema(instance, schema[, ...])

add_defaults_and_validate(instance, schema[, ...])

add_defaults(instance, schema[, current_prop])

load_schema(schema[, make_copy])

get_sec(time_str)

Get Seconds from time.

make_int(a)

Convert the given integer to the Python int type.

new_point_feature([point_localisation, properties])

param point_localisation:

new_line_string_feature(linestring[, properties])

new_multi_polygon_feature(polygon_list[, properties])

param polygon_list:

list of polygon coordinates.

new_feature(geometry[, properties])

new_feature_collection([features])

param features:

shapely_polygon_from_points(points[, reverse])

Create and return a Shapely Polygon object.

geopandas_points_from_localisations(localisations)

Create and return a GeoDataFrame containing shapely Point objects.

geopandas_polygon_from_points(points)

Create and return a GeoDataFrame containing a single polygon.

points_in_zone(localisations, zone)

Evaluate if the given points are contained in the zone.

stops_table_from_geojson(geojson_path)

Create a stops table from the provided geojson file.

stop_table_from_gtfs(gtfs_feed[, routes, zone, ...])

import_osm_graph(method, network_type, simplify[, ...])

Generate an OSM graph from given parameters and store it in a file.

osm_graph_from_point(point, distance, network_type, ...)

Import an OSM graph of an area around the location point.

osm_graph_from_polygon(polygon_points, network_type, ...)

Import an OSM graph of the area within the polygon.

osm_graph_from_place(query, which_result, ...)

Import an OSM graph of the area described by the geocodable query.

save_osm_graph(graph, filename, folder)

Save the given graph in a .graphml file.

osm_graph_from_file(filename[, folder])

Import an osm graph from a .graphml file.

import_gtfs_feed(gtfs_filename[, ...])

Import a gtfs feed from the given file.

transitively_closed_transfers(transfers, ...)

Restrict the transfer table under the given time limit and then make it transitive.

is_transitive(transfers)

Test if the given transfer table is transitive.

make_transfers_transitively_closed(transfers)

Make the given transfer table transitive by incrementally adding transition transfers.

stops2geojson(stops_df)

Create a geojson FeatureCollection from the GTFS stops.

transfers2geojson(transfers_df, stops_df)

Create a geojson FeatureCollection from the GTFS transfers.

create_if_not_exists(folder)

Test the existence of the folder and create it if not present.

display_horizontal_bar([lvl])

Display a horizontal bar in the terminal.

create_sub_scenarios(simulation_scenario)

exception starling_sim.utils.utils.StarlingException

Bases: Exception

Base class for all Starling exceptions.

exception starling_sim.utils.utils.LeavingSimulation

Bases: StarlingException

Exception raised by agents for leaving the simulation.

Agents should raise this exception by calling their leave_simulation() method to leave their loop and terminate their SimPy process.

LeavingSimulation exceptions are caught in the agent simpy_loop_() method so a LeavingSimulationEvent can be traced and the agent main process can terminate.

exception starling_sim.utils.utils.SimulationError

Bases: LeavingSimulation

Simulation error exception.

This exception should be used when an unwanted event occurs in a simulation, like saying “We shouldn’t be here”.

exception starling_sim.utils.utils.PlanningChange(msg=DEFAULT_MESSAGE, *args)

Bases: Exception

Exception raised to interrupt a service vehicle loop when its planning has changed.

DEFAULT_MESSAGE = 'The service vehicle planning has been changed during service activity. Catch this exception to...'
starling_sim.utils.utils.json_dump(data, filepath)

Create a json file and dump the given object

Parameters:

  • data –

  • filepath –

Returns:

starling_sim.utils.utils.json_pretty_dump(data, filepath)

Creates a json file and dumps the given object in a pretty print way

Parameters:

  • data – object to be dumped into the json file

  • filepath – path to the json file

starling_sim.utils.utils.json_load(filepath)

Loads the content of the given json file

Parameters:

filepath – path to the json file

Returns:

object loaded from json file

starling_sim.utils.utils.gz_compression(filepath, delete_source=True)

Compress the given file using gzip.

Delete the source file if asked.

Parameters:

  • filepath – path pointing to the source file

  • delete_source – boolean indicating if the source file should be deleted

starling_sim.utils.utils.gz_decompression(filepath, delete_source=True)

Decompress the given file using gzip.

Delete the source file if asked.

Parameters:

  • filepath – path pointing to the source file

  • delete_source – boolean indicating if the source file should be deleted

Raises:

ValueError if the filepath does not end with ‘.gz’

starling_sim.utils.utils.create_file_information(filepath, mimetype, compressed_mimetype=None, content=None, subject=None, keep_filepath=False)

Create a dict containing file information.

Parameters:

  • filepath – file path

  • mimetype – file mimetype

  • compressed_mimetype – file mimetype after decompression

  • content – content metadata

  • subject – subject metadata

  • keep_filepath – keep complete file path in ‘filename’

Returns:

{ filename/filepath, mimetype, metadata }

starling_sim.utils.utils.validate_against_schema(instance, schema, raise_exception=True)
starling_sim.utils.utils.add_defaults_and_validate(instance, schema, raise_exception=True)
starling_sim.utils.utils.add_defaults(instance, schema, current_prop=None)
starling_sim.utils.utils.load_schema(schema, make_copy=True)
starling_sim.utils.utils.get_sec(time_str)

Get Seconds from time.

starling_sim.utils.utils.make_int(a)

Convert the given integer to the Python int type.

Check that the given number is an Integral, and raise a ValueError if it is not the case.

Parameters:

a – integer to check

Returns:

integer with Python int type

starling_sim.utils.utils.new_point_feature(point_localisation=None, properties=None)
Parameters:

  • point_localisation –

  • properties –

Returns:

starling_sim.utils.utils.new_line_string_feature(linestring, properties=None)
starling_sim.utils.utils.new_multi_polygon_feature(polygon_list, properties=None)
Parameters:

  • polygon_list – list of polygon coordinates.

  • properties –

Returns:

starling_sim.utils.utils.new_feature(geometry, properties=None)
starling_sim.utils.utils.new_feature_collection(features=None)
Parameters:

features –

Returns:

starling_sim.utils.utils.shapely_polygon_from_points(points, reverse=False)

Create and return a Shapely Polygon object.

The polygon is initialised using the given list of tuples representing coordinates. If reverse is True, the coordinates values are inverted. This can be used to set GPS coordinates in order, for instance.

Parameters:

  • points – list of lists containing point coordinates

  • reverse – boolean indicating if coordinates should be reversed. Default is False.

Returns:

Shapely Polygon object

starling_sim.utils.utils.geopandas_points_from_localisations(localisations)

Create and return a GeoDataFrame containing shapely Point objects.

localisations can either be a tuple or list describing a single (lat, lon) point, or a Dataframe containing a ‘lat’ and a ‘lon’ column.

The localisations must be specified using “epsg:4326”

Parameters:

localisations – either a single point (lat, lon) coordinates, or a Dataframe containing a ‘lat’ and a ‘lon’ column, “epsg:4326”

Returns:

GeoDataFrame containing shapely Point objects with crs=”epsg:4326”

starling_sim.utils.utils.geopandas_polygon_from_points(points)

Create and return a GeoDataFrame containing a single polygon.

The GeoDataFrame contains a Shapely Polygon object created using the given points, and stored in the first line of the ‘geometry’ column.

The point coordinates are reversed to have a zone specified with (lon, lat) points, with “epsg:4326”

Parameters:

points – list of coordinates, must be (lon, lat) points.

Returns:

GeoDataFrame containing a shapely Polygon with crs=”epsg:4326”

starling_sim.utils.utils.points_in_zone(localisations, zone)

Evaluate if the given points are contained in the zone.

localisations can either be a tuple or list describing a single (lat, lon) point, or a DataFrame containing a ‘lat’ and a ‘lon’ column.

The function either returns a boolean if a single point is provided, or adds a “in_zone” column to the DataFrame containing booleans.

Parameters:

  • localisations – either a single point (lat, lon) coordinates, or a DataFrame containing a ‘lat’ and a ‘lon’ column, “epsg:4326”

  • zone – GeoDataFrame containing a shapely Polygon with crs=”epsg:4326”

Returns:

either a boolean, or the localisations DataFrame with an additional “in_zone” column containing booleans.

starling_sim.utils.utils.stops_table_from_geojson(geojson_path)

Create a stops table from the provided geojson file.

Parameters:

geojson_path –

Returns:

a DataFrame containing the stops information

starling_sim.utils.utils.stop_table_from_gtfs(gtfs_feed, routes=None, zone=None, fixed_stops=None, active_stops_only=False)
starling_sim.utils.utils.import_osm_graph(method, network_type, simplify, query=None, which_result=None, point=None, dist=None, polygon=None, outfile=None)

Generate an OSM graph from given parameters and store it in a file.

The osmnx function used to generate the OSM graph is specified by the method parameter.

The correct parameters must be provided according to the import method.

Parameters:

  • method – name of the osmnx import method. Among [‘place’, ‘point’, ‘polygon’].

  • network_type – OSM network_type of the graph

  • simplify – boolean indicating if the graph should be simplified

  • query – string, dict or list describing the place (must be geocodable)

  • which_result – integer describing which geocoding result to use, or None to auto-select the first (Multi)Polygon

  • point – [lon, lat] coordinates of the center point

  • dist – distance of the bbox from the center point

  • polygon – list of points describing a polygon

  • outfile – optional name for the output file

starling_sim.utils.utils.osm_graph_from_point(point, distance, network_type, simplify)

Import an OSM graph of an area around the location point.

The import is done with the distance_type parameter set to ‘bbox’.

Parameters:

  • point – (lon, lat) point

  • distance – distance around point

  • network_type – osm network type

  • simplify – boolean indicating if the graph should be simplified

Returns:

a networkx graph

starling_sim.utils.utils.osm_graph_from_polygon(polygon_points, network_type, simplify)

Import an OSM graph of the area within the polygon.

Parameters:

  • polygon_points – list of (lon, lat) points delimiting the network zone

  • network_type – osm network type

  • simplify – boolean indicating if the graph should be simplified

Returns:

a networkx graph

starling_sim.utils.utils.osm_graph_from_place(query, which_result, network_type, simplify)

Import an OSM graph of the area described by the geocodable query.

Parameters:

  • query – string, dict or list describing the place (must be geocodable)

  • which_result – integer describing which geocoding result to use, or None to auto-select the first (Multi)Polygon

  • network_type – osm network type

  • simplify – boolean indicating if the graph should be simplified

Returns:

a networkx graph

starling_sim.utils.utils.save_osm_graph(graph, filename, folder)

Save the given graph in a .graphml file.

Detect if the filename ends with ‘.bz2’, and realise a bz2 compression accordingly.

Parameters:

  • graph – saved graph

  • filename – name of the save file

  • folder – name of the save folder

starling_sim.utils.utils.osm_graph_from_file(filename, folder=None)

Import an osm graph from a .graphml file.

Parameters:

  • filename – path to the .graphml file

  • folder – folder containing the .graphml file. Default is the osm graphs folder.

Returns:

a networkx graph, or None if import fails

starling_sim.utils.utils.import_gtfs_feed(gtfs_filename, transfer_restriction=None, folder=None)

Import a gtfs feed from the given file.

Also check that stop times are ordered and transfers are symmetrical.

Parameters:

  • gtfs_filename – name of a gtfs file

  • transfer_restriction – duration restriction on the transfers

  • folder – folder where the gtfs is stored. Default is the GTFS_FEEDS_FOLDER.

Returns:

gtfs-kit Feed object

starling_sim.utils.utils.transitively_closed_transfers(transfers, restrict_transfer_time)

Restrict the transfer table under the given time limit and then make it transitive.

The restriction on the transfer times help keeping the transfer table at a reasonable size after making it transitive.

Parameters:

  • transfers – transfer table

  • restrict_transfer_time – transfer duration limit

Returns:

transitive closure of the restricted transfer table

starling_sim.utils.utils.is_transitive(transfers)

Test if the given transfer table is transitive.

Parameters:

transfers – transfer table

Returns:

boolean indicating if the table is transitive

starling_sim.utils.utils.make_transfers_transitively_closed(transfers)

Make the given transfer table transitive by incrementally adding transition transfers.

If transfers from A to B and from B to C exist, create a transfer from A to C. If several transfers from A to C exist, keep the one with shorter transfer duration. Repeat.

Parameters:

transfers – transfer table

Returns:

transitive closure of the given transfer table

starling_sim.utils.utils.stops2geojson(stops_df)

Create a geojson FeatureCollection from the GTFS stops.

Parameters:

stops_df – stops DataFrame of the GTFS

Returns:

feature collection

starling_sim.utils.utils.transfers2geojson(transfers_df, stops_df)

Create a geojson FeatureCollection from the GTFS transfers.

Parameters:

  • transfers_df – transfers DataFrame of the GTFS

  • stops_df – stops DataFrame of the GTFS

Returns:

feature collection

starling_sim.utils.utils.create_if_not_exists(folder)

Test the existence of the folder and create it if not present.

Parameters:

folder – path of the folder

starling_sim.utils.utils.display_horizontal_bar(lvl=20)

Display a horizontal bar in the terminal.

Try to make it the size of the terminal width.

Parameters:

lvl – log level

starling_sim.utils.utils.create_sub_scenarios(simulation_scenario)