updating calculate_daylight for processing tables of timestamps

Author: gregory-halverson-jpl

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=60", "setuptools-scm>=8.0", "wheel"]
 
 [project]
 name = "sun-angles"
-version = "1.4.0"
+version = "1.5.0"
 description = "calculates solar zenith and azimuth and daylight hours"
 readme = "README.md"
 authors = [
@@ -16,7 +16,7 @@ classifiers = [
 dependencies = [
     "numpy",
     "rasters",
-    "solar-apparent-time"
+    "solar-apparent-time>=1.4.0"
 ]
 
 requires-python = ">=3.10"

sun_angles/calculate_daylight.py

@@ -5,39 +5,45 @@
 from datetime import datetime
 from dateutil import parser
 import pandas as pd
+
+from solar_apparent_time import solar_day_of_year_for_longitude
+
 from .SHA_deg_from_DOY_lat import SHA_deg_from_DOY_lat
 from .daylight_from_SHA import daylight_from_SHA
 
 def calculate_daylight(
+    time_UTC: Union[datetime, str, list, np.ndarray] = None,
+    geometry: SpatialGeometry = None,
     day_of_year: Union[Raster, np.ndarray, int] = None,
     lat: Union[Raster, np.ndarray, float] = None,
-    SHA_deg: Union[Raster, np.ndarray, float] = None,
-    time_UTC: Union[datetime, str, list, np.ndarray] = None,
-    geometry: SpatialGeometry = None
+    lon: Union[Raster, np.ndarray, float] = None,
+    SHA_deg: Union[Raster, np.ndarray, float] = None
 ) -> Union[Raster, np.ndarray]:
     """
     Calculate the number of daylight hours for a given day and location.
 
-    This function is highly flexible and can be used in several ways depending on the information you have:
+    This function flexibly computes daylight hours based on the information provided:
 
-    - If you already know the sunrise hour angle (`SHA_deg`), provide it directly and the function will return the daylight hours for that value.
-    - If you do not provide `SHA_deg`, the function will compute it using the day of year (`day_of_year`) and latitude (`lat`).
-    - If you do not provide `lat` but do provide a `geometry` object, the function will extract the latitude from `geometry.lat`.
-    - If you do not provide `day_of_year` but do provide `time_UTC`, the function will convert the provided UTC time(s) to day of year. `time_UTC` can be a single datetime, a string, or an array/list of datetimes or strings.
+    - If `SHA_deg` (sunrise hour angle in degrees) is provided, it is used directly to compute daylight hours.
+    - If `SHA_deg` is not provided, it is calculated from `day_of_year` and `lat` (latitude in degrees).
+    - If `lat` is not provided but a `geometry` object is given, latitude is extracted from `geometry.lat`.
+    - If `day_of_year` is not provided but `time_UTC` is given, the function converts the UTC time(s) to day of year, accounting for longitude if available.
 
     Parameters
     ----------
+    time_UTC : Union[datetime, str, list, np.ndarray], optional
+        Datetime(s) in UTC. Used to determine `day_of_year` if not provided. Accepts a single datetime, a string, or an array/list of datetimes or strings.
+        Example: `time_UTC=['2025-06-21', '2025-12-21']` or `time_UTC=datetime(2025, 6, 21)`
+    geometry : SpatialGeometry, optional
+        Geometry object containing latitude (and optionally longitude) information. Used if `lat` or `lon` are not provided.
     day_of_year : Union[Raster, np.ndarray, int], optional
         Day of year (1-366). Can be a Raster, numpy array, or integer. If not provided, will be inferred from `time_UTC` if available.
     lat : Union[Raster, np.ndarray, float], optional
         Latitude in degrees. Can be a Raster, numpy array, or float. If not provided, will be inferred from `geometry` if available.
+    lon : Union[Raster, np.ndarray, float], optional
+        Longitude in degrees. Can be a Raster, numpy array, or float. If not provided, will be inferred from `geometry` if available.
     SHA_deg : Union[Raster, np.ndarray, float], optional
         Sunrise hour angle in degrees. If provided, it is used directly and other parameters are ignored.
-    time_UTC : datetime, str, list, or np.ndarray, optional
-        Datetime(s) in UTC. Used to determine `day_of_year` if `day_of_year` is not provided. Accepts a single datetime, a string, or an array/list of datetimes or strings.
-        Example: `time_UTC=['2025-06-21', '2025-12-21']` or `time_UTC=datetime(2025, 6, 21)`
-    geometry : SpatialGeometry, optional
-        Geometry object containing latitude information. If `lat` is not provided, latitude will be extracted from `geometry.lat`.
 
     Returns
     -------
@@ -61,24 +67,16 @@ def calculate_daylight(
         # If latitude is not provided, try to extract from geometry
         if lat is None and geometry is not None:
             lat = geometry.lat
+        
+        if lon is None and geometry is not None:
+            lon = geometry.lon
+        
+        if day_of_year is None:
+            day_of_year = solar_day_of_year_for_longitude(
+                time_UTC=time_UTC,
+                lon=lon
+            )
 
-        # If DOY is not provided, try to extract from time_UTC
-        if day_of_year is None and time_UTC is not None:
-            def to_doy(val):
-                if isinstance(val, str):
-                    val = parser.parse(val)
-                return int(pd.Timestamp(val).dayofyear)
-
-            # Handle array-like or single value
-            if isinstance(time_UTC, (list, np.ndarray)):
-                day_of_year = np.array([to_doy(t) for t in time_UTC])
-            else:
-                day_of_year = to_doy(time_UTC)
-
-        # Ensure day_of_year is a numpy array if it's a list (for downstream math)
-        if isinstance(day_of_year, list):
-            day_of_year = np.array(day_of_year)
-        # Compute SHA_deg using DOY and latitude
         SHA_deg = SHA_deg_from_DOY_lat(day_of_year, lat)
 
     # Compute daylight hours from SHA_deg