Merge pull request #6 from gregory-halverson/main

v1.3.0 with `UTC_offset_hours_for_longitude` and `solar_day_of_year_for_longitude`

Author: gregory-halverson

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=60", "setuptools-scm>=8.0", "wheel"]
 
 [project]
 name = "solar_apparent_time"
-version = "1.2.0"
+version = "1.3.0"
 description = "methods to translate Python datetime between solar apparent time and Coordinate Universal Time (UTC)"
 readme = "README.md"
 authors = [

solar_apparent_time/solar_apparent_time.py

@@ -1,3 +1,5 @@
+from typing import Union
+
 from datetime import datetime, timedelta
 import numpy as np
 import rasters as rt
@@ -28,6 +30,19 @@ def solar_to_UTC(time_solar: datetime, lon: float) -> datetime:
     """
     return time_solar - timedelta(hours=(np.radians(lon) / np.pi * 12))
 
+def UTC_offset_hours_for_longitude(lon: Union[float, np.ndarray]) -> Union[float, np.ndarray]:
+    """
+    Calculates the offset in hours from UTC based on the given longitude.
+
+    Args:
+        lon (Union[float, np.ndarray]): The longitude in degrees.
+
+    Returns:
+        Union[float, np.ndarray]: The calculated offset in hours from UTC.
+    """
+    # Convert longitude to radians and calculate the offset in hours from UTC
+    return np.radians(lon) / np.pi * 12
+
 def UTC_offset_hours_for_area(geometry: rt.RasterGeometry) -> rt.Raster:
     """
     Calculates the UTC offset in hours for a given raster geometry.
@@ -61,6 +76,29 @@ def solar_day_of_year_for_area(time_UTC: datetime, geometry: rt.RasterGeometry)
 
     return doy
 
+def solar_day_of_year_for_longitude(time_UTC: datetime, lon: Union[float, np.ndarray]) -> Union[float, np.ndarray]:
+    """
+    Calculates the day of year based on the given UTC time and longitude.
+
+    Args:
+        time_UTC (datetime.datetime): The UTC time to calculate the day of year for.
+        lon (Union[float, np.ndarray]): The longitude in degrees.
+
+    Returns:
+        Union[float, np.ndarray]: The calculated day of year.
+    """
+    # Calculate the day of year at the given longitude
+    DOY_UTC = time_UTC.timetuple().tm_yday
+    hour_UTC = time_UTC.hour + time_UTC.minute / 60 + time_UTC.second / 3600
+    offset = UTC_offset_hours_for_longitude(lon)
+    hour_of_day = hour_UTC + offset
+    DOY = DOY_UTC
+    # Adjust the day of year if the hour of day is outside the range [0, 24]
+    DOY = np.where(hour_of_day < 0, DOY - 1, DOY)
+    DOY = np.where(hour_of_day > 24, DOY + 1, DOY)
+
+    return DOY
+
 def solar_hour_of_day_for_area(time_UTC: datetime, geometry: rt.RasterGeometry) -> rt.Raster:
     """
     Calculates the hour of the day for a given UTC time and raster geometry.

solar_apparent_time/version.txt

@@ -1 +1 @@
-1.2.0
+1.3.0