giga-spatial 0.7.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

gigaspatial/generators/zonal/base.py

@@ -1,7 +1,7 @@
 from abc import ABC, abstractmethod
 from pydantic import BaseModel, Field
 from pathlib import Path
-from typing import Dict, List, Optional, Union, Callable, TypeVar, Generic
+from typing import Dict, List, Optional, Union, TypeVar, Generic
 from shapely.geometry import Polygon
 
 import geopandas as gpd
@@ -16,10 +16,8 @@ from gigaspatial.processing.geo import (
     aggregate_polygons_to_zones,
     aggregate_points_to_zones,
 )
-from gigaspatial.processing.tif_processor import (
-    TifProcessor,
-    sample_multiple_tifs_by_polygons,
-)
+from gigaspatial.processing.tif_processor import TifProcessor
+
 from functools import lru_cache
 import logging
 
@@ -209,8 +207,6 @@ class ZonalViewGenerator(ABC, Generic[T]):
         aggregation: Union[str, Dict[str, str]] = "count",
         predicate: str = "within",
         output_suffix: str = "",
-        mapping_function: Optional[Callable] = None,
-        **mapping_kwargs,
     ) -> Dict:
         """Map point data to zones with spatial aggregation.
 
@@ -228,18 +224,12 @@ class ZonalViewGenerator(ABC, Generic[T]):
             predicate (str): Spatial predicate for point-to-zone relationship.
                 Options include "within", "intersects", "contains". Defaults to "within".
             output_suffix (str): Suffix to add to output column names. Defaults to empty string.
-            mapping_function (Callable, optional): Custom function for mapping points to zones.
-                If provided, signature should be mapping_function(self, points, **mapping_kwargs).
-                When used, all other parameters except mapping_kwargs are ignored.
-            **mapping_kwargs: Additional keyword arguments passed to the mapping function.
 
         Returns:
             Dict: Dictionary with zone IDs as keys and aggregated values as values.
                 If value_columns is None, returns point counts per zone.
                 If value_columns is specified, returns aggregated values per zone.
         """
-        if mapping_function is not None:
-            return mapping_function(self, points, **mapping_kwargs)
 
         self.logger.warning(
             "Using default points mapping implementation. Consider creating a specialized mapping function."
@@ -382,40 +372,63 @@ class ZonalViewGenerator(ABC, Generic[T]):
 
     def map_rasters(
         self,
-        tif_processors: List[TifProcessor],
-        mapping_function: Optional[Callable] = None,
+        raster_data: Union[TifProcessor, List[TifProcessor]],
         stat: str = "mean",
-        **mapping_kwargs,
-    ) -> Union[np.ndarray, Dict]:
+        **kwargs,
+    ) -> Dict:
         """Map raster data to zones using zonal statistics.
 
         Samples raster values within each zone and computes statistics. Automatically
         handles coordinate reference system transformations between raster and zone data.
 
         Args:
-            tif_processors (List[TifProcessor]): List of TifProcessor objects for
-                accessing raster data. All processors should have the same CRS.
+            raster_data (Union[TifProcessor, List[TifProcessor]]):
+                Either a TifProcessor object or a list of TifProcessor objects (which will be merged
+                into a single TifProcessor for processing).
             mapping_function (Callable, optional): Custom function for mapping rasters
                 to zones. If provided, signature should be mapping_function(self, tif_processors, **mapping_kwargs).
                 When used, stat and other parameters except mapping_kwargs are ignored.
             stat (str): Statistic to calculate when aggregating raster values within
                 each zone. Options include "mean", "sum", "min", "max", "std", etc.
                 Defaults to "mean".
-            **mapping_kwargs: Additional keyword arguments passed to the mapping function.
+            **mapping_kwargs: Additional keyword arguments for raster data.
 
         Returns:
-            Union[np.ndarray, Dict]: By default, returns a NumPy array of sampled values
-                with shape (n_zones, 1), taking the first non-nodata value encountered.
-                Custom mapping functions may return different data structures.
+            Dict: By default, returns a dictionary of sampled values
+                with zone IDs as keys.
 
         Note:
             If the coordinate reference system of the rasters differs from the zones,
             the zone geometries will be automatically transformed to match the raster CRS.
         """
