Sentinel1Collection

class RadGEEToolbox.Sentinel1Collection.Sentinel1Collection(start_date=None, end_date=None, relative_orbit_start=None, relative_orbit_stop=None, instrument_mode=None, polarization=None, bands=None, orbit_direction=None, boundary=None, resolution=None, resolution_meters=None, collection=None)

Bases: object

Represents a user-defined collection of ESA Sentinel-1 C-band Synthetic Aperture Radar (SAR) GRD data at 10 m/px resolution from Google Earth Engine (GEE). Units of backscatter are in decibels (dB) by default.

This class enables simplified definition, filtering, masking, and processing of Seninel-1 SAR imagery. It supports multiple spatial and temporal filters, multilooking and speckle filtering, caching for efficient computation, and direct conversion between log and linear backscatter scales. It also includes utilities for mosaicking, zonal statistics, and transect analysis.

Initialization can be done by providing filtering parameters or directly passing in a pre-filtered GEE collection.

Inspect the documentation or source code for details on the methods and properties available.

Parameters:

start_date (str) – Start date in ‘YYYY-MM-DD’ format. Required unless collection is provided.
end_date (str) – End date in ‘YYYY-MM-DD’ format. Required unless collection is provided.
relative_orbit_start (int or list) – Relative orbit start number for filtering collection. Required unless collection is provided.
relative_orbit_stop (int or list) – Relative orbit stop number for filtering collection. Required unless collection is provided.
instrument_mode (str or list, optional) – Instrument mode for filtering collection, with options of ‘IW’, ‘EW’, or ‘SM’. Defaults to ‘IW’
polarization (str or list, optional) – Polarization bands in image for filtering collection. Options: [‘VV’], [‘HH’], [‘VV’, ‘VH’], or [‘HH’, ‘HV’]. Default is [‘VV’, ‘VH’].
bands (str or list, optional) – Desired band(s). Must match polarization type. Default is [‘VV’, ‘VH’]
orbit_direction (str or list) – Orbit direction for filtering collection. Options: ‘ASCENDING’ and/or ‘DESCENDING’. Required unless collection is provided. For example, [‘ASCENDING’, ‘DESCENDING’] will include both ascending and descending images.
boundary (ee.Geometry, optional) – A geometry for filtering to images that intersect with the boundary shape. Overrides relative_orbit_start and relative_orbit_stop if provided.
resolution_meters (int) – Resolution in meters for filtering collection. Options of 10, 25, or 40. Required unless collection is provided. NOTE: this is for filtering the GEE collection, not multilooking/reprojecting)
collection (ee.ImageCollection, optional) – A pre-filtered Sentinel-1 ee.ImageCollection object to be converted to a Sentinel1Collection object. Overrides all other filters.

collection

The filtered or user-supplied image collection converted to an ee.ImageCollection object.

Type:: ee.ImageCollection

Raises:: ValueError – Raised if required filter parameters are missing, or if both collection and other filters are provided.

Note

See full usage examples in the documentation or notebooks: https://github.com/radwinskis/RadGEEToolbox/tree/main/Example%20Notebooks

Examples

>>> from RadGEEToolbox import Sentinel1Collection
>>> import ee
>>> ee.Initialize()
>>> counties = ee.FeatureCollection('TIGER/2018/Counties')
>>> salt_lake_county = counties.filter(ee.Filter.And(
...    ee.Filter.eq('NAME', 'Salt Lake'),
...    ee.Filter.eq('STATEFP', '49')))
>>> salt_lake_geometry = salt_lake_county.geometry()
>>> SAR_collection = Sentinel1Collection(
...    start_date='2024-05-01',
...    end_date='2024-05-31',
...    instrument_mode='IW',
...    polarization=['VV', 'VH'],
...    orbit_direction='DESCENDING',
...    boundary=salt_lake_geometry,
...    resolution_meters=10
... )
>>> latest_image = SAR_collection.image_grab(-1)
>>> mean_SAR_backscatter = SAR_collection.mean

property add_month_property

