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

ECOv003_L2T_STARS/generate_filename.py

@@ -0,0 +1,37 @@
+from typing import Union
+from os import makedirs
+from os.path import join, dirname, abspath
+from datetime import date
+
+from dateutil import parser
+
+def generate_filename(
+    directory: str, variable: str, date_UTC: Union[date, str], tile: str, cell_size: int
+) -> str:
+    """
+    Generates a standardized filename for a raster product and ensures its directory exists.
+
+    The filename format is STARS_{variable}_{YYYY-MM-DD}_{tile}_{cell_size}m.tif.
+
+    Args:
+        directory (str): The base directory where the file will be saved.
+        variable (str): The name of the variable (e.g., "NDVI", "albedo").
+        date_UTC (Union[date, str]): The UTC date of the data. Can be a date object or a string.
+        tile (str): The HLS tile ID (e.g., 'H09V05').
+        cell_size (int): The spatial resolution in meters (e.g., 70, 490, 980).
+
+    Returns:
+        str: The full, standardized path to the generated filename.
+    """
+    if isinstance(date_UTC, str):
+        date_UTC = parser.parse(date_UTC).date()
+
+    variable = str(variable)
+    timestamp = date_UTC.strftime("%Y-%m-%d")
+    tile = str(tile)
+    cell_size = int(cell_size)
+    filename = join(directory, f"STARS_{variable}_{timestamp}_{tile}_{cell_size}m.tif")
+    # Ensure the directory structure for the file exists
+    makedirs(dirname(filename), exist_ok=True)
+
+    return filename

ECOv003_L2T_STARS/generate_input_staging_directory.py

@@ -0,0 +1,23 @@
+from os import makedirs
+from os.path import join
+
+def generate_input_staging_directory(
+        input_staging_directory: str, 
+        tile: str, 
+        prefix: str) -> str:
+    """
+    Generates a path for an input staging directory and ensures it exists.
+
+    This is used to organize temporary input files for the Julia processing.
+
+    Args:
+        input_staging_directory (str): The base input staging directory.
+        tile (str): The HLS tile ID.
+        prefix (str): A prefix for the sub-directory name (e.g., "NDVI_coarse").
+
+    Returns:
+        str: The full path to the created or existing staging directory.
+    """
+    directory = join(input_staging_directory, f"{prefix}_{tile}")
+    makedirs(directory, exist_ok=True)  # Create directory if it doesn't exist
+    return directory

ECOv003_L2T_STARS/generate_model_state_tile_date_directory.py

@@ -0,0 +1,28 @@
+from typing import Union
+from datetime import date
+from os import makedirs
+from os.path import join
+
+from dateutil import parser
+
+def generate_model_state_tile_date_directory(
+    model_directory: str, tile: str, date_UTC: Union[date, str]
+) -> str:
+    """
+    Generates a directory for storing model state files (e.g., priors, posteriors)
+    organized by tile and date, and ensures it exists.
+
+    Args:
+        model_directory (str): The base directory for model state files.
+        tile (str): The HLS tile ID.
+        date_UTC (Union[date, str]): The UTC date for the model state.
+
+    Returns:
+        str: The full path to the created or existing model state directory.
+    """
+    if isinstance(date_UTC, str):
+        date_UTC = parser.parse(date_UTC).date()
+
+    directory = join(model_directory, tile, f"{date_UTC:%Y-%m-%d}")
+    makedirs(directory, exist_ok=True)  # Create directory if it doesn't exist
+    return directory

ECOv003_L2T_STARS/generate_output_directory.py

@@ -0,0 +1,28 @@
+from typing import Union
+from datetime import date
+from os import makedirs
+from os.path import join
+
+from dateutil import parser
+
+def generate_output_directory(
+        working_directory: str, 
+        date_UTC: Union[date, str], 
+        tile: str) -> str:
+    """
+    Generates a dated output directory for Julia model results and ensures it exists.
+
+    Args:
+        working_directory (str): The main working directory.
+        date_UTC (Union[date, str]): The UTC date for the output.
+        tile (str): The HLS tile ID.
+
+    Returns:
+        str: The full path to the created or existing output directory.
+    """
+    if isinstance(date_UTC, str):
+        date_UTC = parser.parse(date_UTC).date()
+
+    directory = join(working_directory, f"julia_output_{date_UTC:%y.%m.%d}_{tile}")
+    makedirs(directory, exist_ok=True)  # Create directory if it doesn't exist
+    return directory

