Sentinel1Collection Documentation

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)

Class object representing a combined collection of NASA/USGS Landsat 5, 8, and 9 TM & OLI surface reflectance satellite images at 30 m/px

This class provides methods to filter, process, and analyze Landsat satellite imagery for a given period and region

Arguments:

start_date (str): Start date string in format of yyyy-mm-dd for filtering collection (required unless collection is provided)

end_date (str): End date string in format of yyyy-mm-dd for filtering collection (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): Instrument mode for filtering collection, with options of IW, EW, or SM (optional - defaults to IW)

polarization (str or list): Polarization bands in image for filtering collection. Options: [‘VV’], [‘HH’], [‘VV’, ‘VH’], or [‘HH’, ‘HV’] (optional; default is [‘VV’, ‘VH’])

bands (str or list): Band(s) of interest in each image (optional, 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)

boundary (ee.Geometry): Boundary for filtering images to images that intersect with the boundary shape (optional)

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 argument to provide an ee.ImageCollection object to be converted to a Sentinel1Collection object - will override other arguments!

Attributes:

collection: Returns an ee.ImageCollection object from any Sentinel1Collection image collection object

_dates_list: Cache storage for dates_list property attribute

_dates: Cahce storgage for dates property attribute

_geometry_masked_collection: Cache storage for mask_to_polygon method

_geometry_masked_out_collection: Cache storage for mask_out_polygon method

_median: Cache storage for median property attribute

_mean: Cache storage for mean property attribute

_max: Cache storage for max property attribute

_min: Cache storage for min property attribute

_MosaicByDate: Cache storage for MosaicByDate property attribute

_PixelAreaSumCollection: Cache storage for PixelAreaSumCollection property attribute

_speckle_filter: Cache storage for speckle_filter property attribute

_Sigma0FromDb: Cache storage for Sigma0FromDb property attribute

_DbFromSigma0: Cache storage for DbFromSigma0 property attribute

_multilook: Cache storage for multilook property attribute

Property attributes:

dates_list (returns: Server-Side List): Unreadable Earth Engine list of image dates (server-side)

dates (returns: Client-Side List): Readable pythonic list of image dates (client-side)

max (returns: ee.Image): Returns a temporally reduced max image (calculates max at each pixel)

median (returns: ee.Image): Returns a temporally reduced median image (calculates median at each pixel)

mean (returns: ee.Image): Returns a temporally reduced mean image (calculates mean at each pixel)

min (returns: ee.Image): Returns a temporally reduced min image (calculates min at each pixel)

MosaicByDate (returns: Sentinel1Collection image collection): Mosaics image collection where images with the same date are mosaiced into the same image. Calculates total cloud percentage for subsequent filtering of cloudy mosaics.

Sigma0FromDb (returns: Sentinel1Collection image collection): Converts image collection from decibels to sigma0

DbFromSigma0 (returns: Sentinel1Collection image collection): Converts image collection from sigma0 to decibels

multilook (returns: Sentinel1Collection image collection): Multilooks image collection by specified number of looks (1, 2, 3, or 4)

speckle_filter (returns: Sentinel1Collection image collection): Applies speckle filter to image collection

Methods:

get_filtered_collection(self)

get_boundary_filtered_collection(self)

mask_to_polygon(self, polygon)

mask_out_polygon(self, polygon)

PixelAreaSumCollection(self, band_name, geometry, threshold, scale, maxPixels)

image_grab(self, img_selector)

custom_image_grab(self, img_col, img_selector)

image_pick(self, img_date)

CollectionStitch(self, img_col2)

Static Methods:

image_dater(image)

PixelAreaSum(image, band_name, geometry, threshold=-1, scale=30, maxPixels=1e12)

multilook_fn(image, looks)

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

Usage:

The Sentinel1Collection object alone acts as a base object for which to further filter or process to indices or spatial reductions

To use the Sentinel1Collection functionality, use any of the built in class attributes or method functions. For example, using class attributes:

image_collection = Sentinel1Collection(start_date, end_date, tile_row, tile_path, cloud_percentage_threshold)

ee_image_collection = image_collection.collection #returns ee.ImageCollection from provided argument filters

