STIC-JPL 1.2.1__py3-none-any.whl → 1.2.2__py3-none-any.whl

STIC_JPL/FVC_from_NDVI.py

@@ -11,16 +11,39 @@ 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).
+    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]: Converted FVC data.
+        Union[Raster, np.ndarray]: Estimated Fractional Vegetation Cover (FVC).
     """
-    NDVIv = 0.52  # +- 0.03
-    NDVIs = 0.04  # +- 0.03
+    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
+    return FVC

STIC_JPL/LAI_from_NDVI.py

@@ -3,7 +3,8 @@ import numpy as np
 import rasters as rt
 from rasters import Raster
 
-KPAR = 0.5
+# 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
@@ -16,16 +17,45 @@ def LAI_from_NDVI(
         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).
+    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]: Converted LAI data.
+        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
+    return LAI

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/version.txt

@@ -1 +1 @@
-1.2.1
+1.2.2

{stic_jpl-1.2.1.dist-info → stic_jpl-1.2.2.dist-info}/METADATA

@@ -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.dist-info → stic_jpl-1.2.2.dist-info}/RECORD

@@ -1,27 +1,25 @@
-STIC_JPL/FVC_from_NDVI.py,sha256=NCGMu4-XzvYqg7UOqKqNkfqwmV73zipoc09Q1IubNm0,638
-STIC_JPL/LAI_from_NDVI.py,sha256=iqlCkuH53iDrAz_VbMs4y4EwHcNuGGo5nJfJtnmsO70,833
+STIC_JPL/FVC_from_NDVI.py,sha256=QiALDwRVoOmG9XLfQHZQhAfi8B7QuKc2cae6RIi9yYI,1852
+STIC_JPL/LAI_from_NDVI.py,sha256=XgBIEtFG_sSAzNpb-v2E3rQ1HFoxw4gHhviQoiTVAPU,2529
 STIC_JPL/STIC_JPL.py,sha256=qqxz7JOEHgmP_hoz1ZT_66v0WNs9R0SITRt-60rYb3I,127
 STIC_JPL/__init__.py,sha256=FmTp-Ir0Wbae0SbZgxlNIxq48TDrWCev17Gv1hWskxU,216
 STIC_JPL/canopy_air_stream.py,sha256=UYp3l7mt0XH4SqvCGZhRzCIL-v7-Rvxxfm-C81lheSU,1637
 STIC_JPL/celcius_to_kelvin.py,sha256=QZ1gA8BHBHbdlgn1v8tEMG17yY2r-SCBnaHrGXySItg,316
 STIC_JPL/closure.py,sha256=AzWoLnpoZ1MlQAKq0CgpmCMfDGVsp8-hYZ50ry33cic,4031
 STIC_JPL/constants.py,sha256=xIVTsdc3_Rf3EPSgSk1QPjWiojFGn4lf1Swffov3oTM,595
-STIC_JPL/diagnostic.py,sha256=RXjtZbCEJMiTyRuiMGUvekDgO_GcrhXVXvorR0WlAsk,2613
 STIC_JPL/generate_STIC_inputs.py,sha256=Vwuqq-PLiH2IBd1v0Vt2TVbdIRK8D1zU_uMgReCefmQ,2382
 STIC_JPL/initialize_with_solar.py,sha256=P-22Wn8-sdvh2o4LGb9XfbCdXGWcOxdWwMzEYfx2Nfo,3759
 STIC_JPL/initialize_without_solar.py,sha256=M_7QfP2pr2w5sQO7UOW1GPqxpmQkjmsQ526BgYVVALk,4675
 STIC_JPL/iterate_with_solar.py,sha256=T9DezL59xaV63o6f7_ouCGcQwPi1dIvhlJB26TMGuDo,6373
 STIC_JPL/iterate_without_solar.py,sha256=09RERpN6tdZr6ORDhMwEFXwx8941vyn1HMJQ-Q_bY6s,6140
-STIC_JPL/model.py,sha256=PwN4T7Ic-TMz6c0Br39H0QGX4yK4IdEo2Ww0VP-nD0w,17323
+STIC_JPL/model.py,sha256=W-4MPm4SHcQNGJGRV6xf823pbauFoDooY-YA-yg_I_w,17339
 STIC_JPL/net_radiation.py,sha256=Uwudsazul8V-x5t8KQLi3wpYi-wjMwT__eqZCRV2bIw,1187
 STIC_JPL/process_STIC_table.py,sha256=5s-fxbchyVnPCzUG5KZX-RrHZDpN4JVcwu42s821Kdw,1712
 STIC_JPL/root_zone_initialization.py,sha256=3JVKNDt3ebIiGVfuhBawjKs-BicNwkbfMprkzSxd4Cg,1581
 STIC_JPL/root_zone_iteration.py,sha256=1XOMFE3-TdJZzUU5vouflUO4NKaZwAW6s1KJrNez3Es,3787
 STIC_JPL/soil_moisture_initialization.py,sha256=wWhAmvNT8tAIm_Sul8mEj6VdNuj7K14TBGUjKfqJrso,5610
 STIC_JPL/soil_moisture_iteration.py,sha256=QJXOPMxxwIIskpx9zLkXUPfuhWgFPUBcRnGhZo2UjAw,6493
-STIC_JPL/timer.py,sha256=tn5e3NQmsh55Jp9Fstjf-8KJW4F8UIJs-d_ZLooFYE8,1610
-STIC_JPL/version.txt,sha256=IGYgplfxzMivcrhm_c7yDmQcSPOc4n8zjOgxOUnGPlM,5
-stic_jpl-1.2.1.dist-info/METADATA,sha256=jKGqTkUD0wSUa1LCmVP3fBSC7XMiLJbPYOAgnBw8C7o,5731
-stic_jpl-1.2.1.dist-info/WHEEL,sha256=wXxTzcEDnjrTwFYjLPcsW_7_XihufBwmpiBeiXNBGEA,91
-stic_jpl-1.2.1.dist-info/top_level.txt,sha256=9NkchxttzACJcGcAaWzMaZarzX40OXQ216hERNA9LIo,9
-stic_jpl-1.2.1.dist-info/RECORD,,
+STIC_JPL/version.txt,sha256=xipcxhrEUlk1dT9ewoTAoFKksdpLOjWA3OK313ohVK4,6
+stic_jpl-1.2.2.dist-info/METADATA,sha256=bTOMDANHZrwipZlIVEgzKx-trZnQhi0T-px1i6rjgf0,5789
+stic_jpl-1.2.2.dist-info/WHEEL,sha256=wXxTzcEDnjrTwFYjLPcsW_7_XihufBwmpiBeiXNBGEA,91
+stic_jpl-1.2.2.dist-info/top_level.txt,sha256=9NkchxttzACJcGcAaWzMaZarzX40OXQ216hERNA9LIo,9
+stic_jpl-1.2.2.dist-info/RECORD,,

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/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
-