RadGEEToolbox 1.6.8__py3-none-any.whl → 1.6.10__py3-none-any.whl

RadGEEToolbox/LandsatCollection.py

@@ -149,10 +149,12 @@ class LandsatCollection:
         self.nbr_threshold = -1
         self._masked_clouds_collection = None
         self._masked_water_collection = None
+        self._masked_shadows_collection = None
         self._masked_to_water_collection = None
         self._geometry_masked_collection = None
         self._geometry_masked_out_collection = None
         self._median = None
+        self._monthly_median = None
         self._mean = None
         self._max = None
         self._min = None
@@ -267,25 +269,25 @@ class LandsatCollection:
         )  # green-SWIR / green+SWIR -- full NDWI image
         water = (
             mndwi_calc.updateMask(mndwi_calc.gte(threshold))
-            .rename("ndwi")
+            .rename("mndwi")
             .copyProperties(image)
         )
         if ng_threshold != None:
             water = ee.Algorithms.If(
                 ee.String(image.get("SPACECRAFT_ID")).equals("LANDSAT_5"),
                 mndwi_calc.updateMask(mndwi_calc.gte(threshold))
-                .rename("ndwi")
+                .rename("mndwi")
                 .copyProperties(image)
                 .set("threshold", threshold),
                 mndwi_calc.updateMask(mndwi_calc.gte(ng_threshold))
-                .rename("ndwi")
+                .rename("mndwi")
                 .copyProperties(image)
                 .set("threshold", ng_threshold),
             )
         else:
             water = (
                 mndwi_calc.updateMask(mndwi_calc.gte(threshold))
-                .rename("ndwi")
+                .rename("mndwi")
                 .copyProperties(image)
             )
         return water
@@ -701,6 +703,59 @@ class LandsatCollection:
         else:
             nbr = nbr_calc.updateMask(nbr_calc.gte(threshold)).rename("nbr").copyProperties(image).set("threshold", threshold)
         return nbr
+    
+    @staticmethod
+    def anomaly_fn(image, geometry, band_name=None, anomaly_band_name=None, replace=True):
+        """
+        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.
+
+        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=30,
+            maxPixels=1e13
+        ).toImage()
+
+        # Compute the anomaly by subtracting the mean image from the input image.
+        anomaly_image = image_to_process.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)
+        else:
+            return image.addBands(anomaly_image, overwrite=True)
 
     @staticmethod
     def MaskWaterLandsat(image):
@@ -809,6 +864,70 @@ class LandsatCollection:
             )
         return water
 
+    @staticmethod
+    def mask_via_band_fn(image, band_to_mask, band_for_mask, threshold, mask_above=False, add_band_to_original_image=False):
+        """
+        Masks pixels of interest from a specified band of a target image, based on a specified reference band and threshold.
+        Designed for single image input which contains both the target and reference band.
+        Example use case is masking vegetation from image when targeting land pixels. Can specify whether to mask pixels above or below the threshold.
+
+        Args:
+            image (ee.Image): input ee.Image
+            band_to_mask (str): name of the band which will be masked (target image)
+            band_for_mask (str): name of the band to use for the mask (band you want to remove/mask from target image)
+            threshold (float): value where pixels less or more than threshold (depending on `mask_above` argument) will be masked
+            mask_above (bool): if True, masks pixels above the threshold; if False, masks pixels below the threshold
+
+        Returns:
+            ee.Image: masked ee.Image
+        """
+    
+        band_to_mask_image = image.select(band_to_mask)
+        band_for_mask_image = image.select(band_for_mask)
+ 
+        mask = band_for_mask_image.lte(threshold) if mask_above else band_for_mask_image.gte(threshold)
+
+        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))
+    
+    @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):
+        """
+        Masks pixels of interest from a specified band of a target image, based on a specified reference band and threshold.
+        Designed for the case where the target and reference bands are in separate images.
+        Example use case is masking vegetation from image when targeting land pixels. Can specify whether to mask pixels above or below the threshold.
+
+        Args:
+            image_to_mask (ee.Image): image which will be masked (target image). If multiband, only the first band will be masked.
+            image_for_mask (ee.Image): image to use for the mask (image you want to remove/mask from target image). If multiband, only the first band will be used for the masked.
+            threshold (float): value where pixels less or more than threshold (depending on `mask_above` argument) will be masked
+            band_name_to_mask (str, optional): name of the band in image_to_mask to be masked. If None, the first band will be used.
+            band_name_for_mask (str, optional): name of the band in image_for_mask to be used for masking. If None, the first band will be used.
+            mask_above (bool): if True, masks pixels above the threshold; if False, masks pixels below the threshold.
+
+        Returns:
+            ee.Image: masked ee.Image
+        """
+        if band_name_to_mask is None:
+            band_to_mask = ee.String(image_to_mask.bandNames().get(0))
+        else:
+            band_to_mask = ee.String(band_name_to_mask)
+
+        if band_name_for_mask is None:
+            band_for_mask = ee.String(image_for_mask.bandNames().get(0))
+        else:
+            band_for_mask = ee.String(band_name_for_mask)
+
+        band_to_mask_image = image_to_mask.select(band_to_mask)
+        band_for_mask_image = image_for_mask.select(band_for_mask)
+        if mask_above:
+            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)
+
     @staticmethod
     def halite_mask(image, threshold, ng_threshold=None):
         """