latest_image = image_collection.image_grab(-1) #returns latest image in collection as ee.Image

cloud_masked_collection = image_collection.masked_clouds_collection #returns cloud-masked Sentinel1Collection image collection

NDWI_collection = image_collection.ndwi #returns NDWI Sentinel1Collection image collection

latest_NDWI_image = NDWI_collection.image_grab(-1) #Example showing how class functions work with any Sentinel1Collection image collection object, returning latest ndwi image

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.

Args: self: self is passed into argument, which is a Sentinel1Collection image collection img_col2: secondary Sentinel1Collection image collection to be mosaiced with the primary image collection

Returns: image collection (Sentinel1Collection): Sentinel1Collection image collection

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.

Args: self: self is passed into argument

Returns: image collection (Sentinel1Collection): Sentinel1Collection image collection

property MosaicByDate

Property attribute function to mosaic collection images that share the same date. The property CLOUD_COVER for each image is used to calculate an overall mean, which replaces the CLOUD_COVER property for each mosaiced image. Server-side friendly. NOTE: if images are removed from the collection from cloud filtering, you may have mosaics composed of only one image.

Args: self: self is passed into argument, which is a Sentinel1Collection image collection

Returns: image collection (Sentinel1Collection): Sentinel1Collection image collection with mosaiced imagery and mean CLOUD_COVER as a property

static PixelAreaSum(image, band_name, geometry, threshold=-1, scale=30, maxPixels=1000000000000.0)

Function to calculate the summation of area for pixels of interest (above a specific threshold) in a geometry and store the value as image property (matching name of chosen band).

Args: image (ee.Image): input ee.Image band_name (string): name of band (string) for calculating area geometry (ee.Geometry): ee.Geometry object denoting area to clip to for area calculation threshold (int): integer threshold to specify masking of pixels below threshold (defaults to -1) scale (int): integer scale of image resolution (meters) (defaults to 30) maxPixels (int): integer denoting maximum number of pixels for calculations

Returns: image (ee.Image): ee.Image with area calculation stored as property matching name of band

PixelAreaSumCollection(band_name, geometry, threshold=-1, scale=30, maxPixels=1000000000000.0)

Function to calculate the summation of area for pixels of interest (above a specific threshold) within a geometry and store the value as image property (matching name of chosen band) for an entire image collection. The resulting value has units of square meters.

Args: self: self is the input image collection band_name: name of band (string) for calculating area. geometry: ee.Geometry object denoting area to clip to for area calculation. threshold: integer threshold to specify masking of pixels below threshold (defaults to -1). scale: integer scale of image resolution (meters) (defaults to 30). maxPixels: integer denoting maximum number of pixels for calculations.

Returns: image (ee.Image): Image with area calculation stored as property matching name of band.

property Sigma0FromDb

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

Args: self: self is passed into argument

Returns: image collection (Sentinel1Collection): Sentinel1Collection image collection

custom_image_grab(img_col, img_selector)

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

Args: self: self is passed into argument img_col: ee.ImageCollection with same dates as another Sentinel1Collection image collection object. img_selector: index of image in list of dates for which user seeks to “select”.

Returns: image (ee.Image): ee.Image of selected image

property dates

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

Args: self: self is passed into argument.

Returns: list: list of date strings.

property dates_list

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

Args: self: self is passed into argument.

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

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)

Args:

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:

pd.DataFrame: pandas DataFrame

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)

Args:

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:

ee.FeatureCollection: The FeatureCollection containing the transect with distance and reducer values.

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

Args: self: self is passed into argument

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

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

Args: self: self is passed into argument

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

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

Args: self: self is passed into argument

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

static image_dater(image)

Adds date to image properties as ‘Date_Filter’.

Args: image (ee.Image): Input image

Returns: image (ee.Image): Image with date in properties.

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.

Args: self: self is passed into argument img_selector: index of image in the collection for which user seeks to select/”grab”.

Returns: image (ee.Image): ee.Image of selected 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.

Args: self: self is passed into argument img_date: date (str) of image to select in format of ‘YYYY-MM-DD’

Returns: image (ee.Image): ee.Image of selected image