ECOv003_L2T_STARS/install_STARS_jl.py

@@ -0,0 +1,43 @@
+import subprocess
+import logging
+
+logger = logging.getLogger(__name__)
+
+def install_STARS_jl(
+    github_URL: str = "https://github.com/STARS-Data-Fusion/STARS.jl",
+    environment_name: str = "@ECOv003-L2T-STARS") -> subprocess.CompletedProcess:
+    """
+    Installs the STARS.jl Julia package from GitHub into a specified Julia environment.
+
+    This function executes a Julia command to activate a given environment and
+    then develops (installs in editable mode) the STARS.jl package from its
+    GitHub repository.
+
+    Args:
+        github_URL (str, optional): The URL of the GitHub repository containing STARS.jl.
+                                    Defaults to "https://github.com/STARS-Data-Fusion/STARS.jl".
+        environment_name (str, optional): The name of the Julia environment to install
+                                          the package into. Defaults to "@ECOv003-L2T-STARS".
+
+    Returns:
+        subprocess.CompletedProcess: An object containing information about the
+                                     execution of the Julia command (return code, stdout, stderr).
+    """
+    # Julia command to activate an environment and then add/develop a package from URL
+    julia_command = [
+        "julia",
+        "-e",
+        f'using Pkg; Pkg.activate("{environment_name}"); Pkg.develop(url="{github_URL}")',
+    ]
+
+    # Execute the Julia command as a subprocess
+    result = subprocess.run(julia_command, capture_output=True, text=True, check=False)
+
+    if result.returncode == 0:
+        logger.info(
+            f"STARS.jl installed successfully in environment '{environment_name}'!"
+        )
+    else:
+        logger.error("Error installing STARS.jl:")
+        logger.error(result.stderr)
+    return result

ECOv003_L2T_STARS/instantiate_STARS_jl.py

@@ -0,0 +1,38 @@
+import subprocess
+import logging
+
+logger = logging.getLogger(__name__)
+
+def instantiate_STARS_jl(package_location: str) -> subprocess.CompletedProcess:
+    """
+    Activates a Julia project at a given location and instantiates its dependencies.
+
+    This is necessary to ensure all required Julia packages for STARS.jl are
+    downloaded and ready for use within the specified project environment.
+
+    Args:
+        package_location (str): The directory of the Julia package (where Project.toml is located)
+                                to activate and instantiate.
+
+    Returns:
+        subprocess.CompletedProcess: An object containing information about the
+                                     execution of the Julia command (return code, stdout, stderr).
+    """
+    # Julia command to activate a specific package location and then instantiate its dependencies
+    julia_command = [
+        "julia",
+        "-e",
+        f'using Pkg; Pkg.activate("{package_location}"); Pkg.instantiate()',
+    ]
+
+    # Execute the Julia command as a subprocess
+    result = subprocess.run(julia_command, capture_output=True, text=True, check=False)
+
+    if result.returncode == 0:
+        logger.info(
+            f"STARS.jl instantiated successfully in directory '{package_location}'!"
+        )
+    else:
+        logger.error("Error instantiating STARS.jl:")
+        logger.error(result.stderr)
+    return result

ECOv003_L2T_STARS/load_prior.py

