API Reference

Contents

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

NdviSeasonality

ndvi2gif.ndvi2gif

Temporal compositing, indices, ROI handling, export and GIFs

S1ARDProcessor

ndvi2gif.s1_ard

Sentinel-1 Analysis Ready Data preprocessing

TimeSeriesAnalyzer

ndvi2gif.timeseries

Point/region time series, trends and phenology

SpatialTrendAnalyzer

ndvi2gif.timeseries

Per-pixel trend rasters (server-side)

SpatialPhenologyAnalyzer

ndvi2gif.timeseries

Per-pixel phenology rasters (server-side)

LandCoverClassifier

ndvi2gif.clasification

Supervised/unsupervised land cover classification

HydroperiodAnalyzer

ndvi2gif.hydroperiod

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: object

Generate 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 geometry

    • strPath 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 filter

    • None : 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

periods#

Number of temporal periods per year

Type:

int

start_year#

First year of analysis

Type:

int

end_year#

Last year of analysis (inclusive)

Type:

int

sat#

Selected satellite sensor

Type:

str

index#

Selected spectral/radar index

Type:

str

key#

Statistical reducer method

Type:

str

percentile#

Percentile value for percentile reducer

Type:

int

period_dates#

Date ranges for each period [[start, end], …]

Type:

list of list

period_names#

Names for each temporal period

Type:

list of str

ndvi_col#

Configured satellite image collection

Type:

ee.ImageCollection

imagelist#

Processed composite images

Type:

list of ee.Image

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_indices

Query available indices for satellites

get_year_composite

Generate temporal composite images

get_gif

Create animated visualization

get_export

Export 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 >= 20 and >= 5 nW/cm2/sr are 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, the ceiling and the model as a string), r2, n (pixels that entered the fit), years used, and, with compare_products, product_difference: the median relative difference between the two VIIRS products over this ROI.

Return type:

dict

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 r2 describes 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_difference measures 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, image is clipped to region before 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=True and/or file_dimensions to 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:

dict

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_indices

Get 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:

list of str

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_indices

Get 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_vis and 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 on VV_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_export

Export entire time series automatically

get_year_composite

Generate temporal composites for export

export_with_fishnet

Export 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 using geemap.download_ee_video(). Optionally, an annotated version is created with year labels and a progress bar using geemap.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'). If None, 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=768 pixels and framesPerSecond=10 for 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_composite

Generates yearly composites used in the animation.

get_export

Exports static multi-band images instead of an animation.

geemap.download_ee_video

Handles Earth Engine video export.

geemap.add_text_to_gif

Adds 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.periods and correspond to period_names in 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 a year property, 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 ties with 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_names if they differ, so the output still means “period number”. Ignored when per_year=True.

Returns:

Band peak_period, an integer from 1 to self.periods, plus peak_value and ties if requested. An ee.Image when per_year=False, an ee.ImageCollection of 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 qualityMosaic over 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=True reports 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 frequencyHistogram of the periods report fractional counts for values no pixel holds: count the periods with eq() at the native scale, or reproject() 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() with per_year=True gives 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 p becomes an angle theta = (p - 1) * 2*pi / n; the unit vectors are averaged into C = mean(cos theta) and S = mean(sin theta). The circular mean is atan2(S, C), read back as a period number, and the resultant length R = sqrt(C**2 + S**2) is the concentration: how much the years agree.

R is 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 when peaks is 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 its peak_period band is read.

Returns:

Band circular_mean, the mean peak period, fractional and running from 1 to self.periods (a value of 12.6 with periods=12 means “late December, a fifth of the way into January”); band concentration, R between 0 and 1; and band n_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:
  • year (int) – Target year for composite generation. Must be within satellite data availability range.

  • period_idx (int) – Zero-based index of temporal period within the year. Must be less than self.periods.

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 for key='count'.

Return type:

ee.Image

Notes

Processing workflow:

  1. Extract date range from self.period_dates[period_idx]

  2. Filter satellite collection to date range

  3. Apply index calculation (self.d[self.index])

  4. Apply statistical reducer (max/median/mean/percentile)

  5. 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_composite

Calls this method for all periods

_generate_periods

Defines 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 of get_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_indices

