Merge pull request #9 from gregory-halverson-jpl/main

rebranding to `daylight-evapotranspiration`

Author: gregory-halverson-jpl

README.md

@@ -1,72 +1,81 @@
-# Usage
+# `daylight-evapotranspiration` Python Package
 
 This package provides a set of functions for upscaling instantaneous or daily energy balance and meteorological data to daily evapotranspiration (ET) estimates. Below is a summary of each function and its usage:
 
 [![CI](https://github.com/gregory-halverson-jpl/daily-evapotranspiration-upscaling/actions/workflows/ci.yml/badge.svg)](https://github.com/gregory-halverson-jpl/daily-evapotranspiration-upscaling/actions/workflows/ci.yml)
 
-The `daily-evapotranspiration-upscaling` Python package provides utilities for upscaling energy balance and meteorological data to daily ET, supporting raster, numpy array, and scalar inputs. It is designed for remote sensing, land surface modeling, and geospatial analysis.
+
+The `daylight-evapotranspiration` Python package provides utilities for upscaling energy balance and meteorological data to daily ET, supporting raster, numpy array, and scalar inputs. It is designed for remote sensing, land surface modeling, and geospatial analysis.
 
 [Gregory H. Halverson](https://github.com/gregory-halverson-jpl) (they/them)<br>
 [[email protected]](mailto:[email protected])<br>
 NASA Jet Propulsion Laboratory 329G
 
 ## Installation
 
-This package is available on PyPI as `daily-evapotranspiration-upscaling` (with dashes):
+
+This package is available on PyPI as `daylight-evapotranspiration`:
 
 ```bash
-pip install daily-evapotranspiration-upscaling
+pip install daylight-evapotranspiration
 ```
 
 ## Usage
 
-Import this package as `daily_evapotranspiration_upscaling` (with underscores):
+
+Import this package as `daylight_evapotranspiration`:
 
 ```python
-import daily_evapotranspiration_upscaling
+import daylight_evapotranspiration
 ```
 
 ### 1. `celcius_to_kelvin(T_C)`
-- **Description:** Convert Celsius to Kelvin.
+- **Description:** Convert Celsius to Kelvin. Implements $T_K = T_C + 273.15$ (IUPAC Green Book).
 - **Parameters:** `T_C` (float, array, or raster): Temperature in Celsius.
 - **Returns:** Temperature in Kelvin.
 
 ### 2. `lambda_Jkg_from_Ta_K(Ta_K)`
-- **Description:** Calculate latent heat of vaporization from air temperature (Kelvin).
+- **Description:** Calculate latent heat of vaporization from air temperature (Kelvin) using Henderson-Sellers (1984): $(2.501 - 0.002361 \times (T_a - 273.15)) \times 10^6$ J/kg.
 - **Parameters:** `Ta_K` (float, array, or raster): Air temperature in Kelvin.
 - **Returns:** Latent heat of vaporization (J/kg).
 
 ### 3. `lambda_Jkg_from_Ta_C(Ta_C)`
-- **Description:** Calculate latent heat of vaporization from air temperature (Celsius).
+- **Description:** Calculate latent heat of vaporization from air temperature (Celsius). Converts to Kelvin, then applies Henderson-Sellers (1984).
 - **Parameters:** `Ta_C` (float, array, or raster): Air temperature in Celsius.
 - **Returns:** Latent heat of vaporization (J/kg).
 
 ### 4. `calculate_evaporative_fraction(LE, Rn, G)`
-- **Description:** Compute evaporative fraction from latent heat flux, net radiation, and soil heat flux.
+- **Description:** Compute evaporative fraction (EF) from latent heat flux, net radiation, and soil heat flux: $EF = LE / (Rn - G)$ (Shuttleworth, 1993).
 - **Parameters:**
-	- `LE` (float, array, or raster): Latent heat flux (W/m²)
-	- `Rn` (float, array, or raster): Net radiation (W/m²)
-	- `G` (float, array, or raster): Soil heat flux (W/m²)
+    - `LE` (float, array, or raster): Latent heat flux (W/m²)
+    - `Rn` (float, array, or raster): Net radiation (W/m²)
+    - `G` (float, array, or raster): Soil heat flux (W/m²)
 - **Returns:** Evaporative fraction (unitless).
 
-### 5. `daily_ET_from_daily_LE(LE_daylight, ...)`
-- **Description:** Estimate daily ET from daily latent heat flux (LE) and supporting parameters.
+### 5. `daylight_ET_from_daylight_LE(LE_daylight_Wm2, daylight_hours=None, DOY=None, lat=None, datetime_UTC=None, geometry=None, lambda_Jkg=2450000.0)`
+- **Description:** Estimate daylight ET (kg) from daylight latent heat flux (LE) and supporting parameters. Uses $ET = (LE_{daylight} \times \text{daylight seconds}) / \lambda$ (Monteith, 1965).
 - **Parameters:** See function docstring for details.
-- **Returns:** Daily evapotranspiration (mm/day).
+- **Returns:** Daylight evapotranspiration (kg).
 
-### 6. `daily_ET_from_instantaneous(LE_instantaneous, Rn_instantaneous, G_instantaneous, DOY, lat, hour_of_day, ...)`
-- **Description:** Estimate daily ET from instantaneous measurements of latent heat flux, net radiation, and soil heat flux.
+### 6. `daylight_ET_from_instantaneous_LE(LE_instantaneous_Wm2, Rn_instantaneous_Wm2, G_instantaneous_Wm2, day_of_year=None, lat=None, hour_of_day=None, sunrise_hour=None, daylight_hours=None, time_UTC=None, geometry=None, lambda_Jkg=2450000.0)`
+- **Description:** Upscale instantaneous latent heat flux to daylight ET using EF and integrated net radiation (Verma et al., 1982; Anderson et al., 2007).
 - **Parameters:**
-	- `LE_instantaneous` (float, array, or raster): Instantaneous latent heat flux (W/m²)
-	- `Rn_instantaneous` (float, array, or raster): Instantaneous net radiation (W/m²)
-	- `G_instantaneous` (float, array, or raster): Instantaneous soil heat flux (W/m²)
-	- `DOY` (int): Day of year
-	- `lat` (float): Latitude in degrees
-	- `hour_of_day` (float): Local solar time (hours)
-- **Returns:** Daily evapotranspiration (mm/day).
+    - `LE_instantaneous_Wm2` (float, array, or raster): Instantaneous latent heat flux (W/m²)
+    - `Rn_instantaneous_Wm2` (float, array, or raster): Instantaneous net radiation (W/m²)
+    - `G_instantaneous_Wm2` (float, array, or raster): Instantaneous soil heat flux (W/m²)
+    - `day_of_year` (int): Day of year
+    - `lat` (float): Latitude in degrees
+    - `hour_of_day` (float): Local solar time (hours)
+    - Additional parameters: see function docstring
+- **Returns:** Daylight evapotranspiration (kg).
 
 # References
 
+- Henderson-Sellers, B. (1984). A new formula for latent heat of vaporization of water as a function of temperature. QJRMS, 110(466), 1186-1190.
+- Shuttleworth, W.J. (1993). Evaporation models: A review. Agricultural and Forest Meteorology, 61(1-2), 13-35.
+- Monteith, J.L. (1965). Evaporation and environment. Symposia of the Society for Experimental Biology, 19, 205-234.
+- Verma, S.B., et al. (1982). Remote sensing of evapotranspiration for Nebraska Sandhills. Agricultural Meteorology, 26, 1-10.
+- Anderson, M.C., et al. (2007). A two-source time-integrated model for estimating surface energy fluxes using thermal infrared remote sensing. Remote Sensing of Environment, 112(1), 213-229.
 - Allen, R.G., Pereira, L.S., Raes, D., Smith, M., 1998. Crop evapotranspiration-Guidelines for computing crop water requirements-FAO Irrigation and drainage paper 56. FAO, Rome, 300(9).
 - Bastiaanssen, W.G.M., Menenti, M., Feddes, R.A., Holtslag, A.A.M., 1998. A remote sensing surface energy balance algorithm for land (SEBAL): 1. Formulation. Journal of hydrology, 212, 198-212.
 - Duffie, J. A., & Beckman, W. A. (2013). Solar Engineering of Thermal Processes (4th ed.). Wiley.

daily_evapotranspiration_upscaling/__init__.py

@@ -0,0 +1,2 @@
+from .daylight_evapotranspiration import *
+from .version import __version__