Adds a numeric ‘month’ property to each image in the collection.

Returns:: A Sentinel1Collection image collection with the ‘month’ property added to each image.
Return type:: Sentinel1Collection

static add_month_property_fn(image)

Adds a numeric ‘month’ property to the image based on its date.

Parameters:: image (ee.Image) – Input image.
Returns:: Image with the ‘month’ property added.
Return type:: ee.Image

anomaly(geometry, band_name=None, anomaly_band_name=None, replace=True, scale=10)

Calculates the anomaly of each image in a collection compared to the mean of each image.

This function computes the anomaly for each band in the input image by subtracting the mean value of that band from a provided ImageCollection. The anomaly is a measure of how much the pixel values deviate from the average conditions represented by the collection.

Parameters:

geometry (ee.Geometry) – The geometry for image reduction to define the mean value to be used for anomaly calculation.
band_name (str, optional) – A string representing the band name to be used for the output anomaly image. If not provided, the band name of the first band of the input image will be used.
anomaly_band_name (str, optional) – A string representing the band name to be used for the output anomaly image. If not provided, the band name of the first band of the input image will be used.
replace (bool, optional) – A boolean indicating whether to replace the original band with the anomaly band. If True, the output image will only contain the anomaly band. If False, the output image will retain all original bands and add the anomaly band. Default is True.
scale (int, optional) – The scale (in meters) to use for the image reduction. Default is 10 meters.

Returns:

A Sentinel1Collection where each image represents the anomaly (deviation from: the mean) for the chosen band. The output images retain the same band name.

Return type:

Sentinel1Collection

static anomaly_fn(image, geometry, band_name=None, anomaly_band_name=None, replace=True, scale=10)

Calculates the anomaly of a singleband image compared to the mean of the singleband image.

This function computes the anomaly for each band in the input image by subtracting the mean value of that band from a provided image. The anomaly is a measure of how much the pixel values deviate from the average conditions represented by the mean of the image.

Parameters:

image (ee.Image) – An ee.Image for which the anomaly is to be calculated. It is assumed that this image is a singleband image.
geometry (ee.Geometry) – The geometry for image reduction to define the mean value to be used for anomaly calculation.
band_name (str, optional) – A string representing the band name to be used for the output anomaly image. If not provided, the band name of the first band of the input image will be used.
anomaly_band_name (str, optional) – A string representing the band name to be used for the output anomaly image. If not provided, the band name of the first band of the input image will be used.
replace (bool, optional) – A boolean indicating whether to replace the original band with the anomaly band in the output image. If True, the output image will contain only the anomaly band. If False, the output image will contain both the original band and the anomaly band. Default is True.
scale (int, optional) – The scale (in meters) to use for the image reduction. Default is 10.

Returns:

An ee.Image where each band represents the anomaly (deviation from: the mean) for that band. The output image retains the same band name.

Return type:

ee.Image

binary_mask(threshold=None, band_name=None)

Creates a binary mask (value of 1 for pixels above set threshold and value of 0 for all other pixels) of the Sentinel1Collection image collection based on a specified band. If a singleband image is provided, the band name is automatically determined. If multiple bands are available, the user must specify the band name to use for masking.

Parameters:: band_name (str, optional) – The name of the band to use for masking. Defaults to None.
Returns:: Sentinel1Collection singleband image collection with binary masks applied.
Return type:: Sentinel1Collection

collectionStitch(img_col2)

Function to mosaic two Sentinel1Collection objects which share image dates. Mosaics are only formed for dates where both image collections have images. Image properties are copied from the primary collection. Server-side friendly.

Parameters:: img_col2 – secondary Sentinel1Collection image collection to be mosaiced with the primary image collection
Returns:: Sentinel1Collection image collection
Return type:: Sentinel1Collection

combine(other)

Combines the current Sentinel1Collection with another Sentinel1Collection, using the combine method.

Parameters:: other (Sentinel1Collection) – Another Sentinel1Collection to combine with current collection.
Returns:: A new Sentinel1Collection containing images from both collections.
Return type:: Sentinel1Collection