@@ -905,6 +1024,22 @@ class LandsatCollection:
         cirrus_mask = qa.bitwiseAnd(CirrusBitMask).eq(0)
         return image.updateMask(cloud_mask).updateMask(cirrus_mask)
 
+    @staticmethod
+    def maskL8shadows(image):
+        """
+        Masks cloud shadows based on Landsat 8 QA band.
+
+        Args:
+            image (ee.Image): input ee.Image
+
+        Returns:
+            ee.Image: ee.Image
+        """
+        shadowBitMask = ee.Number(2).pow(4).int()
+        qa = image.select("QA_PIXEL")
+        shadow_mask = qa.bitwiseAnd(shadowBitMask).eq(0)
+        return image.updateMask(shadow_mask)
+
     @staticmethod
     def temperature_bands(img):
         """
@@ -958,6 +1093,64 @@ class LandsatCollection:
             },
         ).rename("LST")
         return image.addBands(LST).copyProperties(image)  # Outputs temperature in C
+    
+    @staticmethod
+    def C_to_F_fn(LST_image):
+        """Converts Land Surface Temperature from Celsius to Fahrenheit.
+
+        This function takes an ee.Image with a band for Land Surface Temperature (LST)
+        in degrees Celsius and converts it to degrees Fahrenheit using the formula:
+        F = C * 9/5 + 32.
+
+        Args:
+            LST_image: An ee.Image where each band represents LST in degrees Celsius.
+
+        Returns:
+            ee.Image: An ee.Image where each band represents LST in degrees Fahrenheit. The output image retains the same band names as the input image alongside an additional band named 'LST_F'.
+        """
+        LST_image = LST_image.select('LST')
+        # Define the conversion formula from Celsius to Fahrenheit.
+        fahrenheit_image = LST_image.multiply(9).divide(5).add(32)
+
+        # Preserve original properties from the input image.
+        # return fahrenheit_image.rename('LST_F').copyProperties(LST_image)
+        return LST_image.addBands(fahrenheit_image.rename('LST_F'), overwrite=True).copyProperties(LST_image)
+    
+    @staticmethod
+    def band_rename_fn(image, current_band_name, new_band_name):
+        """Renames a band in an ee.Image (single- or multi-band) in-place.
+
+        Replaces the band named `current_band_name` with `new_band_name` without
+        retaining the original band name. If the band does not exist, returns the
+        image unchanged.
+
+        Args:
+            image (ee.Image): The input image (can be multiband).
+            current_band_name (str): The existing band name to rename.
+            new_band_name (str): The desired new band name.
+
+        Returns:
+            ee.Image: The image with the band renamed (or unchanged if not found).
+        """
+        img = ee.Image(image)
+        current = ee.String(current_band_name)
+        new = ee.String(new_band_name)
+
+        band_names = img.bandNames()
+        has_band = band_names.contains(current)
+
+        def _rename():
+            # Build a new band-name list with the target name replaced.
+            new_names = band_names.map(
+                lambda b: ee.String(
+                    ee.Algorithms.If(ee.String(b).equals(current), new, b)
+                )
+            )
+            # Rename the image using the updated band-name list.
+            return img.rename(ee.List(new_names))
+
+        out = ee.Image(ee.Algorithms.If(has_band, _rename(), img))
+        return out.copyProperties(img)
 
     @staticmethod
     def PixelAreaSum(
@@ -1071,12 +1264,12 @@ class LandsatCollection:
         else:
             raise ValueError("output_type must be 'ImageCollection' or 'LandsatCollection'")
 
-    def merge(self, other):
+    def combine(self, other):
         """