-        if mapping_function is not None:
-            return mapping_function(self, tif_processors, **mapping_kwargs)
+        raster_processor: Optional[TifProcessor] = None
+
+        if isinstance(raster_data, TifProcessor):
+            raster_processor = raster_data
+        elif isinstance(raster_data, list) and all(
+            isinstance(x, TifProcessor) for x in raster_data
+        ):
+            if not raster_data:
+                self.logger.info("No valid raster data provided")
+                return self.view
+
+            if len(raster_data) > 1:
+                all_source_paths = [tp.dataset_path for tp in raster_data]
+
+                self.logger.info(
+                    f"Merging {len(all_source_paths)} rasters into a single TifProcessor for zonal statistics."
+                )
+                raster_processor = TifProcessor(
+                    dataset_path=all_source_paths, data_store=self.data_store, **kwargs
+                )
+            else:
+                raster_processor = raster_data[0]
+        else:
+            raise ValueError(
+                "raster_data must be a TifProcessor object or a list of TifProcessor objects."
+            )
 
-        raster_crs = tif_processors[0].crs
+        raster_crs = raster_processor.crs
 
         if raster_crs != self.zone_gdf.crs:
             self.logger.info(f"Projecting zones to raster CRS: {raster_crs}")
@@ -424,8 +437,8 @@ class ZonalViewGenerator(ABC, Generic[T]):
             zone_geoms = self.get_zonal_geometries()
 
         # Sample raster values
-        sampled_values = sample_multiple_tifs_by_polygons(
-            tif_processors=tif_processors, polygon_list=zone_geoms, stat=stat
+        sampled_values = raster_processor.sample_by_polygons(
+            polygon_list=zone_geoms, stat=stat
         )
 
         zone_ids = self.get_zone_identifiers()

gigaspatial/generators/zonal/geometry.py

@@ -261,13 +261,16 @@ class GeometryBasedZonalViewGenerator(ZonalViewGenerator[T]):
             f"Mapping {handler.config.product} data (year: {handler.config.year}, resolution: {handler.config.resolution}m)"
         )
         tif_processors = handler.load_data(
-            self.zone_gdf, ensure_available=self.config.ensure_available
+            self.zone_gdf,
+            ensure_available=self.config.ensure_available,
+            merge_rasters=True,
+            **kwargs,
         )
 
         self.logger.info(
             f"Sampling {handler.config.product} data using '{stat}' statistic"
         )
-        sampled_values = self.map_rasters(tif_processors=tif_processors, stat=stat)
+        sampled_values = self.map_rasters(raster_data=tif_processors, stat=stat)
 
         column_name = (
             output_column
@@ -488,57 +491,97 @@ class GeometryBasedZonalViewGenerator(ZonalViewGenerator[T]):
         self,
         country: Union[str, List[str]],
         resolution=1000,
-        predicate: Literal["intersects", "fractional"] = "intersects",
+        predicate: Literal[
+            "centroid_within", "intersects", "fractional"
+        ] = "intersects",
         output_column: str = "population",
         **kwargs,
     ):
-        if isinstance(country, str):
-            country = [country]
+
+        # Ensure country is always a list for consistent handling
+        countries_list = [country] if isinstance(country, str) else country
 
         handler = WPPopulationHandler(
-            project="pop", resolution=resolution, data_store=self.data_store, **kwargs
+            resolution=resolution,
+            data_store=self.data_store,
+            **kwargs,
         )
 
+        # Restrict to single country for age_structures project
+        if handler.config.project == "age_structures" and len(countries_list) > 1:
+            raise ValueError(
+                "For 'age_structures' project, only a single country can be processed at a time."
+            )
+
         self.logger.info(
             f"Mapping WorldPop Population data (year: {handler.config.year}, resolution: {handler.config.resolution}m)"
         )
 
