RadGEEToolbox 1.7.0__py3-none-any.whl → 1.7.1__py3-none-any.whl

RadGEEToolbox/Sentinel1Collection.py

@@ -213,6 +213,11 @@ class Sentinel1Collection:
         self._mean = None
         self._max = None
         self._min = None
+        self._monthly_median = None
+        self._monthly_mean = None
+        self._monthly_max = None
+        self._monthly_min = None
+        self._monthly_sum = None
         self._MosaicByDate = None
         self._PixelAreaSumCollection = None
         self._speckle_filter = None
@@ -307,11 +312,11 @@ class Sentinel1Collection:
 
         Args:
             band_name (string or list of strings): name of band(s) (string) for calculating area. If providing multiple band names, pass as a list of strings.
-            geometry (ee.Geometry): ee.Geometry object denoting area to clip to for area calculation
+            geometry (ee.Geometry): ee.Geometry object denoting area to clip to for area calculation.
             threshold (float): integer threshold to specify masking of pixels below threshold (defaults to -1). If providing multiple band names, the same threshold will be applied to all bands. Best practice in this case is to mask the bands prior to passing to this function and leave threshold at default of -1.
-            scale (int): integer scale of image resolution (meters) (defaults to 10)
-            maxPixels (int): integer denoting maximum number of pixels for calculations
-            output_type (str): 'ImageCollection' to return an ee.ImageCollection, 'Sentinel1Collection' to return a Sentinel1Collection object (defaults to 'ImageCollection')
+            scale (int): integer scale of image resolution (meters) (defaults to 30).
+            maxPixels (int): integer denoting maximum number of pixels for calculations.
+            output_type (str): 'ImageCollection' or 'ee.ImageCollection' to return an ee.ImageCollection, 'Sentinel1Collection' to return a Sentinel1Collection object, or 'DataFrame', 'Pandas', 'pd', 'dataframe', 'df' to return a pandas DataFrame (defaults to 'ImageCollection').
             area_data_export_path (str, optional): If provided, the function will save the resulting area data to a CSV file at the specified path.
 
         Returns:
@@ -336,15 +341,42 @@ class Sentinel1Collection:
 
         # If an export path is provided, the area data will be exported to a CSV file
         if area_data_export_path:
-            Sentinel1Collection(collection=self._PixelAreaSumCollection).ExportProperties(property_names=band_name, file_path=area_data_export_path+'.csv')
+            Sentinel1Collection(collection=self._PixelAreaSumCollection).ExportProperties(property_names=[band_name], file_path=area_data_export_path+'.csv')
 
         # Returning the result in the desired format based on output_type argument or raising an error for invalid input
-        if output_type == 'ImageCollection':
+        if output_type == 'ImageCollection' or output_type == 'ee.ImageCollection':
             return self._PixelAreaSumCollection
         elif output_type == 'Sentinel1Collection':
             return Sentinel1Collection(collection=self._PixelAreaSumCollection)
+        elif output_type == 'DataFrame' or output_type == 'Pandas' or output_type == 'pd' or output_type == 'dataframe' or output_type == 'df':
+            return Sentinel1Collection(collection=self._PixelAreaSumCollection).ExportProperties(property_names=[band_name])
         else:
