giga-spatial 0.6.9__tar.gz → 0.7.1__tar.gz

{giga_spatial-0.6.9 → giga_spatial-0.7.1}/.env_sample

@@ -15,6 +15,7 @@ export GEOREPO_USER_EMAIL=""
 export GIGA_SCHOOL_LOCATION_API_KEY=""
 export GIGA_SCHOOL_PROFILE_API_KEY=""
 export GIGA_SCHOOL_MEASUREMENTS_API_KEY=""
+export HEALTHSITES_API_KEY=""
 export ROOT_DATA_DIR=""
 export BRONZE_DIR=""
 export SILVER_DIR=""

{giga_spatial-0.6.9 → giga_spatial-0.7.1}/CHANGELOG.md

@@ -2,6 +2,185 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v0.7.1] - 2025-10-15
+
+### Added
+
+-   **Healthsites.io API Integration (`HealthSitesFetcher`):**
+    -   New class `HealthSitesFetcher` to fetch and process health facility data from the Healthsites.io API.
+    -   Supports filtering by country, bounding box extent, and date ranges (`from_date`, `to_date`).
+    -   Provides methods for:
+        -   `fetch_facilities()`: Retrieves health facility locations, returning a `pd.DataFrame` or `gpd.GeoDataFrame` based on output format.
+        -   `fetch_statistics()`: Fetches aggregated statistics for health facilities based on provided filters.
+        -   `fetch_facility_by_id()`: Retrieves details for a specific facility using its OSM type and ID.
+    -   Includes robust handling for API pagination, different output formats (JSON, GeoJSON), and nested data structures.
+    -   Integrates with `OSMLocationFetcher` and `pycountry` to standardize country names to OSM English names for consistent querying.
+    -   Configurable parameters for API URL, API key, page size, flat properties, tag format, output format, and request sleep time.
+
+-   **OSMLocationFetcher Enhancements:**
+    -   **Historical Data Fetching (`fetch_locations_changed_between`):**
+        -   New method `fetch_locations_changed_between()` to retrieve OSM objects that were created or modified within a specified date range. This enables historical analysis and change tracking.
+        -   Defaults `include_metadata` to `True` for this method, as it's typically used for change tracking.
+    -   **Comprehensive OSM Country Information (`get_osm_countries`):**
+        -   New static method `get_osm_countries()` to fetch country-level administrative boundaries directly from the OSM database.
+        -   Supports fetching all countries or a specific country by ISO 3166-1 alpha-3 code.
+        -   Option to include various name variants (e.g., `name:en`, `official_name`) and ISO codes.
+    -   **Metadata Inclusion in Fetched Locations:**
+        -   Added `include_metadata` parameter to `fetch_locations()` to optionally retrieve change tracking metadata (timestamp, version, changeset, user, uid) for each fetched OSM element.
+        -   This metadata is now extracted and included in the DataFrame for nodes, relations, and ways.
+    -   **Flexible Date Filtering in Overpass Queries:**
+        -   Introduced `date_filter_type` (`newer`, `changed`) and `start_date`/`end_date` parameters to `_build_queries()` for more granular control over time-based filtering in Overpass QL.
+    -   **Date Normalization Utility:**
+        -   Added `_normalize_date()` helper method to convert various date inputs (string, datetime object) into a standardized ISO 8601 format for Overpass API queries.
+
+-   **TifProcessor**
+    -   **Comprehensive Memory Management:**
+        -   Introduced `_check_available_memory()`, `_estimate_memory_usage()`, and `_memory_guard()` methods for proactive memory assessment across various operations.
+        -   Added warnings (`ResourceWarning`) for potentially high memory usage in batched operations, with suggestions for optimizing `n_workers`.
+    -   **Chunked DataFrame Conversion:**
+        -   Implemented `to_dataframe_chunked()` for memory-efficient processing of large rasters by converting them to DataFrames in manageable chunks.
+        -   Automatic calculation of optimal `chunk_size` based on target memory usage via `_calculate_optimal_chunk_size()`.
+        -   New helper methods: `_get_chunk_windows()`, `_get_chunk_coordinates()`.
+    -   **Raster Clipping Functionality:**
+        -   `clip_to_geometry()`: New method to clip rasters to arbitrary geometries (Shapely, GeoDataFrame, GeoSeries, GeoJSON-like dicts).
+        -   `clip_to_bounds()`: New method to clip rasters to rectangular bounding boxes, supporting optional CRS transformation for the bounds.
+        -   New helper methods for clipping: `_prepare_geometry_for_clipping()`, `_validate_geometry_crs()`, `_create_clipped_processor()`.
+
+-   **WorldPopDownloader Zip Handling:**
+    -   Modified `download_data_unit` in `WPPopulationDownloader` to correctly handle `.zip` files (e.g., school age datasets) by downloading them to a temporary location and extracting the contained `.tif` files.
+    -   Updated `download_data_units` to correctly flatten the list of paths returned by `download_data_unit` when zip extraction results in multiple files.
+    -   Adjusted `WPPopulationConfig.get_data_unit_paths` to correctly identify and return paths for extracted `.tif` files from zip resources. It is now intelligently resolves paths. For school-age datasets, it returns paths to extracted `.tif` files if available; otherwise, it returns the original `.zip` path(s) to trigger download and extraction.
+    -   Added filter support to `WPPopulationConfig.get_data_unit_paths` hence to the `WPPopulationHandler` for:
+        -   School-age datasets: supports `sex` (e.g., "F", "M", "F_M") and `education_level` (e.g., "PRIMARY", "SECONDARY") filters on extracted `.tif` filenames.
+        -   Non-school-age age_structures: supports `sex`, `ages`, `min_age`, and `max_age` filters on `.tif` filenames.
+-   **WorldPop: Filtered aggregation in `GeometryBasedZonalViewGenerator.map_wp_pop`**:
+    -   `map_wp_pop` now enforces a single country input when `handler.config.project` is "age_structures".
+    -   When `predicate` is "centroid_within" and the project is "age_structures", individual `TifProcessor` objects (representing age/sex combinations) are loaded, sampled with `map_rasters(stat="sum")`, and their results are summed per zone, preventing unintended merging.
+
+-   **PoiViewGenerator: Filtered aggregation in `PoiViewGenerator.map_wp_pop`**:
+    -   `map_wp_pop` now enforces a single country input when `handler.config.project` is "age_structures".
+    -   When `predicate` is "centroid_within" and the project is "age_structures", individual `TifProcessor` objects (representing age/sex combinations) are loaded, sampled with `map_zonal_stats(stat="sum")`, and their results are summed per POI, preventing unintended merging.
+
+-   **TifProcessor Multi-Raster Merging in Handlers and Generators:**
+    -   Extended `_load_raster_data` in `BaseHandlerReader` to support an optional `merge_rasters` argument. When `True` and multiple raster paths are provided, `TifProcessor` now merges them into a single `TifProcessor` object during loading.
+    -   Integrated `merge_rasters` argument into `GHSLDataReader` and `WPPopulationReader`'s `load_from_paths` and `load` methods, enabling control over raster merging at the reader level.
+    -   Propagated `merge_rasters` to `GHSLDataHandler`'s `load_into_dataframe`, and `load_into_geodataframe` methods for consistent behavior across the handler interface.
+
+### Changed
+
+-   **TifProcessor**
+    -   **Unified DataFrame Conversion:**
+        -   Refactored `to_dataframe()` to act as a universal entry point, dynamically routing to internal, more efficient methods for single and multi-band processing.
+        -   Deprecated the individual `_to_band_dataframe()`, `_to_rgb_dataframe()`, `_to_rgba_dataframe()`, and `_to_multi_band_dataframe()` methods in favor of the new unified `_to_dataframe()`.
+        -   `to_dataframe()` now includes a `check_memory` parameter.
+    -   **Optimized `open_dataset` Context Manager:**
+        -   The `open_dataset` context manager now directly opens local files when `LocalDataStore` is used, avoiding unnecessary `rasterio.MemoryFile` creation for improved performance and reduced memory overhead.
+    -   **Enhanced `to_geodataframe` and `to_graph`:**
+        -   Added `check_memory` parameter to `to_geodataframe()` and `to_graph()` for memory pre-checks.
+    -   **Refined `sample_by_polygons_batched`:**
+        -   Included `check_memory` parameter for memory checks before batch processing.
+        -   Implemented platform-specific warnings for potential multiprocessing issues on Windows/macOS.
+    -   **Improved Multiprocessing Initialization:**
+        -   The `_initializer_worker()` method now prioritizes merged, reprojected, or original local file paths for opening, ensuring workers access the most relevant data.
+    -   **Modular Masking and Coordinate Extraction:**
+        -   Introduced new private helper methods: `_extract_coordinates_with_mask()`, `_build_data_mask()`, `_build_multi_band_mask()`, and `_bands_to_dict()` to centralize and improve data masking and coordinate extraction logic.
+    -   **Streamlined Band-Mode Validation:**
+        -   Moved the logic for validating `mode` and band count compatibility into a dedicated `_validate_mode_band_compatibility()` method for better code organization.
+
+-   **GigaSchoolLocationFetcher**
+    -   `fetch_locations()` method:
+        -   Added `process_geospatial` parameter (defaults to `False`) to optionally process geospatial data and return a `gpd.GeoDataFrame`.
+    -   `_process_geospatial_data()` method:
+        -   Modified to return a `gpd.GeoDataFrame` by converting the `pd.DataFrame` with a `geometry` column and `EPSG:4326` CRS.
+
+-   **OSMLocationFetcher Refactoring:**
+    -   **Unified Query Execution and Processing:** Refactored the core logic for executing Overpass queries and processing their results into a new private method `_execute_and_process_queries()`. This centralizes common steps and reduces code duplication between `fetch_locations()` and the new `fetch_locations_changed_between()`.
+    -   **Enhanced `_build_queries`:** Modified `_build_queries` to accept `date_filter_type`, `start_date`, `end_date`, and `include_metadata` to construct more dynamic and feature-rich Overpass QL queries.
+    -   **Updated `fetch_locations` Signature:**
+        -   Replaced `since_year` parameter with `since_date` (which can be a `str` or `datetime` object) for more precise time-based filtering.
+        -   Added `include_metadata` parameter.
+    -   **Improved Logging of Category Distribution:**
+        -   Modified the logging for category distribution to correctly handle cases where categories are combined into a list (when `handle_duplicates='combine'`).
+    -   **`since_year` Parameter:** Removed `since_year` from `fetch_locations()` as its functionality is now superseded by the more flexible `since_date` parameter and the `_build_queries` enhancements.
+
+-   **`PoiViewGenerator` Mapping Methods (`map_zonal_stats`, `map_nearest_points`, `map_google_buildings`, `map_ms_buildings`, `map_built_s`, `map_smod`):**
+    -   Changed `map_zonal_stats` and `map_nearest_points` to return `pd.DataFrame` results (including `'poi_id'` and new mapped columns) instead of directly updating the internal view.
+    -   Updated `map_google_buildings`, `map_ms_buildings`, `map_built_s`, and `map_smod` to capture the `pd.DataFrame` returned by their respective underlying mapping calls (`map_nearest_points` or `map_zonal_stats`) and then explicitly call `self._update_view()` with these results.
+    -   This enhances modularity and allows for more flexible result handling and accumulation.
+
+-   **`ZonalViewGenerator.map_rasters` Enhancements:**
+    -   Modified `map_rasters` to accept `raster_data` as either a single `TifProcessor` or a `List[TifProcessor]`.
+    -   Implemented internal merging of `List[TifProcessor]` into a single `TifProcessor` before performing zonal statistics.
+    -   Replaced `sample_multiple_tifs_by_polygons` with the `TifProcessor.sample_by_polygons` method.
+
+### Fixed
+
+-   **TifProcessor**:
+    -   **`to_graph()` Sparse Matrix Creation:**
+        -   Corrected the sparse matrix creation logic in `to_graph()` to ensure proper symmetric graph representation when `graph_type="sparse"`.
+    -   **Coordinate System Handling in `_initializer_worker`:**
+        -   Ensured that `_initializer_worker` correctly handles different data storage scenarios to provide the correct dataset handle to worker processes, preventing `RuntimeError` due to uninitialized raster datasets.
+
+### Removed
+
+-   **OSMLocationFetcher**
+    -   **Redundant Category Distribution Logging:** Removed the explicit category distribution logging for `handle_duplicates == "separate"` since the `value_counts()` method on the 'category' column already provides this.
+
+
+## [v0.7.0] - 2025-09-17
+
+### Added
+
+- **TifProcessor Revamp**
+    - **Explicit Reprojection Method:** Introduced `reproject_to()` method, allowing on-demand reprojection of rasters to a new CRS with customizable `resampling_method` and `resolution`.
+    - **Reprojection Resolution Control:** Added `reprojection_resolution` parameter to `TifProcessor` for precise control over output pixel size during reprojection.
+    - **Advanced Raster Information:** Added `get_raster_info()` method to retrieve a comprehensive dictionary of raster metadata.
+    - **Graph Conversion Capabilities:** Implemented `to_graph()` method to convert raster data into a graph (NetworkX or sparse matrix) based on pixel adjacency (4- or 8-connectivity).
+    - **Internal Refactoring: `_reproject_to_temp_file`:** Introduced `_reproject_to_temp_file` as a helper for reprojection into temporary files.
+
+- **H3 Grid Generation**
+    - **H3 Grid Generation Module (`gigaspatial/grid/h3.py`):**
+        - Introduced `H3Hexagons` class for managing H3 cell IDs.
+        - Supports creation from lists of hexagons, geographic bounds, spatial geometries, or points.
+        - Provides methods to convert H3 hexagons to pandas DataFrames and GeoPandas GeoDataFrames.
+        - Includes functionalities for filtering, getting k-ring neighbors, compacting hexagons, and getting children/parents at different resolutions.
+        - Allows saving H3Hexagons to JSON, Parquet, or GeoJSON files.
+    - **Country-Specific H3 Hexagons (`CountryH3Hexagons`):**
+        - Extends `H3Hexagons` for generating H3 grids constrained by country boundaries.
+        - Integrates with `AdminBoundaries` to fetch country geometries for precise H3 cell generation.
+
+- **Documentation**
+    - Improved `tif.md` example to showcase multi-raster initialization, explicit reprojection, and graph conversion.
+
+### Changed
+
+- **TifProcessor**
+  - **Improved Temporary File Management:** Refactored temporary file handling for merging and reprojection using `tempfile.mkdtemp()` and `shutil.rmtree` for more robust and reliable cleanup. Integrated with context manager (`__enter__`, `__exit__`) and added a dedicated `cleanup()` method.
+  - **Reprojection during Initialization:** Implemented automatic reprojection of single rasters to a specified `target_crs` during `TifProcessor` initialization.
+  - **Enhanced `open_dataset` Context Manager:** The `open_dataset` context manager now intelligently opens the most up-to-date (merged or reprojected) version of the dataset.
+  - **More Flexible Multi-Dataset Validation:** Modified `_validate_multiple_datasets` to issue a warning instead of raising an error for CRS mismatches when `target_crs` is not set.
+  - **Optimized `_get_reprojection_profile`:** Dynamically calculates transform and dimensions based on `reprojection_resolution` and added LZW compression to reprojected TIFF files to reduce file size.
+
+- **ADLSDataStore Enhancements**
+    - **New `copy_file` method:** Implemented a new method for copying individual files within ADLS, with an option to overwrite existing files.
+    - **New `rename` method:** Added a new method to rename (move) files in ADLS, which internally uses `copy_file` and then deletes the source, with options for overwrite, waiting for copy completion, and polling.
+    - **Revamped `rmdir` method:** Modified `rmdir` to perform batch deletions of blobs, addressing the Azure Blob batch delete limit (256 sub-requests) and improving efficiency for large directories.
+
+- **LocalDataStore Enhancements**
+    - **New `copy_file` method:** Implemented a new method for copying individual files.
+
+### Removed
+
+- Removed deprecated `tabular` property and `get_zoned_geodataframe` method from `TifProcessor`. Users should now use `to_dataframe()` and `to_geodataframe()` respectively.
+
+### Dependencies
+
+- Added `networkx` and `h3` as new dependencies.
+
+### Fixed
+
+- Several small fixes and improvements to aggregation methods.
+
 ## [v0.6.9] - 2025-07-26
 
 ### Fixed

