sibi-dst 0.3.32__py3-none-any.whl → 0.3.34__py3-none-any.whl

sibi_dst/osmnx_helper/base_osm_map.py

@@ -11,6 +11,64 @@ from folium.plugins import Fullscreen
 
 
 class BaseOsmMap:
+    """
+    BaseOsmMap class serves as a foundational class for creating and managing maps
+    using OpenStreetMap data. It integrates features from libraries like osmnx and
+    folium to facilitate visualization, tile layer management, bounding box handling,
+    and nearest node calculation for geographic coordinates.
+
+    The class is designed to be subclassed, enabling customization of map processing
+    logic while providing core functionalities needed for map creation and manipulation.
+
+    :ivar tile_options: Dictionary containing options for pre-defined tile layers.
+                        Keys represent display names while values represent tile layer configurations.
+    :type tile_options: dict
+    :ivar bounds: Default map bounds representing geographical extents for Costa Rica.
+    :type bounds: list[list[float]]
+    :ivar osmnx_graph: Input graph representing OpenStreetMap network data, used for
+                       operations like subgraph extraction and nearest node calculation.
+    :type osmnx_graph: networkx.classes.multidigraph.MultiDiGraph
+    :ivar df: DataFrame containing data points with geographic coordinates. It must
+              not be empty and should include latitude and longitude columns as specified
+              in `lat_col` and `lon_col`.
+    :type df: pandas.DataFrame
+    :ivar lat_col: Name of the column in `df` representing latitude coordinates of data points.
+    :type lat_col: str
+    :ivar lon_col: Name of the column in `df` representing longitude coordinates of data points.
+    :type lon_col: str
+    :ivar osm_map: Folium Map object that serves as a container for geographic visualization.
+                   This is dynamically initialized based on the provided data.
+    :type osm_map: folium.Map
+    :ivar G: Subgraph of the provided `osmnx_graph`, extracted based on bounding box
+             derived from the input data.
+    :type G: networkx.classes.multidigraph.MultiDiGraph
+    :ivar map_html_title: HTML-escaped title for map visualization, shown on the interactive map.
+    :type map_html_title: str
+    :ivar zoom_start: Initial zoom level for the map when rendered.
+    :type zoom_start: int
+    :ivar fullscreen: Boolean option to enable or disable fullscreen control on the interactive map.
+    :type fullscreen: bool
+    :ivar fullscreen_position: Position of the fullscreen control on the map, e.g., 'topright'.
+    :type fullscreen_position: str
+    :ivar tiles: Default tile layer to be used for the map visualization.
+    :type tiles: str
+    :ivar verbose: Boolean flag indicating if verbose logging of operations should be enabled.
+    :type verbose: bool
+    :ivar sort_keys: Keys to sort the DataFrame by, if applicable, before processing.
+    :type sort_keys: list[str] or None
+    :ivar dt_field: Column name in `df` representing datetimes, if applicable, for specialized processing.
+    :type dt_field: str or None
+    :ivar dt: List of datetime objects extracted from `dt_field` in `df`, dynamically initialized.
+    :type dt: list[datetime.datetime] or None
+    :ivar calc_nearest_nodes: Boolean flag to indicate whether nearest nodes to the input
+                              points should be calculated from `osmnx_graph`.
+    :type calc_nearest_nodes: bool
+    :ivar nearest_nodes: List of nearest node IDs for each point in the input data, if calculated.
+    :type nearest_nodes: list[int] or None
+    :ivar max_bounds: Boolean indicating whether bounds (default to Costa Rica) should be applied
+                      to fit the map within those limits interactively.
+    :type max_bounds: bool
+    """
     tile_options = {
         "OpenStreetMap": "OpenStreetMap",
         "CartoDB": "cartodbpositron",
@@ -20,6 +78,47 @@ class BaseOsmMap:
     bounds = [[8.0340, -85.9417], [11.2192, -82.5566]]
 
     def __init__(self, osmnx_graph=None, df=None, **kwargs):
+        """
+        Initializes a map visualization handler with input parameters for managing and displaying
+        spatial data in conjunction with an OSMnx graph. It validates input parameters for completeness
+        and correctness, and configures internal attributes for the visualization of map layers.
+
+        :param osmnx_graph: The OSMnx graph to be used for spatial data processing.
+        :param df: The pandas DataFrame containing spatial data.
+        :param kwargs: Additional keyword arguments for customization.
+        :type osmnx_graph: object
+        :type df: pandas.DataFrame
+        :type kwargs: dict
+
+        :raises ValueError: If `osmnx_graph` is not provided.
+        :raises ValueError: If `df` is not provided.
+        :raises ValueError: If the provided `df` is empty.
+
+        :attribute df: A copy of the provided DataFrame.
+        :attribute osmnx_graph: The input OSMnx graph used for spatial data operations.
+        :attribute lat_col: The name of the column in `df` containing latitude values.
+        :attribute lon_col: The name of the column in `df` containing longitude values.
+        :attribute osm_map: Internal representation of the map; initialized to None.
+        :attribute G: Placeholder for graph-related data; initialized to None.
+        :attribute map_html_title: Sanitized HTML title to be used in rendered map outputs.
+        :attribute zoom_start: The initial zoom level for the map visualization (default: 13).
+        :attribute fullscreen: Boolean flag to enable fullscreen map display (default: True).
+        :attribute fullscreen_position: The position of the fullscreen control button
+            (default: 'topright').
+        :attribute tiles: The tile set to be used for the map visualization (default: 'OpenStreetMap').
+        :attribute verbose: Boolean flag for enabling verbose output (default: False).
+        :attribute sort_keys: Optional parameter dictating sorting order for keys (default: None).
+        :attribute dt_field: Optional name of the datetime field in the DataFrame (default: None).
+        :attribute dt: Placeholder for date/time data; initialized to None.
+        :attribute calc_nearest_nodes: Boolean flag to calculate nearest nodes to coordinates
+            (default: False).
+        :attribute nearest_nodes: Placeholder for nearest nodes data; initialized to None.
+        :attribute max_bounds: Boolean flag to restrict the map view to maximum bounds
+            (default: False).
+
+        :note: This class also initializes necessary internal functionalities including DataFrame
+            pre-processing (`_prepare_df`) and base map setup (`_initialise_map`).
+        """
         if osmnx_graph is None:
             raise ValueError('osmnx_graph must be provided')
         if df is None:
@@ -50,6 +149,21 @@ class BaseOsmMap:
 
 
     def _prepare_df(self):
+        """
+        Prepares the underlying DataFrame for further processing.
+
+        This method performs several operations on the DataFrame, such as sorting,
+        resetting the index, and extracting relevant columns into various lists.
+        Additionally, it calculates the nearest nodes from an OSMnx graph if
+        required. The operations are governed by instance attributes and their
+        current states.
+
+        :raises AttributeError: If required attributes for processing are not
+            correctly set or do not exist in the DataFrame.
+        :param self: Object that contains the DataFrame (df) and other related
+            attributes required for processing.
+        :return: None
+        """
         if self.sort_keys:
             self.df.sort_values(by=self.sort_keys, inplace=True)
         self.df.reset_index(drop=True, inplace=True)
@@ -63,6 +177,15 @@ class BaseOsmMap:
 
 
     def _initialise_map(self):
+        """
+        Initializes an OpenStreetMap (OSM) map instance and extracts a subgraph of map
+        data based on provided GPS points. The map's central location is calculated
+        as the mean of the latitudinal and longitudinal values of the GPS points.
+        Additionally, a bounding box is determined to extract the relevant section
+        of the map graph.
+
+        :return: None
+        """
         gps_array = np.array(self.gps_points)
         mean_latitude = np.mean(gps_array[:, 0])
         mean_longitude = np.mean(gps_array[:, 1])
@@ -73,6 +196,24 @@ class BaseOsmMap:
 
 
     def _attach_supported_tiles(self):
+        """
+        Attach supported tile layers from the provided tile options to the map object.
+
+        This method normalizes the default tile layer name and ensures that it is not
+        duplicated in the map by filtering out the default tile from the `tile_options`.
+        Then, it iterates over the filtered tile options and attaches each supported
+        tile layer to the map object using the folium library.
+
+        :raises KeyError: If any key in `tile_options` is invalid or not found.
+
+        :param self:
+            The instance of the class. It is expected to have the following attributes:
+                - tiles (str): The name of the default tile layer.
+                - tile_options (Dict[str, str]): A dictionary of tile layer names
+                  and their associated URLs.
+                - osm_map (folium.Map): The map object to which tile layers are attached.
+        :return: None
+        """
         # Normalize the default tile name to lowercase for comparison
         normalized_default_tile = self.tiles.lower()
 
@@ -84,6 +225,22 @@ class BaseOsmMap:
 
 
     def _get_bounding_box_from_points(self, margin=0.001):
+        """
+        Calculate a bounding box from GPS points with an additional margin.
+
+        This method processes the GPS points in the `self.gps_points` list
+        and calculates a geographical bounding box encompassing all
+        points with an optional margin added to its boundaries. The
+        bounding box is defined by the northernmost, southernmost,
+        easternmost, and westernmost boundaries.
+
+        :param margin: A float value that adds a margin to the bounding
+            box boundaries.
+            Defaults to 0.001.
+        :return: A tuple containing four float values in the order:
+            north (northernmost boundary), south (southernmost boundary),
+            east (easternmost boundary), and west (westernmost boundary).
+        """
         latitudes = [point[0] for point in self.gps_points]
         longitudes = [point[1] for point in self.gps_points]
 
@@ -96,6 +253,26 @@ class BaseOsmMap:
 
 
     def _extract_subgraph(self, north, south, east, west):
+        """
+        Extracts a subgraph from the OSMnx graph based on a specified bounding box.
+
+        This function takes the northern, southern, eastern, and western bounds to
+        define a geographic bounding box. It creates a polygon from these bounds and
+        identifies nodes within the graph that fall within this boundary. A new subgraph
+        is then created using these identified nodes. This functionality supports different
+        approaches depending on the OSMnx version.
+
+        :param north: The northern boundary of the bounding box.
+        :type north: float
+        :param south: The southern boundary of the bounding box.
+        :type south: float
+        :param east: The eastern boundary of the bounding box.
+        :type east: float
+        :param west: The western boundary of the bounding box.
+        :type west: float
+        :return: A subgraph extracted from the OSMnx graph containing nodes within the bounding box.
+        :rtype: networkx.Graph
+        """
         # Create a bounding box polygon
         # from osmnx v2 this is how it is done
         if ox.__version__ >= '2.0':
@@ -117,18 +294,45 @@ class BaseOsmMap:
 
     @abstractmethod
     def process_map(self):
+        """
+        This abstract method serves as a blueprint for processing a map. It is intentionally
+        left unimplemented and must be overridden in any concrete subclass. Subclasses should
+        provide their own specific logic for map processing by implementing this interface.
+
+        :return: None
+        """
         # this is to be implemented at the subclass level
         # implement here your specific map logic.
         ...
 
 
     def pre_process_map(self):
+        """
+        Pre-processes the map data.
+
+        This method is designed to be overridden in a subclass to perform specific
+        pre-processing procedures on map data. When overridden, the implementation
+        in the subclass must call `super().pre_process_map` first to inherit and
+        maintain the existing behavior of this base implementation.
+
+        :return: None
+        """
         # this is to be implemented at the subclass level
         # call super().pre_process_map first to inherit the following behaviour
         ...
 
 
     def _post_process_map(self):
+        """
+        Performs post-processing tasks on the map object to enhance its functionality
+        and ensure required adjustments or attributes are attached to it. This method
+        is mainly used internally to finalize map setup based on current configurations.
+
+        :raises AttributeError: This error is raised if one of the required attributes
+            is not properly initialized or missing during the processing.
+        :raises ValueError: This error is raised if provided bounds are invalid or
+            incompatible for fitting.
+        """
         self._attach_supported_tiles()
         self.add_tile_layer()
         self._add_fullscreen()
@@ -138,26 +342,76 @@ class BaseOsmMap:
 
 
     def add_tile_layer(self):
+        """
+        Adds a tile layer to the OpenStreetMap (OSM) representation.
+        This method is intended to handle the inclusion of additional
+        tile layers in the map. Subclasses should override this method,
+        call their custom logic, and conclude with a call to this base
+        implementation to add necessary controls to the map instance.
+
+        :rtype: None
+        :return: This method does not return any value.
+        """
         # Override in subclass and call super().add_tile_layer at the end
         folium.LayerControl().add_to(self.osm_map)
 
 
     def _add_fullscreen(self):
+        """
+        Adds a fullscreen functionality to the map if the fullscreen attribute is set.
+
+        This method checks whether the fullscreen mode is enabled by evaluating
+        the `fullscreen` attribute of the class. If `fullscreen` is set to True,
+        a Fullscreen instance is created with the specified position from
+        `fullscreen_position` and added to the map (`osm_map`).
+
+        :return: None
+        """
         if self.fullscreen:
             Fullscreen(position=self.fullscreen_position).add_to(self.osm_map)
 
 
     def _add_map_title(self):
+        """
+        Adds a title to the map if the title is specified.
+
+        This method checks if the attribute `map_html_title` is set. If it is,
+        it creates an HTML element containing the title and adds it to the
+        map's root HTML structure using Folium's API.
+
+        :raises AttributeError: If `osm_map` or `osm_map.get_root()` is not defined
+            or does not support the necessary operations.
+        """
         if self.map_html_title:
             self.osm_map.get_root().html.add_child(folium.Element(self.map_html_title))
 
 
     @staticmethod
     def _sanitize_html(input_html):
+        """
+        Sanitizes the provided HTML input by escaping special HTML characters.
+        This method ensures the input string is safe for use in HTML contexts
+        by converting characters like `<`, `>`, and `&` into their corresponding
+        HTML-safe representations.
+
+        :param input_html: The HTML string that needs to be sanitized.
+        :type input_html: str
+        :return: The sanitized version of the input HTML string with special
+            characters escaped.
+        :rtype: str
+        """
         return html.escape(input_html)
 
 
     def generate_map(self):
+        """
+        Generates a map by executing preprocessing, main processing, and
+        post-processing tasks sequentially. This method combines multiple
+        stages to prepare and retrieve the final map object.
+
+        :return: The completed and processed OpenStreetMap map instance
+        :rtype: object
+        """
         self.pre_process_map()
         self.process_map()
         self._post_process_map()

sibi_dst/osmnx_helper/utils.py

@@ -23,6 +23,37 @@ from geopy.distance import geodesic
 
 
 class PBFHandler:
+    """
+    Handles the creation, management, and visualization of graph data derived
+    from .pbf (Protocolbuffer Binary Format) files. This class enables the
+    loading, processing, saving, and reutilization of graph, node, and edge
+    data for geographical regions, supporting verbose mode for detailed outputs.
+
+    :ivar graph: The generated graph object representing the spatial network; can be None if not yet loaded or processed.
+    :type graph: Optional[NetworkX.Graph]
+    :ivar nodes: GeoDataFrame representing the nodes of the graph; can be None if not yet loaded or processed.
+    :type nodes: Optional[geopandas.GeoDataFrame]
+    :ivar edges: GeoDataFrame representing the edges of the graph; can be None if not yet loaded or processed.
+    :type edges: Optional[geopandas.GeoDataFrame]
+    :ivar rebuild: Indicates whether to rebuild the graph data, ignoring any existing cached files. Default is ``False``.
+    :type rebuild: bool
+    :ivar verbose: Enables verbose mode to provide detailed status messages during operations. Default is ``False``.
+    :type verbose: bool
+    :ivar place: The name of the geographical region to process with OpenStreetMap. Default is ``Costa Rica``.
+    :type place: str
+    :ivar filepath: The path to the directory where the graph, nodes, and edges pickle files are saved. Default is ``gis_data/``.
+    :type filepath: str
+    :ivar file_prefix: The prefix for the filenames of the saved graph, node, and edge pickle files. Default is ``costa-rica-``.
+    :type file_prefix: str
+    :ivar network_type: The type of network to extract from OpenStreetMap, such as "all" or other specific network types. Default is ``all``.
+    :type network_type: str
+    :ivar graph_file: Full path of the file to save or load the graph data as a pickle file.
+    :type graph_file: str
+    :ivar node_file: Full path of the file to save or load the graph's node data as a pickle file.
+    :type node_file: str
+    :ivar edge_file: Full path of the file to save or load the graph's edge data as a pickle file.
+    :type edge_file: str
+    """
     def __init__(self, **kwargs):
         self.graph = None
         self.nodes = None
@@ -38,6 +69,23 @@ class PBFHandler:
         self.edge_file = f"{self.filepath}{self.file_prefix}edges.pkl"
 
     def load(self):
+        """
+        Loads the required data files for processing. If the files do not exist or
+        if the `rebuild` flag is set to True, it will process and recreate the
+        necessary data from the source. Otherwise, it will load the data from
+        existing pickle files. This function ensures the target directory exists,
+        and processes files conditionally based on their presence.
+
+        :param verbose: Flag to control the verbosity of the function's output.
+        :param rebuild: Indicates whether the data should be rebuilt from the raw
+            source files.
+        :param graph_file: Path to the graph file to be loaded or rebuilt.
+        :param node_file: Path to the node file to be loaded or rebuilt.
+        :param edge_file: Path to the edge file to be loaded or rebuilt.
+        :param filepath: Path to the directory where files are processed and saved.
+
+        :return: None
+        """
         if self.verbose:
             print("Loading data...")
 
@@ -62,7 +110,31 @@ class PBFHandler:
 
     def process_pbf(self):
         """
-        Load a PBF file and create a graph.
+        Processes the Protocolbuffer Binary Format (PBF) data specified for a given place by
+        utilizing the OSMnx library to create a graph representation and extracts nodes and
+        edges into GeoDataFrames. The function provides verbose output if enabled.
+
+        :param self: Refers to the current instance of the class containing this method.
+
+        :param self.verbose: bool
+            A flag to control verbose output. If True, detailed processing status messages are
+            logged to the console.
+
+        :param self.place: str
+            The name or description of the geographic place for which PBF data is processed. It
+            is used to construct a graph representation of the place.
+
+        :param self.network_type: str
+            The type of network graph to be created, typically one of 'all', 'walk', 'drive',
+            etc., reflecting the type of paths or streets included in the graph.
+
+        :return: None
+            This function does not return a value, but updates class attributes ``graph``,
+            ``nodes``, and ``edges``.
+
+        :raises Exception:
+            Raises a general exception when there is an error in processing the PBF data. Error
+            details are printed when verbose output is enabled.
         """
         try:
             if self.verbose:
@@ -79,7 +151,20 @@ class PBFHandler:
 
     def save_to_pickle(self):
         """
-        Save the graph, nodes, and edges to pickle files.
+        Saves data, including graph, nodes, and edges, to pickle files. Each data object is
+        saved to its corresponding file if available. If verbose mode is enabled, prints
+        messages indicating the saving progress and success.
+
+        :param self:
+            Represents the instance of the class that contains attributes `graph_file`,
+            `graph`, `node_file`, `nodes`, `edge_file`, `edges`, and `verbose`. These
+            attributes determine the files to save to and the data to save.
+
+        :raises Exception:
+            Raises an exception if an error occurs during the saving process.
+
+        :return:
+            None
         """
         try:
             if self.verbose:
@@ -104,7 +189,13 @@ class PBFHandler:
 
     def load_from_pickle(self):
         """
-        Load the graph, nodes, and edges from pickle files.
+        Loads data from pickle files specified by the attributes `graph_file`, `node_file`,
+        and `edge_file` and assigns them to the corresponding attributes `graph`,
+        `nodes`, and `edges`, respectively. Displays verbose messages during the load
+        process if the `verbose` attribute is set to True.
+
+        :raises Exception: If an error occurs during reading or deserialization of the
+                           pickle files.
         """
         try:
             if self.verbose:
@@ -128,7 +219,13 @@ class PBFHandler:
 
     def plot_graph(self):
         """
-        Plot the graph.
+        Plots the loaded graph using the OSMnx library.
+
+        This method checks if a graph is loaded and, if available, plots it. Outputs
+        verbose messages during the process if verbosity is enabled.
+
+        :raises Exception: Raises if an error occurs during the plotting process.
+        :return: None
         """
         try:
             if self.graph is not None:
@@ -145,6 +242,23 @@ class PBFHandler:
 
 
 def get_bounding_box_from_points(gps_points, margin=0.001):
+    """
+    Calculates a bounding box from a list of GPS points, with an optional margin added
+    to expand the bounding box in all directions. The function iterates over the GPS
+    points to determine the maximum and minimum latitude and longitude values, then
+    applies the specified margin to calculate the bounding box's boundaries.
+
+    :param gps_points: A list of GPS points, where each point is represented as a tuple
+        containing a latitude and a longitude (latitude, longitude).
+    :type gps_points: list[tuple[float, float]]
+    :param margin: An optional margin value to expand the bounding box in all directions.
+        Default value is 0.001.
+    :type margin: float
+    :return: A tuple containing the bounding box boundaries in the following order:
+        north (maximum latitude), south (minimum latitude), east (maximum longitude),
+        and west (minimum longitude), each adjusted with the margin.
+    :rtype: tuple[float, float, float, float]
+    """
     latitudes = [point[0] for point in gps_points]
     longitudes = [point[1] for point in gps_points]
 
@@ -157,6 +271,28 @@ def get_bounding_box_from_points(gps_points, margin=0.001):
 
 
 def add_arrows(map_object, locations, color, n_arrows):
+    """
+    Adds directional arrows to a map object to indicate paths or flows along a polyline
+    defined by the given locations.
+
+    The function computes directional arrows based on the locations list, places them
+    along the defined path at intervals determined by the number of arrows, and adds
+    these arrows to the specified `map_object`.
+
+    .. note::
+        The function works optimally when the number of locations is greater than two.
+
+    :param map_object: The folium map object to which the directional arrows will be added.
+    :param locations: A list containing tuples of latitude and longitude values that define
+        the polyline. Each tuple represents a geographic point.
+    :type locations: list[tuple[float, float]]
+    :param color: The color to be used for the directional arrows.
+    :type color: str
+    :param n_arrows: The number of arrows to be drawn along the path.
+    :type n_arrows: int
+    :return: The modified folium map object containing the added arrows.
+    :rtype: folium.Map
+    """
     # Get the number of locations
     n = len(locations)
 
@@ -179,6 +315,26 @@ def add_arrows(map_object, locations, color, n_arrows):
 
 
 def extract_subgraph(G, north, south, east, west):
+    """
+    Extracts a subgraph from the input graph `G` within a specified bounding box. The bounding
+    box is defined by its north, south, east, and west coordinates. The function identifies
+    nodes from the graph that lie within this bounding box and creates a subgraph containing
+    only these nodes and their corresponding edges.
+
+    :param G: The input graph representing the original main graph.
+    :type G: networkx.Graph
+    :param north: The northern latitude that defines the upper boundary of the bounding box.
+    :type north: float
+    :param south: The southern latitude that defines the lower boundary of the bounding box.
+    :type south: float
+    :param east: The eastern longitude that defines the right boundary of the bounding box.
+    :type east: float
+    :param west: The western longitude that defines the left boundary of the bounding box.
+    :type west: float
+    :return: A subgraph extracted from the input graph `G` containing nodes and edges within
+             the specified bounding box.
+    :rtype: networkx.Graph
+    """
     # Create a bounding box polygon
     # from osmnx v2 this is how it is done
     if ox.__version__ >= '2.0':
@@ -199,6 +355,26 @@ def extract_subgraph(G, north, south, east, west):
 
 
 def get_distance_between_points(point_a, point_b, unit='km'):
+    """
+    Calculate the geographical distance between two points on Earth.
+
+    This function computes the distance between two points on the Earth's surface
+    specified in their geographical coordinates (latitude, longitude). The calculation
+    employs the geodesic distance, which represents the shortest distance between
+    two points on the Earth's surface. The distance can be returned in different units of
+    measurement depending on the provided parameter.
+
+    :param point_a: A tuple representing the latitude and longitude of the first
+        point in decimal degrees (e.g., (latitude, longitude)). Must be a tuple of
+        two float values.
+    :param point_b: A tuple representing the latitude and longitude of the second
+        point in decimal degrees (e.g., (latitude, longitude)). Must be a tuple of
+        two float values.
+    :param unit: A string value representing the unit of the calculated distance. Can be
+        'km' for kilometers (default), 'm' for meters, or 'mi' for miles.
+    :return: A float value of the distance between the two points in the specified unit.
+        Returns 0 if the input validation fails or the specified unit is invalid.
+    """
     if not isinstance(point_a, tuple) or len(point_a) != 2:
         return 0
     if not all(isinstance(x, float) and not math.isnan(x) for x in point_a):
@@ -226,6 +402,20 @@ tile_options = {
 
 
 def attach_supported_tiles(map_object, default_tile="OpenStreetMap"):
+    """
+    Attaches supported tile layers to a given folium map object, excluding the
+    default tile layer, to provide layer selection functionality in the map.
+
+    This function allows dynamic addition of multiple tile layers to the map
+    object while avoiding duplication of the default tile. By filtering out the
+    default tile, it prevents redundancy and ensures a cleaner map interface.
+
+    :param map_object: The folium map object to which the tile layers will be added.
+        It must be an instance of Folium's Map class or a compatible map object.
+    :param default_tile: The name of the default tile layer to exclude from the
+        list of tiles added to the map. If not specified, defaults to 'OpenStreetMap'.
+    :return: None. The function modifies the provided map object in place.
+    """
     # Normalize the default tile name to lowercase for comparison
     normalized_default_tile = default_tile.lower()
 
@@ -237,12 +427,44 @@ def attach_supported_tiles(map_object, default_tile="OpenStreetMap"):
 
 
 def get_graph(**options):
+    """
+    Generates and returns a graph along with its nodes and edges based on the
+    provided options. The function initializes a PBFHandler instance with the
+    given options, processes any data required, and retrieves the resulting
+    graph structure.
+
+    :param options: Variable-length keyword arguments passed to initialize the
+                    PBFHandler instance. These parameters play a role in
+                    determining how the graph data is processed and structured.
+    :return: Returns a tuple containing three elements:
+             - The generated graph object
+             - The list or collection of nodes within the graph
+             - The list or collection of edges that describe relationships
+               between nodes in the graph
+    """
     handler = PBFHandler(**options)
     handler.load()
     return handler.graph, handler.nodes, handler.edges
 
 
 def add_query_params(url, params):
+    """
+    Update the query parameters of a given URL with new parameters.
+
+    This function takes a URL and a dictionary of parameters, merges these
+    parameters with the existing parameters in the URL, and returns a new URL
+    with updated query parameters.
+
+    :param url: The original URL whose query parameters are to be updated,
+        including the scheme, netloc, path, and optional query string and fragment.
+    :type url: str
+    :param params: A dictionary containing the new parameters to be added or updated
+        in the query string of the given URL.
+    :type params: dict
+    :return: A new URL with updated query parameters after merging the original
+        and new parameters.
+    :rtype: str
+    """
     # Parse the original URL
     url_components = urlsplit(url)