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

RadGEEToolbox/Sentinel1Collection.py

@@ -2,6 +2,7 @@ import ee
 import math
 import pandas as pd
 import numpy as np
+import warnings
 
 
 class Sentinel1Collection:
@@ -230,6 +231,14 @@ class Sentinel1Collection:
         self._DbFromSigma0 = None
         self._multilook = 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):
         """
@@ -245,7 +254,7 @@ class Sentinel1Collection:
         return image.set({"Date_Filter": date})
 
     @staticmethod
-    def PixelAreaSum(
+    def pixelAreaSum(
         image, band_name, geometry, threshold=-1, scale=10, maxPixels=1e12
     ):
         """
@@ -304,8 +313,26 @@ class Sentinel1Collection:
         # Call to iterate the calculate_and_set_area function over the list of bands, starting with the original image
         final_image = ee.Image(bands.iterate(calculate_and_set_area, image))
         return final_image
+    
+    @staticmethod
+    def PixelAreaSum(
+        image, band_name, geometry, threshold=-1, scale=10, maxPixels=1e12
+    ):
+        warnings.warn(
+            "The 'PixelAreaSum' method is deprecated. Please use 'pixelAreaSum' instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return Sentinel1Collection.pixelAreaSum(
+            image=image,
+            band_name=band_name,
+            geometry=geometry,
+            threshold=threshold,
+            scale=scale,
+            maxPixels=maxPixels,
+        )
 