{giga_spatial-0.6.9 → giga_spatial-0.7.1}/PKG-INFO

@@ -1,13 +1,29 @@
 Metadata-Version: 2.4
 Name: giga-spatial
-Version: 0.6.9
+Version: 0.7.1
 Summary: A package for spatial data download & processing
-Home-page: https://github.com/unicef/giga-spatial
 Author: Utku Can Ozturk
 Author-email: utkucanozturk@gmail.com
 License: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/unicef/giga-spatial
+Project-URL: Documentation, https://unicef.github.io/giga-spatial/
+Project-URL: Source, https://github.com/unicef/giga-spatial
+Project-URL: Issue Tracker, https://github.com/unicef/giga-spatial/issues
+Project-URL: Discussions, https://github.com/unicef/giga-spatial/discussions
+Project-URL: Changelog, https://unicef.github.io/giga-spatial/changelog
 Keywords: gigaspatial,spatial,geospatial,gis,remote sensing,data processing,download,openstreetmap,osm,ghsl,grid,point of interest,POI,raster,vector,school connectivity,unicef,giga,mapping,analysis,python
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
 Classifier: License :: OSI Approved :: GNU Affero General Public License v3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
@@ -24,8 +40,9 @@ Requires-Dist: pycountry==24.6.1
 Requires-Dist: pydantic>=2.10.6
 Requires-Dist: rasterio==1.3.10
 Requires-Dist: Requests==2.32.3
