STIC-JPL 1.2.1__tar.gz → 1.2.2__tar.gz

{stic_jpl-1.2.1 → stic_jpl-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: STIC-JPL
-Version: 1.2.1
+Version: 1.2.2
 Summary: Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
 Author-email: Gregory Halverson <gregory.h.halverson@jpl.nasa.gov>, Kaniska Mallick <kaniska.mallick@list.lu>, Madeleine Pascolini-Campbell <madeleine.a.pascolini-campbell@jpl.nasa.gov>, "Claire S. Villanueva-Weeks" <claire.s.villanueva-weeks@jpl.gov>
 Project-URL: Homepage, https://github.com/JPL-Evapotranspiration-Algorithms/STIC-JPL
@@ -8,6 +8,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Requires-Dist: check-distribution
 Requires-Dist: colored-logging
 Requires-Dist: ECOv002-CMR>=1.0.5
 Requires-Dist: ECOv002-granules>=1.0.3
@@ -16,6 +17,7 @@ Requires-Dist: GEOS5FP>=1.1.1
 Requires-Dist: monte-carlo-sensitivity
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: pytictoc
 Requires-Dist: rasters>=1.4.6
 Requires-Dist: seaborn
 Requires-Dist: SEBAL-soil-heat-flux

stic_jpl-1.2.2/STIC_JPL/FVC_from_NDVI.py

@@ -0,0 +1,49 @@
+from typing import Union
+import numpy as np
+import rasters as rt
+from rasters import Raster
+
+KPAR = 0.5
+MIN_FIPAR = 0.0
+MAX_FIPAR = 1.0
+MIN_LAI = 0.0
+MAX_LAI = 10.0
+
+def FVC_from_NDVI(NDVI: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
+    """
+    Estimate Fractional Vegetation Cover (FVC) from Normalized Difference Vegetation Index (NDVI)
+    using a scaled NDVI approach.
+
+    This method linearly scales NDVI values between two endmembers:
+        - NDVIs: NDVI value for bare soil (typically ~0.04 ± 0.03)
+        - NDVIv: NDVI value for full vegetation (typically ~0.52 ± 0.03)
+
+    The resulting Fractional Vegetation Cover (FVC) is calculated as:
+
+        FVC = clip((NDVI - NDVIs) / (NDVIv - NDVIs), 0.0, 1.0)
+
+    This approach is based on the assumption that NDVI increases linearly with vegetation cover
+    between these two extremes, and is well-supported in the literature.
+
+    References:
+        Carlson, T. N., & Ripley, D. A. (1997). On the relation between NDVI, fractional vegetation cover,
+        and leaf area index. Remote Sensing of Environment, 62(3), 241–252.
+        https://doi.org/10.1016/S0034-4257(97)00104-1
+
+        Gutman, G., & Ignatov, A. (1998). The derivation of the green vegetation fraction from NOAA/AVHRR
+        data for use in numerical weather prediction models. International Journal of Remote Sensing,
+        19(8), 1533–1543. https://doi.org/10.1080/014311698215333
+
+    Parameters:
+        NDVI (Union[Raster, np.ndarray]): Input NDVI data.
+
+    Returns:
+        Union[Raster, np.ndarray]: Estimated Fractional Vegetation Cover (FVC).
+    """
+    NDVIv = 0.52  # NDVI for fully vegetated pixel
+    NDVIs = 0.04  # NDVI for bare soil pixel
+
+    # Scale NDVI to FVC using a linear model and clip to [0, 1]
+    FVC = rt.clip((NDVI - NDVIs) / (NDVIv - NDVIs), 0.0, 1.0)
+
+    return FVC

stic_jpl-1.2.2/STIC_JPL/LAI_from_NDVI.py

@@ -0,0 +1,61 @@
+from typing import Union
+import numpy as np
+import rasters as rt
+from rasters import Raster
+
+# Constants
+KPAR = 0.5  # Extinction coefficient for PAR, assumed average for broadleaf canopies (Weiss & Baret, 2010)
+MIN_FIPAR = 0.0
+MAX_FIPAR = 1.0
+MIN_LAI = 0.0
+MAX_LAI = 10.0
+
+def LAI_from_NDVI(
+        NDVI: Union[Raster, np.ndarray],
+        min_fIPAR: float = MIN_FIPAR,
+        max_fIPAR: float = MAX_FIPAR,
+        min_LAI: float = MIN_LAI,
+        max_LAI: float = MAX_LAI) -> Union[Raster, np.ndarray]:
+    """
+    Estimate Leaf Area Index (LAI) from NDVI using a simplified two-step empirical model.
+
+    This method first approximates the fraction of absorbed photosynthetically active radiation (fIPAR)
+    from NDVI, and then estimates LAI using the Beer–Lambert Law. The extinction coefficient for PAR (KPAR)
+    is assumed to be 0.5, which is typical for broadleaf canopies under diffuse light conditions.
+
+    Steps:
+    1. fIPAR ≈ NDVI - 0.05 (empirical offset to account for soil background and sensor noise)
+       - Based on observed relationships in Myneni & Williams (1994)
+    2. LAI = -ln(1 - fIPAR) / KPAR (Beer–Lambert Law)
+       - From Sellers (1985)
+
+    All outputs are clipped to user-defined minimum and maximum thresholds to ensure physical realism.
+
+    Parameters:
+        NDVI (Union[Raster, np.ndarray]): Input NDVI data.
+        min_fIPAR (float): Minimum fIPAR value for clipping (default 0.0).
+        max_fIPAR (float): Maximum fIPAR value for clipping (default 1.0).
+        min_LAI (float): Minimum LAI value for clipping (default 0.0).
+        max_LAI (float): Maximum LAI value for clipping (default 10.0).
+
+    Returns:
+        Union[Raster, np.ndarray]: Estimated LAI values.
+
+    References:
+        - Sellers, P. J. (1985). Canopy reflectance, photosynthesis and transpiration. 
+          *International Journal of Remote Sensing*, 6(8), 1335–1372.
+        - Myneni, R. B., & Williams, D. L. (1994). On the relationship between FAPAR and NDVI. 
+          *Remote Sensing of Environment*, 49(3), 200–211.
+        - Weiss, M., & Baret, F. (2010). CAN-EYE V6.1 User Manual. INRA-CSE.
+
+    """
+    # Empirical conversion from NDVI to fIPAR (adjusted for background noise)
+    fIPAR = rt.clip(NDVI - 0.05, min_fIPAR, max_fIPAR)
+
+    # Avoid division by zero or log of 0 by masking zero fIPAR values
+    fIPAR = np.where(fIPAR == 0, np.nan, fIPAR)
+
+    # Apply Beer–Lambert law to estimate LAI
+    LAI = rt.clip(-np.log(1 - fIPAR) * (1 / KPAR), min_LAI, max_LAI)
+
+    return LAI

{stic_jpl-1.2.1 → stic_jpl-1.2.2}/STIC_JPL/model.py

@@ -5,8 +5,11 @@ from os.path import join, abspath, expanduser
 from typing import Dict, List
 import numpy as np
 import warnings
-from .diagnostic import diagnostic
+
+from pytictoc import TicToc
+
 import colored_logging as cl
+from check_distribution import check_distribution
 import rasters as rt
 from GEOS5FP import GEOS5FP
 from solar_apparent_time import solar_day_of_year_for_area, solar_hour_of_day_for_area
@@ -29,8 +32,6 @@ from .FVC_from_NDVI import FVC_from_NDVI
 from .LAI_from_NDVI import LAI_from_NDVI
 from .celcius_to_kelvin import celcius_to_kelvin
 
-from .timer import Timer
-
 __author__ = 'Kaniska Mallick, Madeleine Pascolini-Campbell, Gregory Halverson'
 
 logger = logging.getLogger(__name__)
@@ -180,7 +181,7 @@ def STIC_JPL(
             G_method = DEFAULT_G_METHOD,  # method for calculating soil heat flux
         )
     
-    diagnostic(Ms, "Ms", **diag_kwargs)
+    check_distribution(Ms, "Ms")
 
     # STIC analytical equations (convergence on LE)
     gB_ms, gS_ms, dT_C, EF = STIC_closure(
@@ -227,7 +228,9 @@ def STIC_JPL(
     PT_Wm2 = None
     iteration = 1
     LE_Wm2_max_change = 0
-    t = Timer()
+
+    t = TicToc()
+    t.tic()
 
     while (np.nanmax(LE_Wm2_change) >= LE_convergence_target and iteration <= max_iterations):
         logger.info(f"running STIC iteration {cl.val(iteration)} / {cl.val(max_iterations)}")
@@ -330,11 +333,11 @@ def STIC_JPL(
         LE_Wm2_old = LE_Wm2_new
         LE_Wm2_max_change = np.nanmax(LE_Wm2_change)
         logger.info(
-            f"completed STIC iteration {cl.val(iteration)} / {cl.val(max_iterations)} with max LE change: {cl.val(np.round(LE_Wm2_max_change, 3))} ({t} seconds)")
+            f"completed STIC iteration {cl.val(iteration)} / {cl.val(max_iterations)} with max LE change: {cl.val(np.round(LE_Wm2_max_change, 3))} ({t.tocvalue()} seconds)")
         
-        diagnostic(SM, f"SM_{iteration}", **diag_kwargs)
-        diagnostic(G, f"G_{iteration}", **diag_kwargs)
-        diagnostic(LE_Wm2_new, f"LE_{iteration}", **diag_kwargs)
+        check_distribution(SM, f"SM_{iteration}")
+        check_distribution(G, f"G_{iteration}")
+        check_distribution(LE_Wm2_new, f"LE_{iteration}")
 
         if LE_Wm2_max_change <= LE_convergence_target:
             logger.info(f"max LE change {cl.val(np.round(LE_Wm2_max_change, 3))} within convergence target {cl.val(np.round(LE_convergence_target, 3))} with {cl.val(iteration)} iteration{'s' if iteration > 1 else ''}")

stic_jpl-1.2.2/STIC_JPL/version.txt

@@ -0,0 +1 @@
+1.2.2

{stic_jpl-1.2.1 → stic_jpl-1.2.2}/STIC_JPL.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: STIC-JPL
-Version: 1.2.1
+Version: 1.2.2
 Summary: Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
 Author-email: Gregory Halverson <gregory.h.halverson@jpl.nasa.gov>, Kaniska Mallick <kaniska.mallick@list.lu>, Madeleine Pascolini-Campbell <madeleine.a.pascolini-campbell@jpl.nasa.gov>, "Claire S. Villanueva-Weeks" <claire.s.villanueva-weeks@jpl.gov>
 Project-URL: Homepage, https://github.com/JPL-Evapotranspiration-Algorithms/STIC-JPL
@@ -8,6 +8,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Requires-Dist: check-distribution
 Requires-Dist: colored-logging
 Requires-Dist: ECOv002-CMR>=1.0.5
 Requires-Dist: ECOv002-granules>=1.0.3
@@ -16,6 +17,7 @@ Requires-Dist: GEOS5FP>=1.1.1
 Requires-Dist: monte-carlo-sensitivity
 Requires-Dist: numpy
 Requires-Dist: pandas
+Requires-Dist: pytictoc
 Requires-Dist: rasters>=1.4.6
 Requires-Dist: seaborn
 Requires-Dist: SEBAL-soil-heat-flux

{stic_jpl-1.2.1 → stic_jpl-1.2.2}/STIC_JPL.egg-info/SOURCES.txt

@@ -8,7 +8,6 @@ STIC_JPL/canopy_air_stream.py
 STIC_JPL/celcius_to_kelvin.py
 STIC_JPL/closure.py
 STIC_JPL/constants.py
-STIC_JPL/diagnostic.py
 STIC_JPL/generate_STIC_inputs.py
 STIC_JPL/initialize_with_solar.py
 STIC_JPL/initialize_without_solar.py
@@ -21,7 +20,6 @@ STIC_JPL/root_zone_initialization.py
 STIC_JPL/root_zone_iteration.py
 STIC_JPL/soil_moisture_initialization.py
 STIC_JPL/soil_moisture_iteration.py
-STIC_JPL/timer.py
 STIC_JPL/version.txt
 STIC_JPL.egg-info/PKG-INFO
 STIC_JPL.egg-info/SOURCES.txt

{stic_jpl-1.2.1 → stic_jpl-1.2.2}/STIC_JPL.egg-info/requires.txt

@@ -1,3 +1,4 @@
+check-distribution
 colored-logging
 ECOv002-CMR>=1.0.5
 ECOv002-granules>=1.0.3
@@ -6,6 +7,7 @@ GEOS5FP>=1.1.1
 monte-carlo-sensitivity
 numpy
 pandas
+pytictoc
 rasters>=1.4.6
 seaborn
 SEBAL-soil-heat-flux

{stic_jpl-1.2.1 → stic_jpl-1.2.2}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools", "wheel"]
 
 [project]
 name = "STIC-JPL"
-version = "1.2.1"
+version = "1.2.2"
 description = "Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation"
 readme = "README.md"
 authors = [
@@ -17,6 +17,7 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
+    "check-distribution",
     "colored-logging",
     "ECOv002-CMR>=1.0.5",
     "ECOv002-granules>=1.0.3",
@@ -25,6 +26,7 @@ dependencies = [
     "monte-carlo-sensitivity",
     "numpy",
     "pandas",
+    "pytictoc",
     "rasters>=1.4.6",
     "seaborn",
     "SEBAL-soil-heat-flux",

stic_jpl-1.2.1/STIC_JPL/FVC_from_NDVI.py

@@ -1,26 +0,0 @@
-from typing import Union
-import numpy as np
-import rasters as rt
-from rasters import Raster
-
-KPAR = 0.5
-MIN_FIPAR = 0.0
-MAX_FIPAR = 1.0
-MIN_LAI = 0.0
-MAX_LAI = 10.0
-
-def FVC_from_NDVI(NDVI: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    Convert Normalized Difference Vegetation Index (NDVI) to Fractional Vegetation Cover (FVC).
-
-    Parameters:
-        NDVI (Union[Raster, np.ndarray]): Input NDVI data.
-
-    Returns:
-        Union[Raster, np.ndarray]: Converted FVC data.
-    """
-    NDVIv = 0.52  # +- 0.03
-    NDVIs = 0.04  # +- 0.03
-    FVC = rt.clip((NDVI - NDVIs) / (NDVIv - NDVIs), 0.0, 1.0)
-
-    return FVC

stic_jpl-1.2.1/STIC_JPL/LAI_from_NDVI.py

@@ -1,31 +0,0 @@
-from typing import Union
-import numpy as np
-import rasters as rt
-from rasters import Raster
-
-KPAR = 0.5
-MIN_FIPAR = 0.0
-MAX_FIPAR = 1.0
-MIN_LAI = 0.0
-MAX_LAI = 10.0
-
-def LAI_from_NDVI(
-        NDVI: Union[Raster, np.ndarray],
-        min_fIPAR: float = MIN_FIPAR,
-        max_fIPAR: float = MAX_FIPAR,
-        min_LAI: float = MIN_LAI,
-        max_LAI: float = MAX_LAI) -> Union[Raster, np.ndarray]:
-    """
-    Convert Normalized Difference Vegetation Index (NDVI) to Leaf Area Index (LAI).
-
-    Parameters:
-        NDVI (Union[Raster, np.ndarray]): Input NDVI data.
-
-    Returns:
-        Union[Raster, np.ndarray]: Converted LAI data.
-    """
-    fIPAR = rt.clip(NDVI - 0.05, min_fIPAR, max_fIPAR)
-    fIPAR = np.where(fIPAR == 0, np.nan, fIPAR)
-    LAI = rt.clip(-np.log(1 - fIPAR) * (1 / KPAR), min_LAI, max_LAI)
-
-    return LAI

stic_jpl-1.2.1/STIC_JPL/diagnostic.py

@@ -1,70 +0,0 @@
-from typing import Union
-from os.path import join
-from datetime import date
-import numpy as np
-import logging
-
-import colored_logging as cl
-from rasters import Raster
-
-logger = logging.getLogger(__name__)
-
-def diagnostic(values: Union[Raster, np.ndarray], variable: str, show_distributions: bool = True, output_directory: str = None):
-    if isinstance(values, Raster) and output_directory is not None:
-        filename = join(output_directory, f"{variable}.tif")
-        logger.info(filename)
-        values.to_geotiff(filename)
-
-    if show_distributions:
-        unique = np.unique(values)
-        nan_proportion = np.count_nonzero(np.isnan(values)) / np.size(values)
-
-        if len(unique) < 10:
-            logger.info(f"variable {cl.name(variable)} ({values.dtype}) has {cl.val(unique)} unique values")
-
-            for value in unique:
-                if np.isnan(value):
-                    count = np.count_nonzero(np.isnan(values))
-                else:
-                    count = np.count_nonzero(values == value)
-
-                if value == 0 or np.isnan(value):
-                    logger.info(f"* {cl.colored(value, 'red')}: {cl.colored(count, 'red')}")
-                else:
-                    logger.info(f"* {cl.val(value)}: {cl.val(count)}")
-        else:
-            minimum = np.nanmin(values)
-
-            if minimum < 0:
-                minimum_string = cl.colored(f"{minimum:0.3f}", "red")
-            else:
-                minimum_string = cl.val(f"{minimum:0.3f}")
-
-            maximum = np.nanmax(values)
-
-            if maximum <= 0:
-                maximum_string = cl.colored(f"{maximum:0.3f}", "red")
-            else:
-                maximum_string = cl.val(f"{maximum:0.3f}")
-
-            if nan_proportion > 0.5:
-                nan_proportion_string = cl.colored(f"{(nan_proportion * 100):0.2f}%", "yellow")
-            elif nan_proportion == 1:
-                nan_proportion_string = cl.colored(f"{(nan_proportion * 100):0.2f}%", "red")
-            else:
-                nan_proportion_string = cl.val(f"{(nan_proportion * 100):0.2f}%")
-
-            message = "variable " + cl.name(variable) + \
-                " min: " + minimum_string + \
-                " mean: " + cl.val(f"{np.nanmean(values):0.3f}") + \
-                " max: " + maximum_string + \
-                " nan: " + nan_proportion_string
-
-            if np.all(values == 0):
-                message += " all zeros"
-                logger.warning(message)
-            else:
-                logger.info(message)
-
-        if nan_proportion == 1:
-            raise ValueError(f"variable {variable} is blank")

stic_jpl-1.2.1/STIC_JPL/timer.py

@@ -1,77 +0,0 @@
-"""
-This is a minimalistic performance timer.
-"""
-import time
-
-__author__ = "Gregory Halverson"
-
-DEFAULT_FORMAT = "0.2f"
-
-class Timer(object):
-    """
-    This is a minimalistic performance timer.
-    """
-
-    def __init__(self):
-        self._start_time = None
-        self._end_time = None
-        self.start()
-
-    def __enter__(self, *args, **kwargs):
-        self.start()
-        return self
-
-    def __exit__(self, *args, **kwargs):
-        self.end()
-
-    def __repr__(self):
-        # print("Timer.__repr__")
-        return self.__format__(format_string=DEFAULT_FORMAT)
-
-    def __str__(self):
-        # print("Timer.__str__")
-        return self.__repr__()
-
-    def __format__(self, format_string=DEFAULT_FORMAT):
-        if format_string is None or format_string == "":
-            format_string = DEFAULT_FORMAT
-
-        return format(self.duration, format_string)
-
-    @property
-    def now(self):
-        # return datetime.now()
-        return time.perf_counter()
-
-    def start(self):
-        self._start_time = self.now
-
-        return self.start_time
-
-    @property
-    def start_time(self):
-        return self._start_time
-
-    def end(self):
-        self._end_time = self.now
-
-        return self.end_time
-
-    @property
-    def end_time(self):
-        return self._end_time
-
-    @property
-    def duration(self):
-        if self.start_time is None:
-            raise Exception("timer never started")
-
-        if self.end_time is None:
-            end_time = self.now
-        else:
-            end_time = self.end_time
-
-        duration = end_time - self.start_time
-
-        return duration
-

stic_jpl-1.2.1/STIC_JPL/version.txt

@@ -1 +0,0 @@
-1.2.1