ECOv003-L2T-STARS 1.0.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

ECOv003_L2T_STARS/generate_L2T_STARS_runconfig.py

@@ -0,0 +1,249 @@
+from typing import Union
+from datetime import datetime, timezone
+from os import makedirs
+from os.path import join, abspath, exists, expanduser, dirname
+from glob import glob
+import logging
+from shutil import which
+from uuid import uuid4
+import socket
+
+import colored_logging as cl
+from pytictoc import TicToc  # Import pytictoc
+
+from ECOv003_granules import L2TLSTE
+
+from .constants import *
+
+logger = logging.getLogger(__name__)
+
+def generate_L2T_STARS_runconfig(
+    L2T_LSTE_filename: str,
+    prior_L2T_STARS_filename: str = "",
+    orbit: int = None,
+    scene: int = None,
+    tile: str = None,
+    time_UTC: Union[datetime, str] = None,
+    working_directory: str = None,
+    sources_directory: str = None,
+    indices_directory: str = None,
+    model_directory: str = None,
+    executable_filename: str = None,
+    output_directory: str = None,
+    runconfig_filename: str = None,
+    log_filename: str = None,
+    build: str = None,
+    processing_node: str = None,
+    production_datetime: datetime = None,
+    job_ID: str = None,
+    instance_ID: str = None,
+    product_counter: int = None,
+    template_filename: str = None,
+) -> str:
+    """
+    Generates an XML run-configuration file for the L2T_STARS processing.
+
+    This function dynamically creates an XML run-config file by populating a template
+    with provided or default parameters. It also checks for and returns existing
+    run-configs to prevent redundant generation.
+
+    Args:
+        L2T_LSTE_filename (str): Path to the input ECOSTRESS L2T LSTE granule file.
+        prior_L2T_STARS_filename (str, optional): Path to a prior L2T_STARS product file.
+            Defaults to "".
+        orbit (int, optional): Orbit number. If None, derived from L2T_LSTE_filename.
+        scene (int, optional): Scene ID. If None, derived from L2T_LSTE_filename.
+        tile (str, optional): HLS tile ID (e.g., '11SPS'). If None, derived from L2T_LSTE_filename.
+        time_UTC (Union[datetime, str], optional): UTC time of the L2T_LSTE granule. If None,
+            derived from L2T_LSTE_filename.
+        working_directory (str, optional): Root directory for all processing outputs.
+            Defaults to ".".
+        sources_directory (str, optional): Directory for downloaded source data (HLS, VIIRS).
+        indices_directory (str, optional): Directory for intermediate index products.
+        model_directory (str, optional): Directory for model state files (priors, posteriors).
+        executable_filename (str, optional): Path to the L2T_STARS executable. If None,
+            'L2T_STARS' is assumed to be in the system's PATH.
+        output_directory (str, optional): Directory for final L2T_STARS products.
+        runconfig_filename (str, optional): Specific filename for the generated run-config.
+            If None, a default name based on granule ID is used.
+        log_filename (str, optional): Specific filename for the log file. If None,
+            a default name based on granule ID is used.
+        build (str, optional): Build ID of the PGE. Defaults to DEFAULT_BUILD.
+        processing_node (str, optional): Name of the processing node. Defaults to system hostname.
+        production_datetime (datetime, optional): Production date and time. Defaults to now (UTC).
+        job_ID (str, optional): Job identifier. Defaults to a timestamp.
+        instance_ID (str, optional): Unique instance identifier. Defaults to a UUID.
+        product_counter (int, optional): Counter for product generation. Defaults to 1.
+        template_filename (str, optional): Path to the XML run-config template file.
+            Defaults to L2T_STARS_TEMPLATE.
+
+    Returns:
+        str: The absolute path to the generated or existing run-configuration file.
+    """
+    timer = TicToc()  # Initialize pytictoc timer
+    timer.tic()  # Start the timer
+
+    # Load the L2T_LSTE granule to extract necessary metadata if not provided
+    l2t_lste_granule = L2TLSTE(L2T_LSTE_filename)
+
+    # Use values from L2T_LSTE granule if not explicitly provided
+    if orbit is None:
+        orbit = l2t_lste_granule.orbit
+    if scene is None:
+        scene = l2t_lste_granule.scene
+    if tile is None:
+        tile = l2t_lste_granule.tile
+    if time_UTC is None:
+        time_UTC = l2t_lste_granule.time_UTC
+
+    # Set default values for other parameters if not provided
+    if build is None:
+        build = DEFAULT_BUILD
+    if working_directory is None:
+        working_directory = "."
+
+    date_UTC = time_UTC.date()
+
+    logger.info(
+        f"Started generating L2T_STARS run-config for tile {cl.val(tile)} on date {cl.time(date_UTC)}"
+    )
+
+    # Check for previous run-configs to avoid re-generating
+    pattern = join(
+        working_directory, "runconfig", f"ECOv003_L2T_STARS_{tile}_*_{build}_*.xml"
+    )
+    logger.info(f"Scanning for previous run-configs: {cl.val(pattern)}")
+    previous_runconfigs = glob(pattern)
+    previous_runconfig_count = len(previous_runconfigs)
+
+    if previous_runconfig_count > 0:
+        logger.info(f"Found {cl.val(previous_runconfig_count)} previous run-configs")
+        # Return the most recent run-config if found
+        previous_runconfig = sorted(previous_runconfigs)[-1]
+        logger.info(f"Previous run-config: {cl.file(previous_runconfig)}")
+        return previous_runconfig
+
+    # Resolve the path to the run-config template
+    if template_filename is None:
+        template_filename = L2T_STARS_TEMPLATE
+    template_filename = abspath(expanduser(template_filename))
+
+    # Set production datetime if not provided
+    if production_datetime is None:
+        production_datetime = datetime.now(timezone.utc)
+
+    # Set product counter if not provided
+    if product_counter is None:
+        product_counter = 1
+
+    # Format timestamp and generate granule ID
+    timestamp = f"{time_UTC:%Y%m%d}"
+    granule_ID = (
+        f"ECOv003_L2T_STARS_{tile}_{timestamp}_{build}_{product_counter:02d}"
+    )
+
+    # Define run-config filename and resolve absolute path
+    if runconfig_filename is None:
+        runconfig_filename = join(working_directory, "runconfig", f"{granule_ID}.xml")
+    runconfig_filename = abspath(expanduser(runconfig_filename))
+
+    # If the run-config file already exists, log and return its path
+    if exists(runconfig_filename):
+        logger.info(f"Run-config already exists {cl.file(runconfig_filename)}")
+        return runconfig_filename
+
+    # Resolve absolute paths for various directories if not already defined
+    working_directory = abspath(expanduser(working_directory))
+    if sources_directory is None:
+        sources_directory = join(working_directory, DEFAULT_STARS_SOURCES_DIRECTORY)
+    if indices_directory is None:
+        indices_directory = join(working_directory, DEFAULT_STARS_INDICES_DIRECTORY)
+    if model_directory is None:
+        model_directory = join(working_directory, DEFAULT_STARS_MODEL_DIRECTORY)
+
+    # Determine executable path; fall back to just the name if not found in PATH
+    if executable_filename is None:
+        executable_filename = which("L2T_STARS")
+    if executable_filename is None:
+        executable_filename = "L2T_STARS"
+
+    # Define output and log file paths
+    if output_directory is None:
+        output_directory = join(working_directory, DEFAULT_OUTPUT_DIRECTORY)
+    output_directory = abspath(expanduser(output_directory))
+    if log_filename is None:
+        log_filename = join(working_directory, "log", f"{granule_ID}.log")
+    log_filename = abspath(expanduser(log_filename))
+
+    # Get processing node hostname
+    if processing_node is None:
+        processing_node = socket.gethostname()
+
+    # Set Job ID and Instance ID
+    if job_ID is None:
+        job_ID = timestamp
+    if instance_ID is None:
+        instance_ID = str(uuid4())  # Generate a unique UUID for the instance
+
+    # Resolve absolute path for the input L2T_LSTE file
+    L2T_LSTE_filename = abspath(expanduser(L2T_LSTE_filename))
+
+    logger.info(f"Loading L2T_STARS template: {cl.file(template_filename)}")
+
+    # Read the XML template file content
+    with open(template_filename, "r") as file:
+        template = file.read()
+
+    # Replace placeholders in the template with actual values
+    logger.info(f"Orbit: {cl.val(orbit)}")
+    template = template.replace("orbit_number", f"{orbit:05d}")
+    logger.info(f"Scene: {cl.val(scene)}")
+    template = template.replace("scene_ID", f"{scene:03d}")
+    logger.info(f"Tile: {cl.val(tile)}")
+    template = template.replace("tile_ID", f"{tile}")
+    logger.info(f"L2T_LSTE file: {cl.file(L2T_LSTE_filename)}")
+    template = template.replace("L2T_LSTE_filename", L2T_LSTE_filename)
+    logger.info(f"Prior L2T_STARS file: {cl.file(prior_L2T_STARS_filename)}")
+    template = template.replace("prior_L2T_STARS_filename", prior_L2T_STARS_filename)
+    logger.info(f"Working directory: {cl.dir(working_directory)}")
+    template = template.replace("working_directory", working_directory)
+    logger.info(f"Sources directory: {cl.dir(sources_directory)}")
+    template = template.replace("sources_directory", sources_directory)
+    logger.info(f"Indices directory: {cl.dir(indices_directory)}")
+    template = template.replace("indices_directory", indices_directory)
+    logger.info(f"Model directory: {cl.dir(model_directory)}")
+    template = template.replace("model_directory", model_directory)
+    logger.info(f"Executable: {cl.file(executable_filename)}")
+    template = template.replace("executable_filename", executable_filename)
+    logger.info(f"Output directory: {cl.dir(output_directory)}")
+    template = template.replace("output_directory", output_directory)
+    logger.info(f"Run-config: {cl.file(runconfig_filename)}")
+    template = template.replace("runconfig_filename", runconfig_filename)
+    logger.info(f"Log: {cl.file(log_filename)}")
+    template = template.replace("log_filename", log_filename)
+    logger.info(f"Build: {cl.val(build)}")
+    template = template.replace("build_ID", build)
+    logger.info(f"Processing node: {cl.val(processing_node)}")
+    template = template.replace("processing_node", processing_node)
+    logger.info(f"Production date/time: {cl.time(production_datetime)}")
+    template = template.replace("production_datetime", f"{production_datetime:%Y-%m-%dT%H:%M:%SZ}")
+    logger.info(f"Job ID: {cl.val(job_ID)}")
+    template = template.replace("job_ID", job_ID)
+    logger.info(f"Instance ID: {cl.val(instance_ID)}")
+    template = template.replace("instance_ID", instance_ID)
+    logger.info(f"Product counter: {cl.val(product_counter)}")
+    template = template.replace("product_counter", f"{product_counter:02d}")
+
+    # Create the directory for the run-config file if it doesn't exist
+    makedirs(dirname(abspath(runconfig_filename)), exist_ok=True)
+    logger.info(f"Writing run-config file: {cl.file(runconfig_filename)}")
+
+    # Write the populated template to the run-config file
+    with open(runconfig_filename, "w") as file:
+        file.write(template)
+
+    logger.info(
+        f"Finished generating L2T_STARS run-config for orbit {cl.val(orbit)} scene {cl.val(scene)} ({timer.tocvalue():.2f} seconds)"
+    )
+
+    return