-Requires-Dist: scipy==1.15.1
+Requires-Dist: scipy>=1.15.1
 Requires-Dist: Shapely>=2.0.7
+Requires-Dist: networkx>=3.2.1
 Requires-Dist: tqdm==4.65.0
 Requires-Dist: OWSLib==0.32.1
 Requires-Dist: pydantic-settings>=2.7.1
@@ -33,15 +50,16 @@ Requires-Dist: hdx-python-api>=6.3.8
 Requires-Dist: bs4==0.0.2
 Requires-Dist: sqlalchemy-trino==0.5.0
 Requires-Dist: dask>=2024.12.1
+Requires-Dist: h3>=4.2.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
-Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
 Dynamic: license-file
+Dynamic: project-url
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -53,6 +71,14 @@ Dynamic: summary
 
 # GigaSpatial
 
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-brightgreen.svg)](https://opensource.org/license/agpl-v3)
+[![PyPI version](https://badge.fury.io/py/giga-spatial.svg)](https://badge.fury.io/py/giga-spatial)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/giga-spatial.svg?color=dark-green)](https://pypi.org/project/giga-spatial/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI Downloads](https://static.pepy.tech/badge/giga-spatial)](https://pepy.tech/projects/giga-spatial)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/y/unicef/giga-spatial.svg?color=dark-green)](https://github.com/unicef/giga-spatial/graphs/contributors)
+
+
 ## About Giga
 
 [Giga](https://giga.global/) is a UNICEF-ITU initiative to connect every school to the Internet and every young person to information, opportunity and choice. 

{giga_spatial-0.6.9 → giga_spatial-0.7.1}/README.md

@@ -5,6 +5,14 @@
 
 # GigaSpatial
 
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-brightgreen.svg)](https://opensource.org/license/agpl-v3)
+[![PyPI version](https://badge.fury.io/py/giga-spatial.svg)](https://badge.fury.io/py/giga-spatial)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/giga-spatial.svg?color=dark-green)](https://pypi.org/project/giga-spatial/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI Downloads](https://static.pepy.tech/badge/giga-spatial)](https://pepy.tech/projects/giga-spatial)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/y/unicef/giga-spatial.svg?color=dark-green)](https://github.com/unicef/giga-spatial/graphs/contributors)
+
+
 ## About Giga
 
 [Giga](https://giga.global/) is a UNICEF-ITU initiative to connect every school to the Internet and every young person to information, opportunity and choice. 

giga_spatial-0.7.1/docs/examples/processing/tif.md

@@ -0,0 +1,146 @@
+# Processing Raster Files
+
+This example demonstrates how to process raster files using the `TifProcessor` class.
+
+## Prerequisites
+
+Ensure you have installed the `gigaspatial` package and set up the necessary configuration. Follow the [Installation Guide](../getting-started/installation.md) if you haven’t already.
+
+## Example Code
+
+```python
+from gigaspatial.processing import TifProcessor
+from gigaspatial.core.io import LocalDataStore
+from rasterio.warp import Resampling # For reprojection methods
+
+# NOTE: For these examples, replace "/path/to/your/file.tif" with actual paths to your GeoTIFF files.
+# You might need to create dummy files or use existing ones for local testing.
+
+# 1. Initialize with a single TIFF file
+print("--- Single TIFF File Processing ---")
+single_processor = TifProcessor(
+    "/path/to/single_band.tif", 
+    mode="single" # Can be "rgb", "rgba", "multi"
+)
+df_single = single_processor.to_dataframe()
+print("Single-band DataFrame head:")
+print(df_single.head())
+print("Raster Info for single_processor:")
+print(single_processor.get_raster_info())
+
+
+# 2. Initialize with multiple TIFF files for merging and reprojection
+print("\n--- Multi-raster Merging and Reprojection ---")
+# Replace with actual paths to your tif files. Ensure they are compatible for merging.
+# Example: two adjacent tiles from a dataset.
+tif_paths = [
+    "/path/to/raster1.tif",
+    "/path/to/raster2.tif"
+]
+merged_reprojected_processor = TifProcessor(
+    dataset_path=tif_paths,
+    mode="single", # Or "multi", "rgb", "rgba" depending on your data
+    merge_method="mean", # Options: "first", "last", "min", "max", "mean"
+    target_crs="EPSG:4326", # Reproject all rasters to WGS84 during initialization
+)
+df_merged = merged_reprojected_processor.to_dataframe()
+print("Merged and Reprojected DataFrame head:")
+print(df_merged.head())
+print("Raster Info for merged_reprojected_processor:")
+print(merged_reprojected_processor.get_raster_info())
+
+# 3. Explicit Reprojection after initialization
+print("\n--- Explicit Reprojection ---")
+# Reproject the current raster (e.g., the merged one) to a different CRS or resolution
+# In a real scenario, you'd save this to a persistent location.
+reprojected_output_path = "./temp_reprojected_raster.tif" 
+reprojected_path = merged_reprojected_processor.reproject_to(
+    target_crs="EPSG:3857", # Web Mercator
+    output_path=reprojected_output_path,
+    resampling_method=Resampling.bilinear # Different resampling method
+)
+print(f"Raster reprojected to: {reprojected_path}")
+
+# 4. Convert raster to a graph (NetworkX example)
+print("\n--- Raster to Graph Conversion ---")
+# Assuming '/path/to/single_band.tif' is a suitable single-band raster
+graph_processor = TifProcessor(
+    "/path/to/single_band.tif", 
+    mode="single" # Graph conversion typically for single-band data
+)
+graph = graph_processor.to_graph(
+    connectivity=8, # 4-connectivity (von Neumann) or 8-connectivity (Moore)
+    include_coordinates=True, # Include 'x' and 'y' coordinates as node attributes
+    graph_type="networkx" # Or "sparse" for scipy.sparse.csr_matrix
+)
+print(f"Generated a NetworkX graph with {graph.number_of_nodes()} nodes and {graph.number_of_edges()} edges.")
+# Example: Access node attributes (first 5 nodes)
+# for node_id, data in list(graph.nodes(data=True))[:5]:
+#    print(f"Node {node_id}: Value={data['value']:.2f}, X={data.get('x'):.2f}, Y={data.get('y'):.2f}")
+```
+
+## Explanation
+
+The `TifProcessor` class provides robust functionalities for handling GeoTIFF files, from single-band to multi-band (RGB, RGBA) datasets, with advanced processing capabilities including:
+
+-   **Initialization**:
+    -   Can be initialized with a single GeoTIFF file path.
+    -   Supports a list of GeoTIFF file paths for **automatic merging** during initialization, configured via `merge_method` (`first`, `last`, `min`, `max`, `mean`).
+    -   The `mode` parameter (`single`, `rgb`, `rgba`, `multi`) dictates how bands are interpreted and validated.
+    -   `target_crs` and `reprojection_resolution` can be set during initialization to reproject rasters immediately to a consistent CRS and pixel size.
+-   **Data Extraction**:
+    -   `to_dataframe()`: Converts raster data into a pandas DataFrame, with columns for longitude, latitude, and pixel values (or band-specific values for multi-band modes).
+    -   `to_geodataframe()`: Extends `to_dataframe()` by adding a `geometry` column, converting each pixel into a GeoDataFrame representing its bounding box, with the correct CRS.
+-   **Reprojection (`reproject_to`)**:
+    -   Allows explicit reprojection of the current raster to a new Coordinate Reference System (CRS) and/or resolution, saving the output to a specified path or a temporary file.
+    -   Supports different `resampling_method` options (e.g., `Resampling.nearest`, `Resampling.bilinear`).
+-   **Raster Information (`get_raster_info`)**:
+    -   Provides a dictionary containing comprehensive metadata about the raster, such as band count, dimensions, CRS, bounds, transform, data types, nodata values, processing mode, and merge status.
+-   **Graph Conversion (`to_graph`)**:
+    -   Converts raster data into a graph (NetworkX graph or SciPy sparse matrix) based on pixel adjacency.
+    -   Supports `connectivity` of 4 (von Neumann neighborhood) or 8 (Moore neighborhood).
+    -   Can include geographic coordinates and pixel values as node attributes.
+-   **Sampling**:
+    -   `sample_by_coordinates()`: Extracts pixel values at specific geographic coordinates.
+    -   `sample_by_polygons()`: Computes aggregate statistics (e.g., mean, sum, min, max, count) of pixel values within given polygon boundaries, supporting single or multiple statistics.
+    -   `sample_by_polygons_batched()`: Provides a parallelized version of polygon sampling for performance-intensive tasks.
+
+---
+
+# Multi-raster reprojection
+
+The differences in the reprojected metadata are expected and are a direct result of the order of operations: **reproject then merge** versus **merge then reproject**. The two processes follow different steps, leading to variations in the final raster's dimensions, bounds, and resolution.
+
+---
+
+### **Reproject then Merge**
+
+When you specify `target_crs` at initialization, the code first **reprojects each individual raster** to the target CRS (`EPSG:4326`) and then **merges the reprojected outputs**.
+
+- **Step 1: Reprojection**: Each input raster is reprojected from `ESRI:54009` to `EPSG:4326`. During this step, `rasterio`'s `calculate_default_transform` function computes a new transform and pixel dimensions (`width`, `height`) for each raster. The reprojected rasters are now in the same CRS with a consistent resolution (e.g., `0.00918...` degrees).
+- **Step 2: Merging**: The reprojected rasters, which are now in the same CRS and have similar resolutions, are merged. The `rasterio.merge` function can combine these aligned rasters seamlessly. The final output's dimensions are calculated by finding the union of all reprojected rasters' bounds and applying the shared resolution, resulting in a single, larger raster.
+
+This process ensures a uniform resolution and grid alignment across all parts of the final merged raster.
+
+---
+
+### **Merge then Reproject**
+
+When `target_crs` is not specified at initialization, the code first **merges the two rasters** in their original `ESRI:54009` CRS and then **reprojects the single, merged output** to `EPSG:4326`.
+
+- **Step 1: Merging**: The two rasters are merged in `ESRI:54009`. Since they are in the same CRS and have the same resolution (`1000.0` meters), `rasterio.merge` can simply combine them side-by-side. The original raster was `1000x1000`, so merging a second one next to it likely creates a `2000x1000` raster, as seen in the metadata. The resolution remains `1000.0` meters.
+- **Step 2: Reprojection**: The single `2000x1000` raster is then reprojected to `EPSG:4326`. A new transform and pixel dimensions are calculated for this single, larger raster. Since `calculate_default_transform` is working on a different-shaped input, it will calculate a different output resolution and grid shape. The resulting resolution (`0.00973...`) and dimensions (`2076x832`) will be different because the reprojection is performed on a single, larger input rather than two smaller ones.
+
+---
+
+### **Why the Metadata is Different**
+
+- **Resolution**: The `reproject-then-merge` approach maintains a consistent resolution that is calculated for a single tile and then applied to all. The `merge-then-reproject` approach calculates a single resolution for the entire, larger combined area. The process of resampling to a new grid (a core part of reprojection) is inherently sensitive to the input's size and shape.
+- **Dimensions (`width`, `height`)**: The final pixel dimensions are a function of the total bounds and the final resolution. Since the resolution is different in the two methods, the width and height must also be different to cover the same geographic area.
+- **Bounds**: The final bounds are nearly identical in latitude and longitude, which makes sense because both methods represent the same geographic area. Any slight differences are due to rounding and the nuances of resampling.
+
+**Conclusion**: The differences are normal and reflect the non-commutative nature of these two geospatial operations. The **reproject then merge** approach is generally preferable as it ensures greater consistency and can be more accurate when dealing with rasters that have slightly different resolutions or alignments, as it creates a single, clean grid before combining the data.
+
+---
+
+[Back to Examples](../index.md)

{giga_spatial-0.6.9 → giga_spatial-0.7.1}/giga_spatial.egg-info/PKG-INFO

@@ -1,13 +1,29 @@
 Metadata-Version: 2.4
 Name: giga-spatial
-Version: 0.6.9
+Version: 0.7.1
 Summary: A package for spatial data download & processing
-Home-page: https://github.com/unicef/giga-spatial
 Author: Utku Can Ozturk
 Author-email: utkucanozturk@gmail.com
 License: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/unicef/giga-spatial
+Project-URL: Documentation, https://unicef.github.io/giga-spatial/
+Project-URL: Source, https://github.com/unicef/giga-spatial
+Project-URL: Issue Tracker, https://github.com/unicef/giga-spatial/issues
+Project-URL: Discussions, https://github.com/unicef/giga-spatial/discussions
+Project-URL: Changelog, https://unicef.github.io/giga-spatial/changelog
 Keywords: gigaspatial,spatial,geospatial,gis,remote sensing,data processing,download,openstreetmap,osm,ghsl,grid,point of interest,POI,raster,vector,school connectivity,unicef,giga,mapping,analysis,python
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
 Classifier: License :: OSI Approved :: GNU Affero General Public License v3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
@@ -24,8 +40,9 @@ Requires-Dist: pycountry==24.6.1
 Requires-Dist: pydantic>=2.10.6
 Requires-Dist: rasterio==1.3.10
 Requires-Dist: Requests==2.32.3
-Requires-Dist: scipy==1.15.1
+Requires-Dist: scipy>=1.15.1
 Requires-Dist: Shapely>=2.0.7
+Requires-Dist: networkx>=3.2.1
 Requires-Dist: tqdm==4.65.0
 Requires-Dist: OWSLib==0.32.1
 Requires-Dist: pydantic-settings>=2.7.1
@@ -33,15 +50,16 @@ Requires-Dist: hdx-python-api>=6.3.8
 Requires-Dist: bs4==0.0.2
 Requires-Dist: sqlalchemy-trino==0.5.0
 Requires-Dist: dask>=2024.12.1
+Requires-Dist: h3>=4.2.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
-Dynamic: home-page
 Dynamic: keywords
 Dynamic: license
 Dynamic: license-file
+Dynamic: project-url
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
@@ -53,6 +71,14 @@ Dynamic: summary
 
 # GigaSpatial
 
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-brightgreen.svg)](https://opensource.org/license/agpl-v3)
+[![PyPI version](https://badge.fury.io/py/giga-spatial.svg)](https://badge.fury.io/py/giga-spatial)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/giga-spatial.svg?color=dark-green)](https://pypi.org/project/giga-spatial/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI Downloads](https://static.pepy.tech/badge/giga-spatial)](https://pepy.tech/projects/giga-spatial)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/y/unicef/giga-spatial.svg?color=dark-green)](https://github.com/unicef/giga-spatial/graphs/contributors)
+
+
 ## About Giga
 
 [Giga](https://giga.global/) is a UNICEF-ITU initiative to connect every school to the Internet and every young person to information, opportunity and choice. 

{giga_spatial-0.6.9 → giga_spatial-0.7.1}/giga_spatial.egg-info/SOURCES.txt

@@ -61,6 +61,7 @@ gigaspatial/generators/zonal/base.py
 gigaspatial/generators/zonal/geometry.py
 gigaspatial/generators/zonal/mercator.py
 gigaspatial/grid/__init__.py
+gigaspatial/grid/h3.py
 gigaspatial/grid/mercator_tiles.py
 gigaspatial/handlers/__init__.py
 gigaspatial/handlers/base.py
@@ -69,6 +70,7 @@ gigaspatial/handlers/ghsl.py
 gigaspatial/handlers/giga.py
 gigaspatial/handlers/google_open_buildings.py
 gigaspatial/handlers/hdx.py
+gigaspatial/handlers/healthsites.py
 gigaspatial/handlers/mapbox_image.py
 gigaspatial/handlers/maxar_image.py
 gigaspatial/handlers/microsoft_global_buildings.py

giga_spatial-0.6.9/requirements.txt → giga_spatial-0.7.1/giga_spatial.egg-info/requires.txt

@@ -9,12 +9,14 @@ pycountry==24.6.1
 pydantic>=2.10.6
 rasterio==1.3.10
 Requests==2.32.3
-scipy==1.15.1
+scipy>=1.15.1
 Shapely>=2.0.7
+networkx>=3.2.1
 tqdm==4.65.0
 OWSLib==0.32.1
 pydantic-settings>=2.7.1
 hdx-python-api>=6.3.8
 bs4==0.0.2
 sqlalchemy-trino==0.5.0
-dask>=2024.12.1
+dask>=2024.12.1
+h3>=4.2.0

giga_spatial-0.7.1/gigaspatial/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.7.1"

{giga_spatial-0.6.9 → giga_spatial-0.7.1}/gigaspatial/config.py

@@ -38,6 +38,7 @@ class Config(BaseSettings):
     GIGA_SCHOOL_MEASUREMENTS_API_KEY: str = Field(
         default="", alias="GIGA_SCHOOL_MEASUREMENTS_API_KEY"
     )
+    HEALTHSITES_API_KEY: str = Field(default="", alias="HEALTHSITES_API_KEY")
 
     ROOT_DATA_DIR: Path = Field(
         default=Path("."),