API Reference#
This page documents the public API of ndvi2gif. It is generated directly from the source-code docstrings, so it always matches the installed version of the package.
The library exposes seven main classes plus a couple of helper functions:
Object |
Module |
Purpose |
|---|---|---|
|
Temporal compositing, indices, ROI handling, export and GIFs |
|
|
Sentinel-1 Analysis Ready Data preprocessing |
|
|
Point/region time series, trends and phenology |
|
|
Per-pixel trend rasters (server-side) |
|
|
Per-pixel phenology rasters (server-side) |
|
|
Supervised/unsupervised land cover classification |
|
|
Surface water / flooding metrics |
Note
All classes and helper functions can be imported directly from the top-level
package, e.g. from ndvi2gif import NdviSeasonality, HydroperiodAnalyzer.
NdviSeasonality#
- class ndvi2gif.NdviSeasonality(roi=None, periods=4, start_year=2016, end_year=2020, sat='S2', key='max', index='ndvi', percentile=90, orbit='BOTH', normalize_sar=False, use_sar_ard=True, sar_speckle_filter='REFINED_LEE', sar_terrain_correction=True, sar_terrain_model='VOLUME', cloud_filter=True, max_cloud_cover=20, scl_mask=True)#
Bases:
objectGenerate remote sensing index seasonal composition GIFs and images.
Comprehensive framework for creating temporal composites from multiple satellite data sources. Supports 40+ spectral and radar indices with configurable temporal periods and statistical reducers.
- Parameters:
roi (ee.Geometry, str, list, or None, optional) –
Region of interest specification:
None: Default region (Andalusia, Spain)ee.Geometry: Direct Earth Engine geometrystrPath or special format'*.shp': Shapefile path'*.geojson': GeoJSON file path'deimsid/XXXXX': DEIMS.org site ID'wrs:path,row': Landsat WRS-2 tile (e.g., ‘wrs:200,32’)'s2:XXXXX': Sentinel-2 MGRS tile (e.g., ‘s2:30TXN’)
list: Feature collection from Map.draw_features
periods (int, optional) –
Number of temporal periods per year:
4: Seasonal (winter, spring, summer, autumn)12: Monthly (january through december)24: Bi-monthly (~15 days each, p1 through p24)Other : Custom equal division (p1 through pN)
Default is 4.
start_year (int, optional) – Starting year for analysis (inclusive). Must be within satellite data availability. Default is 2016.
end_year (int, optional) – Ending year for analysis (inclusive). Analysis includes years from start_year to end_year. Default is 2020.
sat ({'S2', 'S1', 'Landsat', 'MODIS', 'S3'}, optional) –
Satellite sensor selection:
'S2': Sentinel-2 MSI (optical, 10-20m, 2015-present)'S1': Sentinel-1 SAR (radar, 10m, 2014-present)'Landsat': Merged L4-5-7-8-9 (optical, 30m, 1982-present)'MODIS': Terra/Aqua (optical, 500m, 2000-present)'S3': Sentinel-3 OLCI (ocean/land, 300m, 2016-present)
Default is ‘S2’.
key ({'max', 'min', 'median', 'mean', 'sum', 'percentile', 'std', 'variance', 'range', 'cv', 'count'}, optional) –
Statistical reducer for temporal aggregation:
'max': Maximum value (vegetation peak detection)'min': Minimum value'median': Median value (robust to outliers)'mean': Mean value (smooth temporal profiles)'sum': Total sum (ideal for precipitation, accumulation)'percentile': Custom percentile (set with percentile param)'std': Standard deviation (within-period variability)'variance': Variance (squared variability)'range': Maximum minus minimum (amplitude)'cv': Coefficient of variation, std divided by mean. Only meaningful for indices that stay positive'count': Number of valid observations per pixel (data availability, not a value statistic)
Default is ‘max’.
index (str, optional) –
Spectral or radar index to compute. Available indices depend on satellite. See
get_available_indices()for full list. Common indices:Vegetation:
'ndvi','evi','savi','gndvi'Water:
'ndwi','mndwi','awei'Burn/Fire:
'nbr','nbri'SAR:
'vh','vv','rvi','vv_vh_ratio'
Default is ‘ndvi’.
percentile (int, optional) –
Percentile value when key=’percentile’. Range: 0-100. Common values:
10-25: Lower percentiles (minimum-like)
50: Median equivalent
75-95: Upper percentiles (maximum-like)
Default is 90.
orbit ({'BOTH', 'ASCENDING', 'DESCENDING'}, optional) –
Sentinel-1 orbit direction (only for sat=’S1’):
'BOTH': All orbits (maximum temporal coverage)'ASCENDING': Single orbit (geometric consistency)'DESCENDING': Single orbit (geometric consistency)
Default is ‘BOTH’.
normalize_sar (bool, optional) – If True, applies Z-score normalization to SAR indices for better comparability with optical indices. Only applies when sat=’S1’. Default is False.
use_sar_ard (bool, optional) – If True, applies advanced SAR preprocessing (ARD pipeline) including terrain correction and sophisticated speckle filtering. Recommended for mountainous areas. Default is True.
sar_speckle_filter (str or None, optional) –
Speckle filter algorithm for SAR (when use_sar_ard=True):
'REFINED_LEE': Refined Lee with edge preservation'LEE': Standard Lee filter'GAMMA_MAP': Gamma Maximum A Posteriori'LEE_SIGMA': Lee Sigma filter'BOXCAR': Simple mean filterNone: No speckle filtering
Default is ‘REFINED_LEE’.
sar_terrain_correction (bool, optional) – Enable radiometric terrain correction for SAR data. Essential for mountainous regions. Default is True.
sar_terrain_model ({'VOLUME', 'SURFACE'}, optional) –
Scattering model for terrain correction:
'VOLUME': Volume scattering (vegetation, crops)'SURFACE': Surface scattering (bare soil, water)
Default is ‘VOLUME’.
- roi#
Processed region of interest geometry
- Type:
ee.Geometry
- ndvi_col#
Configured satellite image collection
- Type:
ee.ImageCollection
Examples
Basic seasonal NDVI analysis:
>>> processor = NdviSeasonality( ... roi='study_area.shp', ... periods=4, ... start_year=2020, ... end_year=2023, ... sat='S2', ... index='ndvi' ... ) >>> processor.get_gif('seasonal_ndvi.gif')
Monthly SAR analysis with percentile:
>>> sar_processor = NdviSeasonality( ... periods=12, ... sat='S1', ... index='vh', ... key='percentile', ... percentile=90, ... orbit='DESCENDING' ... ) >>> collection = sar_processor.get_year_composite()
Using DEIMS site with custom periods:
>>> deims_processor = NdviSeasonality( ... roi='deimsid/11696159-444f-4e06-b537-d4c5c0a4e97d', ... periods=8, # 8 periods per year ... sat='MODIS', ... index='evi' ... )
- Raises:
ValueError – If satellite not supported, index not available for satellite, orbit parameter invalid, or ROI cannot be processed.
ImportError – If required dependencies missing (e.g., deims package).
See also
get_available_indicesQuery available indices for satellites
get_year_compositeGenerate temporal composite images
get_gifCreate animated visualization
get_exportExport composites to GeoTIFF files
Notes
The class automatically validates index-satellite compatibility during initialization. Default ROI covers part of Andalusia, Spain for testing. Temporal periods are generated dynamically to support flexible analysis.
References
- calibrate_nighttime_lights(n_pixels=5000, seed=7, compare_products=True)#
Fit the conversion from VIIRS radiance to DMSP-like digital numbers.
The two nighttime lights records do not join up. DMSP-OLS (1992-2013) is a 6-bit sensor with no on-board calibration; VIIRS (2012-present) reports radiance in nW/cm2/sr. Plotting one after the other produces a step at the sensor change that is pure artefact — measured on the Andalusian coast, “lit area” fell from 7888 km2 in 2013 to 2909 km2 in 2014 simply because
DN >= 20and>= 5 nW/cm2/srare two different definitions of lit.The records do overlap, so the conversion can be fitted on this ROI rather than borrowed from a paper about somewhere else. VIIRS is converted into DMSP-like values, not the other way round: DMSP saturates at 63 over city centres, and a saturating 6-bit integer cannot be inverted into an unbounded radiance.
- Parameters:
n_pixels (int, optional) – Pixels sampled for the fit. Default 5000.
seed (int, optional) – Sampling seed, so a fit can be repeated. Default 7.
compare_products (bool, optional) – Also measure how far the VIIRS product used for the fit is from the one
sat='VIIRS'composites, over the years where both exist. Default True. See the notes.
- Returns:
coefficients(a,b, theceilingand themodelas a string),r2,n(pixels that entered the fit),yearsused, and, withcompare_products,product_difference: the median relative difference between the two VIIRS products over this ROI.- Return type:
Notes
The fit rests on two annual DMSP composites, 2012 and 2013, not on twenty-one independent dates. The regression runs across pixels, which is how the literature does it, but the
r2describes agreement between two images over space, not a time series.The coefficients are fitted on a different VIIRS product from the one they will be applied to. DMSP ends in 2013 and the stray-light corrected VCMSLCFG only starts in 2014, so the fit uses VCMCFG. The two differ mainly at high latitudes in summer;
product_differencemeasures the gap over your ROI so the assumption can be judged rather than assumed.The model is saturating, and deliberately so. Measured over the Andalusian coast, the mean digital number rises 10.6, 26.1, 33.0, 44.9, 51.8, 58.8, 61.2, 62.5 across radiance bins from under 1 to over 80 nW/cm2/sr: monotone, flattening against the 63 ceiling, with 85% of the brightest bin saturated. A polynomial fitted to that turns over — a quadratic predicted DN 0 for the centre of Seville — so
63 * (1 - exp(-a * x**b))is used instead, which cannot exceed the ceiling or fall as radiance rises. It linearises, so the fit is still a single linear regression.Saturated pixels are excluded. A DMSP pixel at 63 records only that the sensor ran out of range, and the linearisation has no logarithm there.
Examples
>>> lights = NdviSeasonality(roi=city, sat='VIIRS', index='avg_rad', ... periods=12, start_year=2014, end_year=2024) >>> fit = lights.calibrate_nighttime_lights() >>> fit['r2'], fit['coefficients'] >>> dmsp_like = lights.to_dmsp_like(some_viirs_image, fit['coefficients'])
- export_to_asset(image, asset_id: str, *, description: str | None = None, region=None, scale: int | None = None, crs: str | None = None, crs_transform: list | None = None, pyramiding_policy: dict | None = None, max_pixels: int = 10000000000000, overwrite: bool = False, clip_region: bool = True)#
Export an ee.Image to an Earth Engine Asset (batch task).
- Parameters:
image (ee.Image) – Earth Engine image to export.
asset_id (str) – Full asset path, e.g., “users/yourname/ndvi2gif/landcover_2022”.
description (str, optional) – Task name. If None, a name is derived from asset_id.
region (ee.Geometry, optional) – Export region. If None, uses
self.roi.scale (int, optional) – Pixel resolution in meters. If None, inferred from the sensor via
_default_scale_for_sat().crs (str, optional) – Target projection. If None, uses the image’s default.
crs_transform (list, optional) – Affine transform (6 or 9 numbers) instead of scale. Mutually exclusive with scale.
pyramiding_policy (dict, optional) – Dict mapping band name to policy (e.g., {“class”: “mode”}).
max_pixels (int, optional) – Maximum number of pixels allowed by Earth Engine. Default 1e13.
overwrite (bool, optional) – If True, tries to delete any existing asset with the same ID first.
clip_region (bool, optional) – If True, the image is clipped to region (or self.roi) before export.
- Returns:
The started Earth Engine export task.
- Return type:
ee.batch.Task
- export_to_drive(image, description: str, *, region=None, scale: int | None = None, crs: str = 'EPSG:4326', folder: str | None = None, file_format: str = 'GeoTIFF', format_options: dict | None = None, max_pixels: int = 10000000000000, file_dimensions: int | None = None, clip_region: bool = True)#
Export an ee.Image to Google Drive as a GeoTIFF (batch task).
- Parameters:
image (ee.Image) – Earth Engine image to export (e.g., a classified map or a composite).
description (str) – Export task name shown in the Earth Engine Tasks panel.
region (ee.Geometry, optional) – Export region. If None, uses
self.roi.scale (int, optional) – Pixel resolution in meters. If None, inferred from the sensor via
_default_scale_for_sat().crs (str, optional) – Target projection (e.g.,
"EPSG:4326"). Default is WGS84.folder (str, optional) – Google Drive folder name. If None, uses the Drive root.
file_format (str, optional) – Output format (e.g.,
"GeoTIFF"). Default"GeoTIFF".format_options (dict, optional) – Additional format options for the exporter (e.g., compression). Example:
{"cloudOptimized": True, "compression": "LZW"}.max_pixels (int, optional) – Maximum number of pixels allowed by Earth Engine. Default
1e13.file_dimensions (int, optional) – Maximum pixel dimension per side for each output tile. If provided, large exports are split into multiple files (e.g., 8192 or 10000).
clip_region (bool, optional) – If True,
imageis clipped toregionbefore exporting.
- Returns:
The started Earth Engine export task.
- Return type:
ee.batch.Task
- Raises:
ValueError – If image is not provided.
ee.EEException – If Earth Engine fails to create the export task.
Notes
This is a batch export: monitor progress in the Earth Engine Tasks panel.
Use
clip_region=Trueand/orfile_dimensionsto keep file sizes manageable.For large regions, consider compression via
format_options.
- export_with_fishnet(image, name_prefix='composite', scale=10, crs='EPSG:4326')#
Export large images using a tiled fishnet approach to overcome memory limitations.
Divides the ROI into regular grid tiles and exports each tile separately. Useful for very large spatial extents that exceed Earth Engine’s single-image export limits.
- Parameters:
image (ee.Image) – Earth Engine image to export (typically from get_year_composite()).
name_prefix (str, optional) – Prefix for output filenames. Files named as ‘{prefix}_tile_{id}.tif’. Default is ‘composite’.
scale (int, optional) – Output pixel resolution in meters. Default is 10.
crs (str, optional) – Coordinate reference system. Default is ‘EPSG:4326’.
Notes
Tile size: 50km × 50km for scale ≥ 30m, 25km × 25km for finer scales. Only exports tiles that intersect with the ROI geometry.
References
Adapted from Earth Engine large-area export strategies.
- get_all_available_indices()#
Get all available indices organized by satellite sensor.
Returns a comprehensive dictionary mapping each supported satellite to its available spectral or radar indices. This method provides a complete overview of the library’s capabilities across all supported sensors.
- Returns:
Dictionary with satellite names as keys and sorted lists of available indices as values. Structure:
{'satellite_name': ['index1', 'index2', ...], ...}
- Return type:
Examples
>>> processor = NdviSeasonality() >>> all_indices = processor.get_all_available_indices() >>> print(all_indices.keys()) dict_keys(['S2', 'Landsat', 'MODIS', 'S1', 'S3'])
>>> # Check capabilities of each sensor >>> for sensor, indices in all_indices.items(): ... print(f"{sensor}: {len(indices)} indices") S2: 29 indices # Most comprehensive (basic + Red Edge) Landsat: 20 indices # Basic optical only MODIS: 20 indices # Basic optical only S1: 7 indices # SAR only S3: 30 indices # Basic optical + ocean/coastal
>>> # Find common indices across optical sensors >>> optical_sensors = ['S2', 'Landsat', 'MODIS'] >>> common_indices = set(all_indices[optical_sensors[0]]) >>> for sensor in optical_sensors[1:]: ... common_indices &= set(all_indices[sensor]) >>> print(f"Common optical indices: {len(common_indices)}") Common optical indices: 20
>>> # Check sensor-specific capabilities >>> s2_only = set(all_indices['S2']) - set(all_indices['Landsat']) >>> print(f"S2-only indices: {sorted(s2_only)}") S2-only indices: ['cire', 'ireci', 'mcari', 'mtci', 'ndci', 'ndre', 'psri', 'reip', 's2rep']
>>> # Validate index availability before processing >>> target_index = 'ndre' >>> compatible_sensors = [sensor for sensor, indices in all_indices.items() ... if target_index in indices] >>> print(f"'{target_index}' available on: {compatible_sensors}") 'ndre' available on: ['S2']
Notes
Sensor Capabilities Summary:
Sentinel-2 (S2): Most versatile optical sensor with Red Edge bands enabling advanced vegetation analysis and chlorophyll estimation
Landsat: Long-term optical observations (1982-present) with consistent band configuration across missions, ideal for time series analysis
MODIS: Global daily coverage at coarser resolution, excellent for large-scale monitoring and climate studies
Sentinel-1 (S1): All-weather SAR observations, unique for detecting structural changes, crop monitoring, and flood mapping
Sentinel-3 (S3): Specialized ocean and coastal monitoring with many spectral bands optimized for water quality assessment
This method is particularly useful for:
Sensor capability comparison
Multi-sensor analysis planning
Index availability validation
Documentation and tutorial purposes
See also
get_available_indicesGet indices for a specific satellite
__init__Where sensor-index mappings are defined
- get_available_indices(satellite=None)#
Get list of available spectral/radar indices for a specific satellite.
- Parameters:
satellite (str or None, optional) – Satellite sensor: ‘S2’, ‘S1’, ‘Landsat’, ‘MODIS’, ‘S3’. If None, uses current satellite (self.sat).
- Returns:
Sorted list of available index names.
- Return type:
Examples
>>> processor = NdviSeasonality(sat='S2') >>> indices = processor.get_available_indices() >>> print(len(indices)) # S2 has most indices 29
>>> # Check for different satellite >>> landsat_indices = processor.get_available_indices('Landsat')
See also
get_all_available_indicesGet indices for all satellites
- get_avi(image, L=0.428)#
Advanced Vegetation Index - Non-linear vegetation index for dense vegetation.
References
Bannari, A., Asalhi, H., Teillet, P.M. (2002). Transformed difference vegetation index (TDVI) for vegetation cover mapping. IEEE International Geoscience and Remote Sensing Symposium, 5, 3053-3055.
- get_awei(image)#
Automated Water Extraction Index - Water detection with shadow consideration.
References
Feyisa, G.L., Meilby, H., Fensholt, R., Proud, S.R. (2014). Automated Water Extraction Index: A new technique for surface water mapping using Landsat imagery. Remote Sensing of Environment, 140, 23-35.
- get_aweinsh(image)#
Automated Water Extraction Index (no shadow) - Water detection without shadow pixels.
References
Feyisa, G.L., Meilby, H., Fensholt, R., Proud, S.R. (2014). Automated Water Extraction Index: A new technique for surface water mapping using Landsat imagery. Remote Sensing of Environment, 140, 23-35.
- get_cdom(image)#
Colored Dissolved Organic Matter Index - CDOM absorption assessment in water bodies.
References
Mannino, A., Russ, M.E., Hooker, S.B. (2008). Algorithm development and validation for satellite‐derived distributions of DOC and CDOM in the U.S. Middle Atlantic Bight. Journal of Geophysical Research: Oceans, 113(C7), C07051.
- get_cf_cvg(image)#
Number of cloud-free observations behind a nighttime lights composite.
Present in both VIIRS and DMSP-OLS, with the same meaning in each: how many nights actually contributed to the pixel. It is the quality band of these datasets — a low count means the radiance of that pixel rests on very few nights, which matters in the tropics and in the polar winter.
Units: count of observations
- get_chirps_precipitation(image)#
Daily precipitation from CHIRPS dataset.
Climate Hazards Group InfraRed Precipitation with Station data (CHIRPS) is a quasi-global rainfall dataset combining satellite imagery with in-situ station data.
Units: millimeters per day (mm/d) Temporal resolution: Daily (1981-present) Spatial resolution: ~5.5 km (0.05°) Coverage: 50°S to 50°N latitude
Use with key=’sum’ for monthly/seasonal precipitation totals. Use with key=’mean’ for average daily precipitation rates.
References
Funk, C., Peterson, P., Landsfeld, M. et al. (2015). The climate hazards infrared precipitation with stations—a new environmental record for monitoring extremes. Scientific Data, 2, 150066. https://doi.org/10.1038/sdata.2015.66
UCSB Climate Hazards Center https://developers.google.com/earth-engine/datasets/catalog/UCSB-CHG_CHIRPS_DAILY
- get_cig(image)#
Chlorophyll Index Green - Chlorophyll content estimation using green band.
References
Gitelson, A.A., Gritz, Y., Merzlyak, M.N. (2003). Relationships between leaf chlorophyll content and spectral reflectance and algorithms for non-destructive chlorophyll assessment in higher plant leaves. Journal of Plant Physiology, 160(3), 271-282.
- get_cire(image)#
Chlorophyll Index Red Edge - Chlorophyll content estimation using red-edge band.
References
Gitelson, A.A., Gritz, Y., Merzlyak, M.N. (2003). Relationships between leaf chlorophyll content and spectral reflectance and algorithms for non-destructive chlorophyll assessment in higher plant leaves. Journal of Plant Physiology, 160(3), 271-282.
- get_cri1(image)#
Carotenoid Reflectance Index 1 - Carotenoid pigment detection.
References
Gitelson, A.A., Zur, Y., Chivkunova, O.B., Merzlyak, M.N. (2002). Assessing carotenoid content in plant leaves with reflectance spectroscopy. Photochemistry and Photobiology, 75(3), 272-281.
- get_cri2(image)#
Carotenoid Reflectance Index 2 - Alternative carotenoid assessment.
References
Gitelson, A.A., Zur, Y., Chivkunova, O.B., Merzlyak, M.N. (2002). Assessing carotenoid content in plant leaves with reflectance spectroscopy. Photochemistry and Photobiology, 75(3), 272-281.
- get_dmsp_avg_lights_x_pct(image)#
DMSP-OLS average lights weighted by the share of lit nights.
The product of
avg_visand the percentage of observations in which the pixel was lit, which downweights pixels that only shine occasionally. Useful to separate a steadily lit town from a place that lights up a few nights a year.Units: 6-bit digital number scaled by the lit fraction Temporal resolution: annual (1992-2013) Spatial resolution: ~1 km (30 arc-seconds)
- get_dmsp_avg_vis(image)#
Average visible band of the DMSP-OLS annual composite.
The raw annual average of the cloud-free nights, ephemeral lights (fires, aurorae, lightning) included. Use
get_dmsp_stable_lights()for the cleaned version.Units: 6-bit digital number (0-63), not a physical radiance Temporal resolution: annual (1992-2013) Spatial resolution: ~1 km (30 arc-seconds)
The 6-bit sensor saturates over city centres and the DN is not calibrated between satellites or years, so a DMSP series needs intercalibration before its values can be compared over time.
References
Elvidge, C.D., Baugh, K.E., Kihn, E.A., Kroehl, H.W., Davis, E.R. (1997). Mapping city lights with nighttime data from the DMSP Operational Linescan System. Photogrammetric Engineering and Remote Sensing, 63(6), 727-734.
https://developers.google.com/earth-engine/datasets/catalog/NOAA_DMSP-OLS_NIGHTTIME_LIGHTS
- get_dmsp_stable_lights(image)#
DMSP-OLS lights with the ephemeral ones removed.
Fires, aurorae and other one-off events are dropped and background noise is set to zero, leaving the lights that were there all year: cities, industry, gas flares. This is the band most DMSP studies use.
Units: 6-bit digital number (0-63), background set to 0 Temporal resolution: annual (1992-2013) Spatial resolution: ~1 km (30 arc-seconds)
See
get_dmsp_avg_vis()for the saturation and intercalibration caveats, which apply here too.
- get_dpsvi(image, normalize=False)#
Modified Dual-Polarization SAR Vegetation Index (DPSVIm).
(VV**2 + VV * VH) / sqrt(2)on linear power. It is the modified form of Periasamy’s DPSVI proposed by dos Santos et al. (2021): the original,(VV_max - VV + VH) / sqrt(2) * (VV + VH) / VV * VH, depends onVV_max, the maximum VV of the whole scene, so it is not a per-pixel index and changes with the extent; the modified form is computed pixel by pixel and compares across scenes and dates. Before 1.6.0 this method returned(VV - VH) / (VV + VH)on dB values, which is neither.- Parameters:
image (ee.Image) – Input SAR image with VV and VH bands
normalize (bool, optional) – If True, normalizes output to [0,1] range. Default is False.
References
dos Santos, E.P., da Silva, D.D., do Amaral, C.H. (2021). Vegetation cover monitoring in tropical regions using SAR-C dual-polarization index: seasonal and spatial influences. International Journal of Remote Sensing, 42(19), 7581-7609. https://doi.org/10.1080/01431161.2021.1959955
Periasamy, S. (2018). Significance of dual polarimetric synthetic aperture radar in biomass retrieval: An attempt on Sentinel-1. Remote Sensing of Environment, 217, 537-549. https://doi.org/10.1016/j.rse.2018.09.003
- get_era5_dewpoint_temperature_2m(image)#
Dewpoint temperature at 2 meters height.
Temperature at which air becomes saturated with water vapor. Units: Kelvin
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_dewpoint_temperature_2m_celsius(image)#
Dewpoint temperature at 2 meters height in Celsius.
Temperature at which air becomes saturated with water vapor. Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_dewpoint_temperature_2m_max(image)#
Daily maximum dewpoint temperature at 2 meters height.
Units: Kelvin (K) For Celsius use dewpoint_temperature_2m_max_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_dewpoint_temperature_2m_max_celsius(image)#
Daily maximum dewpoint temperature at 2 meters height in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_dewpoint_temperature_2m_min(image)#
Daily minimum dewpoint temperature at 2 meters height.
Units: Kelvin (K) For Celsius use dewpoint_temperature_2m_min_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_dewpoint_temperature_2m_min_celsius(image)#
Daily minimum dewpoint temperature at 2 meters height in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_potential_evaporation_sum(image)#
Potential evapotranspiration.
Maximum evaporation that would occur with unlimited water availability. Units: meters Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_potential_evaporation_sum_lm2(image)#
Potential evapotranspiration in liters per square meter (L/m²).
Maximum evaporation with unlimited water availability. Converted from meters to L/m² (m × 1000).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_runoff_sum(image)#
Total runoff (surface + sub-surface).
Units: meters Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_runoff_sum_lm2(image)#
Total runoff (surface + sub-surface) in liters per square meter (L/m²).
Converted from meters to L/m² (m × 1000).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_skin_temperature(image)#
Skin temperature - Earth surface temperature.
Temperature of the Earth’s surface (land or water). Units: Kelvin
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_skin_temperature_celsius(image)#
Skin temperature (Earth surface) in Celsius.
Temperature of the Earth’s surface (land or water). Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_skin_temperature_max(image)#
Daily maximum skin temperature (Earth surface).
Units: Kelvin (K) For Celsius use skin_temperature_max_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_skin_temperature_max_celsius(image)#
Daily maximum skin temperature (Earth surface) in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_skin_temperature_min(image)#
Daily minimum skin temperature (Earth surface).
Units: Kelvin (K) For Celsius use skin_temperature_min_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_skin_temperature_min_celsius(image)#
Daily minimum skin temperature (Earth surface) in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_snow_depth_water_equivalent(image)#
Snow depth in water equivalent.
Amount of water that would result from melting the snow. Units: meters of water equivalent
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_snowfall_sum(image)#
Snowfall amount.
Units: meters of water equivalent Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_snowfall_sum_lm2(image)#
Snowfall amount in liters per square meter (L/m²).
Converted from meters of water equivalent to L/m² (m × 1000).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_soil_temperature_level_1(image)#
Soil temperature at level 1 (0-7 cm depth).
Temperature in the topmost soil layer. Units: Kelvin
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_soil_temperature_level_1_celsius(image)#
Soil temperature at level 1 (0-7 cm depth) in Celsius.
Temperature in the topmost soil layer. Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_soil_temperature_level_1_max(image)#
Daily maximum soil temperature at level 1 (0-7 cm depth).
Units: Kelvin (K) For Celsius use soil_temperature_level_1_max_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_soil_temperature_level_1_max_celsius(image)#
Daily maximum soil temperature at level 1 (0-7 cm depth) in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_soil_temperature_level_1_min(image)#
Daily minimum soil temperature at level 1 (0-7 cm depth).
Units: Kelvin (K) For Celsius use soil_temperature_level_1_min_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_soil_temperature_level_1_min_celsius(image)#
Daily minimum soil temperature at level 1 (0-7 cm depth) in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_surface_latent_heat_flux_sum(image)#
Surface latent heat flux.
Energy used for evaporation/condensation. Units: J/m² Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_surface_net_solar_radiation_sum(image)#
Net solar radiation at the surface.
Incoming minus reflected solar radiation. Units: J/m² Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_surface_pressure(image)#
Atmospheric pressure at the surface.
Units: Pascals (Pa)
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_surface_runoff_sum(image)#
Surface runoff only.
Water that flows over the land surface. Units: meters Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_surface_runoff_sum_lm2(image)#
Surface runoff in liters per square meter (L/m²).
Water that flows over the land surface. Converted from meters to L/m² (m × 1000).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_surface_solar_radiation_downwards_sum(image)#
Downward solar radiation at the surface.
Total incoming shortwave radiation. Units: J/m² Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_temperature_2m(image)#
Air temperature at 2 meters height.
Returns temperature in Kelvin. For Celsius: subtract 273.15
References
ERA5-Land: ECMWF Climate Reanalysis https://developers.google.com/earth-engine/datasets/catalog/ECMWF_ERA5_LAND_DAILY_AGGR
- get_era5_temperature_2m_celsius(image)#
Air temperature at 2 meters height in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis https://developers.google.com/earth-engine/datasets/catalog/ECMWF_ERA5_LAND_DAILY_AGGR
- get_era5_temperature_2m_max(image)#
Daily maximum air temperature at 2 meters height.
Units: Kelvin (K) For Celsius use temperature_2m_max_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_temperature_2m_max_celsius(image)#
Daily maximum air temperature at 2 meters height in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_temperature_2m_min(image)#
Daily minimum air temperature at 2 meters height.
Units: Kelvin (K) For Celsius use temperature_2m_min_celsius
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_temperature_2m_min_celsius(image)#
Daily minimum air temperature at 2 meters height in Celsius.
Converted from Kelvin to Celsius (K - 273.15).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_total_evaporation_sum(image)#
Total evapotranspiration from land surface.
Includes evaporation from soil, vegetation, and water bodies. Units: meters of water equivalent Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_total_evaporation_sum_lm2(image)#
Total evapotranspiration in liters per square meter (L/m²).
Includes evaporation from soil, vegetation, and water bodies. Converted from meters to L/m² (m × 1000).
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_total_precipitation_sum(image)#
Total daily precipitation (rain + snow combined).
Units: meters of water equivalent Note: Flow band - accumulated daily sum
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_total_precipitation_sum_lm2(image)#
Total daily precipitation in liters per square meter (L/m²).
Rain + snow combined. Converted from meters to L/m² (m × 1000). Note: 1 mm = 1 L/m²
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_u_component_of_wind_10m(image)#
Eastward wind component at 10 meters height.
Positive values indicate wind from west to east. Units: m/s
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_v_component_of_wind_10m(image)#
Northward wind component at 10 meters height.
Positive values indicate wind from south to north. Units: m/s
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_volumetric_soil_water_layer_1(image)#
Volumetric soil water content at layer 1 (0-7 cm depth).
Volume fraction of water in soil (0-1). Units: m³/m³
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_volumetric_soil_water_layer_2(image)#
Volumetric soil water content at layer 2 (7-28 cm depth).
Volume fraction of water in soil (0-1). Units: m³/m³
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_volumetric_soil_water_layer_3(image)#
Volumetric soil water content at layer 3 (28-100 cm depth).
Volume fraction of water in soil (0-1). Units: m³/m³
References
ERA5-Land: ECMWF Climate Reanalysis
- get_era5_volumetric_soil_water_layer_4(image)#
Volumetric soil water content at layer 4 (100-289 cm depth).
Volume fraction of water in soil (0-1). Units: m³/m³
References
ERA5-Land: ECMWF Climate Reanalysis
- get_evi(image)#
Enhanced Vegetation Index - Improved vegetation monitoring with reduced atmospheric influence.
References
Huete, A., Didan, K., Miura, T., Rodriguez, E.P., Gao, X., Ferreira, L.G. (2002). Overview of the radiometric and biophysical performance of the MODIS vegetation indices. Remote Sensing of Environment, 83(1-2), 195-213.
- get_export(crs='EPSG:4326', scale=10)#
Export all temporal composite images to individual GeoTIFF files with descriptive names.
Processes the complete time series analysis and exports each year’s composite as a separate multi-band GeoTIFF file. Filenames are automatically generated using a descriptive pattern that includes the index, statistical method, and year.
This method orchestrates the entire workflow: generates temporal composites, creates meaningful filenames, and exports all results in a single operation.
- Parameters:
crs (str, optional) – Coordinate Reference System for output rasters in EPSG format. Applied to all exported files. Common options: - ‘EPSG:4326’: WGS84 Geographic (lat/lon) - universal compatibility - ‘EPSG:3857’: Web Mercator - web mapping applications - ‘EPSG:32633’: UTM Zone 33N - metric measurements (example) Default is ‘EPSG:4326’.
scale (int or float, optional) – Output pixel resolution in meters for all exports. Should be appropriate for the satellite sensor: - Sentinel-2: 10-20m (native resolution) - Landsat: 30m (native resolution) - MODIS: 500m (native resolution) - Sentinel-1: 10m (native resolution) - Sentinel-3: 300m (native resolution) Default is 10.
- Returns:
Files are saved to disk with progress information printed to console.
- Return type:
None
Notes
Automatic Filename Generation: Filenames follow the pattern: {sat}_{index}_{statistic}_{year}.tif
Examples: - ‘ndvi_max_2020.tif’ (NDVI with maximum reducer) - ‘evi_median_2021.tif’ (EVI with median reducer) - ‘vh_p90_2022.tif’ (VH SAR with 90th percentile) - ‘rvi_mean_2019.tif’ (RVI SAR with mean reducer)
Statistical Method Naming: - ‘max’: Maximum value reducer - ‘median’: Median value reducer - ‘mean’: Mean value reducer - ‘p{N}’: Percentile reducer (e.g., ‘p90’ for 90th percentile)
Multi-band Structure: Each exported file contains multiple bands representing temporal periods: - 4 periods: [‘winter’, ‘spring’, ‘summer’, ‘autumn’] - 12 periods: [‘january’, ‘february’, …, ‘december’] - 24 periods: [‘p1’, ‘p2’, …, ‘p24’] - Custom: [‘p1’, ‘p2’, …, ‘pN’]
Processing Workflow: 1. Clear previous results and initialize processing 2. Generate temporal composites using get_year_composite() 3. For each successful year: a. Generate descriptive filename b. Export multi-band composite to GeoTIFF c. Provide progress feedback 4. Report completion summary
Examples
>>> # Basic export with default settings >>> processor = NdviSeasonality( ... sat='S2', ... index='ndvi', ... start_year=2020, ... end_year=2023, ... key='max' ... ) >>> processor.get_export() # Exports: ndvi_max_2020.tif, ndvi_max_2021.tif, ndvi_max_2022.tif
>>> # SAR analysis with percentile statistics >>> sar_processor = NdviSeasonality( ... sat='S1', ... index='vh', ... key='percentile', ... percentile=90, ... periods=12 ... ) >>> sar_processor.get_export(scale=20) # Exports: vh_p90_2020.tif, vh_p90_2021.tif, etc.
>>> # Monthly analysis with UTM projection >>> monthly_processor = NdviSeasonality( ... sat='Landsat', ... index='evi', ... periods=12, ... key='median' ... ) >>> monthly_processor.get_export(crs='EPSG:32633', scale=30) # Exports: evi_median_2020.tif, evi_median_2021.tif, etc.
>>> # Multi-sensor comparison workflow >>> sensors = ['S2', 'Landsat', 'MODIS'] >>> for sat in sensors: ... proc = NdviSeasonality(sat=sat, index='ndvi', start_year=2020, end_year=2022) ... proc.get_export() # Creates separate files for each sensor-year combination
Performance Notes#
Processing Time Factors: - Time range: (end_year - start_year + 1) × periods - Spatial extent: ROI area × scale resolution - Sensor complexity: SAR < Optical (due to preprocessing) - Statistical method: max ≈ median < mean < percentile
Optimization Strategies: - Use appropriate scale for sensor (avoid unnecessary upsampling) - Consider seasonal periods (4) vs monthly (12) for time vs detail trade-off - For very large areas, use export_with_fishnet() instead - Process smaller time ranges for iterative analysis
Output File Characteristics: - Format: GeoTIFF with embedded georeferencing - Compression: Default LZW compression for smaller files - Data type: Float32 for index values, preserving fractional precision - NoData handling: Masked pixels preserved from input data
- raises ee.EEException:
If Earth Engine processing fails due to memory limits, timeout, authentication issues, or invalid parameters.
- raises OSError:
If local file system issues occur (insufficient disk space, permission errors, invalid file paths).
- raises RuntimeError:
If no valid temporal composites can be generated (e.g., no satellite data available for specified time range and region).
Warning
Years with insufficient data are automatically skipped with console warnings
Large time ranges or high-resolution analyses may approach computation limits
Existing files with same names will be overwritten without warning
See also
get_export_single : Export individual images with custom names get_year_composite : Generate the temporal composites that are exported export_with_fishnet : Alternative for very large spatial extents get_gif : Create animated visualizations instead of static exports
>>> # Load exported files for further analysis >>> import rasterio >>> with rasterio.open('ndvi_max_2020.tif') as src: ... data = src.read() # Shape: (bands, height, width) ... summer_data = src.read(3) # Read summer band specifically
>>> # Multi-temporal analysis >>> import numpy as np >>> years = range(2020, 2023) >>> summer_trend = [] >>> for year in years: ... with rasterio.open(f'ndvi_max_{year}.tif') as src: ... summer_trend.append(src.read(3)) # Summer band >>> trend = np.array(summer_trend) >>> mean_summer = np.mean(trend, axis=0)
- get_export_single(image, name='mycomposition.tif', crs='EPSG:4326', scale=10)#
Export a single Earth Engine image to a GeoTIFF file.
Exports a specific composite image or any Earth Engine image to the local file system as a GeoTIFF raster. This method is useful for exporting individual images, statistical summaries, or custom analyses derived from the temporal composites.
- Parameters:
image (ee.Image) – Earth Engine image to export. Can be any single or multi-band image, including temporal composites, statistical summaries, or processed derivatives from get_year_composite().
name (str, optional) – Output filename including extension. Should end with ‘.tif’ for GeoTIFF format. The file will be saved in the current working directory. Default is ‘mycomposition.tif’.
crs (str, optional) – Coordinate Reference System for the output raster in EPSG format. Common options: - ‘EPSG:4326’: WGS84 Geographic (lat/lon) - ‘EPSG:3857’: Web Mercator - ‘EPSG:32633’: UTM Zone 33N (example) Default is ‘EPSG:4326’.
scale (int or float, optional) – Output pixel resolution in meters. Should match or be appropriate for the input satellite data: - Sentinel-2: 10-20m - Landsat: 30m - MODIS: 500m - Sentinel-1: 10m - Sentinel-3: 300m Default is 10.
Examples
>>> # Export a single year composite >>> processor = NdviSeasonality(sat='S2', index='ndvi', periods=4) >>> collection = processor.get_year_composite() >>> single_image = collection.first() >>> processor.get_export_single(single_image, 'ndvi_2020_seasonal.tif')
>>> # Export temporal statistics >>> mean_composite = collection.mean() >>> processor.get_export_single(mean_composite, 'ndvi_multiyear_mean.tif', scale=20)
>>> # Export specific band or analysis >>> summer_only = single_image.select('summer') >>> processor.get_export_single(summer_only, 'summer_ndvi_2020.tif')
>>> # Export with custom CRS and higher resolution >>> processor.get_export_single( ... image=single_image, ... name='high_res_composite.tif', ... crs='EPSG:32633', # UTM projection ... scale=10 ... )
>>> # Export derived analysis >>> seasonal_range = single_image.select('summer').subtract(single_image.select('winter')) >>> processor.get_export_single(seasonal_range, 'seasonal_amplitude.tif')
Notes
File Output: - Files are saved to the current working directory (os.getcwd()) - GeoTIFF format with embedded CRS and geotransform information - Multi-band images preserve all bands in a single file - Pixel values maintain original data type and scaling
Performance Considerations: - Export time depends on: image size × number of bands × scale resolution - Large regions or high resolutions may approach Earth Engine limits - Consider using export_with_fishnet() for very large areas - Processing occurs on Earth Engine servers, then downloads locally
Common Use Cases: - Single image export from temporal analysis - Statistical summaries (mean, max, std) across time series - Specific band extraction for focused analysis - Custom mathematical operations on composites - Quality control and validation sample export
- Raises:
ee.EEException – If Earth Engine encounters processing errors, authentication issues, or export limitations (memory, timeout, etc.).
OSError – If there are local file system issues (permissions, disk space, etc.).
ValueError – If parameters are invalid (unsupported CRS, negative scale, etc.).
See also
get_exportExport entire time series automatically
get_year_compositeGenerate temporal composites for export
export_with_fishnetExport large areas using tiled approach
References
Earth Engine Export Documentation: https://developers.google.com/earth-engine/guides/exporting
- get_fai(image)#
Floating Algae Index (FAI) - Detection of floating algae and cyanobacterial blooms in water bodies.
Computes a NIR baseline by linear interpolation between the Red and SWIR2 bands at the NIR wavelength, then subtracts it from the observed NIR reflectance. Positive FAI values indicate floating algae or cyanobacterial surface accumulations; negative values correspond to open water.
Works with surface reflectance (SR) data. Compatible with Sentinel-2, Landsat, and MODIS. Not applicable to Sentinel-3 OLCI (no SWIR band available).
Formula#
FAI = NIR - NIR_baseline NIR_baseline = Red + (SWIR2 - Red) * (lambda_NIR - lambda_red) / (lambda_SWIR2 - lambda_red)
- Sensor-specific center wavelengths (nm) and resulting interpolation factors:
Sentinel-2 MSI : lambda_NIR=835.1, lambda_red=664.5, lambda_SWIR2=2202.4 -> factor=0.1109 Landsat 8/9 OLI : lambda_NIR=864.7, lambda_red=654.6, lambda_SWIR2=2201.2 -> factor=0.1359 MODIS Terra/Aqua : lambda_NIR=858.5, lambda_red=645.0, lambda_SWIR2=2130.0 -> factor=0.1438
Note: The Landsat collection in ndvi2gif merges OLI (L8/9) and TM/ETM+ (L4-7). OLI wavelengths are used as representative values. The interpolation factor for TM/ETM+ (~0.113) differs slightly but the impact on FAI is minor.
References
Hu, C. (2009). A novel ocean color index to detect floating algae in the global oceans. Remote Sensing of Environment, 113(10), 2118-2129. https://doi.org/10.1016/j.rse.2009.05.012
- get_floating_algae(image)#
Floating Algae Index - Detection of floating algae and surface algal blooms.
References
Hu, C. (2009). A novel ocean color index to detect floating algae in the global oceans. Remote Sensing of Environment, 113(10), 2118-2129.
- get_fluorescence_height(image)#
Chlorophyll Fluorescence Line Height - Natural chlorophyll fluorescence detection.
References
Gower, J., King, S., Borstad, G., Brown, L. (2005). Detection of intense plankton blooms using the 709 nm band of the MERIS imaging spectrometer. International Journal of Remote Sensing, 26(9), 2005-2012.
- get_gif(name='mygif.gif', bands=None)#
Create an animated GIF showing the temporal evolution of period composites.
Generates a video animation (downloaded as GIF) where each frame corresponds to one year and each RGB image uses selected period composites (e.g., winter-spring-summer). Internally calls
get_year_composite()and exports the video usinggeemap.download_ee_video(). Optionally, an annotated version is created with year labels and a progress bar usinggeemap.add_text_to_gif().- Parameters:
name (str, optional) – Name of the output file (
.gif). Saved in the current working directory. Default:'mygif.gif'.bands (list of str or None, optional) – Band names to use as
[R, G, B]in the animation. Must be valid periods (e.g.,'winter','spring'or'p1','p2'). IfNone, the first three period names are used (self.period_names[:3]).
Notes
SAR sensors (S1): a typical dB scale is applied (
min=-25,max=0).Optical sensors: a typical vegetation index range is applied (
min=0.15,max=0.85).Output video is set to
dimensions=768pixels andframesPerSecond=10for a balance between clarity and file size.
- Raises:
ee.EEException – If processing or export fails (memory limits, runtime errors, authentication issues).
ValueError – If bands does not contain exactly 3 valid periods present in
self.period_names.OSError – If a file system error occurs when writing the GIF locally.
See also
get_year_compositeGenerates yearly composites used in the animation.
get_exportExports static multi-band images instead of an animation.
geemap.download_ee_videoHandles Earth Engine video export.
geemap.add_text_to_gifAdds annotations (year and progress bar).
Examples
>>> # Seasonal composite with Sentinel-2 (RGB = winter, spring, summer) >>> NdviSeasonality(sat='S2', index='ndvi', periods=4, start_year=2020, end_year=2023).get_gif('ndvi_seasons.gif') >>> # Monthly SAR composite (using specific months as RGB) >>> proc = NdviSeasonality(sat='S1', index='vh', periods=12) >>> proc.get_gif('vh_monthly.gif', bands=['march', 'june', 'september'])
- get_gndvi(image)#
Green Normalized Difference Vegetation Index - Sensitive to chlorophyll content.
References
Gitelson, A.A., Kaufman, Y.J., Merzlyak, M.N. (1996). Use of a green channel in remote sensing of global vegetation from EOS-MODIS. Remote Sensing of Environment, 58(3), 289-298.
- get_ireci(image)#
Inverted Red-Edge Chlorophyll Index - Highly sensitive to chlorophyll content.
References
Frampton, W.J., Dash, J., Watmough, G., Milton, E.J. (2013). Evaluating the capabilities of Sentinel-2 for quantitative estimation of biophysical variables in vegetation. ISPRS Journal of Photogrammetry and Remote Sensing, 82, 83-92.
- get_kd490(image)#
Diffuse Attenuation Coefficient at 490nm - Water transparency and optical depth assessment.
References
Mueller, J.L. (2000). SeaWiFS algorithm for the diffuse attenuation coefficient K(490) using water-leaving radiances at 490 and 555 nm. SeaWiFS Postlaunch Calibration and Validation Analyses, Part 3, 11, 24-27.
- get_lai(image)#
Leaf Area Index approximation - Estimate of leaf area per unit ground area.
References
Boegh, E., Soegaard, H., Broge, N., Hasager, C.B., Jensen, N.O., Schelde, K., Thomsen, A. (2002). Airborne multispectral data for quantifying leaf area index, nitrogen concentration, and photosynthetic efficiency in agriculture. Remote Sensing of Environment, 81(2-3), 179-193.
- get_lst(image)#
Land Surface Temperature (LST) - Multi-sensor implementation with robust error handling Automatically detects sensor and applies appropriate scaling and conversion
Supported sensors and bands: - Landsat 8/9 (OLI/TIRS): ST_B10 (Band 10 - thermal infrared) - Landsat 7 (ETM+): ST_B6 (Band 6 - thermal infrared) - Landsat 4/5 (TM): ST_B6 (Band 6 - thermal infrared) - MODIS Terra/Aqua: LST_Day_1km (Land Surface Temperature)
Note: Sentinel-3 LST is not available in Google Earth Engine as it requires SLSTR instrument data, but only OLCI is available in GEE.
Returns temperature in Celsius degrees with quality control
- get_mcari(image)#
Modified Chlorophyll Absorption Ratio Index - Chlorophyll content with reduced soil influence.
References
Daughtry, C.S.T., Walthall, C.L., Kim, M.S., de Colstoun, E.B., McMurtrey, J.E. (2000). Estimating corn leaf chlorophyll concentration from leaf and canopy reflectance. Remote Sensing of Environment, 74(2), 229-239.
- get_mndwi(image)#
Modified Normalized Difference Water Index - Enhanced water detection, reduces built-up noise.
References
Xu, H. (2006). Modification of normalised difference water index (NDWI) to enhance open water features in remotely sensed imagery. International Journal of Remote Sensing, 27(14), 3025-3033.
- get_msi(image)#
Moisture Stress Index - Plant water stress detection.
References
Rock, B.N., Vogelmann, J.E., Williams, D.L., Vogelmann, A.F., Hoshizaki, T. (1986). Remote detection of forest damage. BioScience, 36(7), 439-445.
- get_mtci(image)#
MERIS Terrestrial Chlorophyll Index - Chlorophyll content adapted for terrestrial vegetation.
References
Dash, J., Curran, P.J. (2004). The MERIS terrestrial chlorophyll index. International Journal of Remote Sensing, 25(23), 5403-5413.
- get_nbr(image)#
Normalized Burn Ratio (NBR) - Ratio Normalizado de Quemadura
Detecta áreas quemadas usando la diferencia entre NIR y SWIR2. NBR = (NIR - SWIR2) / (NIR + SWIR2)
Valores típicos: - > 0.27: Vegetación densa no quemada - 0.1 - 0.27: Vegetación moderada - -0.1 - 0.1: Área quemada reciente - < -0.1: Quemadura severa
Para detectar cambios: dNBR = NBR_prefire - NBR_postfire
Referencias#
Key, C.H., Benson, N.C. (2006). Landscape Assessment: Ground measure of severity, the Composite Burn Index. FIREMON: Fire effects monitoring and inventory framework. USDA Forest Service.
- get_nbri(image)#
Normalized Burn Ratio Index - Fire damage and burn severity assessment.
References
Key, C., Benson, N. (2006). Landscape Assessment: Ground measure of severity, the Composite Burn Index; and Remote sensing of severity, the Normalized Burn Ratio. FIREMON: Fire Effects Monitoring and Inventory System, RMRS-GTR-164-CD.
- get_ndbi(image)#
Normalized Difference Built-up Index (NDBI) - Índice Normalizado de Construcción
Detecta áreas urbanas y construidas usando la diferencia entre SWIR1 y NIR. NDBI = (SWIR1 - NIR) / (SWIR1 + NIR)
Valores: - > 0: Área construida (más alto = más urbano) - < 0: Vegetación/agua - 0.1 - 0.5: Área urbana típica - > 0.5: Área densamente construida
Referencias#
Zha, Y., Gao, J., Ni, S. (2003). Use of normalized difference built-up index in automatically mapping urban areas from TM imagery. International Journal of Remote Sensing, 24(3), 583-594.
- get_ndci(image)#
Normalized Difference Chlorophyll Index - Optimized for cyanobacteria and chlorophyll-a detection in water.
Formula: (Red_Edge1 - Red) / (Red_Edge1 + Red) Uses Red Edge 1 (B5) and Red (B4) - optimized for Sentinel-2.
References
Mishra, S., Mishra, D.R. (2012). Normalized difference chlorophyll index: A novel model for remote estimation of chlorophyll-a concentration in turbid productive waters. Remote Sensing of Environment, 117, 394-406.
Gitelson, A.A., Dall’Olmo, G., Moses, W., Rundquist, D.C., Barrow, T., Fisher, T.R., … Holz, J. (2008). A simple semi-analytical model for remote estimation of chlorophyll-a in turbid waters: Validation. Remote Sensing of Environment, 112(9), 3582-3593.
- get_ndmi(image)#
Normalized Difference Moisture Index - Vegetation water content assessment.
References
Hardisky, M.A., Klemas, V., Smart, R.M. (1983). The influence of soil salinity, growth form, and leaf moisture on the spectral radiance of Spartina alterniflora canopies. Photogrammetric Engineering and Remote Sensing, 49(1), 77-83.
- get_ndre(image)#
Normalized Difference Red Edge - Sensitive to chlorophyll content variations.
References
Gitelson, A., Merzlyak, M.N. (1994). Spectral reflectance changes associated with autumn senescence of Aesculus hippocastanum L. and Acer platanoides L. leaves. Journal of Plant Physiology, 143(3), 286-292.
- get_ndsi(image)#
Normalized Difference Snow Index - Snow cover detection and monitoring.
References
Dozier, J. (1989). Spectral signature of alpine snow cover from the Landsat Thematic Mapper. Remote Sensing of Environment, 28, 9-22.
- get_ndti(image)#
Normalized Difference Tillage Index - Agricultural tillage and residue detection.
References
Van Deventer, A.P., Ward, A.D., Gowda, P.H., Lyon, J.G. (1997). Using thematic mapper data to identify contrasting soil plains and tillage practices. Photogrammetric Engineering and Remote Sensing, 63(1), 87-93.
- get_ndvi(image)#
Normalized Difference Vegetation Index - Most widely used vegetation index.
References
Rouse, J.W., Haas, R.H., Schell, J.A., Deering, D.W. (1974). Monitoring vegetation systems in the Great Plains with ERTS. Third ERTS Symposium, NASA SP-351 I: 309-317.
- get_ndwi(image)#
Normalized Difference Water Index - Water body detection and monitoring.
References
Gao, B. (1996). NDWI - A normalized difference water index for remote sensing of vegetation liquid water from space. Remote Sensing of Environment, 58(3), 257-266.
- get_nmi(image)#
Normalized Multi-band Drought Index - Multi-spectral drought assessment.
References
Wang, L., Qu, J.J. (2007). NMDI: A normalized multi‐band drought index for monitoring soil and vegetation moisture with satellite remote sensing. Geophysical Research Letters, 34(20), L20405.
- get_oci(image)#
OLCI Chlorophyll Index - Custom chlorophyll index using OLCI L1B radiance data.
References
Hu, C., Lee, Z., Franz, B. (2012). Chlorophyll a algorithms for oligotrophic oceans: A novel approach based on three‐band reflectance difference. Journal of Geophysical Research: Oceans, 117(C1), C01011.
- get_peak_period(per_year=False, across_years='median', return_peak_value=False, mask_below=None, return_ties=False, composite=None)#
Map the period of the year in which each pixel reaches its maximum.
Answers “when”, not “how much”: for every pixel, which of the temporal periods holds the highest value of the configured index. The result is a timing map — the month of peak greenness, the season of deepest flooding, the month a city shines brightest.
The periods are the ones the instance is already configured with, so the output values run from 1 to
self.periodsand correspond toperiod_namesin order.- Parameters:
per_year (bool, optional) – If False (default), the years are collapsed first (see
across_years) and a single image is returned: the period in which the typical year peaks. If True, returns one image per year, each tagged with ayearproperty, so the peak can be tracked over time.across_years ({'median', 'mean', 'max'}, optional) – How the yearly composites are combined before the peak is looked up. Ignored when
per_year=True. Default is'median', which is robust to a single anomalous year.return_peak_value (bool, optional) – If True, the output keeps a second band,
peak_value, with the index value at the peak. Default is False.mask_below (float, optional) – Mask out the pixels whose peak value does not reach this threshold. The timing of a pixel with no signal is noise, so this is the usual way to restrict the map to pixels that are actually lit, flooded or vegetated. Default is None (keep every pixel).
return_ties (bool, optional) – If True, the output keeps a band
tieswith the number of periods that reach that same maximum: 1 where the peak is unique, 2 or more where the choice of period was arbitrary. Default is False.composite (ee.Image, optional) – Use this multi-band composite — one band per period, in order — instead of building one. For a composite that has already been processed: chlorophyll masked to the water pixels, an index masked to a land cover, a stack assembled by hand. Its bands are renamed to
period_namesif they differ, so the output still means “period number”. Ignored whenper_year=True.
- Returns:
Band
peak_period, an integer from 1 toself.periods, pluspeak_valueandtiesif requested. Anee.Imagewhenper_year=False, anee.ImageCollectionof one image per year otherwise. Pixels with no valid data in any period are masked.- Return type:
ee.Image or ee.ImageCollection
Notes
The peak is resolved with
qualityMosaicover one candidate image per period, which is what makes empty periods harmless: a period with no data is masked and simply does not compete. Two consequences worth knowing:Ties go to the later period. If two periods hold exactly the same maximum, the second one wins. Rather than picking a winner by some other rule — the first, the middle, the average of the tied periods, all of which invent information the data does not have —
return_ties=Truereports how many periods tied, so the pixels where the answer is arbitrary can be found and dealt with downstream. Exact ties are common with integer values (a count, a saturated 6-bit DMSP city) and rare with reflectance.A pixel masked in every period comes back masked, rather than defaulting to period 1.
Like every composite of this library, the result carries no fixed projection, so anything that asks for it at another scale resamples it. That is harmless for a display, but it makes a
frequencyHistogramof the periods report fractional counts for values no pixel holds: count the periods witheq()at the native scale, orreproject()the image first.This is not the phenological POS of
SpatialPhenologyAnalyzer, which fits and smooths the series before locating the maximum. Here the maximum is taken from the composites as they are: cruder, far cheaper, and defined for any index and any sensor.Examples
Month of peak greenness over six years:
>>> processor = NdviSeasonality(roi=roi, sat='S2', periods=12, ... index='ndvi', key='median', ... start_year=2018, end_year=2023) >>> peak = processor.get_peak_period()
Month of peak nighttime light, restricted to lit pixels:
>>> lights = NdviSeasonality(roi=city, sat='VIIRS', periods=12, ... index='avg_rad', key='mean', ... start_year=2017, end_year=2017) >>> peak = lights.get_peak_period(mask_below=2, return_peak_value=True)
Follow the peak year by year:
>>> peaks = processor.get_peak_period(per_year=True) >>> peaks.aggregate_array('year').getInfo()
- get_peak_statistics(mask_below=None, min_years=2, peaks=None)#
Circular mean and concentration of the peak period across the years.
get_peak_period()withper_year=Truegives one peak period per year. Summarising those with an ordinary average is wrong, because the period of the year is a circular variable: the arithmetic mean of December (12) and January (1) is 6.5 — June — when the answer is late December. The wrap-around is the obvious failure, but not the only one. A pixel that peaks in February in half the years and in June in the other half averages to April, a month in which nothing ever happened there.The statistics that are defined on a circle are computed instead. Each period becomes an angle, the unit vectors are averaged, and the mean direction is read back as a period number:
Each period
pbecomes an angletheta = (p - 1) * 2*pi / n; the unit vectors are averaged intoC = mean(cos theta)andS = mean(sin theta). The circular mean isatan2(S, C), read back as a period number, and the resultant lengthR = sqrt(C**2 + S**2)is the concentration: how much the years agree.Ris the number that makes the mean readable, and it should be reported with it. R near 1 means every year peaked at the same time and the mean is a real date. R near 0 means the years point in every direction, the mean direction is arbitrary, and quoting it alone would invent a season. A bimodal pixel — February and June — has a low R, which is how it can be told from a genuinely April-peaking pixel that the arithmetic mean would have made it look like.- Parameters:
mask_below (float, optional) – Passed to
get_peak_period(): drop the pixels whose peak value does not reach this threshold, in the years where it does not. The timing of a pixel with no signal is noise. Ignored whenpeaksis given.min_years (int, optional) – Mask the pixels with fewer than this many valid years. Two years give a direction but no useful concentration, so raise it when R is going to be interpreted. Default 2.
peaks (ee.ImageCollection, optional) – A collection already produced by
get_peak_period(per_year=True), to avoid recomputing it. Only itspeak_periodband is read.
- Returns:
Band
circular_mean, the mean peak period, fractional and running from 1 toself.periods(a value of 12.6 withperiods=12means “late December, a fifth of the way into January”); bandconcentration, R between 0 and 1; and bandn_years, how many years the pixel contributed.- Return type:
ee.Image
Notes
R has no threshold that makes it “significant”; it is a descriptive statistic. As a rough guide over yearly data, above about 0.8 the years cluster tightly, below about 0.4 the mean carries little meaning. If a test is wanted, R is the statistic the Rayleigh test of uniformity is built on.
Examples
Month of peak greenness and how repeatable it is:
>>> processor = NdviSeasonality(roi=roi, periods=12, sat='S2', ... start_year=2018, end_year=2024) >>> stats = processor.get_peak_statistics() >>> reliable = stats.updateMask(stats.select('concentration').gt(0.7))
Reusing a collection of peaks that is already in hand:
>>> peaks = processor.get_peak_period(per_year=True, mask_below=0.3) >>> stats = processor.get_peak_statistics(peaks=peaks)
- get_period_composite(year, period_idx)#
Generate composite image for a specific temporal period within a year.
Creates a single composite by applying the configured statistical reducer to all satellite images within the defined temporal period. Core processing function for temporal composite generation.
- Parameters:
- Returns:
Single-band composite image with the selected index values, cast to float (to 32-bit integer for
key='count'). Band name depends on reducer type (see_composite_band_name()). A period with no images still returns one band: fully masked, or 0 everywhere forkey='count'.- Return type:
ee.Image
Notes
Processing workflow:
Extract date range from
self.period_dates[period_idx]Filter satellite collection to date range
Apply index calculation (
self.d[self.index])Apply statistical reducer (max/median/mean/percentile)
Return composite image, or a placeholder band if the period has no images
The method assumes valid inputs as validation occurs during initialization.
Examples
Generate winter composite for 2020:
>>> processor = NdviSeasonality(periods=4, start_year=2020) >>> winter_2020 = processor.get_period_composite(2020, 0) # 0=winter
Generate July composite for monthly analysis:
>>> monthly = NdviSeasonality(periods=12, sat='S2') >>> july_2021 = monthly.get_period_composite(2021, 6) # 6=July (0-based)
See also
get_year_compositeCalls this method for all periods
_generate_periodsDefines period date ranges
- get_pri(image)#
Photochemical Reflectance Index - Plant stress and photosynthetic efficiency.
References
Gamon, J.A., Peñuelas, J., Field, C.B. (1992). A narrow-waveband spectral index that tracks diurnal changes in photosynthetic efficiency. Remote Sensing of Environment, 41(1), 35-44.
- get_psri(image)#
Plant Senescence Reflectance Index - Plant senescence and carotenoid/chlorophyll ratio.
References
Merzlyak, M.N., Gitelson, A.A., Chivkunova, O.B., Rakitin, V.Y. (1999). Non‐destructive optical detection of pigment changes during leaf senescence and fruit ripening. Physiologia Plantarum, 106(1), 135-141.
- get_raw_band(image, band)#
Return a single reflectance band through the regular index machinery.
Spectral indices are ratios, so they cancel out multiplicative changes in brightness: a pixel can keep its NDVI unchanged while its actual reflectance drifts. Radiometric work needs the bands themselves. The typical case is selecting pseudo-invariant features (PIFs) for relative radiometric normalization, where the criterion is per-band reflectance stability, not index stability.
The value is surface reflectance (0-1) on every sensor, so the same threshold means the same thing whichever produced it: Landsat is rescaled by
scale_OLI()/scale_ETM(), and Sentinel-2 and MODIS, which store reflectance as integers multiplied by 10000, by_to_reflectance()when the collection is built.Available as
index='blue','green','red','nir','swir1','swir2'on Sentinel-2, Landsat and MODIS, plus'red_edge1','red_edge2'and'red_edge3'on Sentinel-2. Sentinel-3 is not supported: its bands are TOA radiances.- Parameters:
image (ee.Image) – Image with standardized band names (Blue, Green, Red, Nir, Swir1, Swir2, Red_Edge1-3).
band (str) – Standardized band name to extract.
- Returns:
Single-band image of surface reflectance, renamed to
'nd'to match the band bookkeeping ofget_year_composite().- Return type:
ee.Image
Examples
Map how stable SWIR1 is over a whole Sentinel-2 series, one composite per year covering the full year:
>>> n = NdviSeasonality(roi=roi, start_year=2018, end_year=2025, ... periods=1, sat='S2', index='swir1', ... key='std') >>> within_year = n.get_year_composite()
Combine it with the between-year dispersion of the annual means:
>>> m = NdviSeasonality(roi=roi, start_year=2018, end_year=2025, ... periods=1, sat='S2', index='swir1', ... key='mean') >>> between_year = m.get_year_composite().reduce(ee.Reducer.stdDev())
See also
get_available_indicesLists the indices and bands available per sensor
- get_red_edge_position(image)#
Red Edge Position optimized for OLCI - Chlorophyll-sensitive wavelength position indicator.
References
Gower, J., King, S., Borstad, G., Brown, L. (2005). Detection of intense plankton blooms using the 709 nm band of the MERIS imaging spectrometer. International Journal of Remote Sensing, 26(9), 2005-2012.
- get_reip(image)#
Red Edge Inflection Point - Wavelength position of maximum slope in red-edge region.
References
Guyot, G., Baret, F. (1988). Utilisation de la haute resolution spectrale pour suivre l’etat des couverts vegetaux. Proceedings of the 4th International Colloquium on Spectral Signatures of Objects in Remote Sensing, 279-286.
- get_rfdi(image, normalize=False)#
Radar Forest Degradation Index - Forest disturbance and degradation monitoring.
- Parameters:
image (ee.Image) – Input SAR image with VV and VH bands
normalize (bool, optional) – If True, normalizes output to [0,1] range. Default is False.
References
Ningthoujam, R.K., Balzter, H., Tansey, K., Feldpausch, T.R., Mitchard, E.T., Wani, A.A., Joshi, P.K. (2018). Relationships of S-1 C-band SAR backscatter with forest cover, height and aboveground biomass at multiple spatial scales across four forest types. Remote Sensing, 10(9), 1442.
Mitchard, E.T.A., Saatchi, S.S., White, L.J.T., Abernethy, K.A., Jeffery, K.J., Lewis, S.L., et al. (2012). Mapping tropical forest biomass with radar and spaceborne LiDAR in Lopé National Park, Gabon. Biogeosciences, 9(1), 179-191. https://doi.org/10.5194/bg-9-179-2012
Defined by Mitchard et al. as
(HH - HV) / (HH + HV); Sentinel-1 carries VV/VH, so the dual-pol adaptation(VV - VH) / (VV + VH)is used, on linear power (before 1.6.0 it was(VV - VH) / VVon dB).
- get_rvi(image, normalize=False)#
Radar Vegetation Index - More robust vegetation indicator than individual polarizations.
- Parameters:
image (ee.Image) – Input SAR image with VV and VH bands
normalize (bool, optional) – If True, normalizes output to [0,1] range. Default is False.
VH) (Dual-polarization form 4 * VH / (VV +)
linear (computed on)
power (the collection is in dB, which gives meaningless values here.)
References
Kim, Y., Jackson, T., Bindlish, R., Lee, H., Hong, S. (2012). Radar vegetation index for estimating the vegetation water content of rice and soybean. IEEE Geoscience and Remote Sensing Letters, 9(4), 564-568.
Nasirzadehdizaji, R., Balik Sanli, F., Abdikan, S., Cakir, Z., Sekertekin, A., Ustuner, M. (2019). Sensitivity analysis of multi-temporal Sentinel-1 SAR parameters to crop height and canopy coverage. Applied Sciences, 9(4), 655. https://doi.org/10.3390/app9040655
- get_s2rep(image)#
Sentinel-2 Red Edge Position - Simplified red-edge position estimation for Sentinel-2.
References
Frampton, W.J., Dash, J., Watmough, G., Milton, E.J. (2013). Evaluating the capabilities of Sentinel-2 for quantitative estimation of biophysical variables in vegetation. ISPRS Journal of Photogrammetry and Remote Sensing, 82, 83-92.
- get_savi(image, L=0.428)#
Soil Adjusted Vegetation Index - Reduces soil background influence on vegetation indices.
References
Huete, A.R. (1988). A soil-adjusted vegetation index (SAVI). Remote Sensing of Environment, 25(3), 295-309.
- get_spm(image)#
Suspended Particulate Matter Index - Quantification of suspended particles in water.
References
Binding, C.E., Bowers, D.G., Mitchelson‐Jacob, E.G. (2005). Estimating suspended sediment concentrations from ocean colour measurements in moderately turbid waters; the impact of variable particle scattering properties. Remote Sensing of Environment, 94(3), 373-383.
- get_stats(image=None, geom=None, name=None, stat='MEDIAN', scale=10, to_file=False)#
Compute zonal statistics for temporal composites within specified geometries.
Automatically processes all years in the time series, computing statistics for each year separately. If a single image is provided, processes only that image.
- Parameters:
image (ee.Image, ee.ImageCollection, or None, optional) – Input for statistical analysis. Can be: - None: Uses get_year_composite() to process entire time series (default) - ee.Image: Single image (e.g., one year composite) - ee.ImageCollection: Custom collection to process
geom (ee.Geometry, str, or None, optional) – Geometry defining zones for statistics. Can be: - None: Use self.roi (default) - str: Path to shapefile (.shp) or GeoJSON (.geojson) - ee.Geometry: Earth Engine geometry object
name (str or None, optional) – Output filename prefix. If None, uses ‘zonal_stats’. For multi-year: creates ‘{name}_{year}.shp’ files.
stat (str, optional) – Statistical method: ‘MEAN’, ‘MEDIAN’, ‘MAX’, ‘MIN’, ‘STDDEV’. Default is ‘MEDIAN’.
scale (int, optional) – Pixel resolution for analysis in meters. Default is 10.
to_file (bool, optional) – If True, saves results as shapefile(s). Default is False.
- Returns:
Single image: Returns GeoDataFrame with statistics
Multiple years: Returns dict {year: GeoDataFrame} with results per year
- Return type:
dict or geopandas.GeoDataFrame
- get_tsi(image)#
Trophic State Index - Water trophic state classification for eutrophication assessment.
References
Carlson, R.E. (1977). A trophic state index for lakes. Limnology and Oceanography, 22(2), 361-369.
Kratzer, S., Håkansson, B., Sahlin, C. (2003). Assessing Secchi and photic zone depth in the Baltic Sea from satellite data. AMBIO: A Journal of the Human Environment, 32(8), 577-585.
- get_turbidity(image)#
Water Turbidity Index - Suspended sediment and water clarity assessment using OLCI bands.
References
Nechad, B., Ruddick, K.G., Park, Y. (2010). Calibration and validation of a generic multisensor algorithm for mapping of total suspended matter in turbid waters. Remote Sensing of Environment, 114(4), 854-866.
- get_utfvi(image)#
Urban Thermal Field Variance Index (UTFVI) - Versión corregida y simplificada
Fórmula simplificada basada en la relación LST-NDVI: UTFVI = (LST - LST_mean) / std_dev
Donde LST_mean se aproxima usando la relación inversa con NDVI.
Valores esperados: - > 0.5: Zona urbana fuerte (isla de calor) - 0 a 0.5: Zona urbana moderada - < 0: Zona vegetada/fresca
- get_vci(image)#
Vegetation Condition Index (VCI) - Índice de Condición de Vegetación
Compara el NDVI actual con los valores históricos mín/máx para detectar estrés vegetal. VCI = (NDVI - NDVImin) / (NDVImax - NDVImin) * 100
Valores: - 0-20: Sequía severa - 20-40: Sequía moderada - 40-60: Condiciones normales - 60-80: Condiciones favorables - 80-100: Condiciones muy favorables
Referencias#
Kogan, F.N. (1995). Application of vegetation index and brightness temperature for drought detection. Advances in Space Research, 15(11), 91-100.
Note: Esta implementación usa valores aproximados. Para análisis precisos, usar estadísticas multi-anuales específicas del área.
- get_vh(image, normalize=False)#
VH Polarization - Vertical transmit, horizontal receive. Sensitive to vegetation structure.
- Parameters:
image (ee.Image) – Input SAR image with VH band
normalize (bool, optional) – If True, normalizes output to [0,1] range. Default is False.
References
Ulaby, F.T., Moore, R.K., Fung, A.K. (1986). Microwave Remote Sensing: Active and Passive. Volume 3: From Theory to Applications. Artech House, Norwood, MA.
- get_viirs_avg_rad(image)#
Average nighttime radiance from the VIIRS Day/Night Band.
The monthly VCMSLCFG composite: cloud-free average radiance with the stray light of the polar summer corrected, which is what makes it usable at high latitudes. Moonlight, airglow and fires are not removed, so a bright pixel is not necessarily a lit one.
Units: nW/cm²/sr Temporal resolution: monthly (2014-present) Spatial resolution: ~500 m (15 arc-seconds)
Use with
key='mean'or'median'; a monthly composite already is the average of its cloud-free nights.References
Elvidge, C.D., Baugh, K., Zhizhin, M., Hsu, F.C., Ghosh, T. (2017). VIIRS night-time lights. International Journal of Remote Sensing, 38(21), 5860-5879. https://doi.org/10.1080/01431161.2017.1342050
Earth Observation Group, Colorado School of Mines https://developers.google.com/earth-engine/datasets/catalog/NOAA_VIIRS_DNB_MONTHLY_V1_VCMSLCFG
- get_viirs_cloud_mask(image)#
Cloud mask flags of a VIIRS Black Marble daily pixel.
QF_Cloud_Maskis a bitmask, not a number to average: bits hold day or night, cloud confidence, cirrus, snow or ice. Exposed so it can be decoded withbitwiseAndwhen the default quality mask is not enough.
- get_viirs_lunar_irradiance(image)#
Lunar irradiance at the time of the VIIRS overpass.
The moonlight that the BRDF correction of
get_viirs_ntl()removed. Useful to check that a pattern in the lights is not the lunar cycle in disguise.Units: nW/cm²/sr
- get_viirs_ntl(image)#
Daily nighttime radiance, corrected for the moon and the atmosphere.
The Black Marble product (VNP46A2) removes what the monthly composite leaves in: moonlight, atmospheric scattering, terrain and the angle of view are all modelled away, so what is left is the light the surface actually emitted. That is what makes a daily value comparable to the next day’s, and a map of the date of the maximum meaningful.
Units: nW/cm²/sr Temporal resolution: daily (2012-present) Spatial resolution: ~500 m
Cloudy nights are still cloudy: the quality mask (
mask_viirs_quality(), applied whencloud_filter=True) drops the retrievals the algorithm itself grades as poor.References
Román, M.O., Wang, Z., Sun, Q. et al. (2018). NASA’s Black Marble nighttime lights product suite. Remote Sensing of Environment, 210, 113-143. https://doi.org/10.1016/j.rse.2018.03.017
https://developers.google.com/earth-engine/datasets/catalog/NASA_VIIRS_002_VNP46A2
- get_viirs_ntl_gap_filled(image)#
Daily nighttime radiance with the missing nights filled in.
Same as
get_viirs_ntl(), but the pixels without a valid retrieval are filled from a temporal model instead of being left empty. Convenient for a continuous series, dangerous for anything that counts observations: a filled value is a prediction, not a measurement, andquality_flagis what tells them apart.Units: nW/cm²/sr
- get_viirs_quality_flag(image)#
Retrieval quality of a VIIRS Black Marble daily pixel.
Values: 0 high quality (persistent lights), 1 high quality (ephemeral lights), 2 poor quality (outlier or cloud contaminated), 255 no retrieval. See
mask_viirs_quality(), which keeps 0 and 1.With
key='count'this counts the nights that produced a value in each period, which is the coverage behind any daily-lights composite.
- get_viirs_snow_flag(image)#
Snow or ice cover under a VIIRS Black Marble daily pixel.
Values: 0 no snow or ice, 1 snow or ice. Fresh snow reflects artificial light back to the sensor and can double the apparent radiance of a city, so a winter peak deserves a look at this band.
- get_vsdi(image, normalize=False)#
Vegetation Scattering Diversity Index (experimental).
sqrt((VV - VH)**2 + (VV + VH)**2), computed on the dB values of the collection. No publication defining this index has been found — it was previously attributed to Periasamy (2018), who defines DPDD, IDPDD, VDDPI and DPSVI but not this — so treat it as an experimental feature without a physical interpretation, and prefer the documented indices for anything that has to be reported.- Parameters:
image (ee.Image) – Input SAR image with VV and VH bands (dB)
normalize (bool, optional) – If True, normalizes output to [0,1] range. Default is False.
- get_vv(image, normalize=False)#
VV Polarization - Vertical transmit, vertical receive. Sensitive to rough surface scattering.
- Parameters:
image (ee.Image) – Input SAR image with VV band
normalize (bool, optional) – If True, normalizes output to [0,1] range. Default is False.
References
Ulaby, F.T., Moore, R.K., Fung, A.K. (1986). Microwave Remote Sensing: Active and Passive. Volume 3: From Theory to Applications. Artech House, Norwood, MA.
- get_vv_vh_ratio(image, normalize=False)#
VV/VH Ratio - Highly sensitive to structural changes, ideal for crop monitoring and mowing detection.
- Parameters:
image (ee.Image) – Input SAR image with VV and VH bands
normalize (bool, optional) – If True, normalizes output to [0,1] range. Default is False.
References
Mascolo, L., Lopez‐Sanchez, J.M., Vicente‐Guijalba, F., Nunziata, F., Migliaccio, M., Mazzarella, G. (2016). A complete procedure for crop phenology estimation with PolSAR data based on the complex Wishart classifier. IEEE Transactions on Geoscience and Remote Sensing, 54(11), 6505-6515.
Computed on linear power. In dB the same information is the difference
VV - VH; dividing two dB values, as before 1.6.0, gives a number with no physical meaning.
- get_water_leaving_reflectance(image)#
Water Leaving Reflectance - Simplified approximation of water-leaving radiance contribution.
References
Gordon, H.R., Brown, O.B., Evans, R.H., Brown, J.W., Smith, R.C., Baker, K.S., Clark, D.K. (1988). A semianalytic radiance model of ocean color. Journal of Geophysical Research: Atmospheres, 93(D9), 10909-10924.
- get_water_mask(mode='dynamic', water_index='mndwi', threshold=0.0, occurrence=90, return_area=False)#
Water masks for the configured period grid, one band per period.
Which pixels count as water is a choice, not a fact, and it changes the answer: over Iznajar in a single July, NDWI called 11.1 km2 water, MNDWI 10.4 and AWEInsh 7.0. Leaving that choice to be improvised in each analysis is how two studies of the same reservoir stop being comparable, so it is a parameter here.
- Parameters:
mode (str, tuple or ee.Geometry, optional) –
How the water surface is defined.
'dynamic'(default) — the water detected in each period of each year. Follows a drawdown, and is the only mode that can.'permanent'— the pixels that are water in every period that has data: the minimum extent, the pool that never dries. Periods with no scene are skipped rather than counted as dry, so one cloudy month does not empty the pool.'maximum'— the pixels that are water in any period: the maximum extent.('jrc', occurrence)or'jrc'— JRC Global Surface Water occurrence at or aboveoccurrencepercent.an
ee.Geometry,ee.FeatureCollection, or a path to a shapefile or GeoJSON — a zone you supply.
water_index (str, optional) – Index used to detect water in the first three modes. One of
'ndwi','mndwi','awei','aweinsh','wi2015'. Default'mndwi', which handles built-up surroundings better than NDWI.threshold (float, optional) – A pixel is water where the index exceeds this. Default 0.0.
occurrence (int, optional) – Occurrence percentage for the
'jrc'mode. Default 90.return_area (bool, optional) – If True, also return the masked area in km2 per year and period.
- Returns:
One image per year, each with one band per period named after
period_names, holding 1 on water and masked elsewhere. The static modes repeat the same mask in every band and every year, so that consumers do not have to special-case them. Withreturn_area=True, a(collection, areas)tuple whereareasis{year: [km2, ...]}.- Return type:
ee.ImageCollection or tuple
Notes
Report the area whenever the mask is dynamic. Each period is then averaged over a different population of pixels, so a change in the series mixes a change in the quantity with a change in what was measured. The area is what separates the two, which is why
return_areaexists and whywater_mask_areais filled in.A dense algal bloom can fall out of a dynamic mask, and that bias runs downwards. Bloom water is spectrally close to vegetation — the near infrared rises — so a water index stops calling it water, and the pixels dropped are exactly the ones carrying the most chlorophyll. A mean taken over what is left is biased low, and nothing in the output says so. MNDWI holds up better than NDWI here, because the water under a bloom still absorbs the shortwave infrared almost completely, which is why it is the default. Check the area series against the index series before trusting either: a drop in masked area at the same time as a peak in chlorophyll is the signature of this, not of a drawdown. The opposite mistake is just as real — a fixed polygon keeps the dry tail, whose index in summer is pasture, not algae.
``’maximum’`` is the one that misleads. It includes pixels that are dry most of the time, and the chlorophyll index of a dry pixel is grassland. It defines a study domain; it does not compute a mean over water.
The JRC layer ends in December 2021 (GSW 1.4 covers 1984-03 to 2021-12). It is stable and comparable across sites, which is its virtue, but it knows nothing about a drought that came later.
Examples
Chlorophyll over the water actually present in each month:
>>> ndci = NdviSeasonality(roi=reservoir, sat='S2', index='ndci', ... periods=12, start_year=2020, end_year=2024) >>> masks, area = ndci.get_water_mask(return_area=True) >>> composites = ndci.get_year_composite()
The pool that never dries, as a single image:
>>> permanent = ee.Image(ndci.get_water_mask('permanent').first())
A fixed domain from the global layer:
>>> domain = ndci.get_water_mask(('jrc', 95))
- get_wdrvi(image)#
Wide Dynamic Range Vegetation Index - Enhanced vegetation monitoring for dense canopies.
References
Gitelson, A.A. (2004). Wide dynamic range vegetation index for remote quantification of biophysical characteristics of vegetation. Journal of Plant Physiology, 161(2), 165-173.
- get_wi2015(image)#
Water Index 2015 (WI2015) - Linear water index fitted on Landsat surface reflectance.
1.7204 + 171*Green + 3*Red - 70*NIR - 45*SWIR1 - 71*SWIR2on surface reflectance in 0-1, as published. Positive values are water. Before 1.6.0 the coefficients were divided by 100 on the belief that the original ones were meant for unscaled digital numbers; the constant was left as is, so the index sat around 1.5 everywhere and did not separate water from land.References
Fisher, A., Flood, N., Danaher, T. (2016). Comparing Landsat water index methods for automated water classification in eastern Australia. Remote Sensing of Environment, 175, 167-182. https://doi.org/10.1016/j.rse.2015.12.055
- get_year_composite(return_counts: bool = False, count_valid_pixels: bool = False, scale_for_valid: int = 10, maxPixels_for_valid: float = 1000000000.0, count_mode: str = 'granules', return_df: bool = False, df_pivot: bool = False)#
Generate temporal composite images for all years in the time range.
Main processing method that creates multi-band images where each band represents a temporal period (season, month, etc.) using the configured statistical reducer and spectral/radar index.
- Parameters:
return_counts (bool, optional) – If True, also return a list of dictionaries with image counts per year and period. Default is False (only the ImageCollection).
count_valid_pixels (bool, optional) – If True, counts only images that contain at least one valid (non-masked) pixel within the ROI for each period. If False, simply counts the number of images in the filtered ImageCollection, regardless of whether they contribute valid pixels to the ROI. Default is False.
scale_for_valid (int, optional) – Spatial resolution (meters) used when checking valid pixels with
reduceRegion(only applies ifcount_valid_pixels=True). Default is 10.maxPixels_for_valid (float, optional) – Maximum number of pixels allowed for the validity check (only applies if
count_valid_pixels=True). Default is 1e9.count_mode ({'granules', 'unique_dates'}, optional) – How to count inputs per period when
return_counts=True: - ‘granules’: count all scenes (granules) intersecting the ROI after filters (dates, clouds, etc.). - ‘unique_dates’: count unique acquisition dates (YYYY-MM-dd), collapsing multiple tiles/orbits from the same day into one. Default is ‘granules’.
- Returns:
ee.ImageCollection – Collection of multi-band composite images, one per year. Each image has exactly one band per temporal period, named after it, so every year shares the same bands. A period without images is kept as a fully masked band (all zeros for
key='count').(ee.ImageCollection, list of dict), optional – If
return_counts=True, returns a tuple containing the ImageCollection and a list of dictionaries. Each dictionary has the following keys:year : int
period_idx : int
period_name : str
images_count : int
cloud_filter : bool
sat : str
index : str
key : str
percentile : int or None
count_mode : str
Notes
Processing workflow:
Clear previous results (
self.imagelist = [])For each year in range:
Count the scenes of every period (one server call per year), store them in
self.period_scene_countsas{year: [count per period]}, and skip the year if none of its periods has anyOptionally count images per period (granules or unique dates)
Process all periods using
get_period_composite(), which returns a placeholder band for the periods without imagesRename each period band to its period name
Combine into multi-band image
Return ImageCollection from processed images
Optionally return image counts if
return_counts=True
Each band is renamed to its period name before the periods are combined, so a missing period can never shift the names of the following ones. Band names use period names:
4 periods:
['winter', 'spring', 'summer', 'autumn']12 periods:
['january', 'february', ..., 'december']Custom:
['p1', 'p2', ..., 'pN']
Examples
Generate seasonal composites:
>>> collection = processor.get_year_composite() >>> print(collection.size().getInfo()) # Number of years
Count input images per period (unique dates):
>>> collection, counts = processor.get_year_composite( ... return_counts=True, ... count_valid_pixels=False, ... count_mode="unique_dates" ... ) >>> print(counts[0]) {'year': 2020, 'period_idx': 0, 'period_name': 'january', 'images_count': 6, ...}
- Raises:
ee.EEException – If Earth Engine computation fails.
RuntimeError – If no valid data found for any year.
Warning
Years without a single image in any period are skipped with a console warning. Periods without images are reported and filled, not dropped. Large time ranges may approach computation limits.
See also
get_period_compositeGenerates individual period composites
get_exportExport composites to files
get_gifCreate animated visualization
- mask_landsat_clouds(image)#
Mask clouds and shadows in Landsat Collection 2 images using QA_PIXEL band.
- Parameters:
image (ee.Image) – Landsat Collection 2 Level-2 image with QA_PIXEL band
- Returns:
Cloud-masked image
- Return type:
ee.Image
References
Landsat Collection 2 Level-2 Science Products https://www.usgs.gov/landsat-missions/landsat-collection-2-level-2-science-products
- mask_s2_clouds(image)#
Mask clouds and shadows in Sentinel-2 images using QA60 band.
- Parameters:
image (ee.Image) – Sentinel-2 SR image with QA60 band
- Returns:
Cloud-masked image
- Return type:
ee.Image
References
Sentinel-2 Cloud Masking with s2cloudless https://developers.google.com/earth-engine/tutorials/community/sentinel-2-s2cloudless
- mask_s2_scl(image)#
Mask clouds, cloud shadows and cirrus in Sentinel-2 images using the Scene Classification Layer (SCL band).
SCL provides per-pixel classification at 20m resolution, offering more accurate cloud/shadow detection than the QA60 band (which is coarser and misses thin clouds and shadows).
Masked classes: - 1: Saturated / defective pixels - 3: Cloud shadows - 8: Medium probability cloud - 9: High probability cloud - 10: Thin cirrus
- Parameters:
image (ee.Image) – Sentinel-2 SR image with SCL band (S2_SR_HARMONIZED collection).
- Returns:
Cloud/shadow-masked image with SCL band removed.
- Return type:
ee.Image
References
European Space Agency (2021). Sentinel-2 MSI Level-2A Algorithm Theoretical Basis Document. ESA-EOPG-GSCB-TN-0001.
- mask_viirs_quality(image)#
Keep only the good retrievals of a VIIRS Black Marble daily image.
Mandatory_Quality_Flaggrades every pixel of VNP46A2:0: high quality, persistent nighttime lights
1: high quality, ephemeral nighttime lights
2: poor quality, outlier or likely cloud contaminated
255: no retrieval
Grades 0 and 1 are kept. Flag 2 is where a cloud the mask missed shows up as a dark or a bright night, which is exactly the noise that ruins a map of the date of the maximum.
- Parameters:
image (ee.Image) – VNP46A2 image with its quality bands.
- Returns:
The same image with the poor and missing retrievals masked out.
- Return type:
ee.Image
References
Román, M.O., Wang, Z., Sun, Q. et al. (2018). NASA’s Black Marble nighttime lights product suite. Remote Sensing of Environment, 210, 113-143. https://doi.org/10.1016/j.rse.2018.03.017
- to_dmsp_like(image, coefficients, band='avg_rad')#
Apply a fitted conversion, turning VIIRS radiance into DMSP-like DN.
See
calibrate_nighttime_lights(). The output is clamped to the DMSP range, 0 to 63, because values outside it do not exist on that scale — though a pixel pushed to 63 is at the ceiling for the same reason the excluded pixels were, and means only “brighter than DMSP could record”.
S1ARDProcessor#
- class ndvi2gif.S1ARDProcessor(speckle_filter='REFINED_LEE', speckle_filter_kernel_size=7, terrain_correction=True, terrain_flattening_model='VOLUME', dem='COPERNICUS_30', format='LINEAR', input_format='DB')#
Bases:
objectAnalysis Ready Data (ARD) processor for Sentinel-1 SAR imagery.
Implements advanced preprocessing techniques for Sentinel-1 GRD data including radiometric terrain correction and various speckle filtering algorithms.
- Parameters:
speckle_filter ({'REFINED_LEE', 'LEE', 'GAMMA_MAP', 'LEE_SIGMA', 'BOXCAR', None}) – Speckle filter algorithm. Default is ‘REFINED_LEE’.
speckle_filter_kernel_size (int) – Filter kernel size in pixels (must be odd). Default is 7.
terrain_correction (bool) – Enable radiometric terrain correction. Default is True.
terrain_flattening_model ({'VOLUME', 'SURFACE'}) – Scattering model for terrain correction. Default is ‘VOLUME’.
dem ({'COPERNICUS_30', 'SRTM_30', 'SRTM_90'}) – Digital Elevation Model. Default is ‘COPERNICUS_30’.
format ({'LINEAR', 'DB'}) – Output format. Default is ‘LINEAR’.
- dem_ee#
Earth Engine DEM image object
- Type:
ee.Image
Examples
>>> processor = S1ARDProcessor( ... speckle_filter='REFINED_LEE', ... terrain_correction=True ... ) >>> collection = ee.ImageCollection('COPERNICUS/S1_GRD') >>> processed = collection.map(processor.process_image)
- apply_speckle_filter(image)#
Apply the selected speckle filter to reduce SAR noise.
Routes to the appropriate filter implementation based on the configured speckle_filter parameter.
- Parameters:
image (ee.Image) – Input SAR image with VV and VH bands.
- Returns:
Filtered image with reduced speckle noise.
- Return type:
ee.Image
- Raises:
ee.EEException – If underlying Earth Engine focal/statistical operations fail during filtering.
- apply_terrain_correction(image)#
Apply radiometric terrain correction to reduce topographic effects.
Implements the angular-based radiometric slope correction method from Vollrath et al. (2020). This correction compensates for variations in backscatter caused by local terrain slope and aspect relative to the sensor viewing geometry.
- Parameters:
image (ee.Image) – Sentinel-1 image with VV, VH, and angle bands.
- Returns:
Terrain-corrected image with adjusted VV and VH bands.
- Return type:
ee.Image
- Raises:
ee.EEException – If required bands or properties are missing (e.g.,
VV,VH,angle, ororbitProperties_pass) or if Earth Engine operations fail during terrain correction (projection/reprojection errors, invalid geometries).
Notes
The correction factor is clamped between 0.5 and 2.0 to prevent overcorrection in extreme terrain conditions.
References
Vollrath, A., Mullissa, A., & Reiche, J. (2020). Angular-based radiometric slope correction for Sentinel-1 on google earth engine. Remote Sensing, 12(11), 1867.
- from_db(image)#
Convert backscatter values from decibel to linear power scale.
- Parameters:
image (ee.Image) – SAR image with VV and VH bands in dB.
- Returns:
Image with VV and VH as linear power (10 ** (dB / 10)); other bands and properties are kept.
- Return type:
ee.Image
- process_image(image)#
Apply complete preprocessing pipeline to a single image.
Executes the full ARD processing chain in order: 1. Terrain correction (if enabled) 2. Speckle filtering (if configured) 3. Format conversion (if DB requested)
- Parameters:
image (ee.Image) – Raw Sentinel-1 GRD image.
- Returns:
Preprocessed ARD image ready for analysis.
- Return type:
ee.Image
- Raises:
ee.EEException – If any step of the processing chain fails in Earth Engine (terrain correction, speckle filtering, or format conversion).
Examples
>>> processor = S1ARDProcessor() >>> s1_collection = ee.ImageCollection('COPERNICUS/S1_GRD') >>> processed = s1_collection.map(processor.process_image)
- to_db(image)#
Convert backscatter values from linear to decibel scale.
- Parameters:
image (ee.Image) – SAR image with VV and VH bands in linear scale.
- Returns:
Image with bands converted to decibel scale (10*log10).
- Return type:
ee.Image
- Raises:
ee.EEException – If required bands (
VV,VH) are missing or if Earth Engine evaluation fails during the logarithmic conversion.
Notes
Decibel scale is preferred for visualization and some analyses as it compresses the dynamic range and normalizes the distribution.
TimeSeriesAnalyzer#
- class ndvi2gif.TimeSeriesAnalyzer(ndvi_seasonality_instance)#
Bases:
objectAdvanced time series analysis for Earth Engine remote sensing data.
Provides methods for extracting, analyzing, and visualizing temporal patterns in satellite data processed by NdviSeasonality.
- Parameters:
ndvi_seasonality_instance (NdviSeasonality) – Configured NdviSeasonality instance with ROI, periods, years, etc.
- processor#
Reference to the parent processor
- Type:
- roi#
Region of interest
- Type:
ee.Geometry
Examples
>>> processor = NdviSeasonality(sat='S2', index='ndvi') >>> analyzer = TimeSeriesAnalyzer(processor) >>> df = analyzer.extract_time_series() >>> fig = analyzer.plot_comprehensive_analysis()
- analyze_trend(df: DataFrame | None = None, method: str = 'mann_kendall', alpha: float = 0.05) Dict[str, Any]#
Perform comprehensive trend analysis on time series.
- Parameters:
df (pd.DataFrame or None, optional) – Time series dataframe. If None, extracts from ROI centroid.
method ({'mann_kendall', 'linear', 'sen_slope', 'all'}, optional) –
Trend test method:
’mann_kendall’: Non-parametric trend test
’linear’: Linear regression
’sen_slope’: Theil-Sen estimator
’all’: Apply all methods
Default is ‘mann_kendall’.
alpha (float, optional) – Significance level for statistical tests. Default is 0.05.
- Returns:
Trend statistics including:
mann_kendall: tau, p_value, trend direction
linear: slope, r_squared, p_value, confidence interval
sen_slope: median slope, confidence interval
interpretation: text summary of results
- Return type:
- Raises:
ValueError – If method is not one of {‘mann_kendall’, ‘linear’, ‘sen_slope’, ‘all’}.
KeyError – If required columns (
'date','value') are missing from df.RuntimeError – If trend estimation fails due to insufficient or invalid data.
Examples
>>> # Basic trend analysis >>> trends = analyzer.analyze_trend(method='mann_kendall') >>> print(trends['interpretation'])
>>> # All trend methods >>> trends = analyzer.analyze_trend(method='all')
- compare_phenology_years(point: tuple | Point | None = None, reference_year: int | None = None) Dict[str, Any]#
Compare phenological metrics across years to identify anomalies and trends.
- Parameters:
point (location for extraction)
reference_year (year to use as reference (if None, uses mean of all years))
- Returns:
Comparison results with anomalies and trends
- Return type:
- compare_smoothing_impact(point=None, method='threshold', threshold_percentile=50) Dict[str, Any]#
Compare phenological metrics calculated with and without smoothing.
Useful for validating the impact of the v1.0 changes and for documenting differences in JOSS paper.
- Parameters:
- Returns:
Comparison results with metrics from both approaches
- Return type:
Examples
>>> # Compare impact of smoothing >>> comparison = analyzer.compare_smoothing_impact() >>> print("Raw data SOS:", comparison['raw']['2020']['sos']) >>> print("Smoothed SOS:", comparison['smoothed']['2020']['sos'])
- extract_phenology_metrics(df: DataFrame | None = None, method: str = 'threshold', threshold_percentile: float = 50, smoothing: bool = True, smoothing_window: int = 7, smoothing_order: int = 3, min_season_length: int = 60, quality_warnings: bool = True) Dict[str, Any]#
Extract phenological metrics with comprehensive quality control and warnings.
- Parameters:
df (pd.DataFrame or None, optional) – Time series data. If None, extracts from ROI centroid.
method ({'threshold', 'derivative', 'logistic'}, optional) – Extraction method. Default is ‘threshold’.
threshold_percentile (float, optional) – Percentile for threshold method (0-100). Default is 50.
smoothing (bool, optional) – Apply Savitzky-Golay smoothing. Default is True.
smoothing_window (int, optional) – Window length for smoothing. Default is 7.
smoothing_order (int, optional) – Polynomial order for smoothing. Default is 3.
min_season_length (int, optional) – Minimum season length in days. Default is 60.
quality_warnings (bool, optional) – Print quality warnings for each method. Default is True.
- Returns:
Phenological metrics per year with quality indicators.
- Return type:
- extract_time_series(point: Point | Tuple[float, float] | None = None, reducer: str = 'mean', scale: int = 30, use_cache: bool = True) DataFrame#
Extract complete time series for a point or region.
Combines all temporal periods across all years into a continuous time series suitable for analysis.
- Parameters:
point (ee.Geometry.Point, tuple, or None, optional) –
Location for extraction:
None: uses ROI centroid
tuple: (longitude, latitude)
ee.Geometry.Point: direct point geometry
ee.Geometry.Polygon: for spatial averaging
reducer ({'mean', 'median', 'max', 'min', 'stdDev'}, optional) – Spatial reducer if using polygon. Default is ‘mean’.
scale (int, optional) – Scale in meters for spatial reduction. Default is 30.
use_cache (bool, optional) – Whether to use cached results. Default is True.
- Returns:
DataFrame with columns:
date: datetime index
value: index values
year: year
period: period name
doy: day of year
season: meteorological season
month: month number
- Return type:
pd.DataFrame
- Raises:
ValueError – If point is not a valid coordinate tuple or buffer/scale are invalid.
ee.EEException – If Earth Engine extraction fails (geometry errors, reduceRegion failures).
RuntimeError – If no valid data can be extracted for the specified point/period.
Examples
>>> # Extract from ROI centroid >>> df = analyzer.extract_time_series()
>>> # Extract from specific point >>> df = analyzer.extract_time_series(point=(-5.5, 37.1))
>>> # Extract with different reducer >>> df = analyzer.extract_time_series(reducer='median', scale=20)
- plot_comprehensive_analysis(point=None, figsize=(22, 14), save_path=None)#
Create comprehensive time series analysis dashboard.
Generates a multi-panel figure with time series, trends, seasonal patterns, statistics, and quality metrics.
- Parameters:
- Returns:
Generated figure object
- Return type:
matplotlib.figure.Figure
- Raises:
RuntimeError – If the input DataFrame is empty or contains insufficient data for analysis.
OSError – If saving the figure to save_path fails.
Notes
Dashboard includes:
Time series with trend line
Seasonal patterns boxplot
Annual comparison
Trend summary statistics
Autocorrelation function
Value distribution
Phenology summary
Data quality metrics
Seasonal statistics
Examples
>>> # Basic dashboard >>> fig = analyzer.plot_comprehensive_analysis()
>>> # Save to file >>> fig = analyzer.plot_comprehensive_analysis( ... save_path='analysis_dashboard.png' ... )
- plot_phenology_analysis(point=None, method='threshold', threshold_percentile=50, figsize=(24, 16), save_path=None)#
Create comprehensive phenological analysis dashboard.
Generates multi-panel visualization of phenological patterns, timing, amplitudes, and inter-annual variations.
- Parameters:
point (location or None, optional) – Extraction point. If None, uses ROI centroid.
method ({'threshold', 'derivative', 'logistic'}, optional) – Phenology extraction method. Default is ‘threshold’.
threshold_percentile (float, optional) – Threshold percentile if using threshold method. Default is 50.
figsize (tuple, optional) – Figure size. Default is (24, 16).
save_path (str or None, optional) – Path to save figure.
- Returns:
Generated figure
- Return type:
matplotlib.figure.Figure
- Raises:
ValueError – If method is not recognized or required columns are missing in df.
RuntimeError – If phenology metrics cannot be computed due to insufficient data.
OSError – If saving the figure to save_path fails.
Notes
Dashboard panels include:
Time series with phenological markers
Phenological timing trends
Amplitude and peak values
Growth/senescence rates
Season duration analysis
Annual curve comparison
Statistical summaries
Data quality assessment
SpatialTrendAnalyzer#
- class ndvi2gif.SpatialTrendAnalyzer(ndvi_seasonality_instance)#
Bases:
objectSpatial trend analysis for generating pixel-wise trend maps.
Complements TimeSeriesAnalyzer by providing spatial analysis capabilities using Earth Engine’s distributed computing.
- Parameters:
ndvi_seasonality_instance (NdviSeasonality) – Configured NdviSeasonality instance
Examples
>>> processor = NdviSeasonality(sat='S2', index='ndvi') >>> spatial = SpatialTrendAnalyzer(processor) >>> trend_map = spatial.calculate_pixel_trends(method='linear')
- calculate_pixel_trends(method: str = 'linear', min_observations: int = 5, export: bool = False, scale: int = 30) Image#
Calculate per-pixel temporal trends across the ROI.
- Parameters:
method ({'linear', 'sen', 'mann_kendall'}, optional) – Trend calculation method. Default is ‘linear’.
min_observations (int, optional) – Minimum valid observations per pixel. Default is 5.
export (bool, optional) – Export result to GeoTIFF. Default is False.
scale (int, optional) – Output resolution in meters. Default is 30.
- Returns:
Multi-band trend image with:
slope: Trend slope
intercept: Y-intercept
magnitude: Total change over period
method='mann_kendall'adds one more band:tau: Kendall’s tau, the rank correlation with time. Ranges from -1 (strictly decreasing) to +1 (strictly increasing); 0 means no monotonic trend. Unlike the slope it is scale-free, so it compares across bands and sensors
- Return type:
ee.Image
Examples
>>> # Calculate linear trends >>> trend_map = spatial.calculate_pixel_trends()
>>> # Export Sen's slope map >>> trend_map = spatial.calculate_pixel_trends( ... method='sen', ... export=True, ... scale=20 ... )
SpatialPhenologyAnalyzer#
- class ndvi2gif.SpatialPhenologyAnalyzer(ndvi_seasonality_instance)#
Bases:
objectServer-side, per-pixel phenology raster generation with Earth Engine.
While
TimeSeriesAnalyzerextracts phenological metrics for a single point (downloading the time series viagetInfo), this class computes the same family of metrics for every pixel of the ROI entirely on Earth Engine, producing phenology rasters (Start/Peak/End of Season, etc.).Three extraction methods are available, all running fully server-side:
'threshold': amplitude-based thresholding (SOS/EOS as the first/last day-of-year above an amplitude fraction of the seasonal curve).'derivative': SOS/EOS from the steepest positive/negative rate of change between consecutive composites.'harmonic': harmonic (Fourier) regression per pixel, used to reconstruct a smooth seasonal curve from which SOS/POS/EOS are extracted. This is the Earth Engine-friendly replacement for the client-side double-logistic fit (which relies onscipy.optimize.curve_fitand cannot run server-side).
Phenology is computed year by year (each year has its own seasonal cycle). Two entry points are provided:
extract_phenology_rasters()returns one image per year as anee.ImageCollection(useful for analysing how phenology shifts over time, e.g. earlier SOS year after year).phenology_summary()collapses all years into a single multi-bandee.Imageusing a reducer (median/mean), i.e. the typical phenology of the period.
Output bands (per year and in the summary):
sos,pos,eos,los,amplitude,peak_value,baseline,growth_rate,senescence_rate. SOS/POS/EOS/LOS are expressed in day-of-year (days).- Parameters:
ndvi_seasonality_instance (NdviSeasonality) – Configured NdviSeasonality instance with ROI, periods and year range.
Notes
Phenology extraction needs enough intra-annual temporal resolution. Using
periods=12(monthly) orperiods=24(bi-monthly) is strongly recommended; withperiods=4(seasonal) results are coarse and a warning is issued.Examples
>>> processor = NdviSeasonality(sat='S2', index='ndvi', periods=12, ... start_year=2018, end_year=2023) >>> pheno = SpatialPhenologyAnalyzer(processor) >>> # Option A: one phenology image per year >>> yearly = pheno.extract_phenology_rasters(method='harmonic') >>> # Option B: single multi-year median phenology map >>> summary = pheno.phenology_summary(method='harmonic', reducer='median')
- extract_phenology_rasters(method: str = 'threshold', threshold_percentile: float = 50, adaptive_threshold: bool = True, n_harmonics: int = 2, harmonic_step: int = 10, min_observations: int = 5, export: bool = False, export_target: str = 'local', drive_folder: str | None = None, crs: str = 'EPSG:4326', scale: int = 30) ImageCollection#
Compute one per-pixel phenology image per year (Option A).
- Parameters:
method ({'threshold', 'derivative', 'harmonic'}, optional) – Phenology extraction method. Default is ‘threshold’.
threshold_percentile (float, optional) – Amplitude percentile (0-100) defining the season threshold for the
'threshold'and'harmonic'methods. Default is 50.adaptive_threshold (bool, optional) – If True, uses a lower threshold for SOS and a higher one for EOS (mirrors the client-side behaviour). Default is True.
n_harmonics (int, optional) – Number of harmonics for the
'harmonic'method. Default is 2.harmonic_step (int, optional) – Day-of-year step used to reconstruct the smooth harmonic curve. Smaller values give finer SOS/EOS resolution at higher cost. Default is 10.
min_observations (int, optional) – Minimum valid composites per pixel and year. Pixels with fewer are masked. Default is 5.
export (bool, optional) – Export each yearly image to GeoTIFF. Default is False.
export_target ({'local', 'drive'}, optional) – Where to export when
export=True.'local'downloads a GeoTIFF to the working directory (band names are embedded with rasterio if available);'drive'starts a batch task to Google Drive (Earth Engine preserves band names). Default is ‘local’.drive_folder (str or None, optional) – Google Drive folder for
export_target='drive'. Default is None (Drive root).crs (str, optional) – Output CRS for export. Default is ‘EPSG:4326’.
scale (int, optional) – Output resolution in meters (used for export). Default is 30.
- Returns:
One multi-band image per year, each carrying a
'year'property.- Return type:
ee.ImageCollection
Examples
>>> yearly = pheno.extract_phenology_rasters(method='derivative') >>> first = ee.Image(yearly.first())
- phenology_summary(method: str = 'threshold', reducer: str = 'median', threshold_percentile: float = 50, adaptive_threshold: bool = True, n_harmonics: int = 2, harmonic_step: int = 10, min_observations: int = 5, export: bool = False, export_target: str = 'local', drive_folder: str | None = None, crs: str = 'EPSG:4326', scale: int = 30) Image#
Collapse all years into a single multi-band phenology image (Option B).
Builds the per-year collection with
extract_phenology_rasters()and reduces it across years with the requested reducer, yielding the typical phenology of the whole period.- Parameters:
method ({'threshold', 'derivative', 'harmonic'}, optional) – Phenology extraction method. Default is ‘threshold’.
reducer ({'median', 'mean'}, optional) – Reducer applied across years. Default is ‘median’.
threshold_percentile – See
extract_phenology_rasters().adaptive_threshold – See
extract_phenology_rasters().n_harmonics – See
extract_phenology_rasters().harmonic_step – See
extract_phenology_rasters().min_observations – See
extract_phenology_rasters().export_target – See
extract_phenology_rasters().drive_folder – See
extract_phenology_rasters().crs – See
extract_phenology_rasters().scale – See
extract_phenology_rasters().export (bool, optional) – Export the aggregated image to GeoTIFF. Default is False.
- Returns:
Multi-band image with the across-year reduced metrics, keeping the original band names (
sos,pos,eos, …).- Return type:
ee.Image
Examples
>>> summary = pheno.phenology_summary(method='harmonic', reducer='median')
LandCoverClassifier#
- class ndvi2gif.LandCoverClassifier(ndvi_seasonality_instance, resample=None, crs=None)#
Bases:
objectLand cover classification workflow based on temporal NDVI composites.
This class integrates seasonal NDVI metrics (from an
NdviSeasonalityinstance) with supervised and unsupervised classification methods in Google Earth Engine. It supports feature stack generation, training data ingestion, model fitting, and accuracy assessment.- processor#
First (or only) processor; ROI and dates are taken from it.
- Type:
- processors#
Every processor, one per sensor.
- Type:
- multi_sensor#
True when more than one sensor is combined. Band names then carry the sensor as prefix (
S2_ndvi_2023_january).- Type:
- scale#
Pixel size in meters of the feature stack, used for sampling, normalization and export.
- Type:
- feature_stack#
Image containing stacked features (NDVI indices, temporal metrics).
- Type:
ee.Image or None
- training_data#
FeatureCollection with labeled training samples.
- Type:
ee.FeatureCollection or None
- validation_data#
FeatureCollection with labeled validation samples.
- Type:
ee.FeatureCollection or None
- classifier#
Trained Earth Engine classifier.
- Type:
ee.Classifier or None
- classified_image#
Output land cover classification map.
- Type:
ee.Image or None
- roi#
Region of interest inherited from
processor.- Type:
ee.Geometry
- add_training_data(training_points: str | FeatureCollection = None, training_polygons: str | FeatureCollection = None, class_property: str = 'class', points_per_class: int = 100, train_fraction: float = 0.7, seed: int = 0) None#
Add training data for supervised classification.
- Parameters:
training_points (str or ee.FeatureCollection) – Point features with class labels (shapefile path or ee.FeatureCollection)
training_polygons (str or ee.FeatureCollection) – Polygon features to sample points from
class_property (str) – Property containing class values
points_per_class (int) – If using polygons, number of points to sample per class
train_fraction (float) – Share of the samples used for training; the rest is kept for validation. Default 0.7.
seed (int) – Seed of the random train/validation split. The split is drawn on the samples before reading the feature stack, so the same points and seed give the same split whatever the stack — which is what makes classifiers built on different stacks comparable.
- Raises:
ValueError – If no feature stack has been created or if neither points nor polygons are provided.
ee.EEException – If Earth Engine sampling fails when extracting training data.
- classify_supervised(algorithm: str = 'random_forest', train_fraction: float = 0.7, params: Dict = None) Image#
Perform supervised classification.
- Parameters:
algorithm (str) – Classification algorithm: - ‘random_forest’: Random Forest (default) - ‘svm’: Support Vector Machine - ‘cart’: Classification and Regression Trees - ‘naive_bayes’: Naive Bayes - ‘gradient_tree’: Gradient Tree Boost
train_fraction (float) – Has no effect, and never had: the split is made when the samples are loaded, with
add_training_data(train_fraction=...). Kept so existing calls do not break; a value other than 0.7 prints a warning.params (dict) – Algorithm-specific parameters
- Returns:
Classified image
- Return type:
ee.Image
- Raises:
ValueError – If training data has not been added or if the classifier algorithm is not supported.
ee.EEException – If supervised classification fails in Earth Engine.
- classify_unsupervised(algorithm: str = 'kmeans', n_clusters: int = 10, max_iterations: int = 20, n_pixels: int = 5000, seed: int = 0, params: Dict = None) Image#
Perform unsupervised classification (clustering).
The clusterer is trained on a random sample of the feature stack and then applied to every pixel of it. Clusters are numbered arbitrarily: they carry no class meaning until they are interpreted, for instance by crossing them with reference labels or with the mean of each feature per cluster.
- Parameters:
algorithm (str) –
Clustering algorithm:
'kmeans'(default): Weka’s SimpleKMeans (ee.Clusterer.wekaKMeans). Lloyd’s algorithm on Euclidean distance: the samples are split into exactlyn_clustersgroups by repeating “assign every sample to the nearest centroid, move every centroid to the mean of its samples” until nothing moves ormax_iterationsis reached. It minimizes the within-cluster variance, so it favours compact clusters of similar spread.'cascade_kmeans': Cascade SimpleKMeans (ee.Clusterer.wekaCascadeKMeans). Runs k-means for a growing number of clusters and keeps the one that maximizes the Calinski-Harabasz criterion, so it chooses the number of clusters itself between 2 andn_clusters; the result usually has fewer. Use it when the number of classes in the data is unknown.'lvq': Learning Vector Quantization (ee.Clusterer.wekaLVQ). A competitive neural network in Kohonen’s sense:n_clustersprototype vectors are pulled towards the samples that fall closest to them, by a step that shrinks over the training epochs. It does not minimize the within-cluster variance and depends on the order of the samples, so it tends to give clusters of more even size than k-means — useful when k-means collapses a large, homogeneous cover type into one cluster and splits the rest.'lda': deprecated alias of'lvq', kept because that is the clusterer it always ran. The name was wrong: no version of this method performed Latent Dirichlet Allocation.
n_clusters (int) – Number of clusters. For
'cascade_kmeans'it is the maximum, since that algorithm picks its own number.max_iterations (int) – Maximum iterations. Only
'kmeans'takes it; the other two have no equivalent parameter.n_pixels (int) – Number of random pixels sampled from the feature stack to train the clusterer. Default 5000.
seed (int) – Seed of that random sample, so a run can be repeated. Default 0.
params (dict, optional) – Extra keyword arguments for the underlying
ee.Clusterer, such as{'seed': 7}for k-means or{'learningRate': 0.05, 'epochs': 2000}for LVQ. They override the arguments built from the parameters above.
- Returns:
Single-band image named
'cluster', with values from 0 to the number of clusters minus one. Also stored inself.classified_image, which a later call overwrites.- Return type:
ee.Image
- Raises:
ValueError – If no feature stack has been created, or if algorithm is not one of ‘kmeans’, ‘cascade_kmeans’ or ‘lvq’.
ee.EEException – If unsupervised classification fails in Earth Engine.
Examples
Twelve clusters over a multi-temporal stack:
>>> clusters = clf.classify_unsupervised(algorithm='kmeans', ... n_clusters=12)
Let the cascade choose how many classes the data supports:
>>> clusters = clf.classify_unsupervised( ... algorithm='cascade_kmeans', n_clusters=15)
See also
classify_supervisedClassification with labeled training data.
- create_feature_stack(indices: List[str] | Dict[str, List[str]] = None, include_statistics: bool = True, normalize: bool = True) Image#
Create multi-temporal feature stack for classification.
- Parameters:
indices (list of str or dict, optional) – Indices to stack. With a single sensor, a list such as
['ndvi', 'mndwi']. With several sensors, a dict mapping each sensor to its indices, such as{'S2': ['ndvi', 'mndwi'], 'S1': ['vh', 'rvi']}. If None, uses the current index of each processor.include_statistics (bool) – Add temporal statistics (mean, std, max, min)
normalize (bool) – Normalize to [0,1] range
- Returns:
Multi-band feature stack. Bands are named
<index>_<year>_<period>with a single sensor and<sensor>_<index>_<year>_<period>with several.- Return type:
ee.Image
- Raises:
ValueError – If indices contains unsupported names, names sensors that were not passed to the classifier, or is a list with several sensors.
ee.EEException – If Earth Engine image processing fails when computing the stack.
- export_model(path: str, include_samples: bool = True) Dict[str, str]#
Write everything needed to reproduce a supervised classification.
Two files, so the experiment can be repeated or re-fitted outside Earth Engine (scikit-learn, R…):
<path>.json: the configuration of every processor (sensor, periods and their dates, years, reducer, cloud and SAR options, ROI as GeoJSON), the feature stack (indices per sensor, statistics, normalization, pixel size, CRS, resampling), the ordered list of features, the training setup (class property, train fraction, seed), the algorithm with the parameters actually used, the model as described by Earth Engine (explain(): for random forests every tree as text, the feature importance and the out-of-bag error; for CART the tree also in Graphvizdotformat) and the accuracy metrics.<path>_samples.csv: one row per sample with its coordinates, class, every feature value and asplitcolumn (train/validation).
The trees are documentation: no other library loads them. To replicate the model elsewhere, train on the CSV with the same algorithm and parameters; the result is equivalent, not identical tree by tree, since each implementation draws its own randomness.
- Parameters:
- Returns:
Paths written, under the keys
'model'and'samples'.- Return type:
- Raises:
ValueError – If no supervised classification has been run.
Examples
>>> clf.classify_supervised(algorithm='random_forest') >>> clf.export_model('results/tawau_rf') {'model': 'results/tawau_rf.json', 'samples': 'results/tawau_rf_samples.csv'}
Refit the same model in scikit-learn:
>>> import json, pandas as pd >>> from sklearn.ensemble import RandomForestClassifier >>> meta = json.load(open('results/tawau_rf.json')) >>> df = pd.read_csv('results/tawau_rf_samples.csv') >>> train = df[df.split == 'train'] >>> rf = RandomForestClassifier( ... n_estimators=meta['classifier']['parameters']['numberOfTrees']) >>> rf.fit(train[meta['features']], train[meta['training']['class_property']])
- export_results(description: str, scale: float | None = None, region: Geometry | None = None)#
Export the classified image to Google Drive or Earth Engine Asset.
- Parameters:
description (str) – Name of the export task.
scale (float, optional) – Spatial resolution in meters. Defaults to the pixel size of the feature stack (
scale), so the map is exported at the resolution it was classified at. Before 1.6.0 it was always 30.region (ee.Geometry, optional) – Geometry defining the export area. If None, uses the full image extent.
- Returns:
The Earth Engine export task object.
- Return type:
ee.batch.Task
- Raises:
ValueError – If no classified image is available.
ee.EEException – If the export task could not be created.
- get_accuracy_report() DataFrame#
Return accuracy metrics as a pandas DataFrame.
- Returns:
Table with overall accuracy, kappa, producer’s and user’s accuracy for each class.
- Return type:
- Raises:
ValueError – If no accuracy metrics are available.
- get_feature_importance() Dict[str, float]#
Get feature importance scores of the trained classifier.
Available for the tree-based algorithms of
classify_supervised()('random_forest','cart'and'gradient_tree'). Scores are relative within a model: compare features, not models.- Returns:
Mapping of feature (band) names to importance scores, sorted from most to least important.
- Return type:
- Raises:
ValueError – If no tree-based classifier has been trained.
- plot_confusion_matrix(labels: List[str])#
Plot the confusion matrix of the classification results.
- Parameters:
labels (list of str) – List of class names in the same order as the matrix.
- Returns:
Axis object containing the confusion matrix plot.
- Return type:
matplotlib.axes.Axes
- Raises:
ValueError – If no confusion matrix is available (classification or accuracy not run).
HydroperiodAnalyzer#
- class ndvi2gif.HydroperiodAnalyzer(ndvi_seasonality, hydrological_year_start=(9, 1))#
Bases:
objectGEE-native hydroperiod computation from satellite water indices.
Computes hydroperiod entirely in Google Earth Engine using the midpoint temporal weighting method. Each scene in the satellite collection receives a proportional number of days based on its position within the hydrological cycle, then weighted flood and valid days are accumulated per pixel.
- Parameters:
ndvi_seasonality (NdviSeasonality) – Configured
NdviSeasonalityinstance. The ROI, satellite, date range, cloud filtering, and band standardisation are reused directly — no duplicate configuration needed.hydrological_year_start (tuple of (int, int), optional) –
(month, day)marking the start of the hydrological cycle. Default(9, 1)= September 1st.
Examples
import ee from ndvi2gif import NdviSeasonality, HydroperiodAnalyzer ee.Initialize() ns = NdviSeasonality(roi, sat='S2', start_year=2023, end_year=2024) ha = HydroperiodAnalyzer(ns) # Full GEE-native computation result = ha.compute_hydroperiod(index='mndwi', threshold=0.1) # result is an ee.Image with bands: # hydroperiod, valid_days, normalized, # first_flood_doy, last_flood_doy # Export to Drive ha.export_to_drive(folder='my_wetland') # Same, plus the per-date water masks as a separate uint8 file # (0 = dry, 1 = water, 2 = cloud-masked, 255 = no acquisition) ha.export_to_drive(folder='my_wetland', include_masks=True) # Per-pixel IRT (temporal representativity) irt = ha.compute_irt_image()
Notes
Supported water indices (optical sensors):
'ndwi','mndwi','awei','aweinsh','wi2015'The per-pixel IRT is computed as Simpson’s diversity index across monthly periods, which is fully computable per-pixel in GEE. The global IRT uses the Gini-based formula identical to the standalone phydroperiod library (computed client-side from scene dates).
- HISTORICAL_START = {'Landsat': 1984, 'MODIS': 2000, 'S1': 2014, 'S2': 2017}#
First available hydrological year for each sensor’s full archive.
- WATER_INDICES = frozenset({'awei', 'aweinsh', 'mndwi', 'ndwi', 'wi2015'})#
Water indices supported for hydroperiod computation.
- compute_all_cycles(index='mndwi', threshold=0.0, normalize=True, compute_first_last=True)#
Compute hydroperiod for every hydrological cycle in the date range.
Iterates from
ns.start_yeartons.end_year(inclusive), computing one hydroperiod image per cycle. Each cycle spans fromhydrological_year_startin year Y to the same date in year Y+1.- Parameters:
index (str) – Water index for mask generation. Default
'mndwi'.threshold (float) – Water classification threshold. Default
0.0.normalize (bool) – Include
'normalized'band in each cycle image. DefaultTrue.compute_first_last (bool) – Include
'first_flood_doy'/'last_flood_doy'bands. DefaultTrue.
- Returns:
Mapping
{hyd_year: ee.Image}where hyd_year is the starting calendar year of each cycle (e.g.2020for 2020-2021). Each image has the same bands ascompute_hydroperiod()plus a'hyd_year'property for easy identification.- Return type:
Examples
ns = NdviSeasonality(roi, sat='S2', start_year=2019, end_year=2023) ha = HydroperiodAnalyzer(ns) cycles = ha.compute_all_cycles(index='mndwi', threshold=0.1) # cycles = {2019: ee.Image, 2020: ee.Image, ..., 2023: ee.Image} # Export all cycles to Drive for yr, img in cycles.items(): ha.export_to_drive(image=img, description=f'hydroperiod_{yr}_{yr+1}')
- compute_anomalies(cycles=None, index='mndwi', threshold=0.0, reference='period')#
Compute mean hydroperiod and per-cycle anomalies.
Calculates the mean normalised hydroperiod across a reference period and the anomaly of each cycle relative to that mean:
anomaly = cycle_normalized - mean_normalizedPositive values indicate a wetter-than-average year; negative values indicate a drier-than-average year.
- Parameters:
cycles (dict, optional) – Output of
compute_all_cycles():{hyd_year: ee.Image}. IfNone, runscompute_all_cycles()automatically.index (str) – Water index, used only when
cyclesisNone.threshold (float) – Classification threshold, used only when
cyclesisNone.reference (str) –
Reference period for computing the mean:
'period'(default): mean of the cycles in the current analysis range (ns.start_year→ns.end_year).'historical': mean of the full satellite archive, from the sensor’s first available year to the last complete cycle. Gives a climatological baseline independent of the chosen analysis window. Note: GEE builds the full graph lazily so this call is fast, but rendering/export will be slower.
- Returns:
{'mean': ee.Image, 'anomalies': {hyd_year: ee.Image}}'mean': mean normalised hydroperiod (band'mean_hydroperiod', int16). Properties:'reference','ref_start_year','ref_end_year','ref_n_cycles'.'anomalies': per-cycle anomaly images (band'anomaly', int16). Same metadata properties set on each image.
- Return type:
Examples
# Mean of the analysis period result = ha.compute_anomalies(cycles, reference='period') # Climatological baseline (full satellite archive) result = ha.compute_anomalies(cycles, reference='historical') Map.addLayer(result['mean'], vis, 'Mean hydroperiod') for yr, anom in result['anomalies'].items(): Map.addLayer(anom, anom_vis, f'Anomaly {yr}/{yr+1}')
- compute_hydroperiod(index='mndwi', threshold=0.0, hyd_year=None, normalize=True, compute_first_last=True, min_flood_days=3, permanent_threshold=0.95)#
Compute hydroperiod entirely in Google Earth Engine.
Implements the midpoint weighting algorithm:
Generate binary water masks (via
get_water_masks()).For each scene, compute weighted flood and valid-day contributions:
flood_contrib = water * weight(weight where flooded, 0 where dry)valid_contrib = valid_mask * weight(weight where any valid obs)
Sum contributions per pixel across all scenes →
hydroperiodandvalid_days.Optionally normalise:
normalized = (hydroperiod / valid_days) * 365.Optionally compute first / last flood day (day of hydrological year).
- Parameters:
index (str) – Water index for mask generation. Default
'mndwi'.threshold (float) – Water classification threshold. Default
0.0.hyd_year (int, optional) – Starting year of the hydrological cycle. Default
ns.start_year.normalize (bool) – Add a
'normalized'band corrected for uneven temporal coverage. DefaultTrue.compute_first_last (bool) – Add
'first_flood_doy'and'last_flood_doy'bands (days since hydrological year start, 0-indexed). DefaultTrue.min_flood_days (int) – Minimum accumulated flood days required for a pixel to receive a valid
first_flood_doy/last_flood_doyvalue. Pixels below this threshold are masked (likely noise or isolated cloud artefacts). Default3.permanent_threshold (float) – Fraction of valid days that must be flooded for a pixel to be considered permanently inundated (e.g. open sea, permanent lagoons). These pixels get
first_flood_doy = 0andlast_flood_doy = 365because a meaningful onset/recession date cannot be determined. Range [0, 1]. Default0.95.
- Returns:
Multi-band image clipped to the ROI with bands:
hydroperiod: accumulated weighted flood days (float32)valid_days: accumulated weighted valid days (float32)normalized: flood days normalised to 365-day year (int16, optional)first_flood_doy: first flood day of cycle (int16, optional)last_flood_doy: last flood day of cycle (int16, optional)
Image properties:
'hyd_year_start','hyd_year_end','index','threshold'.- Return type:
ee.Image
- compute_irt_global(hyd_year=None)#
Compute the global Temporal Representativity Index (IRT).
Measures how uniformly the available scenes are distributed across the hydrological year. A value of 1 means perfect temporal coverage; 0 means all scenes cluster in a single period.
This uses the Gini-based formula identical to phydroperiod’s
calculate_temporal_representativity(), computed client-side from the scene date metadata.
- compute_irt_image(hyd_year=None, n_periods=12)#
Compute per-pixel Temporal Representativity Index as an
ee.Image.For each pixel, estimates how uniformly its valid (non-cloud) observations are distributed across the hydrological year. This is the GEE-native counterpart of phydroperiod’s
calculate_pixel_irt().Uses Simpson’s diversity index as a per-pixel-computable proxy:
\[\text{IRT}_{pixel} = \frac{N^2}{n_{periods} \cdot \sum n_i^2}\]where \(N\) is the total number of valid observations for that pixel and \(n_i\) is the count in period i. This ranges from \(1/n_{periods}\) (all observations in one period) to 1 (perfectly uniform).
- Parameters:
- Returns:
Single-band IRT image (band
'irt'), values 0–1, clipped to ROI. Masked where no valid observations exist.- Return type:
ee.Image
Notes
Call
get_water_masks()first (or let this method call it automatically via thehyd_yearargument).
- export_to_asset(asset_id, image=None, description=None, scale=10, crs='EPSG:4326', include_masks=False, masks_asset_id=None, **kwargs)#
Export hydroperiod results to an Earth Engine Asset.
- Parameters:
asset_id (str) – Full EE asset path (e.g.
'projects/my-project/assets/hydroperiod_2023_2024').image (ee.Image, optional) – Image to export. If
None, uses the lastcompute_hydroperiod()result.description (str, optional) – Task name. Auto-generated if not provided.
scale (int) – Output pixel size in metres. Default 10.
crs (str) – Output CRS. Default
'EPSG:4326'.include_masks (bool) – Also export the per-date water masks as a separate
uint8asset (0 = dry, 1 = water, 2 = cloud-masked, 255 = no acquisition). The index, threshold and cycle are read from the exported image itself, so the masks always match what is being exported. DefaultFalse.masks_asset_id (str, optional) – Asset path for the masks when
include_masks=True. Defaults toasset_idwith a'_water_masks'suffix.**kwargs – Additional keyword arguments forwarded to
ee.batch.Export.image.toAsset.
- Returns:
Started export task. When
include_masks=True, a(hydroperiod_task, masks_task)tuple is returned instead.- Return type:
ee.batch.Task or tuple of ee.batch.Task
- export_to_drive(image=None, folder='hydroperiod', description=None, scale=10, crs='EPSG:4326', include_masks=False, **kwargs)#
Export hydroperiod results to Google Drive.
- Parameters:
image (ee.Image, optional) – Image to export. If
None, uses the lastcompute_hydroperiod()result.folder (str) – Google Drive destination folder. Default
'hydroperiod'.description (str, optional) – Task name in the Earth Engine Tasks panel. Auto-generated from hydrological year if not provided.
scale (int) – Output pixel size in metres. Default 10 (Sentinel-2).
crs (str) – Output CRS. Default
'EPSG:4326'.include_masks (bool) – Also export the per-date water masks as a separate
uint8file (0 = dry, 1 = water, 2 = cloud-masked, 255 = no acquisition). The index, threshold and cycle are read from the exported image itself, so the masks always match what is being exported. They cannot share the hydroperiod file: a GeoTIFF has a single data type, so bundling them would promote the masks toint16. DefaultFalse.**kwargs – Additional keyword arguments forwarded to
ee.batch.Export.image.toDrive.
- Returns:
Started export task. When
include_masks=True, a(hydroperiod_task, masks_task)tuple is returned instead.- Return type:
ee.batch.Task or tuple of ee.batch.Task
- export_water_masks_to_asset(asset_id, index='mndwi', threshold=0.0, hyd_year=None, masked_value=2, nodata=255, stack=None, description=None, scale=10, crs='EPSG:4326', **kwargs)#
Export the per-date water masks to an Earth Engine Asset.
Asset counterpart of
export_water_masks_to_drive(). Writes the image built byget_water_masks_stack()as auint8asset with one band per acquisition date.- Parameters:
asset_id (str) – Full EE asset path (e.g.
'projects/my-project/assets/water_masks_2023_2024').index (str) – Water index used to build the masks. Default
'mndwi'.threshold (float) – Water classification threshold. Default
0.0.hyd_year (int, optional) – Starting calendar year of the hydrological cycle. Defaults to
ns.start_year.masked_value (int) – Value for pixels observed but masked as cloud/shadow. Default
2.nodata (int) – Value for pixels no scene covered, and for everything outside the ROI. Default
255.stack (ee.Image, optional) – Pre-built mask stack to export. If given,
index,threshold,hyd_year,masked_valueandnodataare ignored.description (str, optional) – Task name. Auto-generated from the hydrological year if not provided.
scale (int) – Output pixel size in metres. Default 10 (Sentinel-2).
crs (str) – Output CRS. Default
'EPSG:4326'.**kwargs – Additional keyword arguments forwarded to
ee.batch.Export.image.toAsset.
- Returns:
Started export task.
- Return type:
ee.batch.Task
Notes
Unlike a GeoTIFF, an Earth Engine asset keeps one data type per band, so this could technically live in the same asset as the hydroperiod bands. It is kept separate anyway, to mirror the Drive export and to keep the date stack independent of the hydroperiod result.
- export_water_masks_to_drive(index='mndwi', threshold=0.0, hyd_year=None, masked_value=2, nodata=255, stack=None, folder='hydroperiod', description=None, scale=10, crs='EPSG:4326', **kwargs)#
Export the per-date water masks to Google Drive as an 8-bit stack.
Sends the image built by
get_water_masks_stack()to Drive as a singleuint8GeoTIFF with one band per acquisition date. This is a separate file from the hydroperiod export on purpose: a GeoTIFF has one data type for the whole file, so keeping the masks apart is what allows them to stay 8-bit instead of being promoted to theint16of the hydroperiod bands.- Parameters:
index (str) – Water index used to build the masks. Default
'mndwi'.threshold (float) – Water classification threshold. Default
0.0.hyd_year (int, optional) – Starting calendar year of the hydrological cycle. Defaults to
ns.start_year.masked_value (int) – Value for pixels observed but masked as cloud/shadow. Default
2.nodata (int) – Value for pixels no scene covered, and for everything outside the ROI. Default
255.stack (ee.Image, optional) – Pre-built mask stack to export. If given,
index,threshold,hyd_year,masked_valueandnodataare ignored.folder (str) – Google Drive destination folder. Default
'hydroperiod'.description (str, optional) – Task name in the Earth Engine Tasks panel. Auto-generated from the hydrological year if not provided.
scale (int) – Output pixel size in metres. Default 10 (Sentinel-2).
crs (str) – Output CRS. Default
'EPSG:4326'.**kwargs – Additional keyword arguments forwarded to
ee.batch.Export.image.toDrive.
- Returns:
Started export task.
- Return type:
ee.batch.Task
Notes
The nodata value is not written into the GeoTIFF header — Earth Engine does not tag it. Set it yourself when reading the file (
rasterio.open(...).read(masked=True)after declaring it, or Properties → No Data in QGIS).Examples
ha.export_water_masks_to_drive( index='mndwi', threshold=0.1, folder='my_wetland', scale=10, crs='EPSG:25829', )
- get_water_masks(index='mndwi', threshold=0.0, hyd_year=None, add_footprint=False)#
Generate weighted binary water masks from the satellite collection.
For each scene in the hydrological year:
Compute the selected water index.
Classify pixels:
index > threshold→ water (1), else → dry (0).Preserve the cloud/nodata mask already applied by
NdviSeasonality(SCL-based for S2 whenscl_mask=True, QA60 otherwise).Mosaic same-day scenes (
max— water wins over dry).Attach temporal weight properties via the midpoint method.
- Parameters:
index (str) – Water index to compute. One of:
'ndwi','mndwi','awei','aweinsh','wi2015'.threshold (float) – Classification threshold. Default
0.0works well for most water indices (positive = water). Increase for stricter mapping.hyd_year (int, optional) – Starting calendar year of the hydrological cycle (e.g.
2023for the Sep 2023 – Aug 2024 cycle). Defaults tons.start_year.add_footprint (bool) – Add a second band
'footprint'(1 inside the acquisition footprint of that date, masked outside), which tells apart “the satellite looked here but the pixel was masked as cloud” from “no scene covered this pixel that day”. Used byget_water_masks_stack(). DefaultFalse.
- Returns:
Binary water masks (band
'water': 1 = water, 0 = dry, masked = nodata/cloud) with properties:weight(days),start_doy,end_doy. A'footprint'band is added whenadd_footprint=True.- Return type:
ee.ImageCollection
Notes
Pixel-level cloud/shadow masking is controlled by the
scl_maskparameter ofNdviSeasonality(defaultTruefor S2).
- get_water_masks_stack(index='mndwi', threshold=0.0, hyd_year=None, masked_value=2, nodata=255)#
Stack the per-date water masks into a single 8-bit image.
Turns the collection returned by
get_water_masks()into one multi-bandee.Image, with one band per acquisition date namedwater_YYYY_MM_DD. Values are stored asuint8, which is four times smaller than theint16hydroperiod bands and is the whole point of exporting the masks separately: a GeoTIFF has a single data type for the entire file, so stacking the masks together with the hydroperiod bands would promote them toint16and waste the saving.Two different kinds of “no value” are distinguished, because they mean different things when interpreting a time series:
masked_value— the sensor did acquire the pixel that day, but it was discarded as cloud, shadow or another invalid class.nodata— no scene covered the pixel at all: outside the acquisition footprint (the slanted edges of Landsat scenes, the gaps between Sentinel-2 orbits) or outside the ROI.
- Parameters:
index (str) – Water index used to build the masks. Default
'mndwi'.threshold (float) – Water classification threshold. Default
0.0.hyd_year (int, optional) – Starting calendar year of the hydrological cycle. Defaults to
ns.start_year.masked_value (int) – Value for pixels observed but masked as cloud/shadow. Default
2.nodata (int) – Value for pixels no scene covered, and for everything outside the ROI. Default
255. Bothmasked_valueandnodatamust be integers in[0, 255], different from 0, from 1 and from each other.
- Returns:
uint8image clipped to the ROI, one band per date:0: dry1: watermasked_value: observed but masked as cloud/shadow (2)nodata: no acquisition, or outside the ROI (255)
Image properties:
'hyd_year_start','hyd_year_end','index','threshold','masked_value','nodata'.- Return type:
ee.Image
Examples
stack = ha.get_water_masks_stack(index='mndwi', threshold=0.1) print(stack.bandNames().getInfo()[:3]) # ['water_2022_09_04', 'water_2022_09_09', 'water_2022_09_14']
See also
export_water_masks_to_driveSend this stack to Google Drive.
export_water_masks_to_assetSend this stack to an Earth Engine asset.
Utility functions#
- ndvi2gif.scale_OLI(image)#
Scale Landsat 8-9 OLI/TIRS sensor data to surface reflectance.
Applies Collection 2 Level-2 scaling factors to convert digital numbers (DN) to surface reflectance values in the range [0, 1]. The scaling formula (DN * 0.0000275 - 0.2) is specific to Landsat Collection 2 products.
- Parameters:
image (ee.Image) – Raw Landsat 8 or 9 image from Collection 2 Level-2 with SR bands. Required bands: SR_B2, SR_B3, SR_B4, SR_B5, SR_B6, SR_B7
- Returns:
Image with scaled and renamed optical bands:
Blue: SR_B2 scaled (0.45-0.51 μm)Green: SR_B3 scaled (0.53-0.59 μm)Red: SR_B4 scaled (0.64-0.67 μm)Nir: SR_B5 scaled (0.85-0.88 μm)Swir1: SR_B6 scaled (1.57-1.65 μm)Swir2: SR_B7 scaled (2.11-2.29 μm)
- Return type:
ee.Image
Examples
Apply to a single Landsat 8 image:
l8_image = ee.Image('LANDSAT/LC08/C02/T1_L2/LC08_044034_20140318') scaled_image = scale_OLI(l8_image) print(scaled_image.bandNames().getInfo()) # Output: ['Blue', 'Green', 'Red', 'Nir', 'Swir1', 'Swir2', ...]
Apply to an image collection:
l8_collection = ee.ImageCollection('LANDSAT/LC08/C02/T1_L2') scaled_collection = l8_collection.map(scale_OLI)
- Raises:
Notes
The scaling coefficients are defined by USGS for Collection 2:
Scale factor: 0.0000275
Offset: -0.2
Valid range after scaling: typically -0.2 to 1.5
Negative values may occur in water or shadow areas
See also
scale_ETMScaling function for Landsat 4-5-7
References
USGS (2021). Landsat Collection 2 Level-2 Science Products. https://www.usgs.gov/landsat-missions/landsat-collection-2-level-2-science-products
- ndvi2gif.scale_ETM(image)#
Scale Landsat 4-5-7 ETM+/TM sensor data to surface reflectance.
Applies Collection 2 Level-2 scaling factors for Enhanced Thematic Mapper Plus (ETM+) on Landsat 7 and Thematic Mapper (TM) on Landsat 4-5. Uses the same scaling formula as OLI but with different band numbering scheme.
- Parameters:
image (ee.Image) – Raw Landsat 4, 5, or 7 image from Collection 2 Level-2. Required bands: SR_B1, SR_B2, SR_B3, SR_B4, SR_B5, SR_B7 Note: SR_B6 (thermal) is excluded as it requires different scaling
- Returns:
Image with scaled and renamed optical bands:
Blue: SR_B1 scaled (0.45-0.52 μm)Green: SR_B2 scaled (0.52-0.60 μm)Red: SR_B3 scaled (0.63-0.69 μm)Nir: SR_B4 scaled (0.77-0.90 μm)Swir1: SR_B5 scaled (1.55-1.75 μm)Swir2: SR_B7 scaled (2.09-2.35 μm)
- Return type:
ee.Image
Examples
Apply to a Landsat 5 image:
l5_image = ee.Image('LANDSAT/LT05/C02/T1_L2/LT05_044034_20110716') scaled_image = scale_ETM(l5_image)
Apply to mixed Landsat collection:
landsat_457 = ee.ImageCollection('LANDSAT/LE07/C02/T1_L2') scaled_collection = landsat_457.map(scale_ETM)
- Raises:
Notes
Band numbering differs between ETM/TM and OLI sensors:
ETM/TM Band 1 (Blue) → OLI Band 2
ETM/TM Band 2 (Green) → OLI Band 3
ETM/TM Band 3 (Red) → OLI Band 4
No Band 6 processing (thermal requires different scaling)
Warning
Landsat 7 ETM+ has scan line corrector failure (SLC-off) after May 2003, resulting in data gaps. Consider using gap-filling techniques or focusing on Landsat 4-5 for historical analysis.
See also
scale_OLIScaling function for Landsat 8-9
References
USGS (2021). Landsat Collection 2 Level-2 Science Products. https://www.usgs.gov/landsat-missions/landsat-collection-2-level-2-science-products
See Also#
Indices Reference — complete list of spectral, SAR and climate variables
Datasets Reference — details on the supported satellite/climate platforms
Tutorials — step-by-step, worked examples
GitHub Repository — source code