-        if predicate == "fractional":
-            if resolution == 100:
-                self.logger.warning(
-                    "Fractional aggregations only supported for datasets with 1000m resolution. Using `intersects` as predicate"
+        if predicate == "fractional" and resolution == 100:
+            self.logger.warning(
+                "Fractional aggregations only supported for datasets with 1000m resolution. Using `intersects` as predicate"
+            )
+            predicate = "intersects"
+
+        if predicate == "centroid_within":
+            if handler.config.project == "age_structures":
+                # Load individual tif processors for the single country
+                all_tif_processors = handler.load_data(
+                    countries_list[0],
+                    ensure_available=self.config.ensure_available,
+                    **kwargs,
                 )
-                predicate = "intersects"
+
+                # Sum results from each tif_processor separately
+                all_results_by_zone = {
+                    zone_id: 0 for zone_id in self.get_zone_identifiers()
+                }
+                self.logger.info(
+                    f"Sampling individual age_structures rasters using 'sum' statistic and summing per zone."
+                )
+                for tif_processor in all_tif_processors:
+                    single_raster_result = self.map_rasters(
+                        raster_data=tif_processor, stat="sum"
+                    )
+                    for zone_id, value in single_raster_result.items():
+                        all_results_by_zone[zone_id] += value
+                result = all_results_by_zone
             else:
-                gdf_pop = pd.concat(
-                    [
-                        handler.load_into_geodataframe(
-                            c, ensure_available=self.config.ensure_available
+                # Existing behavior for non-age_structures projects or if merging is fine
+                tif_processors = []
+                for c in countries_list:
+                    tif_processors.extend(
+                        handler.load_data(
+                            c,
+                            ensure_available=self.config.ensure_available,
+                            **kwargs,
                         )
-                        for c in country
-                    ],
-                    ignore_index=True,
-                )
-
-                result = self.map_polygons(
-                    gdf_pop,
-                    value_columns="pixel_value",
-                    aggregation="sum",
-                    predicate=predicate,
+                    )
+                self.logger.info(
+                    f"Sampling WorldPop Population data using 'sum' statistic"
                 )
-
-                self.add_variable_to_view(result, output_column)
-                return self.view
-
-        tif_processors = []
-        for c in country:
-            tif_processors.extend(
-                handler.load_data(c, ensure_available=self.config.ensure_available)
+                result = self.map_rasters(raster_data=tif_processors, stat="sum")
+        else:
+            gdf_pop = pd.concat(
+                [
+                    handler.load_into_geodataframe(
+                        c,
+                        ensure_available=self.config.ensure_available,
+                        **kwargs,
+                    )
+                    for c in countries_list
+                ],
+                ignore_index=True,
             )
 
-        self.logger.info(f"Sampling WorldPop Population data using 'sum' statistic")
-        sampled_values = self.map_rasters(tif_processors=tif_processors, stat="sum")
+            self.logger.info(f"Aggregating WorldPop Population data to the zones.")
+            result = self.map_polygons(
+                gdf_pop,
+                value_columns="pixel_value",
+                aggregation="sum",
+                predicate=predicate,
+            )
 
-        self.add_variable_to_view(sampled_values, output_column)
+        self.add_variable_to_view(result, output_column)
 
         return self.view

gigaspatial/handlers/base.py

@@ -328,21 +328,33 @@ class BaseHandlerReader(ABC):
                 )
 
     def _load_raster_data(
-        self, raster_paths: List[Union[str, Path]]
-    ) -> List[TifProcessor]:
+        self,
+        raster_paths: List[Union[str, Path]],
+        merge_rasters: bool = False,
+        **kwargs,
+    ) -> Union[List[TifProcessor], TifProcessor]:
         """
         Load raster data from file paths.
 
         Args:
             raster_paths (List[Union[str, Path]]): List of file paths to raster files.
+            merge_rasters (bool): If True, all rasters will be merged into a single TifProcessor.
+                                  Defaults to False.
 
         Returns:
-            List[TifProcessor]: List of TifProcessor objects for accessing the raster data.
+            Union[List[TifProcessor], TifProcessor]: List of TifProcessor objects or a single
+                                                    TifProcessor if merge_rasters is True.
         """
-        return [
-            TifProcessor(data_path, self.data_store, mode="single")
-            for data_path in raster_paths
-        ]
+        if merge_rasters and len(raster_paths) > 1:
+            self.logger.info(
+                f"Merging {len(raster_paths)} rasters into a single TifProcessor."
+            )
+            return TifProcessor(raster_paths, self.data_store, **kwargs)
+        else:
+            return [
+                TifProcessor(data_path, self.data_store, **kwargs)
+                for data_path in raster_paths
+            ]
 
     def _load_tabular_data(
         self, file_paths: List[Union[str, Path]], read_function: Callable = read_dataset
@@ -619,7 +631,9 @@ class BaseHandler(ABC):
             # Download logic
             if data_units is not None:
                 # Map data_units to their paths and select only those that are missing
-                unit_to_path = dict(zip(data_paths,data_units)) #units might be dicts, cannot be used as key
+                unit_to_path = dict(
+                    zip(data_paths, data_units)
+                )  # units might be dicts, cannot be used as key
                 if force_download:
                     # Download all units if force_download
                     self.downloader.download_data_units(data_units, **kwargs)

gigaspatial/handlers/ghsl.py

@@ -610,19 +610,27 @@ class GHSLDataReader(BaseHandlerReader):
         super().__init__(config=config, data_store=data_store, logger=logger)
 
     def load_from_paths(
-        self, source_data_path: List[Union[str, Path]], **kwargs
-    ) -> List[TifProcessor]:
+        self,
+        source_data_path: List[Union[str, Path]],
+        merge_rasters: bool = False,
+        **kwargs,
+    ) -> Union[List[TifProcessor], TifProcessor]:
         """
         Load TifProcessors from GHSL dataset.
         Args:
             source_data_path: List of file paths to load
+            merge_rasters: If True, all rasters will be merged into a single TifProcessor.
+                           Defaults to False.
         Returns:
-            List[TifProcessor]: List of TifProcessor objects for accessing the raster data.
+            Union[List[TifProcessor], TifProcessor]: List of TifProcessor objects for accessing the raster data or a single
+                                                    TifProcessor if merge_rasters is True.
         """
-        return self._load_raster_data(raster_paths=source_data_path)
+        return self._load_raster_data(
+            raster_paths=source_data_path, merge_rasters=merge_rasters
+        )
 
-    def load(self, source, **kwargs):
-        return super().load(source=source, file_ext=".tif")
+    def load(self, source, merge_rasters: bool = False, **kwargs):
+        return super().load(source=source, file_ext=".tif", merge_rasters=merge_rasters)
 
 
 class GHSLDataHandler(BaseHandler):
@@ -763,6 +771,7 @@ class GHSLDataHandler(BaseHandler):
             List[Union[str, Path]],  # list of paths
         ],
         ensure_available: bool = True,
+        merge_rasters: bool = False,
         **kwargs,
     ):
         return super().load_data(
@@ -771,6 +780,7 @@ class GHSLDataHandler(BaseHandler):
             file_ext=".tif",
             extract=True,
             file_pattern=r".*\.tif$",
+            merge_rasters=merge_rasters,
             **kwargs,
         )
 