static leesigma(image, KERNEL_SIZE, geometry, 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.

Args: image (ee.Image): Image for speckle filtering KERNEL_SIZE (int): positive odd integer (neighbourhood window size - suggested to use between 3-9)

Returns: Image (ee.Image): Speckle filtered 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: self: self is passed into argument (image collection) polygon (ee.Geometry): ee.Geometry polygon or shape used to mask image collection.

Returns: image collection (Sentinel1Collection): masked Sentinel1Collection image collection

mask_to_polygon(polygon)

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

Args: self: self is passed into argument (image collection) polygon (ee.Geometry): ee.Geometry polygon or shape used to mask image collection.

Returns: image collection (Sentinel1Collection): masked Sentinel1Collection image collection

property max

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

Args: self: self is passed into argument

Returns: image (ee.Image): max image from entire collection.

property mean

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

Args: self: self is passed into argument

Returns: image (ee.Image): mean image from entire collection.

property median

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

Args: self: self is passed into argument

Returns: image (ee.Image): median image from entire collection.

property min

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

Args: self: self is passed into argument

Returns: image (ee.Image): min image from entire collection.

multilook(looks)

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

Args: self: self is passed into argument looks: number of looks to multilook image collection by (int)

Returns: image collection (Sentinel1Collection): Sentinel1Collection image collection

speckle_filter(KERNEL_SIZE, geometry, Tk=7, sigma=0.9, looks=1)

Property attribute function to apply speckle filter to entire image collection. Results are calculated once per class object then cached for future use.

Args: self: self is passed into argument KERNEL_SIZE: size of kernel for speckle filter (int)

Returns: image collection (Sentinel1Collection): Sentinel1Collection image collection

static transect(image, lines, line_names, reducer='mean', n_segments=None, dist_interval=10, to_pandas=True)

Computes and stores the values along a transect for each line in a list of lines. Builds off of the extract_transect function from the geemap package

where checks are ran to ensure that the reducer column is present in the transect data. If the reducer column is not present, a column of NaNs is created. An ee reducer is used to aggregate the values along the transect, depending on the number of segments or distance interval specified. Defaults to ‘mean’ reducer.

Args:

image (ee.Image): ee.Image object to use for calculating transect values. lines (list): List of ee.Geometry.LineString objects. line_names (list of strings): List of line string names. reducer (str): The ee reducer to use. Defaults to ‘mean’. n_segments (int): The number of segments that the LineString will be split into. Defaults to None. dist_interval (float): The distance interval used for splitting the LineString. If specified, the n_segments parameter will be ignored. Defaults to 10. to_pandas (bool): Whether to convert the result to a pandas dataframe. Defaults to True.

Returns:

pd.DataFrame or ee.FeatureCollection: organized list of values along the transect(s)

transect_iterator(lines, line_names, save_folder_path, reducer='mean', n_segments=None, dist_interval=10, to_pandas=True)

Computes and stores the values along a transect for each line in a list of lines for each image in a Sentinel1Collection image collection, then saves the data for each image to a csv file. Builds off of the extract_transect function from the geemap package

where checks are ran to ensure that the reducer column is present in the transect data. If the reducer column is not present, a column of NaNs is created. An ee reducer is used to aggregate the values along the transect, depending on the number of segments or distance interval specified. Defaults to ‘mean’ reducer. Naming conventions for the csv files follows as: “image-date_line-name.csv”

Args:

self (Sentinel1Collection image collection): Image collection object to iterate for calculating transect values for each image. lines (list): List of ee.Geometry.LineString objects. line_names (list of strings): List of line string names. save_folder_path (str): The path to the folder where the csv files will be saved. reducer (str): The ee reducer to use. Defaults to ‘mean’. n_segments (int): The number of segments that the LineString will be split into. Defaults to None. dist_interval (float): The distance interval used for splitting the LineString. If specified, the n_segments parameter will be ignored. Defaults to 10. to_pandas (bool): Whether to convert the result to a pandas dataframe. Defaults to True.

Raises:

Exception: If the program fails to compute.

Returns:

csv file: file for each image with an organized list of values along the transect(s)