ECOv003_L2T_STARS/generate_NDVI_coarse_directory.py

@@ -0,0 +1,21 @@
+from .generate_input_staging_directory import generate_input_staging_directory
+
+def generate_NDVI_coarse_directory(
+        input_staging_directory: str, 
+        tile: str) -> str:
+    """
+    Generates the specific staging directory for coarse NDVI images.
+
+    Args:
+        input_staging_directory (str): The base input staging directory.
+        tile (str): The HLS tile ID.
+
+    Returns:
+        str: The full path to the coarse NDVI staging directory.
+    """
+    return generate_input_staging_directory(
+        input_staging_directory, 
+        tile, 
+        "NDVI_coarse"
+    )
+

ECOv003_L2T_STARS/generate_NDVI_coarse_image.py

@@ -0,0 +1,30 @@
+from typing import Union
+from datetime import date
+import numpy as np
+
+import rasters as rt
+from rasters import Raster, RasterGeometry
+
+from .VIIRS import VIIRSDownloaderAlbedo, VIIRSDownloaderNDVI
+
+def generate_NDVI_coarse_image(
+        date_UTC: Union[date, str], 
+        VIIRS_connection: VIIRSDownloaderNDVI, 
+        geometry: RasterGeometry = None) -> Raster:
+    """
+    Generates a coarse-resolution NDVI image from VIIRS data.
+
+    Args:
+        date_UTC (Union[date, str]): The UTC date for which to retrieve NDVI data.
+        VIIRS_connection (VIIRSDownloaderNDVI): An initialized VIIRS NDVI downloader object.
+        geometry (RasterGeometry, optional): The target geometry for the VIIRS image.
+                                            If None, the native VIIRS geometry is used.
+
+    Returns:
+        Raster: A Raster object representing the coarse-resolution NDVI image.
+                Zero values are converted to NaN.
+    """
+    coarse_image = VIIRS_connection.NDVI(date_UTC=date_UTC, geometry=geometry)
+    # Convert zero values (often used as NoData in some datasets) to NaN for proper handling
+    coarse_image = rt.where(coarse_image == 0, np.nan, coarse_image)
+    return coarse_image