Lists 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) / VV on 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_Mask is a bitmask, not a number to average: bits hold day or night, cloud confidence, cirrus, snow or ice. Exposed so it can be decoded with bitwiseAnd when 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 when cloud_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, and quality_flag is 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 above occurrence percent.

    • 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. With return_area=True, a (collection, areas) tuple where areas is {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_area exists and why water_mask_area is 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*SWIR2 on 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 if count_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:

  1. Clear previous results (self.imagelist = [])

  2. For each year in range:

    1. Count the scenes of every period (one server call per year), store them in self.period_scene_counts as {year: [count per period]}, and skip the year if none of its periods has any

    2. Optionally count images per period (granules or unique dates)

    3. Process all periods using get_period_composite(), which returns a placeholder band for the periods without images

    4. Rename each period band to its period name

    5. Combine into multi-band image

  3. Return ImageCollection from processed images

  4. 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_composite

Generates individual period composites

get_export

Export composites to files

get_gif

Create 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_Flag grades 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”.

Parameters:
  • image (ee.Image) – A VIIRS image or composite.

  • coefficients (dict) – The coefficients entry of the fit.

  • band (str, optional) – Radiance band to convert. Default 'avg_rad'.

Returns:

One band, dmsp_like.

Return type:

ee.Image

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: object

Analysis 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, or orbitProperties_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: object

Advanced 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:

NdviSeasonality

time_series_cache#

Cache for extracted time series data

Type:

dict

roi#

Region of interest

Type:

ee.Geometry

periods#

Number of temporal periods per year

Type:

int

start_year#

Starting year of analysis

Type:

int

end_year#

Ending year (inclusive)

Type:

int

sat#

Satellite sensor

Type:

str

index#

Vegetation/environmental index

Type:

str

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:

dict

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:

dict

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:
  • point (location or None) – Extraction point

  • method (str) – Phenology method to compare

  • threshold_percentile (float) – Threshold for threshold method

Returns:

Comparison results with metrics from both approaches

Return type:

dict

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:

dict

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:
  • point (location or None, optional) – Extraction point. If None, uses ROI centroid.

  • figsize (tuple, optional) – Figure size (width, height). Default is (22, 14).

  • save_path (str or None, optional) – Path to save figure. If None, displays only.

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: object

Spatial 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 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: object

Server-side, per-pixel phenology raster generation with Earth Engine.

While TimeSeriesAnalyzer extracts phenological metrics for a single point (downloading the time series via getInfo), 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 on scipy.optimize.curve_fit and 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 an ee.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-band ee.Image using 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) or periods=24 (bi-monthly) is strongly recommended; with periods=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:
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: object

Land cover classification workflow based on temporal NDVI composites.

This class integrates seasonal NDVI metrics (from an NdviSeasonality instance) 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:

NdviSeasonality

processors#

Every processor, one per sensor.

Type:

list of NdviSeasonality

multi_sensor#

True when more than one sensor is combined. Band names then carry the sensor as prefix (S2_ndvi_2023_january).

Type:

bool

scale#

Pixel size in meters of the feature stack, used for sampling, normalization and export.

Type:

float

crs#

CRS of the common grid when the sensors are resampled, else None.

Type:

str or None

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

accuracy_results#

Accuracy metrics computed from validation data.

Type:

dict or None

roi#

Region of interest inherited from processor.

Type:

ee.Geometry

periods#

Number of temporal periods per year.

Type:

int

start_year#

First year of the analysis.

Type:

int

end_year#

Last year (inclusive) of the analysis.

Type:

int

sat#

Satellite name used (e.g., ‘S2’, ‘L8’).

Type:

str

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 exactly n_clusters groups by repeating “assign every sample to the nearest centroid, move every centroid to the mean of its samples” until nothing moves or max_iterations is 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 and n_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_clusters prototype 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 in self.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_supervised