@@ -0,0 +1,248 @@
+from os.path import exists
+import logging
+
+from ECOv003_granules import L2TSTARS
+
+from .prior import Prior
+from .generate_filename import generate_filename
+from .generate_model_state_tile_date_directory import generate_model_state_tile_date_directory
+
+logger = logging.getLogger(__name__)
+
+def load_prior(
+        tile: str, 
+        target_resolution: int, 
+        model_directory: str, 
+        L2T_STARS_prior_filename: str) -> Prior:
+    """
+    Loads a prior L2T_STARS product if available and extracts its components.
+
+    This function attempts to load a previously generated L2T_STARS product
+    to use its NDVI and albedo mean, uncertainty, and bias as prior information
+    for the current data fusion run.
+
+    Args:
+        tile (str): The HLS tile ID.
+        target_resolution (int): The target resolution of the L2T_STARS product.
+        model_directory (str): The base directory for model state files.
+        L2T_STARS_prior_filename (str): The filename of the prior L2T_STARS product (zip file).
+
+    Returns:
+        Prior: A Prior object containing paths to the prior data components
+               and a flag indicating if a valid prior was loaded.
+    """
+    using_prior = False
+    prior_date_UTC = None
+    prior_NDVI_filename = None
+    prior_NDVI_UQ_filename = None
+    prior_NDVI_bias_filename = None
+    prior_NDVI_bias_UQ_filename = None
+    prior_albedo_filename = None
+    prior_albedo_UQ_filename = None
+    prior_albedo_bias_filename = None
+    prior_albedo_bias_UQ_filename = None
+
+    # Check if a prior L2T_STARS product is specified and exists
+    if L2T_STARS_prior_filename is not None and exists(L2T_STARS_prior_filename):
+        logger.info(f"Loading prior L2T STARS product: {L2T_STARS_prior_filename}")
+        try:
+            # Initialize L2TSTARS object from the prior product
+            L2T_STARS_prior_granule = L2TSTARS(L2T_STARS_prior_filename)
+            prior_date_UTC = L2T_STARS_prior_granule.date_UTC
+            logger.info(f"Prior date: {cl.time(prior_date_UTC)}")
+
+            # Extract NDVI and albedo mean and uncertainty rasters
+            NDVI_prior_mean = L2T_STARS_prior_granule.NDVI
+            NDVI_prior_UQ = L2T_STARS_prior_granule.NDVI_UQ
+            albedo_prior_mean = L2T_STARS_prior_granule.albedo
+            albedo_prior_UQ = L2T_STARS_prior_granule.albedo_UQ
+
+            # Define the directory for storing prior model state files
+            prior_tile_date_directory = generate_model_state_tile_date_directory(
+                model_directory=model_directory, tile=tile, date_UTC=prior_date_UTC
+            )
+
+            # Generate and save filenames for all prior components
+            prior_NDVI_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="NDVI",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            NDVI_prior_mean.to_geotiff(prior_NDVI_filename)
+
+            prior_NDVI_UQ_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="NDVI.UQ",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            NDVI_prior_UQ.to_geotiff(prior_NDVI_UQ_filename)
+
+            # Note: Prior bias files might not always exist in older products.
+            # Assuming they could be extracted from L2T_STARS_prior_granule if present.
+            # For simplicity, these are placeholders and would need proper extraction logic
+            # from the L2TSTARS granule if they are actual components.
+            # For now, we set them based on `generate_filename` only if a bias layer is retrieved.
+            # If the bias layers are not explicitly part of `L2TSTARS` object, these will be None
+            # unless written explicitly during prior creation.
+            prior_NDVI_bias_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="NDVI.bias",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            # Assuming L2T_STARS_prior_granule has a .NDVI_bias attribute
+            if hasattr(L2T_STARS_prior_granule, "NDVI_bias") and L2T_STARS_prior_granule.NDVI_bias is not None:
+                L2T_STARS_prior_granule.NDVI_bias.to_geotiff(prior_NDVI_bias_filename)
+            else:
+                prior_NDVI_bias_filename = None # Set to None if not available
+
+            prior_NDVI_bias_UQ_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="NDVI.bias.UQ",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            # Assuming L2T_STARS_prior_granule has a .NDVI_bias_UQ attribute
+            if hasattr(L2T_STARS_prior_granule, "NDVI_bias_UQ") and L2T_STARS_prior_granule.NDVI_bias_UQ is not None:
+                L2T_STARS_prior_granule.NDVI_bias_UQ.to_geotiff(prior_NDVI_bias_UQ_filename)
+            else:
+                prior_NDVI_bias_UQ_filename = None # Set to None if not available
+
+
+            prior_albedo_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="albedo",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            albedo_prior_mean.to_geotiff(prior_albedo_filename)
+
+            prior_albedo_UQ_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="albedo.UQ",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            albedo_prior_UQ.to_geotiff(prior_albedo_UQ_filename)
+
+            prior_albedo_bias_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="albedo.bias",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            # Assuming L2T_STARS_prior_granule has a .albedo_bias attribute
+            if hasattr(L2T_STARS_prior_granule, "albedo_bias") and L2T_STARS_prior_granule.albedo_bias is not None:
+                L2T_STARS_prior_granule.albedo_bias.to_geotiff(prior_albedo_bias_filename)
+            else:
+                prior_albedo_bias_filename = None # Set to None if not available
+
+            prior_albedo_bias_UQ_filename = generate_filename(
+                directory=prior_tile_date_directory,
+                variable="albedo.bias.UQ",
+                date_UTC=prior_date_UTC,
+                tile=tile,
+                cell_size=target_resolution,
+            )
+            # Assuming L2T_STARS_prior_granule has a .albedo_bias_UQ attribute
+            if hasattr(L2T_STARS_prior_granule, "albedo_bias_UQ") and L2T_STARS_prior_granule.albedo_bias_UQ is not None:
+                L2T_STARS_prior_granule.albedo_bias_UQ.to_geotiff(prior_albedo_bias_UQ_filename)
+            else:
+                prior_albedo_bias_UQ_filename = None # Set to None if not available
+
+
+            using_prior = True # Mark that a prior was successfully loaded
+        except Exception as e:
+            logger.warning(f"Could not load prior L2T STARS product: {L2T_STARS_prior_filename}. Reason: {e}")
+            using_prior = False # Ensure using_prior is False if loading fails
+
+    # Verify that all expected prior files exist, otherwise disable using_prior
+    # This ensures a partial prior (e.g., only NDVI but not albedo) isn't used
+    if prior_NDVI_filename is not None and exists(prior_NDVI_filename):
+        logger.info(f"Prior NDVI ready: {prior_NDVI_filename}")
+    else:
+        logger.info(f"Prior NDVI not found: {prior_NDVI_filename}")
+        using_prior = False
+
+    if prior_NDVI_UQ_filename is not None and exists(prior_NDVI_UQ_filename):
+        logger.info(f"Prior NDVI UQ ready: {prior_NDVI_UQ_filename}")
+    else:
+        logger.info(f"Prior NDVI UQ not found: {prior_NDVI_UQ_filename}")
+        using_prior = False
+
+    if prior_NDVI_bias_filename is not None and exists(prior_NDVI_bias_filename):
+        logger.info(f"Prior NDVI bias ready: {prior_NDVI_bias_filename}")
+    else:
+        logger.info(f"Prior NDVI bias not found: {prior_NDVI_bias_filename}")
+        using_prior = False
+
+    if prior_NDVI_bias_UQ_filename is not None and exists(prior_NDVI_bias_UQ_filename):
+        logger.info(f"Prior NDVI bias UQ ready: {prior_NDVI_bias_UQ_filename}")
+    else:
+        logger.info(f"Prior NDVI bias UQ not found: {prior_NDVI_bias_UQ_filename}")
+        using_prior = False
+
+    if prior_albedo_filename is not None and exists(prior_albedo_filename):
+        logger.info(f"Prior albedo ready: {prior_albedo_filename}")
+    else:
+        logger.info(f"Prior albedo not found: {prior_albedo_filename}")
+        using_prior = False
+
+    if prior_albedo_UQ_filename is not None and exists(prior_albedo_UQ_filename):
+        logger.info(f"Prior albedo UQ ready: {prior_albedo_UQ_filename}")
+    else:
+        logger.info(f"Prior albedo UQ not found: {prior_albedo_UQ_filename}")
+        using_prior = False
+
+    if prior_albedo_bias_filename is not None and exists(prior_albedo_bias_filename):
+        logger.info(f"Prior albedo bias ready: {prior_albedo_bias_filename}")
+    else:
+        logger.info(f"Prior albedo bias not found: {prior_albedo_bias_filename}")
+        using_prior = False
+
+    if prior_albedo_bias_UQ_filename is not None and exists(
+        prior_albedo_bias_UQ_filename
+    ):
+        logger.info(f"Prior albedo bias UQ ready: {prior_albedo_bias_UQ_filename}")
+    else:
+        logger.info(f"Prior albedo bias UQ not found: {prior_albedo_bias_UQ_filename}")
+        using_prior = False
+    
+    # Final check: if any of the critical prior files are missing, do not use prior
+    if not all([prior_NDVI_filename, prior_NDVI_UQ_filename, prior_albedo_filename, prior_albedo_UQ_filename]):
+        logger.warning("One or more required prior (mean/UQ) files are missing. Prior will not be used.")
+        using_prior = False
+        prior_NDVI_filename = None
+        prior_NDVI_UQ_filename = None
+        prior_albedo_filename = None
+        prior_albedo_UQ_filename = None
+
+    # FIXME where are `prior_NDVI_flag_filename` and `prior_albedo_flag_filename` defined?
+
+    # Create and return the Prior object
+    prior = Prior(
+        using_prior=using_prior,
+        prior_date_UTC=prior_date_UTC,
+        L2T_STARS_prior_filename=L2T_STARS_prior_filename,
+        prior_NDVI_filename=prior_NDVI_filename,
+        prior_NDVI_UQ_filename=prior_NDVI_UQ_filename,
+        prior_NDVI_flag_filename=prior_NDVI_flag_filename,
+        prior_NDVI_bias_filename=prior_NDVI_bias_filename,
+        prior_NDVI_bias_UQ_filename=prior_NDVI_bias_UQ_filename,
+        prior_albedo_filename=prior_albedo_filename,
+        prior_albedo_UQ_filename=prior_albedo_UQ_filename,
+        prior_albedo_flag_filename=prior_albedo_flag_filename,
+        prior_albedo_bias_filename=prior_albedo_bias_filename,
+        prior_albedo_bias_UQ_filename=prior_albedo_bias_UQ_filename,
+    )
+
+    return prior