ECOv003_L2T_STARS/generate_NDVI_fine_directory.py

@@ -0,0 +1,14 @@
+from .generate_input_staging_directory import generate_input_staging_directory
+
+def generate_NDVI_fine_directory(input_staging_directory: str, tile: str) -> str:
+    """
+    Generates the specific staging directory for fine NDVI images.
+
+    Args:
+        input_staging_directory (str): The base input staging directory.
+        tile (str): The HLS tile ID.
+
+    Returns:
+        str: The full path to the fine NDVI staging directory.
+    """
+    return generate_input_staging_directory(input_staging_directory, tile, "NDVI_fine")

ECOv003_L2T_STARS/generate_NDVI_fine_image.py

@@ -0,0 +1,28 @@
+from typing import Union
+from datetime import date
+import numpy as np
+import rasters as rt
+from rasters import Raster
+
+from harmonized_landsat_sentinel import HLS
+
+def generate_NDVI_fine_image(
+        date_UTC: Union[date, str], 
+        tile: str, 
+        HLS_connection: HLS) -> Raster:
+    """
+    Generates a fine-resolution NDVI image from HLS data.
+
+    Args:
+        date_UTC (Union[date, str]): The UTC date for which to retrieve NDVI data.
+        tile (str): The HLS tile ID.
+        HLS_connection (HLS): An initialized HLS data connection object.
+
+    Returns:
+        Raster: A Raster object representing the fine-resolution NDVI image.
+                Zero values are converted to NaN.
+    """
+    fine_image = HLS_connection.NDVI(tile=tile, date_UTC=date_UTC)
+    # Convert zero values to NaN for consistency
+    fine_image = rt.where(fine_image == 0, np.nan, fine_image)
+    return fine_image

