Priestley-Taylor Jet Propulsion Laboratory Soil Mositure (PT-JPL-SM) Evapotranspiration Model Python Implementation
This software package is a Python implementation of the Priestley-Taylor Jet Propulsion Laboratory Soil Moisture (PT-JP-SM) model of evapotranspiration. It was re-implemented in Python by Gregory Halverson at Jet Propulsion Laboratory based on Python code developed by AJ Purdy.
The original PT-JPL model was implemented in MATLAB by Joshua Fisher and re-implemented in Python by Gregory Halverson. The PT-JPL model was designed for processing remote sensing data. It has the ability to partition latent heat flux into canopy transpiration, interception, and soil evaporation. Purdy et al., 2018 incorporated additional constraints from soil water availability on soil evaporation. Additional controls on transpiration are driven by soil water availability and canopy height include a weighting scheme to shift control on transpiration rates from soil water availability to atmospheric demand based on aridity.
The software was developed as part of a research grant by the NASA Research Opportunities in Space and Earth Sciences (ROSES) program. It was designed for use by the Ecosystem Spaceborne Thermal Radiometer Experiment on Space Station (ECOSTRESS) mission as a precursor for the Surface Biology and Geology (SBG) mission. However, it may also be useful for general remote sensing and GIS projects in Python. This package can be utilized for remote sensing research in Jupyter notebooks and deployed for operations in data processing pipelines.
The software is being released according to the SPD-41 open-science requirements of NASA-funded ROSES projects.
Gregory H. Halverson (they/them)
gregory.h.halverson@jpl.nasa.gov
Lead developer
NASA Jet Propulsion Laboratory 329G
Adam J. Purdy (he/him)
adpurdy@csumb.edu
Algorithm inventor
California State University Monterey Bay
Joshua B. Fisher (he/him)
jbfisher@chapman.edu
Algorithm inventor
Chapman University
Margaret C. Johnson (she/her)
maggie.johnson@jpl.nasa.gov
Sensitivity analysis
NASA Jet Propulsion Laboratory 398L
Claire Villanueva-Weeks (she/her)
claire.s.villanueva-weeks@jpl.nasa.gov
Code maintenance
NASA Jet Propulsion Laboratory 329G
Install the PTJPLSM package using pip:
pip install PTJPLSM
For development, clone this repository and install locally:
git clone https://github.com/JPL-Evapotranspiration-Algorithms/PT-JPL-SM.git
cd PT-JPL-SM
make environment
mamba activate PTJPLSM
make install
You can process gridded (raster) or array-based environmental datasets using the PT-JPL-SM model. This workflow is suitable for remote sensing data such as ECOSTRESS or similar sources, and allows for partitioning evapotranspiration (ET) into its components.
from PTJPLSM import PTJPLSM
results = PTJPLSM(
NDVI,
Rn_Wm2,
geometry=None,
time_UTC=None,
hour_of_day=None,
day_of_year=None,
GEOS5FP_connection=None,
ST_C=None,
emissivity=None,
albedo=None,
G=None,
Ta_C=None,
RH=None,
soil_moisture=None,
field_capacity=None,
wilting_point=None,
Topt=None,
fAPARmax=None,
canopy_height_meters=None,
delta_Pa=None,
gamma_Pa=GAMMA_PA,
epsilon=None,
beta_Pa=BETA_PA,
PT_alpha=PT_ALPHA,
field_capacity_scale=FIELD_CAPACITY_SCALE,
minimum_Topt=MINIMUM_TOPT,
field_capacity_directory=SOIL_CAPACITY_DIRECTORY,
wilting_point_directory=SOIL_CAPACITY_DIRECTORY,
canopy_height_directory=GEDI_DOWNLOAD_DIRECTORY,
floor_Topt=FLOOR_TOPT,
resampling=RESAMPLING
)-
Required:
NDVI: Normalized Difference Vegetation Index (Raster or np.ndarray)Rn_Wm2: Net radiation (W/m²) (Raster or np.ndarray)
-
Optional:
geometry: Geospatial metadata for rasterstime_UTC: Observation timehour_of_day,day_of_year: Time informationST_C: Surface temperature (°C)albedo: Surface albedoG: Soil heat fluxTa_C: Air temperature (°C)RH: Relative humidity (0-1)soil_moisture: Soil moisturefield_capacity,wilting_point: Soil propertiesTopt: Optimal plant temperaturefAPARmax: Maximum fAPARcanopy_height_meters: Canopy height
If some inputs (e.g., Ta_C, RH, soil_moisture, field_capacity, wilting_point, canopy_height_meters, Topt, fAPARmax) are not provided, the function will attempt to load or compute them using the provided geometry and time_UTC.
All input rasters/arrays should be spatially aligned and have the same shape.
Suppose you have loaded ECOSTRESS or similar remote sensing data as rasters or arrays:
from PTJPLSM import PTJPLSM
# Example: Load your input data (replace with your actual data loading code)
geometry = ... # RasterGeometry object
time_UTC = ... # datetime object
NDVI = ... # NDVI raster or array
Ta_C = ... # Air temperature raster or array
RH = ... # Relative humidity raster or array
Rn = ... # Net radiation raster or array
ST_C = ... # Surface temperature raster or array
albedo = ... # Albedo raster or array
# Run the PTJPLSM model
results = PTJPLSM(
geometry=geometry,
time_UTC=time_UTC,
NDVI=NDVI,
Ta_C=Ta_C,
RH=RH,
Rn_Wm2=Rn,
ST_C=ST_C,
albedo=albedo
)
# Access the total latent heat flux (evapotranspiration)
LE = results["LE"]
# Optionally, set a colormap and export to GeoTIFF
from ECOv002_granules import ET_COLORMAP
LE.cmap = ET_COLORMAP
LE.to_geotiff("example_LE.tif")The returned dictionary contains the following keys (each value is a Raster or np.ndarray):
G: Soil heat fluxRn_soil: Net radiation of the soilLE_soil: Soil evaporationRn_canopy: Net radiation of the canopyPET: Potential evapotranspirationLE_canopy: Canopy transpirationLE_interception: Interception evaporationLE: Total instantaneous evapotranspiration (constrained between 0 and PET)
- The function is robust to missing optional parameters, but key variables (e.g.,
NDVI,Rn_Wm2,Ta_C,RH,soil_moisture) must be provided or derivable. - All input rasters/arrays should be spatially aligned and have the same shape.
You can process tabular data (e.g., site-level or point measurements, or extracted pixel values) using the PT-JPL-SM model. This workflow is suitable for batch processing, sensitivity analysis, and is compatible with ECOSTRESS Cal-Val or similar datasets.
Required columns:
NDVI: Normalized Difference Vegetation IndexST_C: Surface temperature (°C)albedo: Surface albedoTa_CorTa: Air temperature (°C)RH: Relative humidity (0-1)SM: Soil moistureRn: Net radiation (W/m²) (can be computed withverma_net_radiation_tableif not present)
Optional columns (will be loaded if missing):
Topt: Optimal plant temperaturefAPARmax: Maximum fAPARcanopy_height_meters: Canopy heightfield_capacity: Soil field capacitywilting_point: Soil wilting pointG: Soil heat flux (will be calculated if missing)geometry: Geometry objectlat,lon: Latitude and longitude (used to construct geometry if needed)
-
Prepare your DataFrame
- Ensure your data includes the required columns listed above.
- If you do not have
Rn, you can compute it using theverma_net_radiation_tablefunction.
-
Process the Table
- Use
process_PTJPLSM_tableto process your DataFrame and run the PT-JPL-SM model.
- Use
-
Analyze the Output
- The output DataFrame will include the original columns plus new columns for each model output.
Suppose you have a CSV file with columns: NDVI, ST_C, albedo, Ta_C, RH, SM, Rn, lat, lon
import pandas as pd
from PTJPLSM.process_PTJPLSM_table import process_PTJPLSM_table
# Load your data
df = pd.read_csv('my_input_data.csv')
# (Optional) Compute net radiation if not present
# from verma_net_radiation import verma_net_radiation_table
# df = verma_net_radiation_table(df)
# Process the table and run the PT-JPL-SM model
output_df = process_PTJPLSM_table(df)
# The output DataFrame will have new columns: 'G', 'Rn_soil', 'LE_soil', 'Rn_canopy', 'PET',
# 'LE_canopy', 'LE_interception', 'LE' in addition to the original columns.
print(output_df.head())G: Soil heat fluxRn_soil: Net radiation of the soilLE_soil: Soil evaporationRn_canopy: Net radiation of the canopyPET: Potential evapotranspirationLE_canopy: Canopy transpirationLE_interception: Interception evaporationLE: Total instantaneous evapotranspiration (constrained between 0 and PET)
- If any required columns are missing, a KeyError will be raised.
- If geometry is not provided, latitude and longitude columns are required to construct spatial context.
- All input columns should be numeric and of compatible shape.
- This function is suitable for batch-processing site-level or point data tables for ET partitioning and for use in sensitivity analysis workflows (see the PTJPLSM Sensitivity notebook for an example).
Run the unit tests using pytest:
make test
The PT-JPL-SM and PT-JPL models, when processing on top of pre-computed net radiation, do not take surface temperature directly into account on their own. When coupled with a net radiation model that is sensitive to surface temperature, such as verma-net-radiation, PT-JPL-SM exhibits moderate sensitivity to surface temperature, with an average percent change in latent heat flux of 20%.
This project is licensed under the terms of the LICENSE file.
Purdy, A. J., Fisher, J. B., Goulden, M. L., Colliander, A., Halverson, G. H., Tu, K., & Famiglietti, J. S. (2018). "SMAP soil moisture improves global evapotranspiration." Remote Sensing of Environment, 219, 1-14. https://doi.org/10.1016/j.rse.2018.09.023
Fisher, J. B., Tu, K. P., & Baldocchi, D. D. (2008). "Global estimates of the land–atmosphere water flux based on monthly AVHRR and ISLSCP-II data, validated at 16 FLUXNET sites." Remote Sensing of Environment, 112(3), 901-919. https://doi.org/10.1016/j.rse.2007.06.025