-    def PixelAreaSumCollection(
+    def pixelAreaSumCollection(
         self, band_name, geometry, threshold=-1, scale=10, maxPixels=1e12, output_type='ImageCollection', area_data_export_path=None
     ):
         """
@@ -332,7 +359,7 @@ class Sentinel1Collection:
             collection = self.collection
             # Area calculation for each image in the collection, using the PixelAreaSum function
             AreaCollection = collection.map(
-                lambda image: Sentinel1Collection.PixelAreaSum(
+                lambda image: Sentinel1Collection.pixelAreaSum(
                     image,
                     band_name=band_name,
                     geometry=geometry,
@@ -348,17 +375,35 @@ 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=prop_names, file_path=area_data_export_path+'.csv')
+            Sentinel1Collection(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 == '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=prop_names)
+            return Sentinel1Collection(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', 'Sentinel1Collection', 'DataFrame', 'Pandas', 'pd', 'dataframe', or 'df'.")
 
+    def PixelAreaSumCollection(
+        self, band_name, geometry, threshold=-1, scale=10, maxPixels=1e12, output_type='ImageCollection', area_data_export_path=None
+    ):
+        warnings.warn(
+            "The 'PixelAreaSumCollection' method is deprecated. Please use 'pixelAreaSumCollection' instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.pixelAreaSumCollection(
+            band_name=band_name,
+            geometry=geometry,
+            threshold=threshold,
+            scale=scale,
+            maxPixels=maxPixels,
+            output_type=output_type,
+            area_data_export_path=area_data_export_path
+        )
+
     @staticmethod
     def add_month_property_fn(image):
         """
@@ -707,7 +752,7 @@ class Sentinel1Collection:
         return Sentinel1Collection(collection=self._speckle_filter)
 
     @property
-    def Sigma0FromDb(self):
+    def sigma0FromDb(self):
         """
         Property attribute function to convert image collection from decibels to sigma0. Results are calculated once per class object then cached for future use.
 
@@ -732,9 +777,18 @@ class Sentinel1Collection:
             sigma0_collection = collection.map(conversion)
             self._Sigma0FromDb = sigma0_collection
         return Sentinel1Collection(collection=self._Sigma0FromDb)
+    
+    @property
+    def Sigma0FromDb(self):
+        warnings.warn(
+            "The 'Sigma0FromDb' property is deprecated. Please use 'sigma0FromDb' instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.sigma0FromDb
 
     @property
-    def DbFromSigma0(self):
+    def dbFromSigma0(self):
         """
         Property attribute function to convert image collection from decibels to sigma0. Results are calculated once per class object then cached for future use.
 
@@ -760,6 +814,15 @@ class Sentinel1Collection:
             self._DbFromSigma0 = dB_collection
         return Sentinel1Collection(collection=self._DbFromSigma0)
     
+    @property
+    def DbFromSigma0(self):
+        warnings.warn(
+            "The 'DbFromSigma0' property is deprecated. Please use 'dbFromSigma0' instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.dbFromSigma0
+    
     @staticmethod
     def anomaly_fn(image, geometry, band_name=None, anomaly_band_name=None, replace=True, scale=10):
         """
@@ -847,7 +910,7 @@ class Sentinel1Collection:
             self._dates = dates
         return self._dates
     
-    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.
 
@@ -902,6 +965,14 @@ class Sentinel1Collection:
             print(f"Properties saved to {file_path}")
             
         return df
+    
+    def ExportProperties(self, property_names, file_path=None):
+        warnings.warn(
+            "The 'ExportProperties' method is deprecated. Please use 'exportProperties' instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.exportProperties(property_names=property_names, file_path=file_path)
 
     def get_filtered_collection(self):
         """
@@ -1966,6 +2037,9 @@ class Sentinel1Collection:
 
         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.')
+        
+        native_projection = image_collection.first().select(target_band).projection()
+
         # 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':
@@ -2021,7 +2095,7 @@ class Sentinel1Collection:
         # 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')
+        final_s_image = partial_s_col.sum().rename('s_statistic').setDefaultProjection(native_projection)
 
 
         ########## PART 2 - VARIANCE and Z-SCORE ##########
@@ -2084,7 +2158,7 @@ class Sentinel1Collection:
             mask = ee.Image(1).clip(geometry)
             final_image = final_image.updateMask(mask)
 
-        return final_image
+        return final_image.setDefaultProjection(native_projection)
 
     def sens_slope_trend(self, target_band=None, join_method='system:time_start', geometry=None):
             """
@@ -2120,6 +2194,8 @@ class Sentinel1Collection:
             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.')
 
+            native_projection = image_collection.first().select(target_band).projection()
+
             # Add Year Band (Time X-Axis)
             def add_year_band(image):
                 # Handle user-defined date strings vs system time
@@ -2147,7 +2223,7 @@ class Sentinel1Collection:
                 mask = ee.Image(1).clip(geometry)
                 slope_band = slope_band.updateMask(mask)
 
-            return slope_band
+            return slope_band.setDefaultProjection(native_projection)
     
 
     def mask_to_polygon(self, polygon):
@@ -2161,20 +2237,15 @@ class Sentinel1Collection:
             Sentinel1Collection: masked Sentinel1Collection image collection
 
         """
-        if self._geometry_masked_collection is None:
-            # Convert the polygon to a mask
-            mask = ee.Image.constant(1).clip(polygon)
+        # 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).copyProperties(img).set('system:time_start', img.get('system:time_start')))
-
-            # Update the internal collection state
-            self._geometry_masked_collection = Sentinel1Collection(
-                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 Sentinel1Collection(collection=masked_collection)
 
     def mask_out_polygon(self, polygon):
         """
@@ -2187,23 +2258,18 @@ class Sentinel1Collection:
             Sentinel1Collection: masked Sentinel1Collection 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).copyProperties(img).set('system:time_start', img.get('system:time_start')))
-
-            # Update the internal collection state
-            self._geometry_masked_out_collection = Sentinel1Collection(
-                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 Sentinel1Collection(collection=masked_collection)
 
     def image_grab(self, img_selector):
         """
@@ -2255,7 +2321,7 @@ class Sentinel1Collection:
         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 Sentinel1Collection objects which share image dates.
         Mosaics are only formed for dates where both image collections have images.
@@ -2307,9 +2373,17 @@ class Sentinel1Collection:
 
         # Return a Sentinel1Collection instance
         return Sentinel1Collection(collection=new_col)
+    
+    def CollectionStitch(self, img_col2):
+        warnings.warn(
+            "The 'CollectionStitch' method 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.
         The property CLOUD_COVER for each image is used to calculate an overall mean,
@@ -2370,6 +2444,74 @@ class Sentinel1Collection:
 
         # 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 = [
+                    "platform_number",
+                    "instrument",
+                    "instrumentMode",
+                    "orbitNumber_start",
+                    "orbitNumber_stop",
+                    "orbitProperties_pass",
+                    "resolution_meters",
+                    "transmitterReceiverPolarisation",
+                    "system:time_start",
+                    "crs"
+                ]
+                
+                # 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 = Sentinel1Collection(collection=mosaiced_col)
+
+        # Convert the list of mosaics to an ImageCollection
+        return self._MosaicByDate
+
+    @property
+    def MosaicByDate(self):
+        warnings.warn(
+            "The 'MosaicByDate' property is deprecated. Please use 'mosaicByDate' instead.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return self.mosaicByDate
 
     @staticmethod
     def ee_to_df(