-        Merges the current LandsatCollection with another LandsatCollection, where images/bands with the same date are combined to a single multiband image.
+        Combines the current LandsatCollection with another LandsatCollection, using the `combine` method.
 
         Args:
-            other (LandsatCollection): Another LandsatCollection to merge with current collection.
+            other (LandsatCollection): Another LandsatCollection to combine with current collection.
 
         Returns:
             LandsatCollection: A new LandsatCollection containing images from both collections.
@@ -1089,6 +1282,72 @@ class LandsatCollection:
         merged_collection = self.collection.combine(other.collection)
         return LandsatCollection(collection=merged_collection)
 
+    def merge(self, collections=None, multiband_collection=None, date_key='Date_Filter'):
+        """
+        Merge many singleband LandsatCollection products into the parent collection, 
+        or merge a single multiband collection with parent collection,
+        pairing images by exact Date_Filter and returning one multiband image per date.
+
+        NOTE: if you want to merge two multiband collections, use the `combine` method instead.
+
+        Args:
+            collections (list): List of singleband collections to merge with parent collection, effectively adds one band per collection to each image in parent
+            multiband_collection (LandsatCollection, optional): A multiband collection to merge with parent. Specifying a collection here will override `collections`.
+            date_key (str): image property key for exact pairing (default 'Date_Filter')
+
+        Returns:
+            LandsatCollection: parent with extra single bands attached (one image per date)
+        """
+
+        if collections is None and multiband_collection is not None:
+            # Exact-date inner-join merge of two collections (adds ALL bands from 'other').
+            join = ee.Join.inner()
+            flt  = ee.Filter.equals(leftField=date_key, rightField=date_key)
+            paired = join.apply(self.collection, multiband_collection.collection, flt)
+
+            def _pair_two(f):
+                f = ee.Feature(f)
+                a = ee.Image(f.get('primary'))
+                b = ee.Image(f.get('secondary'))
+                # Overwrite on name collision
+                merged = a.addBands(b, None, True)
+                # Keep parent props + date key
+                merged = merged.copyProperties(a, a.propertyNames())
+                merged = merged.set(date_key, a.get(date_key))
+                return ee.Image(merged)
+
+            return LandsatCollection(collection=ee.ImageCollection(paired.map(_pair_two)))
+
+        # Preferred path: merge many singleband products into the parent
+        if not isinstance(collections, list) or len(collections) == 0:
+            raise ValueError("Provide a non-empty list of LandsatCollection objects in `collections`.")
+
+        result = self.collection
+        for extra in collections:
+            if not isinstance(extra, LandsatCollection):
+                raise ValueError("All items in `collections` must be LandsatCollection objects.")
+
+            join = ee.Join.inner()
+            flt  = ee.Filter.equals(leftField=date_key, rightField=date_key)
+            paired = join.apply(result, extra.collection, flt)
+
+            def _attach_one(f):
+                f = ee.Feature(f)
+                parent = ee.Image(f.get('primary'))
+                sb     = ee.Image(f.get('secondary'))
+                # Assume singleband product; grab its first band name server-side
+                bname  = ee.String(sb.bandNames().get(0))
+                # Add the single band; overwrite if the name already exists in parent
+                merged = parent.addBands(sb.select([bname]).rename([bname]), None, True)
+                # Preserve parent props + date key
+                merged = merged.copyProperties(parent, parent.propertyNames())
+                merged = merged.set(date_key, parent.get(date_key))
+                return ee.Image(merged)
+
+            result = ee.ImageCollection(paired.map(_attach_one))
+
+        return LandsatCollection(collection=result)
+
     @staticmethod
     def dNDWIPixelAreaSum(image, geometry, band_name="ndwi", scale=30, maxPixels=1e12):
         """
@@ -1358,6 +1617,84 @@ class LandsatCollection:
             col = self.collection.min()
             self._min = col
         return self._min
+    
+    @property
+    def monthly_median_collection(self):
+        """Creates a monthly median composite from a LandsatCollection 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.
+
+        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:
+            LandsatCollection: A new LandsatCollection 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 = LandsatCollection(collection=monthly_collection.filter(ee.Filter.gt('image_count', 0)))
+            self._monthly_median = final_collection
+        else:
+            pass
+
+        return self._monthly_median
 
     @property
     def ndwi(self):