@@ -801,8 +811,10 @@ class GHSLDataHandler(BaseHandler):
         tif_processors = self.load_data(
             source=source, ensure_available=ensure_available, **kwargs
         )
+        if isinstance(tif_processors, TifProcessor):
+            return tif_processors.to_dataframe(**kwargs)
         return pd.concat(
-            [tp.to_dataframe() for tp in tif_processors], ignore_index=True
+            [tp.to_dataframe(**kwargs) for tp in tif_processors], ignore_index=True
         )
 
     def load_into_geodataframe(
@@ -832,8 +844,10 @@ class GHSLDataHandler(BaseHandler):
         tif_processors = self.load_data(
             source=source, ensure_available=ensure_available, **kwargs
         )
+        if isinstance(tif_processors, TifProcessor):
+            return tif_processors.to_geodataframe(**kwargs)
         return pd.concat(
-            [tp.to_geodataframe() for tp in tif_processors], ignore_index=True
+            [tp.to_geodataframe(**kwargs) for tp in tif_processors], ignore_index=True
         )
 
     def get_available_data_info(

gigaspatial/handlers/giga.py

@@ -8,6 +8,7 @@ from shapely.geometry import Point
 import pycountry
 from typing import Optional, Union
 import logging
+import geopandas as gpd
 
 from gigaspatial.config import config as global_config
 
@@ -40,11 +41,14 @@ class GigaSchoolLocationFetcher:
         if self.logger is None:
             self.logger = global_config.get_logger(self.__class__.__name__)
 
-    def fetch_locations(self, **kwargs) -> pd.DataFrame:
+    def fetch_locations(
+        self, process_geospatial: bool = False, **kwargs
+    ) -> Union[pd.DataFrame, gpd.GeoDataFrame]:
         """
         Fetch and process school locations.
 
         Args:
+            process_geospatial (bool): Whether to process geospatial data and return a GeoDataFrame. Defaults to False.
             **kwargs: Additional parameters for customization
                 - page_size: Override default page size
                 - sleep_time: Override default sleep time between requests
@@ -122,11 +126,12 @@ class GigaSchoolLocationFetcher:
 
         df = pd.DataFrame(all_data)
 
-        df = self._process_geospatial_data(df)
+        if process_geospatial:
+            df = self._process_geospatial_data(df)
 
         return df
 
-    def _process_geospatial_data(self, df: pd.DataFrame) -> pd.DataFrame:
+    def _process_geospatial_data(self, df: pd.DataFrame) -> gpd.GeoDataFrame:
         """
         Process and enhance the DataFrame with geospatial information.
 
@@ -144,7 +149,7 @@ class GigaSchoolLocationFetcher:
         )
         self.logger.info(f"Created geometry for all {len(df)} records")
 
-        return df
+        return gpd.GeoDataFrame(df, geometry="geometry", crs="EPSG:4326")
 
 
 @dataclass(config=ConfigDict(arbitrary_types_allowed=True))