ECOv003_L2T_STARS/generate_STARS_inputs.py

@@ -0,0 +1,231 @@
+from typing import Union
+from datetime import date, datetime
+from dateutil.rrule import rrule, DAILY
+import logging
+
+import colored_logging as cl
+from rasters import Raster, RasterGeometry
+from harmonized_landsat_sentinel import HLS2CMR
+
+from ECOv003_exit_codes import AuxiliaryLatency
+
+from .constants import VIIRS_GIVEUP_DAYS
+from .generate_filename import generate_filename
+from .daterange import get_date
+from .generate_NDVI_coarse_image import generate_NDVI_coarse_image
+from .generate_NDVI_fine_image import generate_NDVI_fine_image
+from .generate_albedo_coarse_image import generate_albedo_coarse_image
+from .generate_albedo_fine_image import generate_albedo_fine_image
+from .calibrate_fine_to_coarse import calibrate_fine_to_coarse
+from .VIIRS.VIIRSDownloader import VIIRSDownloaderAlbedo, VIIRSDownloaderNDVI
+
+logger = logging.getLogger(__name__)
+
+def generate_STARS_inputs(
+    tile: str,
+    date_UTC: date,
+    HLS_start_date: date,
+    HLS_end_date: date,
+    VIIRS_start_date: date,
+    VIIRS_end_date: date,
+    NDVI_resolution: int,
+    albedo_resolution: int,
+    target_resolution: int,
+    NDVI_coarse_geometry: RasterGeometry,
+    albedo_coarse_geometry: RasterGeometry,
+    working_directory: str,
+    NDVI_coarse_directory: str,
+    NDVI_fine_directory: str,
+    albedo_coarse_directory: str,
+    albedo_fine_directory: str,
+    HLS_connection: HLS2CMR,
+    NDVI_VIIRS_connection: VIIRSDownloaderNDVI,
+    albedo_VIIRS_connection: VIIRSDownloaderAlbedo,
+    calibrate_fine: bool = False,
+):
+    """
+    Generates and stages the necessary coarse and fine resolution input images
+    for the STARS data fusion process.
+
+    This function iterates through the VIIRS date range, retrieving and saving
+    coarse NDVI and albedo images. For dates within the HLS range, it also
+    retrieves and saves fine NDVI and albedo images. It can optionally
+    calibrate the fine images to the coarse images.
+
+    Args:
+        tile (str): The HLS tile ID.
+        date_UTC (date): The target UTC date for the L2T_STARS product.
+        HLS_start_date (date): The start date for HLS data retrieval for the fusion period.
+        HLS_end_date (date): The end date for HLS data retrieval for the fusion period.
+        VIIRS_start_date (date): The start date for VIIRS data retrieval for the fusion period.
+        VIIRS_end_date (date): The end date for VIIRS data retrieval for the fusion period.
+        NDVI_resolution (int): The resolution of the coarse NDVI data.
+        albedo_resolution (int): The resolution of the coarse albedo data.
+        target_resolution (int): The desired output resolution of the fused product.
+        NDVI_coarse_geometry (RasterGeometry): The target geometry for coarse NDVI images.
+        albedo_coarse_geometry (RasterGeometry): The target geometry for coarse albedo images.
+        working_directory (str): The main working directory.
+        NDVI_coarse_directory (str): Directory for staging coarse NDVI images.
+        NDVI_fine_directory (str): Directory for staging fine NDVI images.
+        albedo_coarse_directory (str): Directory for staging coarse albedo images.
+        albedo_fine_directory (str): Directory for staging fine albedo images.
+        HLS_connection (HLS2CMR): An initialized HLS data connection object.
+        NDVI_VIIRS_connection (VIIRSDownloaderNDVI): An initialized VIIRS NDVI downloader.
+        albedo_VIIRS_connection (VIIRSDownloaderAlbedo): An initialized VIIRS albedo downloader.
+        calibrate_fine (bool, optional): If True, calibrate fine images to coarse images.
+                                         Defaults to False.
+
+    Raises:
+        AuxiliaryLatency: If coarse VIIRS data is missing within the VIIRS_GIVEUP_DAYS window.
+    """
+    missing_coarse_dates = set()  # Track dates where coarse data could not be generated
+
+    # Process each day within the VIIRS data fusion window
+    for processing_date in [
+        get_date(dt) for dt in rrule(DAILY, dtstart=VIIRS_start_date, until=VIIRS_end_date)
+    ]:
+        logger.info(
+            f"Preparing coarse image for STARS NDVI at {cl.place(tile)} on {cl.time(processing_date)}"
+        )
+
+        try:
+            # Generate coarse NDVI image
+            NDVI_coarse_image = generate_NDVI_coarse_image(
+                date_UTC=processing_date,
+                VIIRS_connection=NDVI_VIIRS_connection,
+                geometry=NDVI_coarse_geometry,
+            )
+
+            # Define filename for coarse NDVI and save
+            NDVI_coarse_filename = generate_filename(
+                directory=NDVI_coarse_directory,
+                variable="NDVI",
+                date_UTC=processing_date,
+                tile=tile,
+                cell_size=NDVI_resolution,
+            )
+            logger.info(
+                f"Saving coarse image for STARS NDVI at {cl.place(tile)} on {cl.time(processing_date)}: {NDVI_coarse_filename}"
+            )
+            NDVI_coarse_image.to_geotiff(NDVI_coarse_filename)
+
+            # If the processing date is within the HLS range, generate fine NDVI
+            if processing_date >= HLS_start_date:
+                logger.info(
+                    f"Preparing fine image for STARS NDVI at {cl.place(tile)} on {cl.time(processing_date)}"
+                )
+                try:
+                    NDVI_fine_image = generate_NDVI_fine_image(
+                        date_UTC=processing_date,
+                        tile=tile,
+                        HLS_connection=HLS_connection,
+                    )
+
+                    # Optionally calibrate the fine NDVI image to the coarse NDVI image
+                    if calibrate_fine:
+                        logger.info(
+                            f"Calibrating fine image for STARS NDVI at {cl.place(tile)} on {cl.time(processing_date)}"
+                        )
+                        NDVI_fine_image = calibrate_fine_to_coarse(
+                            NDVI_fine_image, NDVI_coarse_image
+                        )
+
+                    # Define filename for fine NDVI and save
+                    NDVI_fine_filename = generate_filename(
+                        directory=NDVI_fine_directory,
+                        variable="NDVI",
+                        date_UTC=processing_date,
+                        tile=tile,
+                        cell_size=target_resolution,
+                    )
+                    logger.info(
+                        f"Saving fine image for STARS NDVI at {cl.place(tile)} on {cl.time(processing_date)}: {NDVI_fine_filename}"
+                    )
+                    NDVI_fine_image.to_geotiff(NDVI_fine_filename)
+                except Exception:  # Catch any exception during HLS fine image generation
+                    logger.info(f"HLS NDVI is not available on {processing_date}")
+        except Exception as e:
+            logger.exception(e)
+            logger.warning(
+                f"Unable to produce coarse NDVI for date {processing_date}"
+            )
+            missing_coarse_dates.add(processing_date)  # Add date to missing set
+
+        logger.info(
+            f"Preparing coarse image for STARS albedo at {cl.place(tile)} on {cl.time(processing_date)}"
+        )
+        try:
+            # Generate coarse albedo image
+            albedo_coarse_image = generate_albedo_coarse_image(
+                date_UTC=processing_date,
+                VIIRS_connection=albedo_VIIRS_connection,
+                geometry=albedo_coarse_geometry,
+            )
+
+            # Define filename for coarse albedo and save
+            albedo_coarse_filename = generate_filename(
+                directory=albedo_coarse_directory,
+                variable="albedo",
+                date_UTC=processing_date,
+                tile=tile,
+                cell_size=albedo_resolution,
+            )
+            logger.info(
+                f"Saving coarse image for STARS albedo at {cl.place(tile)} on {cl.time(processing_date)}: {albedo_coarse_filename}"
+            )
+            albedo_coarse_image.to_geotiff(albedo_coarse_filename)
+
+            # If the processing date is within the HLS range, generate fine albedo
+            if processing_date >= HLS_start_date:
+                logger.info(
+                    f"Preparing fine image for STARS albedo at {cl.place(tile)} on {cl.time(processing_date)}"
+                )
+                try:
+                    albedo_fine_image = generate_albedo_fine_image(
+                        date_UTC=processing_date,
+                        tile=tile,
+                        HLS_connection=HLS_connection,
+                    )
+
+                    # Optionally calibrate the fine albedo image to the coarse albedo image
+                    if calibrate_fine:
+                        logger.info(
+                            f"Calibrating fine image for STARS albedo at {cl.place(tile)} on {cl.time(processing_date)}"
+                        )
+                        albedo_fine_image = calibrate_fine_to_coarse(
+                            albedo_fine_image, albedo_coarse_image
+                        )
+
+                    # Define filename for fine albedo and save
+                    albedo_fine_filename = generate_filename(
+                        directory=albedo_fine_directory,
+                        variable="albedo",
+                        date_UTC=processing_date,
+                        tile=tile,
+                        cell_size=target_resolution,
+                    )
+                    logger.info(
+                        f"Saving fine image for STARS albedo at {cl.place(tile)} on {cl.time(processing_date)}: {albedo_fine_filename}"
+                    )
+                    albedo_fine_image.to_geotiff(albedo_fine_filename)
+                except Exception:  # Catch any exception during HLS fine image generation
+                    logger.info(f"HLS albedo is not available on {processing_date}")
+        except Exception as e:
+            logger.exception(e)
+            logger.warning(
+                f"Unable to produce coarse albedo for date {processing_date}"
+            )
+            missing_coarse_dates.add(processing_date)  # Add date to missing set
+
+    # Check for missing coarse dates within the give-up window
+    coarse_latency_dates = [
+        d
+        for d in missing_coarse_dates
+        if (datetime.utcnow().date() - d).days <= VIIRS_GIVEUP_DAYS
+    ]
+
+    if len(coarse_latency_dates) > 0:
+        raise AuxiliaryLatency(
+            f"Missing coarse dates within {VIIRS_GIVEUP_DAYS}-day window: "
+            f"{', '.join([str(d) for d in sorted(list(coarse_latency_dates))])}"
+        )