Classification 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 Graphviz dot format) and the accuracy metrics.

  • <path>_samples.csv: one row per sample with its coordinates, class, every feature value and a split column (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:
  • path (str) – Output path without extension, e.g. 'results/tawau_s2_s1'. Missing folders are created.

  • include_samples (bool, optional) – Also write the samples CSV. Default True.

Returns:

Paths written, under the keys 'model' and 'samples'.

Return type:

dict

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:

pandas.DataFrame

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:

dict

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: object

GEE-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 NdviSeasonality instance. 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_year to ns.end_year (inclusive), computing one hydroperiod image per cycle. Each cycle spans from hydrological_year_start in 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. Default True.

  • compute_first_last (bool) – Include 'first_flood_doy' / 'last_flood_doy' bands. Default True.

Returns:

Mapping {hyd_year: ee.Image} where hyd_year is the starting calendar year of each cycle (e.g. 2020 for 2020-2021). Each image has the same bands as compute_hydroperiod() plus a 'hyd_year' property for easy identification.

Return type:

dict

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_normalized

Positive 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}. If None, runs compute_all_cycles() automatically.

  • index (str) – Water index, used only when cycles is None.

  • threshold (float) – Classification threshold, used only when cycles is None.

  • 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:

dict

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:

  1. Generate binary water masks (via get_water_masks()).

  2. 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)

  3. Sum contributions per pixel across all scenes → hydroperiod and valid_days.

  4. Optionally normalise: normalized = (hydroperiod / valid_days) * 365.

  5. 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. Default True.

  • compute_first_last (bool) – Add 'first_flood_doy' and 'last_flood_doy' bands (days since hydrological year start, 0-indexed). Default True.

  • min_flood_days (int) – Minimum accumulated flood days required for a pixel to receive a valid first_flood_doy / last_flood_doy value. Pixels below this threshold are masked (likely noise or isolated cloud artefacts). Default 3.

  • 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 = 0 and last_flood_doy = 365 because a meaningful onset/recession date cannot be determined. Range [0, 1]. Default 0.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.

Parameters:

hyd_year (int, optional) – Starting year of the hydrological cycle.

Returns:

IRT value between 0 (worst) and 1 (best). Requires one .getInfo() call to retrieve scene dates.

Return type:

float

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:
  • hyd_year (int, optional) – Starting year of the hydrological cycle.

  • n_periods (int) – Number of periods the year is divided into. Default 12 (monthly).

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 the hyd_year argument).

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 last compute_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 uint8 asset (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. Default False.

  • masks_asset_id (str, optional) – Asset path for the masks when include_masks=True. Defaults to asset_id with 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 last compute_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 uint8 file (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 to int16. Default False.

  • **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 by get_water_masks_stack() as a uint8 asset 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_value and nodata are 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 single uint8 GeoTIFF 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 the int16 of 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_value and nodata are 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:

  1. Compute the selected water index.

  2. Classify pixels: index > threshold → water (1), else → dry (0).

  3. Preserve the cloud/nodata mask already applied by NdviSeasonality (SCL-based for S2 when scl_mask=True, QA60 otherwise).

  4. Mosaic same-day scenes (max — water wins over dry).

  5. 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.0 works well for most water indices (positive = water). Increase for stricter mapping.

  • hyd_year (int, optional) – Starting calendar year of the hydrological cycle (e.g. 2023 for the Sep 2023 – Aug 2024 cycle). Defaults to ns.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 by get_water_masks_stack(). Default False.

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 when add_footprint=True.

Return type:

ee.ImageCollection

Notes

Pixel-level cloud/shadow masking is controlled by the scl_mask parameter of NdviSeasonality (default True for 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-band ee.Image, with one band per acquisition date named water_YYYY_MM_DD. Values are stored as uint8, which is four times smaller than the int16 hydroperiod 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 to int16 and 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. Both masked_value and nodata must be integers in [0, 255], different from 0, from 1 and from each other.

Returns:

uint8 image clipped to the ROI, one band per date:

  • 0 : dry

  • 1 : water

  • masked_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_drive

Send this stack to Google Drive.

export_water_masks_to_asset

Send 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:
  • KeyError – If expected OLI surface reflectance bands are missing in image (e.g., SR_B2–SR_B7).

  • TypeError – If image is not an ee.Image.

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_ETM

Scaling 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:
  • KeyError – If expected ETM+ surface reflectance bands are missing in image (e.g., SR_B1–SR_B5 and SR_B7).

  • TypeError – If image is not an ee.Image.

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_OLI

Scaling 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#