custom_image_grab(img_col, img_selector)

Function to select (“grab”) image of a specific index from an ee.ImageCollection object.

Parameters:

img_col (ee.ImageCollection) – ee.ImageCollection with same dates as another Sentinel1Collection image collection object.
img_selector (int) – index of image in list of dates for which user seeks to “select”.

Returns:

ee.Image of selected image

Return type:

ee.Image

property dates

Property attribute to retrieve list of dates as readable and indexable client-side list object.

Returns:: list of date strings.
Return type:: list

property dates_list

Property attribute to retrieve list of dates as server-side (GEE) object.

Returns:: Server-side ee.List of dates.
Return type:: ee.List

property dbFromSigma0

Property attribute function to convert image collection from decibels to sigma0. Results are calculated once per class object then cached for future use.

Returns:: Sentinel1Collection image collection
Return type:: Sentinel1Collection

static ee_to_df(ee_object, columns=None, remove_geom=True, sort_columns=False, **kwargs)

Converts an ee.FeatureCollection to pandas dataframe. Adapted from the geemap package (https://geemap.org/common/#geemap.common.ee_to_df)

Parameters:

ee_object (ee.FeatureCollection) – ee.FeatureCollection.
columns (list) – List of column names. Defaults to None.
remove_geom (bool) – Whether to remove the geometry column. Defaults to True.
sort_columns (bool) – Whether to sort the column names. Defaults to False.
kwargs – Additional arguments passed to ee.data.computeFeature.

Raises:

TypeError – ee_object must be an ee.FeatureCollection

Returns:

pandas DataFrame

Return type:

pd.DataFrame

exportProperties(property_names, file_path=None)

Fetches and returns specified properties from each image in the collection as a list, and returns a pandas DataFrame and optionally saves the results to a csv file.

Parameters:

property_names (list or str) – A property name or list of property names to retrieve. The ‘Date_Filter’ property is always included to provide temporal context.
file_path (str, optional) – If provided, the function will save the resulting DataFrame to a CSV file at this path. Defaults to None.

Returns:

A pandas DataFrame containing the requested properties for each image, sorted chronologically by ‘Date_Filter’.

Return type:

pd.DataFrame

export_to_asset_collection(asset_collection_path, region, scale, dates=None, filename_prefix='', crs=None, max_pixels=10000000000000, description_prefix='export', overwrite=False)

Exports an image collection to a Google Earth Engine asset collection. The asset collection will be created if it does not already exist, and each image exported will be named according to the provided filename prefix and date.

Parameters:

asset_collection_path (str) – The path to the asset collection.
region (ee.Geometry) – The region to export.
scale (int) – The scale of the export.
dates (list, optional) – The dates to export. Defaults to None.
filename_prefix (str, optional) – The filename prefix. Defaults to “”, i.e. blank.
crs (str, optional) – The coordinate reference system. Defaults to None, which will use the image’s CRS.
max_pixels (int, optional) – The maximum number of pixels. Defaults to int(1e13).
description_prefix (str, optional) – The description prefix. Defaults to “export”.
overwrite (bool, optional) – Whether to overwrite existing assets. Defaults to False.

Returns:

(queues export tasks)

Return type:

None

static extract_transect(image, line, reducer='mean', n_segments=100, dist_interval=None, scale=None, crs=None, crsTransform=None, tileScale=1.0, to_pandas=False, **kwargs)

Extracts transect from an image. Adapted from the geemap package (https://geemap.org/common/#geemap.common.extract_transect).

Parameters:

image (ee.Image) – The image to extract transect from.
line (ee.Geometry.LineString) – The LineString used to extract transect from an image.
reducer (str, optional) – The ee.Reducer to use, e.g., ‘mean’, ‘median’, ‘min’, ‘max’, ‘stdDev’. Defaults to “mean”.
n_segments (int, optional) – The number of segments that the LineString will be split into. Defaults to 100.
dist_interval (float, optional) – The distance interval used for splitting the LineString. If specified, the n_segments parameter will be ignored. Defaults to None.
scale (float, optional) – A nominal scale in meters of the projection to work in. Defaults to None.
crs (ee.Projection, optional) – The projection to work in. If unspecified, the projection of the image’s first band is used. If specified in addition to scale, rescaled to the specified scale. Defaults to None.
crsTransform (list, optional) – The list of CRS transform values. This is a row-major ordering of the 3x2 transform matrix. This option is mutually exclusive with ‘scale’, and will replace any transform already set on the projection. Defaults to None.
tileScale (float, optional) – A scaling factor used to reduce aggregation tile size; using a larger tileScale (e.g. 2 or 4) may enable computations that run out of memory with the default. Defaults to 1.
to_pandas (bool, optional) – Whether to convert the result to a pandas dataframe. Default to False.

Raises:

TypeError – If the geometry type is not LineString.
Exception – If the program fails to compute.

Returns:

The FeatureCollection containing the transect with distance and reducer values.

Return type:

ee.FeatureCollection

static extract_zonal_stats_from_buffer(image, coordinates, buffer_size=1, reducer_type='mean', scale=10, tileScale=1, coordinate_names=None)

Function to extract spatial statistics from an image for a list or single set of (long, lat) coordinates, providing individual statistics for each location. A radial buffer is applied around each coordinate to extract the statistics, which defaults to 1 meter. The function returns a pandas DataFrame with the statistics for each coordinate.

NOTE: Be sure the coordinates are provided as longitude, latitude (x, y) tuples!

Parameters:

image (ee.Image) – The image from which to extract statistics. Should be single-band.
coordinates (list or tuple) – A single (lon, lat) tuple or a list of (lon, lat) tuples.
buffer_size (int, optional) – The radial buffer size in meters. Defaults to 1.
reducer_type (str, optional) – The ee.Reducer to use (‘mean’, ‘median’, ‘min’, etc.). Defaults to ‘mean’.
scale (int, optional) – The scale in meters for the reduction. Defaults to 10.
tileScale (int, optional) – The tile scale factor. Defaults to 1.
coordinate_names (list, optional) – A list of names for the coordinates.

Returns:

A pandas DataFrame with the image’s ‘Date_Filter’ as the index and a: column for each coordinate location.

Return type:

pd.DataFrame

get_boundary_and_orbit_filtered_collection()

Function to filter image collection based on Sentinel1Collection class arguments. Automatically calculated when using collection method, depending on provided class arguments (when tile info is provided).

Returns:: Filtered image collection - used for subsequent analyses or to acquire ee.ImageCollection from Sentinel1Collection object
Return type:: ee.ImageCollection

get_boundary_filtered_collection()

Function to filter and mask image collection based on Sentinel1Collection class arguments. Automatically calculated when using collection method, depending on provided class arguments (when boundary info is provided).

Returns:: Filtered image collection - used for subsequent analyses or to acquire ee.ImageCollection from Sentinel1Collection object
Return type:: ee.ImageCollection

get_filtered_collection()

Function to filter image collection based on Sentinel1Collection class arguments. Automatically calculated when using collection method, depending on provided class arguments (when tile info is provided).

Returns:: Filtered image collection - used for subsequent analyses or to acquire ee.ImageCollection from Sentinel1Collection object
Return type:: ee.ImageCollection

static image_dater(image)

Adds date to image properties as ‘Date_Filter’.

Parameters:: image (ee.Image) – Input image
Returns:: Image with date in properties.
Return type:: ee.Image

image_grab(img_selector)

Function to select (“grab”) an image by index from the collection. Easy way to get latest image or browse imagery one-by-one.

Parameters:: img_selector (int) – index of image in the collection for which user seeks to select/”grab”.
Returns:: ee.Image of selected image
Return type:: ee.Image

image_pick(img_date)

Function to select (“grab”) image of a specific date in format of ‘YYYY-MM-DD’ - will not work correctly if collection is composed of multiple images of the same date.

Parameters:: img_date (str) – date of image to select from collection, in format of ‘YYYY-MM-DD’
Returns:: ee.Image of selected image
Return type:: ee.Image

iterate_zonal_stats(geometries, band=None, reducer_type='mean', scale=10, geometry_names=None, buffer_size=1, tileScale=1, dates=None, file_path=None)

Iterates over a collection of images and extracts spatial statistics (defaults to mean) for a given list of geometries or coordinates. Individual statistics are calculated for each geometry or coordinate provided. When coordinates are provided, a radial buffer is applied around each coordinate to extract the statistics, where the size of the buffer is determined by the buffer_size argument (defaults to 1 meter). The function returns a pandas DataFrame with the statistics for each coordinate and date, or optionally exports the data to a table in .csv format.

Parameters:

geometries (ee.Geometry, ee.Feature, ee.FeatureCollection, list, or tuple) – Input geometries for which to extract statistics. Can be a single ee.Geometry, an ee.Feature, an ee.FeatureCollection, a list of (lon, lat) tuples, or a list of ee.Geometry objects. Be careful to NOT provide coordinates as (lat, lon)!
band (str, optional) – The name of the band to use for statistics. If None, the first band is used. Defaults to None.
reducer_type (str, optional) – The ee.Reducer to use, e.g., ‘mean’, ‘median’, ‘max’, ‘sum’. Defaults to ‘mean’. Any ee.Reducer method can be used.
scale (int, optional) – Pixel scale in meters for the reduction. Defaults to 10.
geometry_names (list, optional) – A list of string names for the geometries. If provided, must match the number of geometries. Defaults to None.
buffer_size (int, optional) – Radial buffer in meters around coordinates. Defaults to 1.
tileScale (int, optional) – A scaling factor to reduce aggregation tile size. Defaults to 1.
dates (list, optional) – A list of date strings (‘YYYY-MM-DD’) for filtering the collection, such that only images from these dates are included for zonal statistic retrieval. Defaults to None, which uses all dates in the collection.
file_path (str, optional) – File path to save the output CSV.

Returns:

A pandas DataFrame with dates as the index and coordinate names: as columns. Returns None if using ‘iterative’ mode with file_path.

Return type:

pd.DataFrame or None

Raises:

ValueError – If input parameters are invalid.
TypeError – If geometries input type is unsupported.

static leesigma(image, KERNEL_SIZE, geometry=None, Tk=7, sigma=0.9, looks=1)

Implements the improved lee sigma filter for speckle filtering, adapted from https://github.com/adugnag/gee_s1_ard (by Dr. Adugna Mullissa). See: Lee, J.-S. Wen, J.-H. Ainsworth, T.L. Chen, K.-S. Chen, A.J. Improved sigma filter for speckle filtering of SAR imagery. IEEE Trans. Geosci. Remote Sens. 2009, 47, 202–213.

Parameters:

image (ee.Image) – Image for speckle filtering
KERNEL_SIZE (int) – positive odd integer (neighbourhood window size - suggested to use between 3-9)
geometry (ee.Geometry) – Geometry to use for speckle filtering (optional). Defaults to footprint of input image.
Tk (int) – number of bright pixels in a 3x3 window (default is 7)
sigma (float) – noise standard deviation (default is 0.9)
looks (int) – number of looks (1, 2, 3, or 4) corresponding to the input image (default is 1). This does NOT perform multilooking, but rather is used to determine the sigma range for filtering.

Returns:

Speckle filtered image

Return type:

ee.Image

mann_kendall_trend(target_band=None, join_method='system:time_start', geometry=None)

Calculates the Mann-Kendall S-value, Variance, Z-Score, and Confidence Level for each pixel in the image collection, in addition to calculating the Sen’s slope for each pixel in the image collection. The output is an image with the following bands: ‘s_statistic’, ‘variance’, ‘z_score’, ‘confidence’, and ‘slope’.

This function can be used to identify trends in the image collection over time, such as increasing or decreasing values in the target band, and can be used to assess the significance of these trends. Note that this function is computationally intensive and may take a long time to run for large image collections or high-resolution images.

The ‘s_statistic’ band represents the Mann-Kendall S-value, which is a measure of the strength and direction of the trend. The ‘variance’ band represents the variance of the S-value, which is a measure of the variability of the S-value. The ‘z_score’ band represents the Z-Score, which is a measure of the significance of the trend. The ‘confidence’ band represents the confidence level of the trend based on the z_score, which is a probabilistic measure of the confidence in the trend (percentage). The ‘slope’ band represents the Sen’s slope, which is a measure of the rate of change in the target band over time. This value can be small as multispectral indices commonly range from -1 to 1, so a slope may have values of <0.2 for most cases.

Be sure to select the correct band for the target_band parameter, as this will be used to calculate the trend statistics. You may optionally provide an ee.Geometry object for the geometry parameter to limit the area over which the trend statistics are calculated. The geometry parameter is optional and defaults to None, which means that the trend statistics will be calculated over the entire footprint of the image collection.

Parameters:

image_collection (Sentinel1Collection or ee.ImageCollection) – The input image collection for which the Mann-Kendall and Sen’s slope trend statistics will be calculated.
target_band (str) – The band name to be used for the output anomaly image. e.g. ‘ndvi’
join_method (str, optional) – The method used to join images in the collection. Options are ‘system:time_start’ or ‘Date_Filter’. Default is ‘system:time_start’.
geometry (ee.Geometry, optional) – An ee.Geometry object to limit the area over which the trend statistics are calculated and mask the output image. Default is None.

Returns:

An image with the following bands: ‘s_statistic’, ‘variance’, ‘z_score’, ‘confidence’, and ‘slope’.

Return type:

ee.Image

mask_out_polygon(polygon)

Function to mask Sentinel1Collection image collection by a polygon (ee.Geometry), where pixels inside the polygon are masked out.

Args: (image collection): polygon (ee.Geometry): ee.Geometry polygon or shape used to mask image collection.

Returns:: masked Sentinel1Collection image collection
Return type:: Sentinel1Collection

mask_to_polygon(polygon)

Function to mask Sentinel1Collection image collection by a polygon (ee.Geometry), where pixels outside the polygon are masked out.

Args: (image collection): polygon (ee.Geometry): ee.Geometry polygon or shape used to mask image collection.

Returns:: masked Sentinel1Collection image collection
Return type:: Sentinel1Collection

property max

Property attribute function to calculate max image from image collection. Results are calculated once per class object then cached for future use.

Returns:: max image from entire collection.
Return type:: ee.Image

property mean

Property attribute function to calculate mean image from image collection. Results are calculated once per class object then cached for future use.

Returns:: mean image from entire collection.
Return type:: ee.Image

property median

Property attribute function to calculate median image from image collection. Results are calculated once per class object then cached for future use.

Returns:: median image from entire collection.
Return type:: ee.Image

merge(collections=None, multiband_collection=None, date_key='Date_Filter')

Merge many singleband Sentinel1Collection products into the parent collection, or merge a single multiband collection with parent collection, pairing images by exact Date_Filter and returning one multiband image per date.

NOTE: if you want to merge two multiband collections, use the combine method instead.

Parameters:

collections (list) – List of singleband collections to merge with parent collection, effectively adds one band per collection to each image in parent
multiband_collection (Sentinel1Collection, optional) – A multiband collection to merge with parent. Specifying a collection here will override collections.
date_key (str) – image property key for exact pairing (default ‘Date_Filter’)

Returns:

parent with extra single bands attached (one image per date)

Return type:

Sentinel1Collection

property min

Property attribute function to calculate min image from image collection. Results are calculated once per class object then cached for future use.

Returns:: min image from entire collection.
Return type:: ee.Image

property monthly_max_collection

Creates a monthly max composite from a Sentinel1Collection image collection.

This function computes the max for each month within the collection’s date range, for each band in the collection. It automatically handles the full temporal extent of the input collection.