@@ -2022,6 +2359,19 @@ class LandsatCollection:
             col = self.collection.map(LandsatCollection.maskL8clouds)
             self._masked_clouds_collection = LandsatCollection(collection=col)
         return self._masked_clouds_collection
+    
+    @property
+    def masked_shadows_collection(self):
+        """
+        Property attribute to mask shadows and return collection as class object.
+
+        Returns:
+            LandsatCollection: LandsatCollection image collection
+        """
+        if self._masked_shadows_collection is None:
+            col = self.collection.map(LandsatCollection.maskL8shadows)
+            self._masked_shadows_collection = LandsatCollection(collection=col)
+        return self._masked_shadows_collection
 
     @property
     def LST(self):
@@ -2062,6 +2412,18 @@ class LandsatCollection:
             .map(LandsatCollection.image_dater)
         )
         return LandsatCollection(collection=col)
+    
+    def C_to_F(self):
+        """
+        Function to convert an LST collection from Celcius to Fahrenheit, adding a new band 'LST_F' to each image in the collection.
+
+        Returns:
+            LandsatCollection: A LandsatCollection image collection with LST in Fahrenheit as band titled 'LST_F'.
+        """
+        if self._LST is None:
+            raise ValueError("LST has not been calculated yet. Access the LST property first.")
+        col = self._LST.collection.map(LandsatCollection.C_to_F_fn)
+        return LandsatCollection(collection=col)
 
     def mask_to_polygon(self, polygon):
         """
@@ -2169,14 +2531,17 @@ class LandsatCollection:
         )
         return LandsatCollection(collection=col)
     
-    def binary_mask(self, threshold=None, band_name=None):
+    def binary_mask(self, threshold=None, band_name=None, classify_above_threshold=True, mask_zeros=False):
         """
         Function to create a binary mask (value of 1 for pixels above set threshold and value of 0 for all other pixels) of the LandsatCollection image collection based on a specified band.
         If a singleband image is provided, the band name is automatically determined.
         If multiple bands are available, the user must specify the band name to use for masking.
 
         Args:
+            threshold (float, optional): The threshold value for creating the binary mask. Defaults to None.
             band_name (str, optional): The name of the band to use for masking. Defaults to None.
+            classifiy_above_threshold (bool, optional): If True, pixels above the threshold are classified as 1. If False, pixels below the threshold are classified as 1. Defaults to True.
+            mask_zeros (bool, optional): If True, pixels with a value of 0 after the binary mask are masked out in the output binary mask. Useful for classifications. Defaults to False.
 
         Returns:
             LandsatCollection: LandsatCollection singleband image collection with binary masks applied.
