RadGEEToolbox 1.7.2__py3-none-any.whl → 1.7.4__py3-none-any.whl

RadGEEToolbox/GenericCollection.py

@@ -1,6 +1,7 @@
 import ee
 import pandas as pd
 import numpy as np
+import warnings
 
 
 class GenericCollection:
@@ -81,6 +82,11 @@ class GenericCollection:
         self._monthly_sum = None
         self._monthly_max = None
         self._monthly_min = None
+        self._yearly_median = None
+        self._yearly_mean = None
+        self._yearly_max = None
+        self._yearly_min = None
+        self._yearly_sum = None
         self._mean = None
         self._max = None
         self._min = None
@@ -88,6 +94,14 @@ class GenericCollection:
         self._PixelAreaSumCollection = None
         self._daily_aggregate_collection = None
 
+    def __call__(self):
+        """
+        Allows the object to be called as a function, returning itself. 
+        This enables property-like methods to be accessed with or without parentheses 
+        (e.g., .mosaicByDate or .mosaicByDate()).
+        """
+        return self
+
     @staticmethod
     def image_dater(image):
         """
@@ -163,7 +177,7 @@ class GenericCollection:
         if replace:
             return anomaly_image.copyProperties(image).set('system:time_start', image.get('system:time_start'))
         else:
-            return image.addBands(anomaly_image, overwrite=True).copyProperties(image)
+            return image.addBands(anomaly_image, overwrite=True).copyProperties(image).set('system:time_start', image.get('system:time_start'))
 
     @staticmethod
     def mask_via_band_fn(image, band_to_mask, band_for_mask, threshold, mask_above=False, add_band_to_original_image=False):
@@ -191,7 +205,7 @@ class GenericCollection:
         if add_band_to_original_image:
             return image.addBands(band_to_mask_image.updateMask(mask).rename(band_to_mask), overwrite=True)
         else:
-            return ee.Image(band_to_mask_image.updateMask(mask).rename(band_to_mask).copyProperties(image))
+            return ee.Image(band_to_mask_image.updateMask(mask).rename(band_to_mask).copyProperties(image).set('system:time_start', image.get('system:time_start')))
     
     @staticmethod
     def mask_via_singleband_image_fn(image_to_mask, image_for_mask, threshold, band_name_to_mask=None, band_name_for_mask=None, mask_above=True):
@@ -227,7 +241,7 @@ class GenericCollection:
             mask = band_for_mask_image.gt(threshold)
         else:
             mask = band_for_mask_image.lt(threshold)
-        return band_to_mask_image.updateMask(mask).rename(band_to_mask).copyProperties(image_to_mask)
+        return band_to_mask_image.updateMask(mask).rename(band_to_mask).copyProperties(image_to_mask).set('system:time_start', image_to_mask.get('system:time_start'))
     
     @staticmethod
     def band_rename_fn(image, current_band_name, new_band_name):
@@ -263,10 +277,10 @@ class GenericCollection:
             return img.rename(ee.List(new_names))
 
         out = ee.Image(ee.Algorithms.If(has_band, _rename(), img))
-        return out.copyProperties(img)
+        return out.copyProperties(img).set('system:time_start', img.get('system:time_start'))
 
     @staticmethod
-    def PixelAreaSum(
+    def pixelAreaSum(
         image, band_name, geometry, threshold=-1, scale=30, maxPixels=1e12
     ):
         """
@@ -326,7 +340,19 @@ class GenericCollection:
         final_image = ee.Image(bands.iterate(calculate_and_set_area, image))
         return final_image #.set('system:time_start', image.get('system:time_start'))
 