-            raise ValueError("output_type must be 'ImageCollection' or 'Sentinel1Collection'")
+            raise ValueError("Incorrect `output_type`. The `output_type` argument must be one of the following: 'ImageCollection', 'ee.ImageCollection', 'Sentinel1Collection', 'DataFrame', 'Pandas', 'pd', 'dataframe', or 'df'.")
+
+    @staticmethod
+    def add_month_property_fn(image):
+        """
+        Adds a numeric 'month' property to the image based on its date.
+
+        Args:
+            image (ee.Image): Input image.
+
+        Returns:
+            ee.Image: Image with the 'month' property added.
+        """
+        return image.set('month', image.date().get('month'))
+
+    @property
+    def add_month_property(self):
+        """
+        Adds a numeric 'month' property to each image in the collection.
+
+        Returns:
+            Sentinel1Collection: A Sentinel1Collection image collection with the 'month' property added to each image.
+        """
+        col = self.collection.map(Sentinel1Collection.add_month_property_fn)
+        return Sentinel1Collection(collection=col)
+
 
     def combine(self, other):
         """
@@ -719,6 +751,64 @@ class Sentinel1Collection:
             dB_collection = collection.map(conversion)
             self._DbFromSigma0 = dB_collection
         return Sentinel1Collection(collection=self._DbFromSigma0)
+    
+    @staticmethod
+    def 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.
+
+        Args:
+            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:
+            ee.Image: An ee.Image where each band represents the anomaly (deviation from
+                        the mean) for that band. The output image retains the same band name.
+        """
+        if band_name:
+            band_name = band_name
+        else:
+            band_name = ee.String(image.bandNames().get(0))
+
+        image_to_process = image.select([band_name])
+
+        # Calculate the mean image of the provided collection.
+        mean_image = image_to_process.reduceRegion(
+            reducer=ee.Reducer.mean(),
+            geometry=geometry,
+            scale=scale,
+            maxPixels=1e13
+        ).toImage()
+
+        # Compute the anomaly by subtracting the mean image from the input image.
+        if scale == 10:
+            anomaly_image = image_to_process.subtract(mean_image)
+        else:
+            anomaly_image = image_to_process.reproject(crs=image_to_process.projection(), scale=scale).subtract(mean_image)
+
+        if anomaly_band_name is None:
+            if band_name:
+                anomaly_image = anomaly_image.rename(band_name) 
+            else:
+                # Preserve original properties from the input image.
+                anomaly_image = anomaly_image.rename(ee.String(image.bandNames().get(0))) 
+        else:
+            anomaly_image = anomaly_image.rename(anomaly_band_name) 
+        # return anomaly_image
+        if replace:
+            return anomaly_image.copyProperties(image).set('system:time_start', image.get('system:time_start'))
+        else:
+            return image.addBands(anomaly_image, overwrite=True)
 
     @property
     def dates_list(self):
@@ -887,6 +977,27 @@ class Sentinel1Collection:
             .select(self.bands)
         )
         return filtered_collection
+    
+    def remove_duplicate_dates(self, sort_by='system:time_start', ascending=True):
+        """
+        Removes duplicate images that share the same date, keeping only the first one encountered.
+        Useful for handling duplicate Sentinel-1A/1B acquisitions or overlapping tiles.
+        
+        Args:
+            sort_by (str): Property to sort by before filtering distinct dates. 
+                           Defaults to 'system:time_start'. Take care to provide a property that exists in all images if using a custom property.
+            ascending (bool): Sort order. Defaults to True.
+
+        Returns:
+            Sentinel1Collection: A new Sentinel1Collection object with distinct dates.
+        """
+        # Sort the collection to ensure the "best" image comes first (e.g. least cloudy)
+        sorted_col = self.collection.sort(sort_by, ascending)
+        
+        # distinct() retains the first image for each unique value of the specified property
+        distinct_col = sorted_col.distinct('Date_Filter')
+        
+        return Sentinel1Collection(collection=distinct_col)
 
     @property
     def median(self):
@@ -940,6 +1051,450 @@ class Sentinel1Collection:
             col = self.collection.min()
             self._min = col
         return self._min
