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

fixing `calculate_daylight`

Author: gregory-halverson-jpl

README.md

@@ -60,15 +60,15 @@ import sun_angles
 	- Duffie, J. A., & Beckman, W. A. (2013). Solar Engineering of Thermal Processes (4th ed.). Wiley.
 
 
-### 5. `calculate_daylight(DOY=None, lat=None, SHA_deg=None, datetime_UTC=None, geometry=None)`
-- **Description:** Calculates daylight hours for a given day and location. Flexible input: provide SHA directly, or let the function compute it from DOY and latitude.
+### 5. `calculate_daylight(day_of_year=None, lat=None, SHA_deg=None, time_UTC=None, geometry=None)`
+- **Description:** Computes daylight hours for a specific day and location. Accepts multiple input types: you can provide the sunrise hour angle (SHA) directly, or supply day of year and latitude (or a datetime or geometry), and the function will calculate SHA as needed.
 - **Parameters:** 
-	- `DOY` (optional): Day of year.
-	- `lat` (optional): Latitude in degrees.
+	- `day_of_year` (optional): Day of year (int, array, or Raster).
+	- `lat` (optional): Latitude in degrees (float, array, or Raster).
 	- `SHA_deg` (optional): Sunrise hour angle in degrees.
-	- `datetime_UTC` (optional): Datetime in UTC.
+	- `time_UTC` (optional): Datetime in UTC (datetime, string, or array).
 	- `geometry` (optional): Geometry object with latitude.
-- **Returns:** Daylight hours.
+- **Returns:** Daylight hours (float, array, or Raster).
 
 
 ### 6. `sunrise_from_SHA(SHA_deg)`

pyproject.toml

@@ -2,8 +2,8 @@
 requires = ["setuptools>=60", "setuptools-scm>=8.0", "wheel"]
 
 [project]
-name = "sun_angles"
-version = "1.3.0"
+name = "sun-angles"
+version = "1.4.0"
 description = "calculates solar zenith and azimuth and daylight hours"
 readme = "README.md"
 authors = [

sun_angles/daylight.py

@@ -48,10 +48,10 @@ def daylight_from_SHA(SHA_deg: Union[Raster, np.ndarray]) -> Union[Raster, np.nd
 
 
 def calculate_daylight(
-    DOY: Union[Raster, np.ndarray, int] = 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,
-    datetime_UTC: datetime = None,
+    time_UTC: Union[datetime, str, list, np.ndarray] = None,
     geometry: SpatialGeometry = None
 ) -> Union[Raster, np.ndarray]:
     """
@@ -81,23 +81,31 @@ def calculate_daylight(
     Union[Raster, np.ndarray]
         Daylight hours for the given inputs.
     """
+
     # If SHA_deg is not provided, calculate it from DOY and latitude
     if SHA_deg is None:
         # If latitude is not provided, try to extract from geometry
         if lat is None and geometry is not None:
             lat = geometry.lat
 
-        # If DOY is not provided, try to extract from datetime_UTC
-        if DOY is None and datetime_UTC is not None:
-            # If datetime_UTC is a string, parse it to a datetime object
-            if isinstance(datetime_UTC, str):
-                datetime_UTC = parser.parse(datetime_UTC)
-
-            # Convert datetime to day of year
-            DOY = int(pd.Timestamp(datetime_UTC).dayofyear)
-
+        # 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(DOY, lat)
+        SHA_deg = SHA_deg_from_DOY_lat(day_of_year, lat)
 
     # Compute daylight hours from SHA_deg
     daylight_hours = daylight_from_SHA(SHA_deg)

sun_angles/version.py

@@ -1,4 +1,4 @@
 from os.path import join, abspath, dirname
-
 from importlib.metadata import version
+
 __version__ = version("sun-angles")

tests/test_daylight_time_utc.py

@@ -0,0 +1,45 @@
+import unittest
+import numpy as np
+from datetime import datetime
+from sun_angles.daylight import calculate_daylight
+
+class TestCalculateDaylight(unittest.TestCase):
+    def test_time_utc_single_datetime(self):
+        # Test with a single datetime object
+        doy = 100
+        lat = 34.0
+        dt = datetime(2025, 4, 10)  # DOY 100
+        # Should match result with explicit DOY
+        daylight1 = calculate_daylight(day_of_year=doy, lat=lat)
+        daylight2 = calculate_daylight(time_UTC=dt, lat=lat)
+        np.testing.assert_allclose(daylight1, daylight2, rtol=1e-6)
+
+    def test_time_utc_single_string(self):
+        # Test with a single string
+        doy = 200
+        lat = 45.0
+        dt_str = '2025-07-19'  # DOY 200
+        daylight1 = calculate_daylight(day_of_year=doy, lat=lat)
+        daylight2 = calculate_daylight(time_UTC=dt_str, lat=lat)
+        np.testing.assert_allclose(daylight1, daylight2, rtol=1e-6)
+
+    def test_time_utc_array_datetime(self):
+        # Test with an array of datetime objects
+        lats = np.array([0.0, 45.0, -45.0])
+        dts = [datetime(2025, 1, 1), datetime(2025, 6, 21), datetime(2025, 12, 21)]
+        doys = [1, 172, 355]
+        daylight1 = calculate_daylight(day_of_year=doys, lat=lats)
+        daylight2 = calculate_daylight(time_UTC=dts, lat=lats)
+        np.testing.assert_allclose(daylight1, daylight2, rtol=1e-6)
+
+    def test_time_utc_array_string(self):
+        # Test with an array of strings
+        lats = np.array([10.0, 20.0, 30.0])
+        dt_strs = ['2025-03-01', '2025-06-01', '2025-09-01']
+        doys = [60, 152, 244]
+        daylight1 = calculate_daylight(day_of_year=doys, lat=lats)
+        daylight2 = calculate_daylight(time_UTC=dt_strs, lat=lats)
+        np.testing.assert_allclose(daylight1, daylight2, rtol=1e-6)
+
+if __name__ == '__main__':
+    unittest.main()