-    def PixelAreaSumCollection(
+    @staticmethod
+    def PixelAreaSum(
+        image, band_name, geometry, threshold=-1, scale=30, maxPixels=1e12
+    ):
+        warnings.warn(
+            "The `PixelAreaSum` static method is deprecated and will be removed in future versions. Please use the `pixelAreaSum` static method instead.",
+            DeprecationWarning,
+            stacklevel=2)
+        return GenericCollection.pixelAreaSum(
+            image, band_name, geometry, threshold, scale, maxPixels
+        )
+
+    def pixelAreaSumCollection(
         self, band_name, geometry, threshold=-1, scale=30, maxPixels=1e12, output_type='ImageCollection', area_data_export_path=None
     ):
         """
@@ -353,7 +379,7 @@ class GenericCollection:
             collection = self.collection
             # Area calculation for each image in the collection, using the PixelAreaSum function
             AreaCollection = collection.map(
-                lambda image: GenericCollection.PixelAreaSum(
+                lambda image: GenericCollection.pixelAreaSum(
                     image,
                     band_name=band_name,
                     geometry=geometry,
@@ -369,17 +395,28 @@ class GenericCollection:
 
         # If an export path is provided, the area data will be exported to a CSV file
         if area_data_export_path:
-            GenericCollection(collection=self._PixelAreaSumCollection).ExportProperties(property_names=prop_names, file_path=area_data_export_path+'.csv')
+            GenericCollection(collection=self._PixelAreaSumCollection).exportProperties(property_names=prop_names, 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' or output_type == 'ee.ImageCollection':
             return self._PixelAreaSumCollection
         elif output_type == 'GenericCollection':
             return GenericCollection(collection=self._PixelAreaSumCollection)
         elif output_type == 'DataFrame' or output_type == 'Pandas' or output_type == 'pd' or output_type == 'dataframe' or output_type == 'df':
-            return GenericCollection(collection=self._PixelAreaSumCollection).ExportProperties(property_names=prop_names)
+            return GenericCollection(collection=self._PixelAreaSumCollection).exportProperties(property_names=prop_names)
         else:
             raise ValueError("Incorrect `output_type`. The `output_type` argument must be one of the following: 'ImageCollection', 'ee.ImageCollection', 'GenericCollection', 'DataFrame', 'Pandas', 'pd', 'dataframe', or 'df'.")
 
+    def PixelAreaSumCollection(
+        self, band_name, geometry, threshold=-1, scale=30, maxPixels=1e12, output_type='ImageCollection', area_data_export_path=None
+    ):
+        warnings.warn(
+            "The `PixelAreaSumCollection` method is deprecated and will be removed in future versions. Please use the `pixelAreaSumCollection` method instead.",
+            DeprecationWarning,
+            stacklevel=2)
+        return self.pixelAreaSumCollection(
+            band_name, geometry, threshold, scale, maxPixels, output_type, area_data_export_path
+        )
+
     @staticmethod
     def add_month_property_fn(image):
         """
@@ -539,7 +576,7 @@ class GenericCollection:
         
         return GenericCollection(collection=distinct_col)
 
-    def ExportProperties(self, property_names, file_path=None):
+    def exportProperties(self, 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.
 
@@ -594,6 +631,13 @@ class GenericCollection:
             print(f"Properties saved to {file_path}")
             
         return df
+    
+    def ExportProperties(self, property_names, file_path=None):
+        warnings.warn(
+            "The `ExportProperties` method is deprecated and will be removed in future versions. Please use the `exportProperties` method instead.",
+            DeprecationWarning,
+            stacklevel=2)
+        return self.exportProperties(property_names, file_path)
 
     def get_generic_collection(self):
         """
@@ -959,6 +1003,391 @@ class GenericCollection:
 
         return self._monthly_sum
     
+    def yearly_mean_collection(self, start_month=1, end_month=12):
+        """
+        Creates a yearly mean composite from the collection, with optional monthly filtering.
+
+        This function computes the mean for each year within the collection's date range.
+        You can specify a range of months (e.g., start_month=6, end_month=10 for June-October)
+        to calculate the mean only using imagery from that specific season for each year.
+
+        The resulting images have 'system:time_start', 'year', 'image_count', 'season_start',
+        'season_end', and 'Date_Filter' properties. Years with no images (after filtering) are excluded.
+
+        Args:
+            start_month (int): The starting month (1-12) for the filter. Defaults to 1 (January).
+            end_month (int): The ending month (1-12) for the filter. Defaults to 12 (December).
+
+        Returns:
+            Object: A new instance of the same class (e.g., GenericCollection) containing the yearly mean composites.
+        """
+        if self._yearly_mean is None:
+
+            date_range = self.collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            start_date_full = ee.Date(date_range.get('min'))
+            end_date_full = ee.Date(date_range.get('max'))
+            
+            start_year = start_date_full.get('year')
+            end_year = end_date_full.get('year')
+
+            if start_month != 1 or end_month != 12:
+                processing_collection = self.collection.filter(ee.Filter.calendarRange(start_month, end_month, 'month'))
+            else:
+                processing_collection = self.collection
+
+            # Capture projection from the first image to restore it after reduction
+            target_proj = self.collection.first().projection()
+
+            years = ee.List.sequence(start_year, end_year)
+
+            def create_yearly_composite(year):
+                year = ee.Number(year)
+                # Define the full calendar year range
+                start_of_year = ee.Date.fromYMD(year, 1, 1)
+                end_of_year = start_of_year.advance(1, 'year')
+
+                yearly_subset = processing_collection.filterDate(start_of_year, end_of_year)
+
+                # Calculate stats
+                image_count = yearly_subset.size()
+                yearly_reduction = yearly_subset.mean()
+
+                # Define the timestamp for the composite.
+                # We use the start_month of that year to accurately reflect the data start time.
+                composite_date = ee.Date.fromYMD(year, start_month, 1)
+
+                return yearly_reduction.set({
+                    'system:time_start': composite_date.millis(),
+                    'year': year,
+                    'month': start_month,  
+                    'Date_Filter': composite_date.format('YYYY-MM-dd'), 
+                    'image_count': image_count,
+                    'season_start': start_month,
+                    'season_end': end_month
+                }).reproject(target_proj)
+
+            # Map the function over the years list
+            yearly_composites_list = years.map(create_yearly_composite)
+            
+            # Convert to Collection
+            yearly_collection = ee.ImageCollection.fromImages(yearly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            final_collection = yearly_collection.filter(ee.Filter.gt('image_count', 0))
+
+            self._yearly_mean = GenericCollection(collection=final_collection)
+        else: 
+            pass
+        return self._yearly_mean
+
+    def yearly_median_collection(self, start_month=1, end_month=12):
+        """
+        Creates a yearly median composite from the collection, with optional monthly filtering.
+
+        This function computes the median for each year within the collection's date range.
+        You can specify a range of months (e.g., start_month=6, end_month=10 for June-October)
+        to calculate the median only using imagery from that specific season for each year.
+        The resulting images have 'system:time_start', 'year', 'image_count', 'season_start',
+        'season_end', and 'Date_Filter' properties. Years with no images (after filtering) are excluded.
+
+        Args:
+            start_month (int): The starting month (1-12) for the filter. Defaults to 1 (January).
+            end_month (int): The ending month (1-12) for the filter. Defaults to 12 (December).
+
+        Returns:
+            Object: A new instance of the same class (e.g., GenericCollection) containing the yearly median composites.
+        """
+        if self._yearly_median is None:
+
+            date_range = self.collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            start_date_full = ee.Date(date_range.get('min'))
+            end_date_full = ee.Date(date_range.get('max'))
+            
+            start_year = start_date_full.get('year')
+            end_year = end_date_full.get('year')
+
+            if start_month != 1 or end_month != 12:
+                processing_collection = self.collection.filter(ee.Filter.calendarRange(start_month, end_month, 'month'))
+            else:
+                processing_collection = self.collection
+
+            # Capture projection from the first image to restore it after reduction
+            target_proj = self.collection.first().projection()
+
+            years = ee.List.sequence(start_year, end_year)
+
+            def create_yearly_composite(year):
+                year = ee.Number(year)
+                # Define the full calendar year range
+                start_of_year = ee.Date.fromYMD(year, 1, 1)
+                end_of_year = start_of_year.advance(1, 'year')
+
+                # Filter to the specific year using the PRE-FILTERED seasonal collection
+                yearly_subset = processing_collection.filterDate(start_of_year, end_of_year)
+
+                # Calculate stats
+                image_count = yearly_subset.size()
+                yearly_reduction = yearly_subset.median()
+
+                # Define the timestamp for the composite.
+                # We use the start_month of that year to accurately reflect the data start time.
+                composite_date = ee.Date.fromYMD(year, start_month, 1)
+
+                return yearly_reduction.set({
+                    'system:time_start': composite_date.millis(),
+                    'year': year,
+                    'month': start_month,  
+                    'Date_Filter': composite_date.format('YYYY-MM-dd'), 
+                    'image_count': image_count,
+                    'season_start': start_month,
+                    'season_end': end_month
+                }).reproject(target_proj)
+
+            # Map the function over the years list
+            yearly_composites_list = years.map(create_yearly_composite)
+            
+            # Convert to Collection
+            yearly_collection = ee.ImageCollection.fromImages(yearly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            final_collection = yearly_collection.filter(ee.Filter.gt('image_count', 0))
+
+            self._yearly_median = GenericCollection(collection=final_collection)
+        else: 
+            pass
+        return self._yearly_median
+
+    def yearly_max_collection(self, start_month=1, end_month=12):
+        """
+        Creates a yearly max composite from the collection, with optional monthly filtering.
+
+        This function computes the max for each year within the collection's date range.
+        You can specify a range of months (e.g., start_month=6, end_month=10 for June-October)
+        to calculate the max only using imagery from that specific season for each year.
+        The resulting images have 'system:time_start', 'year', 'image_count', 'season_start',
+        'season_end', and 'Date_Filter' properties. Years with no images (after filtering) are excluded.
+
+        Args:
+            start_month (int): The starting month (1-12) for the filter. Defaults to 1 (January).
+            end_month (int): The ending month (1-12) for the filter. Defaults to 12 (December).
+
+        Returns:
+            Object: A new instance of the same class (e.g., GenericCollection) containing the yearly max composites.
+        """
+        if self._yearly_max is None:
+
+            date_range = self.collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            start_date_full = ee.Date(date_range.get('min'))
+            end_date_full = ee.Date(date_range.get('max'))
+            
+            start_year = start_date_full.get('year')
+            end_year = end_date_full.get('year')
+
+            if start_month != 1 or end_month != 12:
+                processing_collection = self.collection.filter(ee.Filter.calendarRange(start_month, end_month, 'month'))
+            else:
+                processing_collection = self.collection
+
+            # Capture projection from the first image to restore it after reduction
+            target_proj = self.collection.first().projection()
+
+            years = ee.List.sequence(start_year, end_year)
+
+            def create_yearly_composite(year):
+                year = ee.Number(year)
+                # Define the full calendar year range
+                start_of_year = ee.Date.fromYMD(year, 1, 1)
+                end_of_year = start_of_year.advance(1, 'year')
+
+                # Filter to the specific year using the PRE-FILTERED seasonal collection
+                yearly_subset = processing_collection.filterDate(start_of_year, end_of_year)
+
+                # Calculate stats
+                image_count = yearly_subset.size()
+                yearly_reduction = yearly_subset.max()
+
+                # Define the timestamp for the composite.
+                # We use the start_month of that year to accurately reflect the data start time.
+                composite_date = ee.Date.fromYMD(year, start_month, 1)
+
+                return yearly_reduction.set({
+                    'system:time_start': composite_date.millis(),
+                    'year': year,
+                    'month': start_month,  
+                    'Date_Filter': composite_date.format('YYYY-MM-dd'), 
+                    'image_count': image_count,
+                    'season_start': start_month,
+                    'season_end': end_month
+                }).reproject(target_proj)
+
+            # Map the function over the years list
+            yearly_composites_list = years.map(create_yearly_composite)
+            
+            # Convert to Collection
+            yearly_collection = ee.ImageCollection.fromImages(yearly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            final_collection = yearly_collection.filter(ee.Filter.gt('image_count', 0))
+
+            self._yearly_max = GenericCollection(collection=final_collection)
+        else: 
+            pass
+        return self._yearly_max
+    
+    def yearly_min_collection(self, start_month=1, end_month=12):
+        """
+        Creates a yearly min composite from the collection, with optional monthly filtering.
+
+        This function computes the min for each year within the collection's date range.
+        You can specify a range of months (e.g., start_month=6, end_month=10 for June-October)
+        to calculate the min only using imagery from that specific season for each year.
+        The resulting images have 'system:time_start', 'year', 'image_count', 'season_start',
+        'season_end', and 'Date_Filter' properties. Years with no images (after filtering) are excluded.
+
+        Args:
+            start_month (int): The starting month (1-12) for the filter. Defaults to 1 (January).
+            end_month (int): The ending month (1-12) for the filter. Defaults to 12 (December).
+
+        Returns:
+            Object: A new instance of the same class (e.g., GenericCollection) containing the yearly min composites.
+        """
+        if self._yearly_min is None:
+
+            date_range = self.collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            start_date_full = ee.Date(date_range.get('min'))
+            end_date_full = ee.Date(date_range.get('max'))
+            
+            start_year = start_date_full.get('year')
+            end_year = end_date_full.get('year')
+
+            if start_month != 1 or end_month != 12:
+                processing_collection = self.collection.filter(ee.Filter.calendarRange(start_month, end_month, 'month'))
+            else:
+                processing_collection = self.collection
+
+            # Capture projection from the first image to restore it after reduction
+            target_proj = self.collection.first().projection()
+
+            years = ee.List.sequence(start_year, end_year)
+
+            def create_yearly_composite(year):
+                year = ee.Number(year)
+                # Define the full calendar year range
+                start_of_year = ee.Date.fromYMD(year, 1, 1)
+                end_of_year = start_of_year.advance(1, 'year')
+
+                # Filter to the specific year using the PRE-FILTERED seasonal collection
+                yearly_subset = processing_collection.filterDate(start_of_year, end_of_year)
+
+                # Calculate stats
+                image_count = yearly_subset.size()
+                yearly_reduction = yearly_subset.min()
+
+                # Define the timestamp for the composite.
+                # We use the start_month of that year to accurately reflect the data start time.
+                composite_date = ee.Date.fromYMD(year, start_month, 1)
+
+                return yearly_reduction.set({
+                    'system:time_start': composite_date.millis(),
+                    'year': year,
+                    'month': start_month,  
+                    'Date_Filter': composite_date.format('YYYY-MM-dd'), 
+                    'image_count': image_count,
+                    'season_start': start_month,
+                    'season_end': end_month
+                }).reproject(target_proj)
+
+            # Map the function over the years list
+            yearly_composites_list = years.map(create_yearly_composite)
+            
+            # Convert to Collection
+            yearly_collection = ee.ImageCollection.fromImages(yearly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            final_collection = yearly_collection.filter(ee.Filter.gt('image_count', 0))
+
+            self._yearly_min = GenericCollection(collection=final_collection)
+        else: 
+            pass
+        return self._yearly_min
+
+    def yearly_sum_collection(self, start_month=1, end_month=12):
+        """
+        Creates a yearly sum composite from the collection, with optional monthly filtering.
+
+        This function computes the sum for each year within the collection's date range.
+        You can specify a range of months (e.g., start_month=6, end_month=10 for June-October)
+        to calculate the sum only using imagery from that specific season for each year.
+        The resulting images have 'system:time_start', 'year', 'image_count', 'season_start',
+        'season_end', and 'Date_Filter' properties. Years with no images (after filtering) are excluded.
+
+        Args:
+            start_month (int): The starting month (1-12) for the filter. Defaults to 1 (January).
+            end_month (int): The ending month (1-12) for the filter. Defaults to 12 (December).
+
+        Returns:
+            Object: A new instance of the same class (e.g., GenericCollection) containing the yearly sum composites.
+        """
+        if self._yearly_sum is None:
+
+            date_range = self.collection.reduceColumns(ee.Reducer.minMax(), ["system:time_start"])
+            start_date_full = ee.Date(date_range.get('min'))
+            end_date_full = ee.Date(date_range.get('max'))
+            
+            start_year = start_date_full.get('year')
+            end_year = end_date_full.get('year')
+
+            if start_month != 1 or end_month != 12:
+                processing_collection = self.collection.filter(ee.Filter.calendarRange(start_month, end_month, 'month'))
+            else:
+                processing_collection = self.collection
+
+            # Capture projection from the first image to restore it after reduction
+            target_proj = self.collection.first().projection()
+
+            years = ee.List.sequence(start_year, end_year)
+
+            def create_yearly_composite(year):
+                year = ee.Number(year)
+                # Define the full calendar year range
+                start_of_year = ee.Date.fromYMD(year, 1, 1)
+                end_of_year = start_of_year.advance(1, 'year')
+
+                # Filter to the specific year using the PRE-FILTERED seasonal collection
+                yearly_subset = processing_collection.filterDate(start_of_year, end_of_year)
+
+                # Calculate stats
+                image_count = yearly_subset.size()
+                yearly_reduction = yearly_subset.sum()
+
+                # Define the timestamp for the composite.
+                # We use the start_month of that year to accurately reflect the data start time.
+                composite_date = ee.Date.fromYMD(year, start_month, 1)
+
+                return yearly_reduction.set({
+                    'system:time_start': composite_date.millis(),
+                    'year': year,
+                    'month': start_month,  
+                    'Date_Filter': composite_date.format('YYYY-MM-dd'), 
+                    'image_count': image_count,
+                    'season_start': start_month,
+                    'season_end': end_month
+                }).reproject(target_proj)
+
+            # Map the function over the years list
+            yearly_composites_list = years.map(create_yearly_composite)
+            
+            # Convert to Collection
+            yearly_collection = ee.ImageCollection.fromImages(yearly_composites_list)
+
+            # Filter out any composites that were created from zero images.
+            final_collection = yearly_collection.filter(ee.Filter.gt('image_count', 0))
+
+            self._yearly_sum = GenericCollection(collection=final_collection)
+        else: 
+            pass
+        return self._yearly_sum
+
     @property
     def monthly_max_collection(self):
         """Creates a monthly max composite from a GenericCollection image collection.
@@ -1523,7 +1952,7 @@ class GenericCollection:
             new_band_names = band_names.map(lambda b: ee.String(b).cat('_mm'))
             
             converted_image = image.multiply(10800).rename(new_band_names)
-            return converted_image.copyProperties(image, image.propertyNames())
+            return converted_image.copyProperties(image, image.propertyNames()).set('system:time_start', image.get('system:time_start'))
 
         # Map the function over the entire collection
         converted_collection = self.collection.map(convert_to_mm)
@@ -1537,6 +1966,236 @@ class GenericCollection:
             _dates_list=self._dates_list # Pass along the cached dates!
         )
 
+    def mann_kendall_trend(self, 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.
+
+        Args: 
+            image_collection (GenericCollection 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:
+            ee.Image: An image with the following bands: 's_statistic', 'variance', 'z_score', 'confidence', and 'slope'.
+        """
+        ########## PART 1 - S-VALUE CALCULATION ##########
+        ##### https://vsp.pnnl.gov/help/vsample/design_trend_mann_kendall.htm #####
+        image_collection = self
+        if isinstance(image_collection, GenericCollection):
+            image_collection = image_collection.collection
+        elif isinstance(image_collection, ee.ImageCollection):
+            pass
+        else:
+            raise ValueError(f'The chosen `image_collection`: {image_collection} is not a valid GenericCollection or ee.ImageCollection object.')
+        
+        if target_band is None:
+            raise ValueError('The `target_band` parameter must be specified.')
+        if not isinstance(target_band, str):
+            raise ValueError(f'The chosen `target_band`: {target_band} is not a valid string.')
+
+        if geometry is not None and not isinstance(geometry, ee.Geometry):
+            raise ValueError(f'The chosen `geometry`: {geometry} is not a valid ee.Geometry object.')
+        # define the join, which will join all images newer than the current image
+        # use system:time_start if the image does not have a Date_Filter property
+        if join_method == 'system:time_start':
+            # get all images where the leftField value is less than (before) the rightField value
+            time_filter = ee.Filter.lessThan(leftField='system:time_start', 
+                                            rightField='system:time_start')
+        elif join_method == 'Date_Filter':
+            # get all images where the leftField value is less than (before) the rightField value
+            time_filter = ee.Filter.lessThan(leftField='Date_Filter', 
+                                            rightField='Date_Filter')
+        else:
+            raise ValueError(f'The chosen `join_method`: {join_method} does not match the options of "system:time_start" or "Date_Filter".')
+        
+        native_projection = image_collection.first().select(target_band).projection()
+
+        # for any matches during a join, set image as a property key called 'future_image'
+        join = ee.Join.saveAll(matchesKey='future_image')
+
+        # apply the join on the input collection 
+        # joining all images newer than the current image with the current image
+        joined_collection = ee.ImageCollection(join.apply(primary=image_collection, 
+                                                secondary=image_collection, condition=time_filter))
+        
+        # defining a collection to calculate the partial S value for each match in the join
+        # e.g. t4-t1, t3-t1, t2-1 if there are 4 images
+        def calculate_partial_s(current_image):
+            # select the target band for arithmetic
+            current_val = current_image.select(target_band)
+            # get the joined images from the current image properties and cast the joined images as a list
+            future_image_list = ee.List(current_image.get('future_image'))
+            # convert the joined list to an image collection
+            future_image_collection = ee.ImageCollection(future_image_list)
+
+            # define a function that will calculate the difference between the joined images and the current image, 
+            # then calculate the partial S sign based on the value of the difference calculation
+            def get_sign(future_image):
+                # select the target band for arithmetic from the future image
+                future_val = future_image.select(target_band)
+                # calculate the difference, i.e. t2-t1
+                difference = future_val.subtract(current_val)
+                # determine the sign of the difference value (1 if diff > 0, 0 if 0, and -1 if diff < 0)
+                # use .unmask(0) to set any masked pixels as 0 to avoid 
+                
+                sign = difference.signum().unmask(0)
+                
+                return sign
+            
+            # map the get_sign() function along the future image col 
+            # then sum the values for each pixel to get the partial S value
+            return future_image_collection.map(get_sign).sum()
+
+        # calculate the partial s value for each image in the joined/input image collection
+        partial_s_col = joined_collection.map(calculate_partial_s)
+
+        # convert the image collection to an image of s_statistic values per pixel
+        # where the s_statistic is the sum of partial s values
+        # renaming the band as 's_statistic' for later usage
+        final_s_image = partial_s_col.sum().rename('s_statistic').setDefaultProjection(native_projection)
+
+
+        ########## PART 2 - VARIANCE and Z-SCORE ##########
+        # to calculate variance we need to know how many pixels were involved in the partial_s calculations per pixel
+        # we do this by using count() and turn the value to a float for later arithmetic
+        n = image_collection.select(target_band).count().toFloat()
+
+        ##### VARIANCE CALCULATION #####
+        # as we are using floating point values with high precision, it is HIGHLY 
+        # unlikely that there will be multiple pixel values with the same value.
+        # Thus, we opt to use the simplified variance calculation approach as the
+        # impacts to the output value are negligible and the processing benefits are HUGE
+        # variance = (n * (n - 1) * (2n + 5)) / 18
+        var_s = n.multiply(n.subtract(1))\
+                .multiply(n.multiply(2).add(5))\
+                .divide(18).rename('variance')
+        
+        z_score = ee.Image().expression(
+                    """
+                    (s > 0) ? (s - 1) / sqrt(var) :
+                    (s < 0) ? (s + 1) / sqrt(var) :
+                    0
+                    """,
+                    {'s': final_s_image, 'var': var_s}
+                ).rename('z_score')
+        
+        confidence = z_score.abs().divide(ee.Number(2).sqrt()).erf().rename('confidence')
+
+        stat_bands = ee.Image([var_s, z_score, confidence])
+
+        mk_stats_image = final_s_image.addBands(stat_bands)
+
+        ########## PART 3 - Sen's Slope ##########
+        def add_year_band(image):
+            if join_method == 'Date_Filter':
+                # Get the string 'YYYY-MM-DD'
+                date_string = image.get('Date_Filter')
+                # Parse it into an ee.Date object (handles the conversion to time math)
+                date = ee.Date.parse('YYYY-MM-dd', date_string)
+            else:
+                # Standard way: assumes system:time_start exists
+                date = image.date()
+            years = date.difference(ee.Date('1970-01-01'), 'year')
+            return image.addBands(ee.Image(years).float().rename('year'))
+        
+        slope_input = image_collection.map(add_year_band).select(['year', target_band])
+
+        sens_slope = slope_input.reduce(ee.Reducer.sensSlope())
+
+        slope_band = sens_slope.select('slope')
+
+        # add a mask to the final image to remove pixels with less than min_observations
+        # mainly an effort to mask pixels outside of the boundary of the input image collection
+        min_observations = 1
+        valid_mask = n.gte(min_observations)
+
+        final_image = mk_stats_image.addBands(slope_band).updateMask(valid_mask)
+
+        if geometry is not None:
+            mask = ee.Image(1).clip(geometry)
+            final_image = final_image.updateMask(mask)
+
+        return final_image.setDefaultProjection(native_projection)
+
+    def sens_slope_trend(self, target_band=None, join_method='system:time_start', geometry=None):
+            """
+            Calculates Sen's Slope (trend magnitude) for the collection.
+            This is a lighter-weight alternative to the full `mann_kendall_trend` function if only
+            the direction and magnitude of the trend are needed.
+
+            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.
+
+            Args:
+                target_band (str): The name of the band to analyze. Defaults to 'ndvi'.
+                join_method (str): Property to use for time sorting ('system:time_start' or 'Date_Filter').
+                geometry (ee.Geometry, optional): Geometry to mask the final output.
+
+            Returns:
+                ee.Image: An image containing the 'slope' band.
+            """
+            image_collection = self
+            if isinstance(image_collection, GenericCollection):
+                image_collection = image_collection.collection
+            elif isinstance(image_collection, ee.ImageCollection):
+                pass
+            else:
+                raise ValueError(f'The chosen `image_collection`: {image_collection} is not a valid GenericCollection or ee.ImageCollection object.')
+            
+            if target_band is None:
+                raise ValueError('The `target_band` parameter must be specified.')
+            if not isinstance(target_band, str):
+                raise ValueError(f'The chosen `target_band`: {target_band} is not a valid string.')
+
+            if geometry is not None and not isinstance(geometry, ee.Geometry):
+                raise ValueError(f'The chosen `geometry`: {geometry} is not a valid ee.Geometry object.')
+
+            # Add Year Band (Time X-Axis)
+            def add_year_band(image):
+                # Handle user-defined date strings vs system time
+                if join_method == 'Date_Filter':
+                    date_string = image.get('Date_Filter')
+                    date = ee.Date.parse('YYYY-MM-dd', date_string)
+                else:
+                    date = image.date()
+                    
+                # Convert to fractional years relative to epoch
+                years = date.difference(ee.Date('1970-01-01'), 'year')
+                return image.addBands(ee.Image(years).float().rename('year'))
+
+            # Prepare Collection: Select ONLY [Year, Target]
+            # sensSlope expects Band 0 = Independent (X), Band 1 = Dependent (Y)
+            slope_input = self.collection.map(add_year_band).select(['year', target_band])
+
+            # Run the Native Reducer
+            sens_result = slope_input.reduce(ee.Reducer.sensSlope())
+            
+            # Extract and Mask
+            slope_band = sens_result.select('slope')
+
+            if geometry is not None:
+                mask = ee.Image(1).clip(geometry)
+                slope_band = slope_band.updateMask(mask)
+
+            return slope_band
+    
+
     def mask_to_polygon(self, polygon):
         """
         Function to mask GenericCollection image collection by a polygon (ee.Geometry), where pixels outside the polygon are masked out.
@@ -1548,20 +2207,15 @@ class GenericCollection:
             GenericCollection: masked GenericCollection image collection
 
         """
-        if self._geometry_masked_collection is None:
-            # Convert the polygon to a mask
-            mask = ee.Image.constant(1).clip(polygon)
-
-            # Update the mask of each image in the collection
-            masked_collection = self.collection.map(lambda img: img.updateMask(mask))
+        # Convert the polygon to a mask
+        mask = ee.Image.constant(1).clip(polygon)
 
-            # Update the internal collection state
-            self._geometry_masked_collection = GenericCollection(
-                collection=masked_collection
-            )
+        # Update the mask of each image in the collection
+        masked_collection = self.collection.map(lambda img: img.updateMask(mask)\
+                                .copyProperties(img).set('system:time_start', img.get('system:time_start')))
 
         # Return the updated object
-        return self._geometry_masked_collection
+        return GenericCollection(collection=masked_collection)
 
     def mask_out_polygon(self, polygon):
         """
@@ -1574,23 +2228,18 @@ class GenericCollection:
             GenericCollection: masked GenericCollection image collection
 
         """
-        if self._geometry_masked_out_collection is None:
-            # Convert the polygon to a mask
-            full_mask = ee.Image.constant(1)
+        # Convert the polygon to a mask
+        full_mask = ee.Image.constant(1)
 
-            # Use paint to set pixels inside polygon as 0
-            area = full_mask.paint(polygon, 0)
+        # Use paint to set pixels inside polygon as 0
+        area = full_mask.paint(polygon, 0)
 
-            # Update the mask of each image in the collection
-            masked_collection = self.collection.map(lambda img: img.updateMask(area))
-
-            # Update the internal collection state
-            self._geometry_masked_out_collection = GenericCollection(
-                collection=masked_collection
-            )
+        # Update the mask of each image in the collection
+        masked_collection = self.collection.map(lambda img: img.updateMask(area)\
+                            .copyProperties(img).set('system:time_start', img.get('system:time_start')))
 
         # Return the updated object
-        return self._geometry_masked_out_collection
+        return GenericCollection(collection=masked_collection)
 
     
     def binary_mask(self, threshold=None, band_name=None, classify_above_threshold=True, mask_zeros=False):
@@ -1625,20 +2274,26 @@ class GenericCollection:
         if classify_above_threshold:
             if mask_zeros:
                 col = self.collection.map(
-                    lambda image: image.select(band_name).gte(threshold).rename(band_name).updateMask(image.select(band_name).gt(0)).copyProperties(image).set('system:time_start', image.get('system:time_start'))
+                    lambda image: image.select(band_name).gte(threshold).rename(band_name)
+                    .updateMask(image.select(band_name).gt(0)).copyProperties(image)
+                    .set('system:time_start', image.get('system:time_start'))
                 )
             else:
                 col = self.collection.map(
-                    lambda image: image.select(band_name).gte(threshold).rename(band_name).copyProperties(image).set('system:time_start', image.get('system:time_start'))
+                    lambda image: image.select(band_name).gte(threshold).rename(band_name)
+                    .copyProperties(image).set('system:time_start', image.get('system:time_start'))
                 )
         else:
             if mask_zeros:
                 col = self.collection.map(
-                    lambda image: image.select(band_name).lte(threshold).rename(band_name).updateMask(image.select(band_name).gt(0)).copyProperties(image).set('system:time_start', image.get('system:time_start'))
+                    lambda image: image.select(band_name).lte(threshold).rename(band_name)
+                    .updateMask(image.select(band_name).gt(0)).copyProperties(image)
+                    .set('system:time_start', image.get('system:time_start'))
                 )
             else:
                 col = self.collection.map(
-                    lambda image: image.select(band_name).lte(threshold).rename(band_name).copyProperties(image).set('system:time_start', image.get('system:time_start'))
+                    lambda image: image.select(band_name).lte(threshold).rename(band_name)
+                    .copyProperties(image).set('system:time_start', image.get('system:time_start'))
                 )
         return GenericCollection(collection=col)
     
@@ -1760,7 +2415,8 @@ class GenericCollection:
             )
 
             # guarantee single band + keep properties
-            out = ee.Image(out).select([band_name_to_mask]).copyProperties(prim, prim.propertyNames())
+            out = ee.Image(out).select([band_name_to_mask]).copyProperties(prim, prim.propertyNames())\
+                                    .set('system:time_start', prim.get('system:time_start'))
             out = out.set('Date_Filter', prim.get('Date_Filter'))
             return ee.Image(out)                  # <-- return as Image
 
@@ -1842,7 +2498,7 @@ class GenericCollection:
         new_col = self.collection.filter(ee.Filter.eq("Date_Filter", img_date))
         return new_col.first()
 
-    def CollectionStitch(self, img_col2):
+    def collectionStitch(self, img_col2):
         """
         Function to mosaic two GenericCollection objects which share image dates.
         Mosaics are only formed for dates where both image collections have images.
@@ -1894,9 +2550,16 @@ class GenericCollection:
 
         # Return a GenericCollection instance
         return GenericCollection(collection=new_col)
+    
+    def CollectionStitch(self, img_col2):
+        warnings.warn(
+            "CollectionStitch is deprecated. Please use collectionStitch instead.",
+            DeprecationWarning,
+            stacklevel=2)
+        return self.collectionStitch(img_col2)
 
     @property
-    def MosaicByDate(self):
+    def mosaicByDateDepr(self):
         """
         Property attribute function to mosaic collection images that share the same date.
 
@@ -1952,6 +2615,64 @@ class GenericCollection:
 
         # Convert the list of mosaics to an ImageCollection
         return self._MosaicByDate
+    
+    @property
+    def mosaicByDate(self):
+        """
+        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.
+
+        Returns:
+            LandsatCollection: LandsatCollection image collection with mosaiced imagery and mean CLOUD_COVER as a property
+        """
+        if self._MosaicByDate is None:
+            distinct_dates = self.collection.distinct("Date_Filter")
+
+            # Define a join to link images by Date_Filter
+            filter_date = ee.Filter.equals(leftField="Date_Filter", rightField="Date_Filter")
+            join = ee.Join.saveAll(matchesKey="date_matches")
+
+            # Apply the join
+            # Primary: Distinct dates collection
+            # Secondary: The full original collection
+            joined_col = ee.ImageCollection(join.apply(distinct_dates, self.collection, filter_date))
+
+            # Define the mosaicking function 
+            def _mosaic_day(img):
+                # Recover the list of images for this day
+                daily_list = ee.List(img.get("date_matches"))
+                daily_col = ee.ImageCollection.fromImages(daily_list)
+                
+                # Create the mosaic
+                mosaic = daily_col.mosaic().setDefaultProjection(img.projection())
+
+                # Properties to preserve from the representative image
+                props_of_interest = [
+                    "system:time_start",
+                    "Date_Filter" 
+                ]
+                
+                # Return mosaic with properties set
+                return mosaic.copyProperties(img, props_of_interest)
+            # 5. Map the function and wrap the result
+            mosaiced_col = joined_col.map(_mosaic_day)
+            self._MosaicByDate = GenericCollection(collection=mosaiced_col)
+
+        # Convert the list of mosaics to an ImageCollection
+        return self._MosaicByDate
+    
+    @property
+    def MosaicByDate(self):
+        warnings.warn(
+            "MosaicByDate is deprecated. Please use mosaicByDate instead.",
+            DeprecationWarning,
+            stacklevel=2)
+        return self.mosaicByDate
 
     @staticmethod
     def ee_to_df(