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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: STIC-JPL
-Version: 1.1.0
+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,14 +8,21 @@ 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
-Requires-Dist: ECOv002-granules
+Requires-Dist: ECOv002-CMR>=1.0.5
+Requires-Dist: ECOv002-granules>=1.0.3
+Requires-Dist: ECOv003-granules
 Requires-Dist: GEOS5FP>=1.1.1
+Requires-Dist: monte-carlo-sensitivity
 Requires-Dist: numpy
 Requires-Dist: pandas
-Requires-Dist: rasters
+Requires-Dist: pytictoc
+Requires-Dist: rasters>=1.4.6
+Requires-Dist: seaborn
+Requires-Dist: SEBAL-soil-heat-flux
 Requires-Dist: solar-apparent-time
+Requires-Dist: verma-net-radiation>=1.1.0
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest>=6.0; extra == "dev"
@@ -24,7 +31,8 @@ Requires-Dist: jupyter; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 
-# Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
+# `STIC-JPL` 
+## Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
 
 [![CI](https://github.com/JPL-Evapotranspiration-Algorithms/STIC/actions/workflows/ci.yml/badge.svg)](https://github.com/JPL-Evapotranspiration-Algorithms/STIC/actions/workflows/ci.yml)
 
@@ -63,21 +71,23 @@ NASA Jet Propulsion Laboratory 329G
 
 ## Installation
 
-Use the pip package manager to install the `STIC` PyPi package.
+Use the pip package manager to install the `STIC-JPL` PyPi package with dashes in the name.
 
 ```
-pip install STIC
+pip install STIC-JPL
 ```
 
 ## Usage
 
-Import the `STIC` function from the `STIC` package.
+Import the `STIC_JPL` function from the `STIC_JPL` package with underscores in the name.
 
 ```
-from STIC import STIC
+from STIC_JPL import STIC_JPL
 ```
 
-See the [ECOSTRESS example](ECOSTRESS%20Example.ipynb) for usage.
+See the [ECOSTRESS example](ECOSTRESS%20Example.ipynb) notebook for usage.
+
+See the [STIC sensitivity](STIC%20Sensitivity.ipynb) notebook for sensitivity analysis.
 
 ## References
  

{stic_jpl-1.1.0 → stic_jpl-1.2.2}/README.md

@@ -1,4 +1,5 @@
-# Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
+# `STIC-JPL` 
+## Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
 
 [![CI](https://github.com/JPL-Evapotranspiration-Algorithms/STIC/actions/workflows/ci.yml/badge.svg)](https://github.com/JPL-Evapotranspiration-Algorithms/STIC/actions/workflows/ci.yml)
 
@@ -37,21 +38,23 @@ NASA Jet Propulsion Laboratory 329G
 
 ## Installation
 
-Use the pip package manager to install the `STIC` PyPi package.
+Use the pip package manager to install the `STIC-JPL` PyPi package with dashes in the name.
 
 ```
-pip install STIC
+pip install STIC-JPL
 ```
 
 ## Usage
 
-Import the `STIC` function from the `STIC` package.
+Import the `STIC_JPL` function from the `STIC_JPL` package with underscores in the name.
 
 ```
-from STIC import STIC
+from STIC_JPL import STIC_JPL
 ```
 
-See the [ECOSTRESS example](ECOSTRESS%20Example.ipynb) for usage.
+See the [ECOSTRESS example](ECOSTRESS%20Example.ipynb) notebook for usage.
+
+See the [STIC sensitivity](STIC%20Sensitivity.ipynb) notebook for sensitivity analysis.
 
 ## References
  

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.2/STIC_JPL/STIC_JPL.py

@@ -0,0 +1,3 @@
+from .model import *
+from .generate_STIC_inputs import generate_STIC_inputs
+from .process_STIC_table import process_STIC_table

stic_jpl-1.2.2/STIC_JPL/celcius_to_kelvin.py

@@ -0,0 +1,11 @@
+from typing import Union
+import numpy as np
+from rasters import Raster
+
+def celcius_to_kelvin(T_C: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
+    """
+    convert temperature in celsius to kelvin.
+    :param T_C: temperature in celsius
+    :return: temperature in kelvin
+    """
+    return T_C + 273.15

stic_jpl-1.2.2/STIC_JPL/generate_STIC_inputs.py

@@ -0,0 +1,65 @@
+import logging
+
+import numpy as np
+from dateutil import parser
+from pandas import DataFrame
+from rasters import Point
+from sentinel_tiles import sentinel_tiles
+from solar_apparent_time import UTC_to_solar
+from SEBAL_soil_heat_flux import calculate_SEBAL_soil_heat_flux
+
+from .model import STIC_JPL, MAX_ITERATIONS, USE_VARIABLE_ALPHA
+
+logger = logging.getLogger(__name__)
+
+def generate_STIC_inputs(STIC_inputs_from_calval_df: DataFrame) -> DataFrame:
+    """
+    STIC_inputs_from_claval_df:
+        Pandas DataFrame containing the columns: tower, lat, lon, time_UTC, albedo, elevation_km
+    return:
+        Pandas DataFrame containing the columns: tower, lat, lon, time_UTC, doy, albedo, elevation_km, AOT, COT, vapor_gccm, ozone_cm, SZA, KG
+    """
+    # output_rows = []
+    STIC_inputs_df = STIC_inputs_from_calval_df.copy()
+
+    hour_of_day = []
+    doy = []
+    Topt = []
+    fAPARmax = []
+
+    for i, input_row in STIC_inputs_from_calval_df.iterrows():
+        tower = input_row.tower
+        lat = input_row.lat
+        lon = input_row.lon
+        time_UTC = input_row.time_UTC
+        albedo = input_row.albedo
+        elevation_km = input_row.elevation_km
+        logger.info(f"collecting STIC inputs for tower {tower} lat {lat} lon {lon} time {time_UTC} UTC")
+        time_UTC = parser.parse(str(time_UTC))
+        time_solar = UTC_to_solar(time_UTC, lon)
+        hour_of_day.append(time_solar.hour)
+        doy.append(time_UTC.timetuple().tm_yday)
+        date_UTC = time_UTC.date()
+        tile = sentinel_tiles.toMGRS(lat, lon)[:5]
+        tile_grid = sentinel_tiles.grid(tile=tile, cell_size=70)
+        rows, cols = tile_grid.shape
+        row, col = tile_grid.index_point(Point(lon, lat))
+        geometry = tile_grid[max(0, row - 1):min(row + 2, rows - 1),
+                             max(0, col - 1):min(col + 2, cols - 1)]
+    
+    if not "hour_of_day" in STIC_inputs_df.columns:
+        STIC_inputs_df["hour_of_day"] = hour_of_day
+
+    if not "doy" in STIC_inputs_df.columns:
+        STIC_inputs_df["doy"] = doy
+    
+    if not "Topt" in STIC_inputs_df.columns:
+        STIC_inputs_df["Topt"] = Topt
+    
+    if not "fAPARmax" in STIC_inputs_df.columns:
+        STIC_inputs_df["fAPARmax"] = fAPARmax
+    
+    if "Ta" in STIC_inputs_df and "Ta_C" not in STIC_inputs_df:
+        STIC_inputs_df.rename({"Ta": "Ta_C"}, inplace=True)
+    
+    return STIC_inputs_df

{stic_jpl-1.1.0 → stic_jpl-1.2.2}/STIC_JPL/initialize_with_solar.py

@@ -5,8 +5,7 @@ import rasters as rt
 
 from rasters import Raster
 
-from .vegetation_conversion.vegetation_conversion import FVC_from_NDVI
-from .soil_heat_flux import calculate_SEBAL_soil_heat_flux
+from SEBAL_soil_heat_flux import calculate_SEBAL_soil_heat_flux
 
 from .constants import *
 from .soil_moisture_initialization import initialize_soil_moisture

{stic_jpl-1.1.0 → stic_jpl-1.2.2}/STIC_JPL/iterate_with_solar.py

@@ -5,7 +5,7 @@ import rasters as rt
 
 from rasters import Raster
 
-from .soil_heat_flux import calculate_SEBAL_soil_heat_flux
+from SEBAL_soil_heat_flux import calculate_SEBAL_soil_heat_flux
 
 from .constants import *
 from .canopy_air_stream import calculate_canopy_air_stream_vapor_pressure

stic_jpl-1.1.0/STIC_JPL/STIC_JPL.py → stic_jpl-1.2.2/STIC_JPL/model.py

@@ -5,19 +5,18 @@ 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 .meteorology_conversion import calculate_air_density, calculate_specific_heat, calculate_specific_humidity, calculate_surface_pressure, celcius_to_kelvin
+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
-
-from .timer import Timer
+from SEBAL_soil_heat_flux import calculate_SEBAL_soil_heat_flux
 
 from rasters import Raster, RasterGeometry
 
-from .vegetation_conversion.vegetation_conversion import FVC_from_NDVI, LAI_from_NDVI
-
 from .constants import *
 from .closure import STIC_closure
 from .soil_moisture_initialization import initialize_soil_moisture
@@ -29,8 +28,9 @@ from .initialize_without_solar import initialize_without_solar
 from .iterate_with_solar import iterate_with_solar
 from .iterate_without_solar import iterate_without_solar
 from .root_zone_initialization import calculate_root_zone_moisture
-
-from .soil_heat_flux import calculate_SEBAL_soil_heat_flux
+from .FVC_from_NDVI import FVC_from_NDVI
+from .LAI_from_NDVI import LAI_from_NDVI
+from .celcius_to_kelvin import celcius_to_kelvin
 
 __author__ = 'Kaniska Mallick, Madeleine Pascolini-Campbell, Gregory Halverson'
 
@@ -181,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(
@@ -228,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)}")
@@ -331,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/process_STIC_table.py

@@ -0,0 +1,61 @@
+import logging
+
+import numpy as np
+from dateutil import parser
+from pandas import DataFrame
+from rasters import Point
+from sentinel_tiles import sentinel_tiles
+from solar_apparent_time import UTC_to_solar
+from SEBAL_soil_heat_flux import calculate_SEBAL_soil_heat_flux
+
+from .model import STIC_JPL, MAX_ITERATIONS, USE_VARIABLE_ALPHA
+
+logger = logging.getLogger(__name__)
+
+def process_STIC_table(
+        input_df: DataFrame, 
+        max_iterations = MAX_ITERATIONS, 
+        use_variable_alpha = USE_VARIABLE_ALPHA) -> DataFrame:
+    hour_of_day = np.float64(np.array(input_df.hour_of_day))
+    lon = np.float64(np.array(input_df.lon))
+    ST_C = np.float64(np.array(input_df.ST_C))
+    emissivity = np.float64(np.array(input_df.EmisWB))
+    NDVI = np.float64(np.array(input_df.NDVI))
+    albedo = np.float64(np.array(input_df.albedo))
+    Ta_C = np.float64(np.array(input_df.Ta_C))
+    RH = np.float64(np.array(input_df.RH))
+    Rn = np.float64(np.array(input_df.Rn))
+    Rg = np.float64(np.array(input_df.Rg))
+
+    if "G" in input_df:
+        G = np.array(input_df.G)
+    else:
+        G = calculate_SEBAL_soil_heat_flux(
+            Rn=Rn,
+            ST_C=ST_C,
+            NDVI=NDVI,
+            albedo=albedo
+        )
+    
+    results = STIC_JPL(
+        hour_of_day=hour_of_day,
+        # longitude=lon,
+        ST_C = ST_C,
+        emissivity=emissivity,
+        NDVI=NDVI,
+        albedo=albedo,
+        Ta_C=Ta_C,
+        RH=RH,
+        Rn_Wm2=Rn,
+        G=G,
+        # Rg_Wm2=Rg,
+        max_iterations=max_iterations,
+        use_variable_alpha=use_variable_alpha
+    )
+
+    output_df = input_df.copy()
+
+    for key, value in results.items():
+        output_df[key] = value
+
+    return output_df

{stic_jpl-1.1.0 → stic_jpl-1.2.2}/STIC_JPL/soil_moisture_initialization.py

@@ -4,7 +4,8 @@ import numpy as np
 import rasters as rt
 from rasters import Raster
 
-from .vegetation_conversion.vegetation_conversion import FVC_from_NDVI
+from .FVC_from_NDVI import FVC_from_NDVI
+from .LAI_from_NDVI import LAI_from_NDVI
 
 from .constants import GAMMA_HPA
 from .root_zone_initialization import calculate_root_zone_moisture

stic_jpl-1.2.2/STIC_JPL/version.txt

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: STIC-JPL
-Version: 1.1.0
+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,14 +8,21 @@ 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
-Requires-Dist: ECOv002-granules
+Requires-Dist: ECOv002-CMR>=1.0.5
+Requires-Dist: ECOv002-granules>=1.0.3
+Requires-Dist: ECOv003-granules
 Requires-Dist: GEOS5FP>=1.1.1
+Requires-Dist: monte-carlo-sensitivity
 Requires-Dist: numpy
 Requires-Dist: pandas
-Requires-Dist: rasters
+Requires-Dist: pytictoc
+Requires-Dist: rasters>=1.4.6
+Requires-Dist: seaborn
+Requires-Dist: SEBAL-soil-heat-flux
 Requires-Dist: solar-apparent-time
+Requires-Dist: verma-net-radiation>=1.1.0
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: pytest>=6.0; extra == "dev"
@@ -24,7 +31,8 @@ Requires-Dist: jupyter; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 
-# Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
+# `STIC-JPL` 
+## Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation
 
 [![CI](https://github.com/JPL-Evapotranspiration-Algorithms/STIC/actions/workflows/ci.yml/badge.svg)](https://github.com/JPL-Evapotranspiration-Algorithms/STIC/actions/workflows/ci.yml)
 
@@ -63,21 +71,23 @@ NASA Jet Propulsion Laboratory 329G
 
 ## Installation
 
-Use the pip package manager to install the `STIC` PyPi package.
+Use the pip package manager to install the `STIC-JPL` PyPi package with dashes in the name.
 
 ```
-pip install STIC
+pip install STIC-JPL
 ```
 
 ## Usage
 
-Import the `STIC` function from the `STIC` package.
+Import the `STIC_JPL` function from the `STIC_JPL` package with underscores in the name.
 
 ```
-from STIC import STIC
+from STIC_JPL import STIC_JPL
 ```
 
-See the [ECOSTRESS example](ECOSTRESS%20Example.ipynb) for usage.
+See the [ECOSTRESS example](ECOSTRESS%20Example.ipynb) notebook for usage.
+
+See the [STIC sensitivity](STIC%20Sensitivity.ipynb) notebook for sensitivity analysis.
 
 ## References
  

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

@@ -1,16 +1,21 @@
 README.md
 pyproject.toml
+STIC_JPL/FVC_from_NDVI.py
+STIC_JPL/LAI_from_NDVI.py
 STIC_JPL/STIC_JPL.py
 STIC_JPL/__init__.py
 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
 STIC_JPL/iterate_with_solar.py
 STIC_JPL/iterate_without_solar.py
+STIC_JPL/model.py
 STIC_JPL/net_radiation.py
+STIC_JPL/process_STIC_table.py
 STIC_JPL/root_zone_initialization.py
 STIC_JPL/root_zone_iteration.py
 STIC_JPL/soil_moisture_initialization.py
@@ -21,13 +26,5 @@ STIC_JPL.egg-info/SOURCES.txt
 STIC_JPL.egg-info/dependency_links.txt
 STIC_JPL.egg-info/requires.txt
 STIC_JPL.egg-info/top_level.txt
-STIC_JPL/meteorology_conversion/__init__.py
-STIC_JPL/meteorology_conversion/meteorology_conversion.py
-STIC_JPL/soil_heat_flux/__init__.py
-STIC_JPL/soil_heat_flux/calculate_SEBAL_soil_heat_flux.py
-STIC_JPL/timer/__init__.py
-STIC_JPL/timer/timer.py
-STIC_JPL/vegetation_conversion/__init__.py
-STIC_JPL/vegetation_conversion/vegetation_conversion.py
 tests/test_import_STIC.py
 tests/test_import_dependencies.py

stic_jpl-1.2.2/STIC_JPL.egg-info/requires.txt

@@ -0,0 +1,23 @@
+check-distribution
+colored-logging
+ECOv002-CMR>=1.0.5
+ECOv002-granules>=1.0.3
+ECOv003-granules
+GEOS5FP>=1.1.1
+monte-carlo-sensitivity
+numpy
+pandas
+pytictoc
+rasters>=1.4.6
+seaborn
+SEBAL-soil-heat-flux
+solar-apparent-time
+verma-net-radiation>=1.1.0
+
+[dev]
+build
+pytest>=6.0
+pytest-cov
+jupyter
+pytest
+twine

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

@@ -3,7 +3,7 @@ requires = ["setuptools", "wheel"]
 
 [project]
 name = "STIC-JPL"
-version = "1.1.0"
+version = "1.2.2"
 description = "Surface Temperature Initiated Closure (STIC) Evapotranspiration Model Python Implementation"
 readme = "README.md"
 authors = [
@@ -17,14 +17,21 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
+    "check-distribution",
     "colored-logging",
-    "ECOv002-CMR",
-    "ECOv002-granules",
+    "ECOv002-CMR>=1.0.5",
+    "ECOv002-granules>=1.0.3",
+    "ECOv003-granules",
     "GEOS5FP>=1.1.1",
+    "monte-carlo-sensitivity",
     "numpy",
     "pandas",
-    "rasters",
-    "solar-apparent-time"
+    "pytictoc",
+    "rasters>=1.4.6",
+    "seaborn",
+    "SEBAL-soil-heat-flux",
+    "solar-apparent-time",
+    "verma-net-radiation>=1.1.0"
 ]
 requires-python = ">=3.10"
 

stic_jpl-1.1.0/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.1.0/STIC_JPL/meteorology_conversion/__init__.py

@@ -1 +0,0 @@
-from .meteorology_conversion import *

stic_jpl-1.1.0/STIC_JPL/meteorology_conversion/meteorology_conversion.py

@@ -1,123 +0,0 @@
-from typing import Union
-import numpy as np
-import rasters as rt
-from rasters import Raster
-
-# gas constant for dry air in joules per kilogram per kelvin
-RD = 286.9
-
-# gas constant for moist air in joules per kilogram per kelvin
-RW = 461.5
-
-# specific heat of water vapor in joules per kilogram per kelvin
-CPW = 1846.0
-
-# specific heat of dry air in joules per kilogram per kelvin
-CPD = 1005.0
-
-def kelvin_to_celsius(T_K: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    convert temperature in kelvin to celsius.
-    :param T_K: temperature in kelvin
-    :return: temperature in celsius
-    """
-    return T_K - 273.15
-
-def celcius_to_kelvin(T_C: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    convert temperature in celsius to kelvin.
-    :param T_C: temperature in celsius
-    :return: temperature in kelvin
-    """
-    return T_C + 273.15
-
-def calculate_specific_humidity(
-        Ea_Pa: Union[Raster, np.ndarray], 
-        Ps_Pa: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    Calculate the specific humidity of air as a ratio of kilograms of water to kilograms of air.
-    
-    Args:
-        Ea_Pa (Union[Raster, np.ndarray]): Actual water vapor pressure in Pascal.
-        surface_pressure_Pa (Union[Raster, np.ndarray]): Surface pressure in Pascal.
-    
-    Returns:
-        Union[Raster, np.ndarray]: Specific humidity in kilograms of water per kilograms of air.
-    """
-    return ((0.622 * Ea_Pa) / (Ps_Pa - (0.387 * Ea_Pa)))
-
-def calculate_specific_heat(specific_humidity: Union[Raster, np.ndarray]):
-    # calculate specific heat capacity of the air (Cp)
-    # in joules per kilogram per kelvin
-    # from specific heat of water vapor (CPW)
-    # and specific heat of dry air (CPD)
-    Cp_Jkg = specific_humidity * CPW + (1 - specific_humidity) * CPD
-
-    return Cp_Jkg
-
-def calculate_air_density(
-        surface_pressure_Pa: Union[Raster, np.ndarray], 
-        Ta_K: Union[Raster, np.ndarray], 
-        specific_humidity: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    Calculate air density.
-
-    Parameters:
-    surface_pressure_Pa (Union[Raster, np.ndarray]): Surface pressure in Pascal.
-    Ta_K (Union[Raster, np.ndarray]): Air temperature in Kelvin.
-    specific_humidity (Union[Raster, np.ndarray]): Specific humidity.
-
-    Returns:
-    Union[Raster, np.ndarray]: Air density in kilograms per cubic meter.
-    """
-    # numerator: Pa(N / m ^ 2 = kg * m / s ^ 2); denominator: J / kg / K * K)
-    rhoD = surface_pressure_Pa / (RD * Ta_K)
-
-    # calculate air density (rho) in kilograms per cubic meter
-    rho = rhoD * ((1.0 + specific_humidity) / (1.0 + specific_humidity * (RW / RD)))
-
-    return rho
-
-def SVP_kPa_from_Ta_C(Ta_C: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    Calculate the saturation vapor pressure in kiloPascal (kPa) from air temperature in Celsius.
-
-    Parameters:
-    Ta_C (Union[Raster, np.ndarray]): Air temperature in Celsius.
-
-    Returns:
-    Union[Raster, np.ndarray]: Saturation vapor pressure in kPa.
-
-    """
-    SVP_kPa = np.clip(0.611 * np.exp((Ta_C * 17.27) / (Ta_C + 237.7)), 1, None)
-
-    return SVP_kPa
-
-def SVP_Pa_from_Ta_C(Ta_C: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    Calculate the saturation vapor pressure in Pascal (Pa) from the air temperature in Celsius (Ta_C).
-
-    Parameters:
-        Ta_C (Union[Raster, np.ndarray]): Air temperature in Celsius.
-
-    Returns:
-        Union[Raster, np.ndarray]: Saturation vapor pressure in Pascal (Pa).
-    """
-    return SVP_kPa_from_Ta_C(Ta_C) * 1000
-
-def calculate_surface_pressure(elevation_m: Union[Raster, np.ndarray], Ta_C: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    Calculate surface pressure using elevation and air temperature.
-
-    Parameters:
-        elevation_m (Union[Raster, np.ndarray]): Elevation in meters.
-        Ta_K (Union[Raster, np.ndarray]): Air temperature in Kelvin.
-
-    Returns:
-        Union[Raster, np.ndarray]: Surface pressure in Pascal (Pa).
-    """
-    Ta_K = kelvin_to_celsius(Ta_C)
-    Ps_Pa = 101325.0 * (1.0 - 0.0065 * elevation_m / Ta_K) ** (9.807 / (0.0065 * 287.0))  # [Pa]
-
-    return Ps_Pa
-

stic_jpl-1.1.0/STIC_JPL/soil_heat_flux/__init__.py

@@ -1 +0,0 @@
-from .calculate_SEBAL_soil_heat_flux import calculate_SEBAL_soil_heat_flux

stic_jpl-1.1.0/STIC_JPL/soil_heat_flux/calculate_SEBAL_soil_heat_flux.py

@@ -1,40 +0,0 @@
-from typing import Union
-
-import numpy as np
-import rasters as rt
-from rasters import Raster
-
-def calculate_SEBAL_soil_heat_flux(
-        Rn: Union[Raster, np.ndarray], 
-        ST_C: Union[Raster, np.ndarray], 
-        NDVI: Union[Raster, np.ndarray], 
-        albedo: Union[Raster, np.ndarray]) -> Union[Raster, np.ndarray]:
-    """
-    This function calculates the soil heat flux (G) in the Surface Energy Balance Algorithm for Land (SEBAL) model.
-    The formula used in the function is a simplification of the more complex relationship between these variables in the energy balance at the surface.
-    
-    Parameters:
-    Rn (np.ndarray): Net radiation at the surface.
-    ST_C (np.ndarray): Surface temperature in Celsius.
-    NDVI (np.ndarray): Normalized Difference Vegetation Index, indicating the presence and condition of vegetation.
-    albedo (np.ndarray): Measure of the diffuse reflection of solar radiation.
-    
-    Returns:
-    np.ndarray: The soil heat flux (G), a key component in the energy balance.
-    
-    Reference:
-    "Evapotranspiration Estimation Based on Remote Sensing and the SEBAL Model in the Bosten Lake Basin of China" [^1^][1]
-    """
-    # Empirical coefficients used in the calculation
-    coeff1 = 0.0038
-    coeff2 = 0.0074
-    
-    # Vegetation cover correction factor
-    NDVI_correction = 1 - 0.98 * NDVI ** 4
-    
-    # Calculation of the soil heat flux (G)
-    G = Rn * ST_C * (coeff1 + coeff2 * albedo) * NDVI_correction
-    
-    G = rt.clip(G, 0, None)
-
-    return G

stic_jpl-1.1.0/STIC_JPL/timer/__init__.py

@@ -1 +0,0 @@
-from .timer import *

stic_jpl-1.1.0/STIC_JPL/timer/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.1.0/STIC_JPL/vegetation_conversion/__init__.py

@@ -1 +0,0 @@
-from .vegetation_conversion import *

stic_jpl-1.1.0/STIC_JPL/vegetation_conversion/vegetation_conversion.py

@@ -1,47 +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
-
-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.1.0/STIC_JPL/version.txt

@@ -1 +0,0 @@
-1.0.4

stic_jpl-1.1.0/STIC_JPL.egg-info/requires.txt

@@ -1,16 +0,0 @@
-colored-logging
-ECOv002-CMR
-ECOv002-granules
-GEOS5FP>=1.1.1
-numpy
-pandas
-rasters
-solar-apparent-time
-
-[dev]
-build
-pytest>=6.0
-pytest-cov
-jupyter
-pytest
-twine