ECOv003_L2T_STARS/generate_albedo_coarse_directory.py

@@ -0,0 +1,18 @@
+
+from .generate_input_staging_directory import generate_input_staging_directory
+
+
+def generate_albedo_coarse_directory(input_staging_directory: str, tile: str) -> str:
+    """
+    Generates the specific staging directory for coarse albedo images.
+
+    Args:
+        input_staging_directory (str): The base input staging directory.
+        tile (str): The HLS tile ID.
+
+    Returns:
+        str: The full path to the coarse albedo staging directory.
+    """
+    return generate_input_staging_directory(
+        input_staging_directory, tile, "albedo_coarse"
+    )

ECOv003_L2T_STARS/generate_albedo_coarse_image.py

@@ -0,0 +1,30 @@
+from typing import Union
+from datetime import date
+
+import numpy as np
+
+import rasters as rt
+from rasters import Raster, RasterGeometry
+
+from .VIIRS.VIIRSDownloader import VIIRSDownloaderAlbedo
+
+def generate_albedo_coarse_image(
+    date_UTC: Union[date, str], VIIRS_connection: VIIRSDownloaderAlbedo, geometry: RasterGeometry = None
+) -> Raster:
+    """
+    Generates a coarse-resolution albedo image from VIIRS data.
+
+    Args:
+        date_UTC (Union[date, str]): The UTC date for which to retrieve albedo data.
+        VIIRS_connection (VIIRSDownloaderAlbedo): An initialized VIIRS albedo downloader object.
+        geometry (RasterGeometry, optional): The target geometry for the VIIRS image.
+                                            If None, the native VIIRS geometry is used.
+
+    Returns:
+        Raster: A Raster object representing the coarse-resolution albedo image.
+                Zero values are converted to NaN.
+    """
+    coarse_image = VIIRS_connection.albedo(date_UTC=date_UTC, geometry=geometry)
+    # Convert zero values to NaN for consistency
+    coarse_image = rt.where(coarse_image == 0, np.nan, coarse_image)
+    return coarse_image

