Earth Engine¶

Split a GeoDataFrame into chunks.

Parameters¶

gdf : GeoDataFrame GeoDataFrame to chunk chunk_size : int Number of features per chunk

Returns¶

list List of GeoDataFrame chunks

Initialize image collection from string, ImageCollection, or Image.

Initialize Earth Engine API using Pydantic-style config fields.

Validate feature collection.

Validate image collection.

Prepare an ee.Image from the collection with temporal filtering.

Parameters¶

band : str Band to select start_date : str, optional Start date for temporal filtering end_date : str, optional End date for temporal filtering temporal_reducer : str, optional How to reduce temporally (mean, median, max, etc.)

Returns¶

ee.Image Processed image ready for spatial reduction

Process a single chunk by reducing image over features.

Parameters¶

chunk : GeoDataFrame Chunk of features to process image : ee.Image Prepared image to reduce band : str Band name (for output column naming) reducer : str Spatial reducer name scale : float Spatial resolution in meters max_pixels : int Maximum pixels per region tile_scale : int Tile scale factor

Returns¶

GeoDataFrame Processed chunk with reduction results

Core method to reduce image over regions with automatic chunking.

This is the unified processing pipeline used by both map_to_points and map_to_zones.

Print all available band names.

Examples¶

profiler.display_band_names() Available bands (2): 1. avg_rad 2. cf_cvg

Print comprehensive information about the collection.

Examples¶

>>> profiler.display_collection_info()¶

GEE Collection Information¶

Dataset ID: nightlights Collection: NOAA/VIIRS/DNB/MONTHLY_V1/VCMCFG Type: ImageCollection Number of images: 154

Bands: Available bands (2): 1. avg_rad 2. cf_cvg

Temporal coverage: Date range: From: 2012-04-01 To: 2024-12-01

============================================================

Print the date range of the ImageCollection.

Parameters¶

date_format : str Date format string (default: "%Y-%m-%d")

Examples¶

profiler.display_date_range() Date range: From: 2012-04-01 To: 2024-12-01

Print properties of an image.

Parameters¶

image_index : int Index of image to inspect (default: 0)

Get all band names from the collection or image.

Returns¶

list List of band names

Examples¶

profiler = GEEProfiler(dataset_id="nightlights") bands = profiler.get_band_names() print(bands) ['avg_rad', 'cf_cvg']

Get the number of images in the collection.

Returns¶

int Number of images

Get the date range of an ImageCollection.

Parameters¶

date_format : str Date format string (default: "%Y-%m-%d")

Returns¶

dict Dictionary with 'min' and 'max' dates

Raises¶

TypeError If collection is an Image (not ImageCollection)

Examples¶

date_range = profiler.get_date_range() print(date_range)

Get properties of an image from the collection.

Parameters¶

image_index : int Index of image to inspect (default: 0 for first image)

Returns¶

dict Image properties

Map GEE values to point locations with optional circular buffers.

This method extracts values from the Earth Engine image/collection at point locations. If buffer_radius_m is provided, circular buffers are created around points and spatial reduction is applied within each buffer.

Parameters¶

gdf : GeoDataFrame Point locations to enrich (must have Point geometries) band : str, optional Band to extract (uses config default if None) reducer : str, optional Spatial reducer: mean, median, min, max, sum, etc. (uses config default if None) buffer_radius_m : float, optional Buffer radius in meters around each point. If None or 0, point values are extracted directly. start_date : str, optional Start date YYYY-MM-DD for temporal filtering (uses config if None) end_date : str, optional End date YYYY-MM-DD for temporal filtering (uses config if None) temporal_reducer : str, optional How to aggregate over time if multiple images: mean, median, max, etc. (uses config default if None) chunk_size : int, optional Features per chunk for API rate limiting (uses config default if None) scale : float, optional Spatial resolution in meters (uses config/dataset default if None)

Returns¶

GeoDataFrame Enriched GeoDataFrame with new column: {band}_{reducer}

Examples¶

Extract nightlight values at school points with 1km buffers¶

profiler = GEEProfiler(dataset_id="nightlights") enriched = profiler.map_to_points( ... gdf=schools, ... band="avg_rad", ... reducer="mean", ... buffer_radius_m=1000, ... start_date="2020-01-01", ... end_date="2020-12-31" ... ) print(enriched[["school_id", "avg_rad_mean"]].head())

Map GEE values to polygon zones with spatial aggregation.

This method aggregates values from the Earth Engine image/collection within polygon boundaries (e.g., administrative zones, grid cells).

Parameters¶

gdf : GeoDataFrame Polygon zones to aggregate over band : str, optional Band to extract (uses config default if None) reducer : str, optional Spatial reducer: mean, median, min, max, sum, etc. (uses config default if None) start_date : str, optional Start date YYYY-MM-DD for temporal filtering end_date : str, optional End date YYYY-MM-DD for temporal filtering temporal_reducer : str, optional How to aggregate over time: mean, median, max, etc. chunk_size : int, optional Features per chunk for API rate limiting scale : float, optional Spatial resolution in meters

Returns¶

GeoDataFrame Enriched GeoDataFrame with new column: {band}_{reducer}

Examples¶

Aggregate population within admin boundaries¶

profiler = GEEProfiler(dataset_id="population") zones_enriched = profiler.map_to_zones( ... gdf=admin_boundaries, ... band="population_density", ... reducer="sum", ... start_date="2020-01-01", ... end_date="2020-12-31" ... ) print(zones_enriched[["admin_name", "population_density_sum"]].head())

Check if band exists in collection.

Parameters¶

band_name : str Band name to validate

Returns¶

bool True if band exists

Check if requested dates are within collection's date range.

Parameters¶

start_date : str Start date in YYYY-MM-DD format end_date : str End date in YYYY-MM-DD format

Returns¶

bool True if dates are valid