sibi-dst 0.3.42__py3-none-any.whl → 0.3.44__py3-none-any.whl

sibi_dst/df_helper/_artifact_updater_multi_wrapper.py

@@ -25,7 +25,7 @@ class ArtifactUpdaterMultiWrapper:
     def __init__(self, wrapped_classes=None, debug=False, **kwargs):
         self.wrapped_classes = wrapped_classes or {}
         self.debug = debug
-        self.logger = Logger.default_logger(logger_name=self.__class__.__name__)
+        self.logger = kwargs.setdefault('logger',Logger.default_logger(logger_name=self.__class__.__name__))
         self.logger.set_level(logging.DEBUG if debug else logging.INFO)
 
         today = datetime.datetime.today()
@@ -73,7 +73,12 @@ class ArtifactUpdaterMultiWrapper:
             raise ValueError(f"Unsupported data type: {data_type}")
 
         return [
-            artifact_class(parquet_start_date=self.parquet_start_date, parquet_end_date=self.parquet_end_date)
+            artifact_class(
+                parquet_start_date=self.parquet_start_date,
+                parquet_end_date=self.parquet_end_date,
+                logger=self.logger,
+                debug=self.debug
+            )
             for artifact_class in self.wrapped_classes[data_type]
         ]
 

sibi_dst/df_helper/_df_helper.py

@@ -112,6 +112,7 @@ class DfHelper:
         :return: None
         """
         self.logger.debug(f"backend used: {self.backend}")
+        self.logger.debug(f"kwargs passed to backend plugins: {kwargs}")
         self._backend_query = self.__get_config(QueryConfig, kwargs)
         self._backend_params = self.__get_config(ParamsConfig, kwargs)
         if self.backend == 'django_db':
@@ -124,8 +125,8 @@ class DfHelper:
         elif self.backend == 'sqlalchemy':
             self.backend_sqlalchemy = self.__get_config(SqlAlchemyConnectionConfig, kwargs)
 
-    @staticmethod
-    def __get_config(model: [T], kwargs: Dict[str, Any]) -> Union[T]:
+
+    def __get_config(self, model: [T], kwargs: Dict[str, Any]) -> Union[T]:
         """
         Initializes a Pydantic model with the keys it recognizes from the kwargs,
         and removes those keys from the kwargs dictionary.
@@ -135,7 +136,9 @@ class DfHelper:
         """
         # Extract keys that the model can accept
         recognized_keys = set(model.__annotations__.keys())
+        self.logger.debug(f"recognized keys: {recognized_keys}")
         model_kwargs = {k: kwargs.pop(k) for k in list(kwargs.keys()) if k in recognized_keys}
+        self.logger.debug(f"model_kwargs: {model_kwargs}")
         return model(**model_kwargs)
 
     def load_parallel(self, **options):

sibi_dst/df_helper/_parquet_artifact.py

@@ -1,11 +1,12 @@
+import datetime
+import logging
 from typing import Optional, Any, Dict
 
 import dask.dataframe as dd
 import fsspec
 
 from sibi_dst.df_helper import DfHelper
-from sibi_dst.utils import DataWrapper
-from sibi_dst.utils import DateUtils
+from sibi_dst.utils import DataWrapper, DateUtils, Logger
 
 
 class ParquetArtifact(DfHelper):
@@ -82,7 +83,12 @@ class ParquetArtifact(DfHelper):
             **kwargs,
         }
         self.df: Optional[dd.DataFrame] = None
+        self.debug = self.config.setdefault('debug', False)
+        self.logger = self.config.setdefault('logger',Logger.default_logger(logger_name=f'parquet_artifact_{__class__.__name__}'))
+        self.logger.set_level(logging.DEBUG if self.debug else logging.INFO)
         self.data_wrapper_class = data_wrapper_class
+        self.class_params = self.config.setdefault('class_params', None)
+        self.load_params = self.config.setdefault('load_params', None)
         self.date_field = self.config.setdefault('date_field', None)
         if self.date_field is None:
             raise ValueError('date_field must be set')
@@ -131,7 +137,30 @@ class ParquetArtifact(DfHelper):
 
     def update_parquet(self, period: str = 'today', **kwargs) -> None:
         """Update the Parquet file with data from a specific period."""
-        kwargs.update(self.parse_parquet_period(period=period))
+
+        def itd_config():
+            try:
+                start_date = kwargs.pop('history_begins_on')
+            except KeyError:
+                raise ValueError("For period 'itd', you must provide 'history_begins_on' in kwargs.")
+            return {'parquet_start_date': start_date, 'parquet_end_date': datetime.date.today().strftime('%Y-%m-%d')}
+
+        def ytd_config():
+            return {
+                'parquet_start_date': datetime.date(datetime.date.today().year, 1, 1).strftime('%Y-%m-%d'),
+                'parquet_end_date': datetime.date.today().strftime('%Y-%m-%d')
+            }
+
+        config_map = {
+            'itd': itd_config,
+            'ytd': ytd_config
+        }
+
+        if period in config_map:
+            kwargs.update(config_map[period]())
+        else:
+            kwargs.update(self.parse_parquet_period(period=period))
+        print(kwargs)
         self.generate_parquet(**kwargs)
 
     def rebuild_parquet(self, **kwargs) -> None:
@@ -150,6 +179,7 @@ class ParquetArtifact(DfHelper):
 
     def _prepare_params(self, kwargs: Dict[str, Any]) -> Dict[str, Any]:
         """Prepare the parameters for generating the Parquet file."""
+        kwargs = {**self.config, **kwargs}
         return {
             'class_params': kwargs.pop('class_params', None),
             'date_field': kwargs.pop('date_field', self.date_field),

sibi_dst/df_helper/_parquet_reader.py

@@ -1,10 +1,11 @@
+import logging
 from typing import Optional
 
 import dask.dataframe as dd
 import fsspec
 
 from sibi_dst.df_helper import DfHelper
-
+from sibi_dst.utils import Logger
 
 class ParquetReader(DfHelper):
     """