@@ -2195,11 +2560,175 @@ class LandsatCollection:
         if threshold is None:
             raise ValueError("Threshold must be specified for binary masking.")
 
+        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)
+                )
+            else:
+                col = self.collection.map(
+                    lambda image: image.select(band_name).gte(threshold).rename(band_name).copyProperties(image)
+                )
+        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)
+                )
+            else:
+                col = self.collection.map(
+                    lambda image: image.select(band_name).lte(threshold).rename(band_name).copyProperties(image)
+                )
+        return LandsatCollection(collection=col)
+    
+    def anomaly(self, geometry, band_name=None, anomaly_band_name=None, replace=True):
+        """
+        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.
+
+        Returns:
+            LandsatCollection: A LandsatCollection 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: LandsatCollection.anomaly_fn(image, geometry=geometry, band_name=band_name, anomaly_band_name=anomaly_band_name, replace=replace))
+        return LandsatCollection(collection=col)
+    
+    def mask_via_band(self, band_to_mask, band_for_mask, threshold=-1, mask_above=True, add_band_to_original_image=False):
+        """
+        Masks select pixels of a selected band from an image based on another specified band and threshold (optional). 
+        Example use case is masking vegetation from image when targeting land pixels. Can specify whether to mask pixels above or below the threshold.
+
+        Args:
+            band_to_mask (str): name of the band which will be masked (target image)
+            band_for_mask (str): name of the band to use for the mask (band you want to remove/mask from target image)
+            threshold (float): value between -1 and 1 where pixels less than threshold will be masked; defaults to -1 assuming input band is already classified (masked to pixels of interest).
+            mask_above (bool): if True, masks pixels above the threshold; if False, masks pixels below the threshold
+
+        Returns:
+            LandsatCollection: A new LandsatCollection with the specified band masked to pixels excluding from `band_for_mask`.
+        """
+        if self.collection.size().eq(0).getInfo():
+            raise ValueError("The collection is empty.")
+
         col = self.collection.map(
-            lambda image: image.select(band_name).gte(threshold).rename(band_name)
+            lambda image: LandsatCollection.mask_via_band_fn(
+                image,
+                band_to_mask=band_to_mask,
+                band_for_mask=band_for_mask,
+                threshold=threshold,
+                mask_above=mask_above,
+                add_band_to_original_image=add_band_to_original_image
+            )
         )
         return LandsatCollection(collection=col)
 
+    def mask_via_singleband_image(self, image_collection_for_mask, band_name_to_mask, band_name_for_mask, threshold=-1, mask_above=False, add_band_to_original_image=False):
+        """
+        Masks select pixels of a selected band from an image collection based on another specified singleband image collection and threshold (optional).
+        Example use case is masking vegetation from image when targeting land pixels. Can specify whether to mask pixels above or below the threshold.
+        This function pairs images from the two collections based on an exact match of the 'Date_Filter' property.
+        
+        Args:
+            image_collection_for_mask (LandsatCollection): LandsatCollection image collection to use for masking (source of pixels that will be used to mask the parent image collection)
+            band_name_to_mask (str): name of the band which will be masked (target image)
+            band_name_for_mask (str): name of the band to use for the mask (band which contains pixels the user wants to remove/mask from target image)
+            threshold (float): threshold value where pixels less (or more, depending on `mask_above`) than threshold will be masked; defaults to -1.
+            mask_above (bool): if True, masks pixels above the threshold; if False, masks pixels below the threshold
+            add_band_to_original_image (bool): if True, adds the band used for masking to the original image as an additional band; if False, only the masked band is retained in the output image.
+
+        Returns:
+            LandsatCollection: A new LandsatCollection with the specified band masked to pixels excluding from `band_for_mask`.
+        """
+        
+        if self.collection.size().eq(0).getInfo():
+            raise ValueError("The collection is empty.")
+        if not isinstance(image_collection_for_mask, LandsatCollection):
+            raise ValueError("image_collection_for_mask must be a LandsatCollection object.")
+        size1 = self.collection.size().getInfo()
+        size2 = image_collection_for_mask.collection.size().getInfo()
+        if size1 != size2:
+            raise ValueError(f"Warning: Collections have different sizes ({size1} vs {size2}). Please ensure both collections have the same number of images and matching dates.")
+        if size1 == 0 or size2 == 0:
+            raise ValueError("Warning: One of the input collections is empty.")
+
+        # Pair by exact Date_Filter property
+        primary   = self.collection.select([band_name_to_mask])
+        secondary = image_collection_for_mask.collection.select([band_name_for_mask])
+        join = ee.Join.inner()
+        flt  = ee.Filter.equals(leftField='Date_Filter', rightField='Date_Filter')
+        paired = join.apply(primary, secondary, flt)
+
+        def _map_pair(f):
+            f = ee.Feature(f)                     # <-- treat as Feature
+            prim = ee.Image(f.get('primary'))     # <-- get the primary Image
+            sec  = ee.Image(f.get('secondary'))   # <-- get the secondary Image
+
+            merged = prim.addBands(sec.select([band_name_for_mask]))
+
+            out = LandsatCollection.mask_via_band_fn(
+                merged,
+                band_to_mask=band_name_to_mask,
+                band_for_mask=band_name_for_mask,
+                threshold=threshold,
+                mask_above=mask_above,
+                add_band_to_original_image=add_band_to_original_image
+            )
+
+            # guarantee single band + keep properties
+            out = ee.Image(out).select([band_name_to_mask]).copyProperties(prim, prim.propertyNames())
+            out = out.set('Date_Filter', prim.get('Date_Filter'))
+            return ee.Image(out)                  # <-- return as Image
+
+        col = ee.ImageCollection(paired.map(_map_pair))
+        return LandsatCollection(collection=col)
+
+    def band_rename(self, current_band_name, new_band_name):
+        """Renames a band in all images of the LandsatCollection in-place.
+
+        Replaces the band named `current_band_name` with `new_band_name` without
+        retaining the original band name. If the band does not exist in an image,
+        that image is returned unchanged.
+
+        Args:
+            current_band_name (str): The existing band name to rename.
+            new_band_name (str): The desired new band name.
+
+        Returns:
+            LandsatCollection: The LandsatCollection with the band renamed in all images.
+        """
+        # check if `current_band_name` exists in the first image
+        first_image = self.collection.first()
+        has_band = first_image.bandNames().contains(current_band_name).getInfo()
+        if not has_band:
+            raise ValueError(f"Band '{current_band_name}' does not exist in the collection.")
+
+        renamed_collection = self.collection.map(
+            lambda img: self.band_rename_fn(img, current_band_name, new_band_name)
+        )
+        return LandsatCollection(collection=renamed_collection)
+
     def image_grab(self, img_selector):
         """
         Selects ("grabs") an image by index from the collection. Easy way to get latest image or browse imagery one-by-one.