+    
+    @property
+    def monthly_median_collection(self):
+        """Creates a monthly median composite from a Sentinel1Collection image collection.
+
+        This function computes the median 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.
+
+        The resulting images have a 'system:time_start' property set to the
+        first day of each month and an 'image_count' property indicating how
+        many images were used in the composite. Months with no images are
+        automatically excluded from the final collection.
+
+        Returns:
+            Sentinel1Collection: A new Sentinel1Collection object with monthly median composites.
+        """
+        if self._monthly_median is None:
+            collection = self.collection
+            # Get the start and end dates of the entire collection.
+            date_range = collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            start_date = ee.Date(date_range.get('min'))
+            end_date = ee.Date(date_range.get('max'))
+
+            # Calculate the total number of months in the date range.
+            # The .round() is important for ensuring we get an integer.
+            num_months = end_date.difference(start_date, 'month').round()
+
+            # Generate a list of starting dates for each month.
+            # This uses a sequence and advances the start date by 'i' months.
+            def get_month_start(i):
+                return start_date.advance(i, 'month')
+            
+            month_starts = ee.List.sequence(0, num_months).map(get_month_start)
+
+            # Define a function to map over the list of month start dates.
+            def create_monthly_composite(date):
+                # Cast the input to an ee.Date object.
+                start_of_month = ee.Date(date)
+                # The end date is exclusive, so we advance by 1 month.
+                end_of_month = start_of_month.advance(1, 'month')
+
+                # Filter the original collection to get images for the current month.
+                monthly_subset = collection.filterDate(start_of_month, end_of_month)
+
+                # Count the number of images in the monthly subset.
+                image_count = monthly_subset.size()
+
+                # Compute the median. This is robust to outliers like clouds.
+                monthly_median = monthly_subset.median()
+
+                # Set essential properties on the resulting composite image.
+                # The timestamp is crucial for time-series analysis and charting.
+                # The image_count is useful metadata for quality assessment.
+                return monthly_median.set({
+                    'system:time_start': start_of_month.millis(),
+                    'month': start_of_month.get('month'),
+                    'year': start_of_month.get('year'),
+                    'Date_Filter': start_of_month.format('YYYY-MM-dd'),
+                    'image_count': image_count
+                })
+
+            # Map the composite function over the list of month start dates.
+            monthly_composites_list = month_starts.map(create_monthly_composite)
+
+            # Convert the list of images into an ee.ImageCollection.
+            monthly_collection = ee.ImageCollection.fromImages(monthly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            # This prevents empty/masked images from being in the final collection.
+            final_collection = Sentinel1Collection(collection=monthly_collection.filter(ee.Filter.gt('image_count', 0)))
+            self._monthly_median = final_collection
+        else:
+            pass
+
+        return self._monthly_median
+    
+    @property
+    def monthly_mean_collection(self):
+        """Creates a monthly mean composite from a Sentinel1Collection image collection.
+
+        This function computes the mean 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.
+
+        The resulting images have a 'system:time_start' property set to the
+        first day of each month and an 'image_count' property indicating how
+        many images were used in the composite. Months with no images are
+        automatically excluded from the final collection.
+
+        NOTE: the day of month for the 'system:time_start' property is set to the earliest date of the first month observed and may not be the first day of the month.
+
+        Returns:
+            Sentinel1Collection: A new Sentinel1Collection object with monthly mean composites.
+        """
+        if self._monthly_mean is None:
+            collection = self.collection
+            target_proj = collection.first().projection()
+            # Get the start and end dates of the entire collection.
+            date_range = collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            original_start_date = ee.Date(date_range.get('min'))
+            end_date = ee.Date(date_range.get('max'))
+
+            start_year = original_start_date.get('year')
+            start_month = original_start_date.get('month')
+            start_date = ee.Date.fromYMD(start_year, start_month, 1)
+
+            # Calculate the total number of months in the date range.
+            # The .round() is important for ensuring we get an integer.
+            num_months = end_date.difference(start_date, 'month').round()
+
+            # Generate a list of starting dates for each month.
+            # This uses a sequence and advances the start date by 'i' months.
+            def get_month_start(i):
+                return start_date.advance(i, 'month')
+            
+            month_starts = ee.List.sequence(0, num_months).map(get_month_start)
+
+            # Define a function to map over the list of month start dates.
+            def create_monthly_composite(date):
+                # Cast the input to an ee.Date object.
+                start_of_month = ee.Date(date)
+                # The end date is exclusive, so we advance by 1 month.
+                end_of_month = start_of_month.advance(1, 'month')
+
+                # Filter the original collection to get images for the current month.
+                monthly_subset = collection.filterDate(start_of_month, end_of_month)
+
+                # Count the number of images in the monthly subset.
+                image_count = monthly_subset.size()
+
+                # Compute the mean. This is robust to outliers like clouds.
+                monthly_mean = monthly_subset.mean()
+
+                # Set essential properties on the resulting composite image.
+                # The timestamp is crucial for time-series analysis and charting.
+                # The image_count is useful metadata for quality assessment.
+                return monthly_mean.set({
+                    'system:time_start': start_of_month.millis(),
+                    'month': start_of_month.get('month'),
+                    'year': start_of_month.get('year'),
+                    'Date_Filter': start_of_month.format('YYYY-MM-dd'),
+                    'image_count': image_count
+                }).reproject(target_proj)
+
+            # Map the composite function over the list of month start dates.
+            monthly_composites_list = month_starts.map(create_monthly_composite)
+
+            # Convert the list of images into an ee.ImageCollection.
+            monthly_collection = ee.ImageCollection.fromImages(monthly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            # This prevents empty/masked images from being in the final collection.
+            final_collection = Sentinel1Collection(collection=monthly_collection.filter(ee.Filter.gt('image_count', 0)))
+            self._monthly_mean = final_collection
+        else:
+            pass
+
+        return self._monthly_mean
+    
+    @property
+    def monthly_sum_collection(self):
+        """Creates a monthly sum composite from a Sentinel1Collection image collection.
+
+        This function computes the sum 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.
+
+        The resulting images have a 'system:time_start' property set to the
+        first day of each month and an 'image_count' property indicating how
+        many images were used in the composite. Months with no images are
+        automatically excluded from the final collection.
+
+        NOTE: the day of month for the 'system:time_start' property is set to the earliest date of the first month observed and may not be the first day of the month.
+
+        Returns:
+            Sentinel1Collection: A new Sentinel1Collection object with monthly sum composites.
+        """
+        if self._monthly_sum is None:
+            collection = self.collection
+            target_proj = collection.first().projection()
+            # Get the start and end dates of the entire collection.
+            date_range = collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            original_start_date = ee.Date(date_range.get('min'))
+            end_date = ee.Date(date_range.get('max'))
+
+            start_year = original_start_date.get('year')
+            start_month = original_start_date.get('month')
+            start_date = ee.Date.fromYMD(start_year, start_month, 1)
+
+            # Calculate the total number of months in the date range.
+            # The .round() is important for ensuring we get an integer.
+            num_months = end_date.difference(start_date, 'month').round()
+
+            # Generate a list of starting dates for each month.
+            # This uses a sequence and advances the start date by 'i' months.
+            def get_month_start(i):
+                return start_date.advance(i, 'month')
+            
+            month_starts = ee.List.sequence(0, num_months).map(get_month_start)
+
+            # Define a function to map over the list of month start dates.
+            def create_monthly_composite(date):
+                # Cast the input to an ee.Date object.
+                start_of_month = ee.Date(date)
+                # The end date is exclusive, so we advance by 1 month.
+                end_of_month = start_of_month.advance(1, 'month')
+
+                # Filter the original collection to get images for the current month.
+                monthly_subset = collection.filterDate(start_of_month, end_of_month)
+
+                # Count the number of images in the monthly subset.
+                image_count = monthly_subset.size()
+
+                # Compute the sum. This is robust to outliers like clouds.
+                monthly_sum = monthly_subset.sum()
+
+                # Set essential properties on the resulting composite image.
+                # The timestamp is crucial for time-series analysis and charting.
+                # The image_count is useful metadata for quality assessment.
+                return monthly_sum.set({
+                    'system:time_start': start_of_month.millis(),
+                    'month': start_of_month.get('month'),
+                    'year': start_of_month.get('year'),
+                    'Date_Filter': start_of_month.format('YYYY-MM-dd'),
+                    'image_count': image_count
+                }).reproject(target_proj)
+
+            # Map the composite function over the list of month start dates.
+            monthly_composites_list = month_starts.map(create_monthly_composite)
+
+            # Convert the list of images into an ee.ImageCollection.
+            monthly_collection = ee.ImageCollection.fromImages(monthly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            # This prevents empty/masked images from being in the final collection.
+            final_collection = Sentinel1Collection(collection=monthly_collection.filter(ee.Filter.gt('image_count', 0)))
+            self._monthly_sum = final_collection
+        else:
+            pass
+
+        return self._monthly_sum
+    
+    @property
+    def monthly_max_collection(self):
+        """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.
+
+        The resulting images have a 'system:time_start' property set to the
+        first day of each month and an 'image_count' property indicating how
+        many images were used in the composite. Months with no images are
+        automatically excluded from the final collection.
+
+        NOTE: the day of month for the 'system:time_start' property is set to the earliest date of the first month observed and may not be the first day of the month.
+
+        Returns:
+            Sentinel1Collection: A new Sentinel1Collection object with monthly max composites.
+        """
+        if self._monthly_max is None:
+            collection = self.collection
+            target_proj = collection.first().projection()
+            # Get the start and end dates of the entire collection.
+            date_range = collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            original_start_date = ee.Date(date_range.get('min'))
+            end_date = ee.Date(date_range.get('max'))
+
+            start_year = original_start_date.get('year')
+            start_month = original_start_date.get('month')
+            start_date = ee.Date.fromYMD(start_year, start_month, 1)
+
+            # Calculate the total number of months in the date range.
+            # The .round() is important for ensuring we get an integer.
+            num_months = end_date.difference(start_date, 'month').round()
+
+            # Generate a list of starting dates for each month.
+            # This uses a sequence and advances the start date by 'i' months.
+            def get_month_start(i):
+                return start_date.advance(i, 'month')
+            
+            month_starts = ee.List.sequence(0, num_months).map(get_month_start)
+
+            # Define a function to map over the list of month start dates.
+            def create_monthly_composite(date):
+                # Cast the input to an ee.Date object.
+                start_of_month = ee.Date(date)
+                # The end date is exclusive, so we advance by 1 month.
+                end_of_month = start_of_month.advance(1, 'month')
+
+                # Filter the original collection to get images for the current month.
+                monthly_subset = collection.filterDate(start_of_month, end_of_month)
+
+                # Count the number of images in the monthly subset.
+                image_count = monthly_subset.size()
+
+                # Compute the max. This is robust to outliers like clouds.
+                monthly_max = monthly_subset.max()
+
+                # Set essential properties on the resulting composite image.
+                # The timestamp is crucial for time-series analysis and charting.
+                # The image_count is useful metadata for quality assessment.
+                return monthly_max.set({
+                    'system:time_start': start_of_month.millis(),
+                    'month': start_of_month.get('month'),
+                    'year': start_of_month.get('year'),
+                    'Date_Filter': start_of_month.format('YYYY-MM-dd'),
+                    'image_count': image_count
+                }).reproject(target_proj)
+
+            # Map the composite function over the list of month start dates.
+            monthly_composites_list = month_starts.map(create_monthly_composite)
+
+            # Convert the list of images into an ee.ImageCollection.
+            monthly_collection = ee.ImageCollection.fromImages(monthly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            # This prevents empty/masked images from being in the final collection.
+            final_collection = Sentinel1Collection(collection=monthly_collection.filter(ee.Filter.gt('image_count', 0)))
+            self._monthly_max = final_collection
+        else:
+            pass
+
+        return self._monthly_max
+    
+    @property
+    def monthly_min_collection(self):
+        """Creates a monthly min composite from a Sentinel1Collection image collection.
+
+        This function computes the min 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.
+
+        The resulting images have a 'system:time_start' property set to the
+        first day of each month and an 'image_count' property indicating how
+        many images were used in the composite. Months with no images are
+        automatically excluded from the final collection.
+
+        NOTE: the day of month for the 'system:time_start' property is set to the earliest date of the first month observed and may not be the first day of the month.
+
+        Returns:
+            Sentinel1Collection: A new Sentinel1Collection object with monthly min composites.
+        """
+        if self._monthly_min is None:
+            collection = self.collection
+            target_proj = collection.first().projection()
+            # Get the start and end dates of the entire collection.
+            date_range = collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            original_start_date = ee.Date(date_range.get('min'))
+            end_date = ee.Date(date_range.get('max'))
+
+            start_year = original_start_date.get('year')
+            start_month = original_start_date.get('month')
+            start_date = ee.Date.fromYMD(start_year, start_month, 1)
+
+            # Calculate the total number of months in the date range.
+            # The .round() is important for ensuring we get an integer.
+            num_months = end_date.difference(start_date, 'month').round()
+
+            # Generate a list of starting dates for each month.
+            # This uses a sequence and advances the start date by 'i' months.
+            def get_month_start(i):
+                return start_date.advance(i, 'month')
+            
+            month_starts = ee.List.sequence(0, num_months).map(get_month_start)
+
+            # Define a function to map over the list of month start dates.
+            def create_monthly_composite(date):
+                # Cast the input to an ee.Date object.
+                start_of_month = ee.Date(date)
+                # The end date is exclusive, so we advance by 1 month.
+                end_of_month = start_of_month.advance(1, 'month')
+
+                # Filter the original collection to get images for the current month.
+                monthly_subset = collection.filterDate(start_of_month, end_of_month)
+
+                # Count the number of images in the monthly subset.
+                image_count = monthly_subset.size()
+
+                # Compute the min. This is robust to outliers like clouds.
+                monthly_min = monthly_subset.min()
+
+                # Set essential properties on the resulting composite image.
+                # The timestamp is crucial for time-series analysis and charting.
+                # The image_count is useful metadata for quality assessment.
+                return monthly_min.set({
+                    'system:time_start': start_of_month.millis(),
+                    'month': start_of_month.get('month'),
+                    'year': start_of_month.get('year'),
+                    'Date_Filter': start_of_month.format('YYYY-MM-dd'),
+                    'image_count': image_count
+                }).reproject(target_proj)
+
+            # Map the composite function over the list of month start dates.
+            monthly_composites_list = month_starts.map(create_monthly_composite)
+
+            # Convert the list of images into an ee.ImageCollection.
+            monthly_collection = ee.ImageCollection.fromImages(monthly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            # This prevents empty/masked images from being in the final collection.
+            final_collection = Sentinel1Collection(collection=monthly_collection.filter(ee.Filter.gt('image_count', 0)))
+            self._monthly_min = final_collection
+        else:
+            pass
+
+        return self._monthly_min
+    
+    def anomaly(self, 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.
+
+        Args:
+            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:
+            Sentinel1Collection: A Sentinel1Collection where each image represents the anomaly (deviation from
+                        the mean) for the chosen band. The output images retain the same band name.
+        """
+        if self.collection.size().eq(0).getInfo():
+            raise ValueError("The collection is empty.")
+        if band_name is None:
+            first_image = self.collection.first()
+            band_names = first_image.bandNames()
+            if band_names.size().getInfo() == 0:
+                raise ValueError("No bands available in the collection.")
+            elif band_names.size().getInfo() > 1:
+                band_name = band_names.get(0).getInfo()
+                print("Multiple bands available, will be using the first band in the collection for anomaly calculation. Please specify a band name if you wish to use a different band.")
+            else:
+                band_name = band_names.get(0).getInfo()
+
+        col = self.collection.map(lambda image: Sentinel1Collection.anomaly_fn(image, geometry=geometry, band_name=band_name, anomaly_band_name=anomaly_band_name, replace=replace, scale=scale))
+        return Sentinel1Collection(collection=col)
 
     def binary_mask(self, threshold=None, band_name=None):
         """
@@ -1734,24 +2289,30 @@ class Sentinel1Collection:
             ValueError: If input parameters are invalid.
             TypeError: If geometries input type is unsupported.
         """
+        # Create a local reference to the collection object to allow for modifications (like band selection) without altering the original instance
         img_collection_obj = self
+
+        # If a specific band is requested, select only that band
         if band:
             img_collection_obj = Sentinel1Collection(collection=img_collection_obj.collection.select(band))
         else: 
+            # If no band is specified, default to using the first band of the first image in the collection
             first_image = img_collection_obj.image_grab(0)
             first_band = first_image.bandNames().get(0)
             img_collection_obj = Sentinel1Collection(collection=img_collection_obj.collection.select([first_band]))
-        # Filter collection by dates if provided
+        
+        # If a list of dates is provided, filter the collection to include only images matching those dates
         if dates:
             img_collection_obj = Sentinel1Collection(
                 collection=self.collection.filter(ee.Filter.inList('Date_Filter', dates))
             )
 
-        # Initialize variables
+        # Initialize variables to hold the standardized feature collection and coordinates
         features = None
         validated_coordinates = [] 
         
-        # Function to standardize feature names if no names are provided
+        # Define a helper function to ensure every feature has a standardized 'geo_name' property
+        # This handles features that might have different existing name properties or none at all
         def set_standard_name(feature):
             has_geo_name = feature.get('geo_name')
             has_name = feature.get('name')
@@ -1762,33 +2323,38 @@ class Sentinel1Collection:
                 ee.Algorithms.If(has_index, has_index, 'unnamed_geometry')))
             return feature.set({'geo_name': new_name})
 
+        # Handle input: FeatureCollection or single Feature
         if isinstance(geometries, (ee.FeatureCollection, ee.Feature)):
             features = ee.FeatureCollection(geometries)
             if geometry_names:
                  print("Warning: 'geometry_names' are ignored when the input is an ee.Feature or ee.FeatureCollection.")
 
+        # Handle input: Single ee.Geometry
         elif isinstance(geometries, ee.Geometry):
              name = geometry_names[0] if (geometry_names and geometry_names[0]) else 'unnamed_geometry'
              features = ee.FeatureCollection([ee.Feature(geometries).set('geo_name', name)])
 
+        # Handle input: List (could be coordinates or ee.Geometry objects)
         elif isinstance(geometries, list):
             if not geometries: # Handle empty list case
                 raise ValueError("'geometries' list cannot be empty.")
             
-            # Case: List of coordinates
+            # Case: List of tuples (coordinates)
             if all(isinstance(i, tuple) for i in geometries):
                 validated_coordinates = geometries
+                # Generate default names if none provided
                 if geometry_names is None:
                     geometry_names = [f"Location_{i+1}" for i in range(len(validated_coordinates))]
                 elif len(geometry_names) != len(validated_coordinates):
                      raise ValueError("geometry_names must have the same length as the coordinates list.")
+                # Create features with buffers around the coordinates
                 points = [
                     ee.Feature(ee.Geometry.Point(coord).buffer(buffer_size), {'geo_name': str(name)})
                     for coord, name in zip(validated_coordinates, geometry_names)
                 ]
                 features = ee.FeatureCollection(points)
             
-            # Case: List of Geometries
+            # Case: List of ee.Geometry objects
             elif all(isinstance(i, ee.Geometry) for i in geometries):
                 if geometry_names is None:
                     geometry_names = [f"Geometry_{i+1}" for i in range(len(geometries))]
@@ -1803,6 +2369,7 @@ class Sentinel1Collection:
             else:
                 raise TypeError("Input list must be a list of (lon, lat) tuples OR a list of ee.Geometry objects.")
 
+        # Handle input: Single tuple (coordinate)
         elif isinstance(geometries, tuple) and len(geometries) == 2:
             name = geometry_names[0] if geometry_names else 'Location_1'
             features = ee.FeatureCollection([
@@ -1811,39 +2378,48 @@ class Sentinel1Collection:
         else:
             raise TypeError("Unsupported type for 'geometries'.")
         
+        # Apply the naming standardization to the created FeatureCollection
         features = features.map(set_standard_name)
 
+        # Dynamically retrieve the Earth Engine reducer based on the string name provided
         try:
             reducer = getattr(ee.Reducer, reducer_type)()
         except AttributeError:
             raise ValueError(f"Unknown reducer_type: '{reducer_type}'.")
 
+        # Define the function to map over the image collection
         def calculate_stats_for_image(image):
             image_date = image.get('Date_Filter')
+            # Calculate statistics for all geometries in 'features' for this specific image
             stats_fc = image.reduceRegions(
                 collection=features, reducer=reducer, scale=scale, tileScale=tileScale
             )
 
+            # Helper to ensure the result has the reducer property, even if masked
+            # If the property is missing (e.g., all pixels masked), set it to a sentinel value (-9999)
             def guarantee_reducer_property(f):
                 has_property = f.propertyNames().contains(reducer_type)
                 return ee.Algorithms.If(has_property, f, f.set(reducer_type, -9999))
+            
+            # Apply the guarantee check
             fixed_stats_fc = stats_fc.map(guarantee_reducer_property)
 
+            # Attach the image date to every feature in the result so we know which image it came from
             return fixed_stats_fc.map(lambda f: f.set('image_date', image_date))
 
+        # Map the calculation over the image collection and flatten the resulting FeatureCollections into one
         results_fc = ee.FeatureCollection(img_collection_obj.collection.map(calculate_stats_for_image)).flatten()
+        
+        # Convert the Earth Engine FeatureCollection to a pandas DataFrame (client-side operation)
         df = Sentinel1Collection.ee_to_df(results_fc, remove_geom=True)
 
-        # Checking for issues
+        # Check for empty results or missing columns
         if df.empty: 
-            # print("No results found for the given parameters. Check if the geometries intersect with the images, if the dates filter is too restrictive, or if the provided bands are empty.")
-            # return df
             raise ValueError("No results found for the given parameters. Check if the geometries intersect with the images, if the dates filter is too restrictive, or if the provided bands are empty.")
         if reducer_type not in df.columns:
             print(f"Warning: Reducer '{reducer_type}' not found in results.")
-            # return df
 
-        # Get the number of rows before dropping nulls for a helpful message
+        # Filter out the sentinel values (-9999) which indicate failed reductions/masked pixels
         initial_rows = len(df)
         df.dropna(subset=[reducer_type], inplace=True)
         df = df[df[reducer_type] != -9999]
@@ -1851,9 +2427,18 @@ class Sentinel1Collection:
         if dropped_rows > 0:
             print(f"Warning: Discarded {dropped_rows} results due to failed reductions (e.g., no valid pixels in geometry).")
 
-        # Reshape DataFrame to have dates as index and geometry names as columns
+        # Pivot the DataFrame so that each row represents a date and each column represents a geometry location
         pivot_df = df.pivot(index='image_date', columns='geo_name', values=reducer_type)
+        # Rename the column headers (geometry names) to include the reducer type 
+        pivot_df.columns = [f"{col}_{reducer_type}" for col in pivot_df.columns]
+        # Rename the index axis to 'Date' so it is correctly labeled when moved to a column later
         pivot_df.index.name = 'Date'
+        # Remove the name of the columns axis (which defaults to 'geo_name') so it doesn't appear as a confusing label in the final output
+        pivot_df.columns.name = None
+        # Reset the index to move the 'Date' index into a regular column and create a standard numerical index (0, 1, 2...)
+        pivot_df = pivot_df.reset_index(drop=False)
+
+        # If a file path is provided, save the resulting DataFrame to CSV
         if file_path:
             # Check if file_path ends with .csv and remove it if so for consistency
             if file_path.endswith('.csv'):