@@ -53,6 +54,9 @@ class ParquetReader(DfHelper):
             **kwargs,
         }
         self.df: Optional[dd.DataFrame] = None
+        self.debug = self.config.setdefault('debug', False)
+        self.logger = self.config.setdefault('logger', Logger.default_logger(logger_name=self.__class__.__name__))
+        self.logger.set_level(logging.DEBUG if self.debug else logging.INFO)
         self.parquet_storage_path = self.config.setdefault('parquet_storage_path', None)
         if self.parquet_storage_path is None:
             raise ValueError('parquet_storage_path must be set')

sibi_dst/df_helper/backends/django/_load_from_db.py

@@ -64,6 +64,7 @@ class DjangoLoadFromDb:
         self.connection_config = db_connection
         self.debug = kwargs.pop('debug', False)
         self.logger = logger or Logger.default_logger(logger_name=self.__class__.__name__)
+        self.logger.set_level(Logger.DEBUG if self.debug else Logger.INFO)
         if self.connection_config.model is None:
             if self.debug:
                 self.logger.debug('Model must be specified')

sibi_dst/df_helper/backends/parquet/_filter_handler.py

@@ -17,8 +17,9 @@ class ParquetFilterHandler(object):
     :ivar logger: Logger object to handle logging within the class. Defaults to the class-level logger.
     :type logger: Logger
     """
-    def __init__(self, logger=None):
+    def __init__(self, logger=None, debug=False):
         self.logger = logger or Logger.default_logger(logger_name=self.__class__.__name__)
+        self.logger.set_level(Logger.DEBUG if debug else Logger.INFO)
 
     @staticmethod
     def apply_filters_dask(df, filters):

sibi_dst/df_helper/backends/parquet/_parquet_options.py

@@ -62,6 +62,7 @@ class ParquetConfig(BaseModel):
     parquet_end_date: Optional[str] = None
     fs: Optional[fsspec.spec.AbstractFileSystem] = None  # Your fsspec filesystem object
     logger: Optional[Logger] = None
+    debug: bool = False
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
     @model_validator(mode='after')
@@ -83,9 +84,7 @@ class ParquetConfig(BaseModel):
         # Configure paths based on fsspec
         if self.logger is None:
             self.logger = Logger.default_logger(logger_name=self.__class__.__name__)
-        #self.fs = fsspec.filesystem("file") if "://" not in str(self.parquet_storage_path) else fsspec.filesystem(
-        #    str(self.parquet_storage_path).split("://")[0])
-        # Validation for parquet path
+        self.logger.set_level(Logger.DEBUG if self.debug else Logger.INFO)
 
 
         if self.parquet_storage_path is None:

sibi_dst/df_helper/backends/sqlalchemy/_db_connection.py

@@ -63,3 +63,4 @@ class SqlAlchemyConnectionConfig(BaseModel):
                 connection.execute(text("SELECT 1"))
         except OperationalError as e:
             raise ValueError(f"Failed to connect to the database: {e}")
+

sibi_dst/df_helper/backends/sqlalchemy/_io_dask.py

@@ -29,6 +29,7 @@ class SQLAlchemyDask:
         self.engine = create_engine(engine_url)
         self.Session = sessionmaker(bind=self.engine)
         self.logger = logger or Logger.default_logger(logger_name=self.__class__.__name__)
+        self.logger.set_level(logger.DEBUG if debug else logger.INFO)
 
     @staticmethod
     def infer_dtypes_from_model(model):
@@ -70,11 +71,7 @@ class SQLAlchemyDask:
                 # Build query
                 self.query = select(self.model)
                 if self.filters:
-                    """
-                    deprecated specific filter handling to a generic one
-                    #self.query = SqlAlchemyFilterHandler.apply_filters_sqlalchemy(self.query, self.model, self.filters)
-                    """
-                    self.query = FilterHandler(backend="sqlalchemy", logger=self.logger).apply_filters(self.query,
+                    self.query = FilterHandler(backend="sqlalchemy", logger=self.logger, debug=self.debug).apply_filters(self.query,
                                                                                                        model=self.model,
                                                                                                        filters=self.filters)
                 else:

sibi_dst/df_helper/core/_filter_handler.py

@@ -25,7 +25,7 @@ class FilterHandler:
     :ivar backend_methods: A dictionary mapping backend-specific methods for column retrieval and operation application.
     :type backend_methods: dict
     """