@@ -2879,6 +3408,7 @@ class LandsatCollection:
     def iterate_zonal_stats(
         self,
         geometries,
+        band=None,
         reducer_type="mean",
         scale=30,
         geometry_names=None,
@@ -2894,6 +3424,7 @@ class LandsatCollection:
 
         Args:
             geometries (ee.Geometry, ee.Feature, ee.FeatureCollection, list, or tuple): Input geometries for which to extract statistics. Can be a single ee.Geometry, an ee.Feature, an ee.FeatureCollection, a list of (lon, lat) tuples, or a list of ee.Geometry objects. Be careful to NOT provide coordinates as (lat, lon)!
+            band (str, optional): The name of the band to use for statistics. If None, the first band is used. Defaults to None.
             reducer_type (str, optional): The ee.Reducer to use, e.g., 'mean', 'median', 'max', 'sum'. Defaults to 'mean'. Any ee.Reducer method can be used.
             scale (int, optional): Pixel scale in meters for the reduction. Defaults to 30.
             geometry_names (list, optional): A list of string names for the geometries. If provided, must match the number of geometries. Defaults to None.
@@ -2911,6 +3442,12 @@ class LandsatCollection:
             TypeError: If geometries input type is unsupported.
         """
         img_collection_obj = self
+        if band:
+            img_collection_obj = LandsatCollection(collection=img_collection_obj.collection.select(band))
+        else: 
+            first_image = img_collection_obj.image_grab(0)
+            first_band = first_image.bandNames().get(0)
+            img_collection_obj = LandsatCollection(collection=img_collection_obj.collection.select([first_band]))
         # Filter collection by dates if provided
         if dates:
             img_collection_obj = LandsatCollection(
@@ -2993,18 +3530,33 @@ class LandsatCollection:
             stats_fc = image.reduceRegions(
                 collection=features, reducer=reducer, scale=scale, tileScale=tileScale
             )
-            return stats_fc.map(lambda f: f.set('image_date', image_date))
+
+            def guarantee_reducer_property(f):
+                has_property = f.propertyNames().contains(reducer_type)
+                return ee.Algorithms.If(has_property, f, f.set(reducer_type, -9999))
+            fixed_stats_fc = stats_fc.map(guarantee_reducer_property)
+
+            return fixed_stats_fc.map(lambda f: f.set('image_date', image_date))
 
         results_fc = ee.FeatureCollection(img_collection_obj.collection.map(calculate_stats_for_image)).flatten()
         df = LandsatCollection.ee_to_df(results_fc, remove_geom=True)
 
         # Checking for issues
         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
+            # 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
+            # return df
+
+        # Get the number of rows before dropping nulls for a helpful message
+        initial_rows = len(df)
+        df.dropna(subset=[reducer_type], inplace=True)
+        df = df[df[reducer_type] != -9999]
+        dropped_rows = initial_rows - len(df)
+        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_df = df.pivot(index='image_date', columns='geo_name', values=reducer_type)
@@ -3018,6 +3570,61 @@ class LandsatCollection:
             return
         return pivot_df
         
+    def export_to_asset_collection(
+        self,
+        asset_collection_path,
+        region,
+        scale,
+        dates=None,
+        filename_prefix="",
+        crs=None,
+        max_pixels=int(1e13),
+        description_prefix="export"
+    ):
+        """
+        Exports an image collection to a Google Earth Engine asset collection. The asset collection will be created if it does not already exist, 
+        and each image exported will be named according to the provided filename prefix and date.
+
+        Args:
+            asset_collection_path (str): The path to the asset collection.
+            region (ee.Geometry): The region to export.
+            scale (int): The scale of the export.
+            dates (list, optional): The dates to export. Defaults to None.
+            filename_prefix (str, optional): The filename prefix. Defaults to "", i.e. blank.
+            crs (str, optional): The coordinate reference system. Defaults to None, which will use the image's CRS.
+            max_pixels (int, optional): The maximum number of pixels. Defaults to int(1e13).
+            description_prefix (str, optional): The description prefix. Defaults to "export".
+
+        Returns:
+            None: (queues export tasks)
+        """
+        ic = self.collection
+        if dates is None:
+            dates = self.dates
+        try:
+            ee.data.createAsset({'type': 'ImageCollection'}, asset_collection_path)
+        except Exception:
+            pass
+
+        for date_str in dates:
+            img = ee.Image(ic.filter(ee.Filter.eq('Date_Filter', date_str)).first())
+            asset_id = asset_collection_path + "/" + filename_prefix + date_str
+            desc = description_prefix + "_" + filename_prefix + date_str
+
+            params = {
+                'image': img,
+                'description': desc,
+                'assetId': asset_id,
+                'region': region,
+                'scale': scale,
+                'maxPixels': max_pixels
+            }
+            if crs:
+                params['crs'] = crs
+
+            ee.batch.Export.image.toAsset(**params).start()
+
+        print("Queued", len(dates), "export tasks to", asset_collection_path)