ECOv003_L2T_STARS/generate_albedo_fine_directory.py

@@ -0,0 +1,17 @@
+
+from .generate_input_staging_directory import generate_input_staging_directory
+
+def generate_albedo_fine_directory(input_staging_directory: str, tile: str) -> str:
+    """
+    Generates the specific staging directory for fine albedo images.
+
+    Args:
+        input_staging_directory (str): The base input staging directory.
+        tile (str): The HLS tile ID.
+
+    Returns:
+        str: The full path to the fine albedo staging directory.
+    """
+    return generate_input_staging_directory(
+        input_staging_directory, tile, "albedo_fine"
+    )

ECOv003_L2T_STARS/generate_albedo_fine_image.py

@@ -0,0 +1,30 @@
+from typing import Union
+from datetime import date
+
+import numpy as np
+
+import rasters as rt
+from rasters import Raster
+
+from harmonized_landsat_sentinel import HLS
+
+def generate_albedo_fine_image(
+        date_UTC: Union[date, str], 
+        tile: str, 
+        HLS_connection: HLS) -> Raster:
+    """
+    Generates a fine-resolution albedo image from HLS data.
+
+    Args:
+        date_UTC (Union[date, str]): The UTC date for which to retrieve albedo data.
+        tile (str): The HLS tile ID.
+        HLS_connection (HLS): An initialized HLS data connection object.
+
+    Returns:
+        Raster: A Raster object representing the fine-resolution albedo image.
+                Zero values are converted to NaN.
+    """
+    fine_image = HLS_connection.albedo(tile=tile, date_UTC=date_UTC)
+    # Convert zero values to NaN for consistency
+    fine_image = rt.where(fine_image == 0, np.nan, fine_image)
+    return fine_image