-    def __init__(self, backend, logger=None):
+    def __init__(self, backend, logger=None, debug=False):
         """
         Initialize the FilterHandler.
 
@@ -36,6 +36,7 @@ class FilterHandler:
         self.backend = backend
         self.logger = logger or Logger.default_logger(
             logger_name=self.__class__.__name__)  # No-op logger if none provided
+        self.logger.set_level(Logger.DEBUG if debug else Logger.INFO)
         self.backend_methods = self._get_backend_methods(backend)
 
     def apply_filters(self, query_or_df, model=None, filters=None):

sibi_dst/osmnx_helper/__init__.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
-from .base_osm_map import BaseOsmMap
-from .utils import PBFHandler
+from .v1.base_osm_map import BaseOsmMap
+from .v1.utils import PBFHandler
 
 __all__ = [
     "BaseOsmMap",

sibi_dst/osmnx_helper/{basemaps → v1/basemaps}/router_plotter.py

@@ -1,20 +1,21 @@
 from __future__ import annotations
-from sibi_dst.osmnx_helper.utils import get_distance_between_points, add_arrows
+from sibi_dst.osmnx_helper.v1.utils import get_distance_between_points, add_arrows
 from collections import defaultdict
 import folium
 from folium.plugins import AntPath
 import networkx as nx
 
 from sibi_dst.osmnx_helper import BaseOsmMap
-from sibi_dst.osmnx_helper.basemaps.calendar_html import calendar_html
+from sibi_dst.osmnx_helper.v1.basemaps.calendar_html import calendar_html
 
 class RoutePlotter(BaseOsmMap):
     def __init__(self, osmnx_graph, df, **kwargs):
         self.action_field = kwargs.pop('action_field', '')
         self.action_groups = kwargs.pop('action_groups', {})
         self.action_styles = kwargs.pop('action_styles', {})
-        self.use_ant_path = kwargs.pop('use_ant_path', True)
-        self.show_calendar = kwargs.pop('show_calendar', True)
+        self.use_ant_path = kwargs.pop('use_ant_path', False)
+        self.show_calendar = kwargs.pop('show_calendar', False)
+        self.show_order_markers = kwargs.pop('show_order_markers', False)
         self.show_map_title = kwargs.pop('show_map_title', True)
         self.sort_keys = kwargs.pop('sort_keys', None)
         self.main_route_layer = folium.FeatureGroup(name="Main Route")
@@ -24,6 +25,8 @@ class RoutePlotter(BaseOsmMap):
         self.actions = []
         self.action_group_counts = {action_group: 0 for action_group in self.action_groups}
         self.marker_count = 1
+        # Add a snapping threshold (in meters) to avoid drawing nodes/markers that are too close.
+        self.snap_distance = kwargs.pop('snap_distance', 30)
         kwargs.update({'calc_nearest_nodes': True})
         kwargs['dt_field'] = 'date_time'
         super().__init__(osmnx_graph, df, **kwargs)
@@ -36,6 +39,8 @@ class RoutePlotter(BaseOsmMap):
         self._calculate_routes()
         self._plot_routes()
         self._add_markers()
+        if self.show_order_markers:
+            self._add_order_markers()
         self.main_route_layer.add_to(self.osm_map)
         if self.show_calendar:
             self._add_calendar()
@@ -57,8 +62,8 @@ class RoutePlotter(BaseOsmMap):
                 self.route_polylines.append((polyline, color))
                 for action_group, action_markers in markers.items():
                     self.markers[action_group].extend(action_markers)
-                    self.action_group_counts[action_group] += 1
-                    self.marker_count += 1
+                    self.action_group_counts[action_group] += len(action_markers)
+                    self.marker_count += len(action_markers)
         if self.verbose:
             print("Route and marker calculation complete.")
 
@@ -70,7 +75,7 @@ class RoutePlotter(BaseOsmMap):
 
     def _calculate_route(self, i):
         if self.verbose:
-            print(f"Calculating for item:{i}")
+            print(f"Calculating for item: {i}")
         orig = self.nearest_nodes[i]
         dest = self.nearest_nodes[i + 1]
         try:
@@ -81,17 +86,31 @@ class RoutePlotter(BaseOsmMap):
             lats, lons = zip(*[(self.G.nodes[node]['y'] + offset, self.G.nodes[node]['x']) for node in route])
             color = 'blue' if i < self.max_distance_index else 'red'
             polyline = list(zip(lats, lons))
+            # Apply node snapping to the polyline to remove points that are too close.
+            polyline = self._snap_polyline(polyline)
             markers = self._calculate_markers(i)
             return polyline, color, markers
         except nx.NetworkXNoPath:
             if self.verbose:
-                print(f"Item:{i}-No path found for {orig} to {dest}")
+                print(f"Item: {i} - No path found for {orig} to {dest}")
             return None, None, {}
         except nx.NodeNotFound:
             if self.verbose:
-                print(f"Item:{i}-No path found for {orig} to {dest}")
+                print(f"Item: {i} - No path found for {orig} to {dest}")
             return None, None, {}
 
+    def _snap_polyline(self, polyline: list[tuple[float, float]]) -> list[tuple[float, float]]:
+        """
+        Returns a filtered polyline where consecutive points closer than snap_distance are removed.
+        """
+        if not polyline:
+            return polyline
+        snapped_polyline = [polyline[0]]
+        for point in polyline[1:]:
+            if get_distance_between_points(snapped_polyline[-1], point, 'm') >= self.snap_distance:
+                snapped_polyline.append(point)
+        return snapped_polyline
+
     def _calculate_markers(self, i):
         # Calculate markers for action groups
         markers = defaultdict(list)
@@ -110,24 +129,26 @@ class RoutePlotter(BaseOsmMap):
     def _plot_routes(self):
         if self.verbose:
             print("Plotting routes and markers...")
-        # self.action_group_counts = {action_group: 0 for action_group in self.feature_groups.keys()}
         for polyline, color in self.route_polylines:
             if self.use_ant_path:
                 AntPath(
                     locations=polyline,
                     color=color,
-                    weight=3,  # Increase line thickness
-                    opacity=10,  # Increase opacity
-                    # pulse_color=color,
-                    delay=1000,  # Slower animation to reduce flickering
-                    # dash_array=[20, 30]  # Adjust dash pattern if needed
+                    weight=3,       # Increased line thickness
+                    opacity=10,     # Increased opacity
+                    delay=1000,     # Slower animation to reduce flickering
                 ).add_to(self.main_route_layer)
             else:
                 folium.PolyLine(locations=polyline, color=color).add_to(self.main_route_layer)
                 self.osm_map = add_arrows(self.osm_map, polyline, color, n_arrows=3)
-        # Plot markers for action groups
+        # Plot markers for action groups with snapping to avoid drawing too many nearby markers.
         for action_group, action_markers in self.markers.items():
+            seen_positions = []
             for location, tooltip, popup_data, action_style in action_markers:
+                # Skip marker if a nearby marker (within snap_distance) has already been added.
+                if any(get_distance_between_points(location, pos, 'm') < self.snap_distance for pos in seen_positions):
+                    continue
+                seen_positions.append(location)
                 folium.Marker(
                     location=location,
                     popup=folium.Popup(popup_data, max_width=600),
@@ -145,11 +166,14 @@ class RoutePlotter(BaseOsmMap):
     def _add_markers(self):
         if self.verbose:
             print("Adding markers...")
-        # Add start marker
+        # Add a start marker
         start_popup = folium.Popup(f"Start of route at {self.dt[0]}", max_width=300)
-        folium.Marker(location=self.gps_points[0], popup=start_popup,
-                      icon=folium.Icon(icon='flag-checkered', prefix='fa')).add_to(self.osm_map)
-        # Add total distance marker at the end
+        folium.Marker(
+            location=self.gps_points[0],
+            popup=start_popup,
+            icon=folium.Icon(icon='flag-checkered', prefix='fa')
+        ).add_to(self.osm_map)
+        # Add an end marker with total distance info
         folium.Marker(
             self.gps_points[-1],
             popup=f"End of Route at {self.dt[self.max_time_index]}. Total Distance Travelled: {self.total_distance / 1000:.2f} km",
@@ -165,15 +189,15 @@ class RoutePlotter(BaseOsmMap):
     def _add_map_title(self):
         if self.map_html_title and self.show_map_title:
             title_html = f'''
-                 <div style="position: fixed; 
-                             top: 10px; 
-                             left: 50%; 
+                 <div style="position: fixed;
+                             top: 10px;
+                             left: 50%;
                              transform: translate(-50%, 0%);
-                             z-index: 9999; 
-                             font-size: 24px; 
-                             font-weight: bold; 
-                             background-color: white; 
-                             padding: 10px; 
+                             z-index: 9999;
+                             font-size: 24px;
+                             font-weight: bold;
+                             background-color: white;
+                             padding: 10px;
                              border: 2px solid black;
                              border-radius: 5px;">
                     {self.map_html_title}
@@ -181,6 +205,37 @@ class RoutePlotter(BaseOsmMap):
                  '''
             self.osm_map.get_root().html.add_child(folium.Element(title_html))
 
+    def _add_order_markers(self):
+        """Adds numbered markers to indicate the visit order."""
+        order_feature_group = folium.FeatureGroup(name="Visit Order")
+        for idx, location in enumerate(self.gps_points):
+            # Create a DivIcon with the number (starting at 1)
+            icon = folium.DivIcon(
+                icon_size=(24, 24),
+                icon_anchor=(12, 12),
+                html=f'''
+                    <div style="
+                        font-size: 12pt;
+                        color: black;
+                        background-color: white;
+                        border: 1px solid black;
+                        border-radius: 50%;
+                        width: 24px;
+                        height: 24px;
+                        text-align: center;
+                        line-height: 24px;">
+                        {idx + 1}
+                    </div>
+                '''
+            )
+            folium.Marker(
+                location=location,
+                icon=icon,
+                tooltip=f"GPS Set No. {idx + 1}: {self.dt[idx]}"
+            ).add_to(order_feature_group)
+
+        order_feature_group.add_to(self.osm_map)
+
     def _get_data(self, index):
-        # implement in subclass to populate popups
-        ...
+        # Implement in subclass to populate popups
+        ...

sibi_dst/osmnx_helper/v2/base_osm_map.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import html
+from abc import ABC, abstractmethod
+from typing import Optional
+
+import folium
+import geopandas as gpd
+import numpy as np
+import osmnx as ox
+import pandas as pd
+from folium.plugins import Fullscreen
+from networkx import MultiDiGraph
+
+
+class BaseOsmMap(ABC):
+    # Define available tile options for the map
+    tile_options = {
+        "OpenStreetMap": "OpenStreetMap",
+        "CartoDB": "cartodbpositron",
+        "CartoDB Voyager": "cartodbvoyager"
+    }
+    # Default geographical bounds (Costa Rica)
+    bounds = [[8.0340, -85.9417], [11.2192, -82.5566]]
+
+    def __init__(
+            self,
+            osmnx_graph: MultiDiGraph,
+            df: pd.DataFrame,
+            lat_col: str = "latitude",
+            lon_col: str = "longitude",
+            map_html_title: str = "OSM Basemap",
+            zoom_start: int = 13,
+            fullscreen: bool = True,
+            fullscreen_position: str = "topright",
+            tiles: str = "OpenStreetMap",
+            verbose: bool = False,
+            sort_keys: Optional[list[str]] = None,
+            dt_field: Optional[str] = None,
+            calc_nearest_nodes: bool = False,
+            max_bounds: bool = False,
+    ):
+        if df.empty:
+            raise ValueError("df must not be empty")
+
+        # Store attributes
+        self.df = df.copy()
+        self.osmnx_graph = osmnx_graph
+        self.lat_col = lat_col
+        self.lon_col = lon_col
+        self.map_html_title = self._sanitize_html(map_html_title)
+        self.zoom_start = zoom_start
+        self.fullscreen = fullscreen
+        self.fullscreen_position = fullscreen_position
+        self.tiles = tiles
+        self.verbose = verbose
+        self.sort_keys = sort_keys
+        self.dt_field = dt_field
+        self.calc_nearest_nodes = calc_nearest_nodes
+        self.max_bounds = max_bounds
+        self.dt = self.df[self.dt_field].to_list() if self.dt_field else None
+        self.nearest_nodes = None
+        self.G = None
+        self.osm_map = None
+
+        self._prepare_df()
+        self._initialize_map()
+
+    def _prepare_df(self):
+        """Sort and preprocess the DataFrame."""
+        if self.sort_keys:
+            self.df.sort_values(by=self.sort_keys, inplace=True, ignore_index=True)
+        self.gps_points = self.df[[self.lat_col, self.lon_col]].to_numpy()
+
+        # Compute nearest nodes if required
+        if self.calc_nearest_nodes and not self.df.empty:
+            self.nearest_nodes = ox.distance.nearest_nodes(
+                self.osmnx_graph, X=self.df[self.lon_col], Y=self.df[self.lat_col]
+            )
+
+    def _initialize_map(self):
+        """Initialize the folium map centered around the dataset."""
+        if self.gps_points.size == 0:
+            raise ValueError("No valid GPS points available for map initialization")
+
+        center = self.gps_points.mean(axis=0).tolist()
+        if self.osm_map is None:
+            self.osm_map = folium.Map(
+                location=center, zoom_start=self.zoom_start, tiles=self.tiles, max_bounds=self.max_bounds
+            )
+        self.G = self._extract_subgraph(*self._get_bounding_box_from_points())
+
+    def _get_bounding_box_from_points(self, margin: float = 0.001) -> tuple[float, float, float, float]:
+        """Compute bounding box for the dataset with margin."""
+        latitudes, longitudes = self.gps_points[:, 0], self.gps_points[:, 1]
+        return max(latitudes) + margin, min(latitudes) - margin, max(longitudes) + margin, min(longitudes) - margin
+
+    def _extract_subgraph(self, north: float, south: float, east: float, west: float) -> MultiDiGraph:
+        """Extract a subgraph from OSM data within the bounding box."""
+        bbox_poly = gpd.GeoSeries([ox.utils_geo.bbox_to_poly((west, south, east, north))])
+        nodes_gdf = ox.graph_to_gdfs(self.osmnx_graph, nodes=True, edges=False)
+        nodes_within_bbox = gpd.sjoin(nodes_gdf, gpd.GeoDataFrame(geometry=bbox_poly), predicate="within")
+        return self.osmnx_graph.subgraph(nodes_within_bbox.index)
+
+    def _post_process_map(self):
+        """Perform final adjustments to the map."""
+        self._attach_supported_tiles()
+        self.add_tile_layer()
+        self._add_fullscreen()
+        self._add_map_title()
+        if self.max_bounds and self.bounds:
+            self.osm_map.fit_bounds(self.bounds)
+
+    def _attach_supported_tiles(self):
+        """Attach additional tile layers to the map."""
+        for name, tile in self.tile_options.items():
+            if tile.lower() != self.tiles.lower():
+                folium.TileLayer(name=name, tiles=tile, show=False).add_to(self.osm_map)
+
+    def _add_fullscreen(self):
+        """Enable fullscreen control if required."""
+        if self.fullscreen:
+            Fullscreen(position=self.fullscreen_position).add_to(self.osm_map)
+
+    def _add_map_title(self):
+        """Add a title to the map if provided."""
+        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: str) -> str:
+        """Sanitize HTML input to prevent script injection."""
+        return html.escape(input_html)
+
+    @abstractmethod
+    def process_map(self):
+        """Abstract method to define map processing logic in subclasses."""
+        pass
+
+    def pre_process_map(self):
+        """Optional preprocessing step before main processing."""
+        pass
+
+    def add_tile_layer(self):
+        """Add a layer control to the map."""
+        folium.LayerControl().add_to(self.osm_map)
+
+    def generate_map(self) -> folium.Map:
+        """Generate and return the processed map."""
+        self.pre_process_map()
+        self.process_map()
+        self._post_process_map()
+        return self.osm_map