ECOv003_L2T_STARS/prior.py

@@ -0,0 +1,56 @@
+from datetime import date
+
+class Prior:
+    """
+    A data class to encapsulate information about a prior L2T_STARS product.
+
+    This class holds filenames and flags related to the use of a previous
+    STARS product as a 'prior' in the data fusion process. This can help
+    to constrain the solution and improve accuracy, especially when
+    observations for the current date are sparse.
+
+    Attributes:
+        using_prior (bool): True if a prior product is being used, False otherwise.
+        prior_date_UTC (date): The UTC date of the prior product.
+        L2T_STARS_prior_filename (str): Path to the prior L2T_STARS zip file.
+        prior_NDVI_filename (str): Path to the prior NDVI mean file.
+        prior_NDVI_UQ_filename (str): Path to the prior NDVI uncertainty (UQ) file.
+        prior_NDVI_flag_filename (str): Path to the prior NDVI flag file.
+        prior_NDVI_bias_filename (str): Path to the prior NDVI bias file.
+        prior_NDVI_bias_UQ_filename (str): Path to the prior NDVI bias uncertainty file.
+        prior_albedo_filename (str): Path to the prior albedo mean file.
+        prior_albedo_UQ_filename (str): Path to the prior albedo uncertainty (UQ) file.
+        prior_albedo_flag_filename (str): Path to the prior albedo flag file.
+        prior_albedo_bias_filename (str): Path to the prior albedo bias file.
+        prior_albedo_bias_UQ_filename (str): Path to the prior albedo bias uncertainty file.
+    """
+
+    def __init__(
+        self,
+        using_prior: bool = False,
+        prior_date_UTC: date = None,
+        L2T_STARS_prior_filename: str = None,
+        prior_NDVI_filename: str = None,
+        prior_NDVI_UQ_filename: str = None,
+        prior_NDVI_flag_filename: str = None,
+        prior_NDVI_bias_filename: str = None,
+        prior_NDVI_bias_UQ_filename: str = None,
+        prior_albedo_filename: str = None,
+        prior_albedo_UQ_filename: str = None,
+        prior_albedo_flag_filename: str = None,
+        prior_albedo_bias_filename: str = None,
+        prior_albedo_bias_UQ_filename: str = None,
+    ):
+        self.using_prior = using_prior
+        self.prior_date_UTC = prior_date_UTC
+        self.L2T_STARS_prior_filename = L2T_STARS_prior_filename
+        self.prior_NDVI_filename = prior_NDVI_filename
+        self.prior_NDVI_UQ_filename = prior_NDVI_UQ_filename
+        self.prior_NDVI_flag_filename = prior_NDVI_flag_filename
+        self.prior_NDVI_bias_filename = prior_NDVI_bias_filename
+        self.prior_NDVI_bias_UQ_filename = prior_NDVI_bias_UQ_filename
+        self.prior_albedo_filename = prior_albedo_filename
+        self.prior_albedo_UQ_filename = prior_albedo_UQ_filename
+        self.prior_albedo_flag_filename = prior_albedo_flag_filename
+        self.prior_albedo_bias_filename = prior_albedo_bias_filename
+        self.prior_albedo_bias_UQ_filename = prior_albedo_bias_UQ_filename