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

including `UTC_offset_hours`, `day_of_year`, and `hour_of_day`

Author: gregory-halverson-jpl

README.md

@@ -5,3 +5,60 @@ The `solar_apparent_time` Python package translates Python datetime between sola
 [Gregory H. Halverson](https://github.com/gregory-halverson-jpl) (they/them)<br>
 [[email protected]](mailto:[email protected])<br>
 NASA Jet Propulsion Laboratory 329G
+
+## Usage
+
+### `UTC_to_solar(time_UTC: datetime, lon: float) -> datetime`
+
+Converts Coordinated Universal Time (UTC) to solar apparent time at given longitude for single time.
+
+**Parameters:**
+- `time_UTC` (datetime): The UTC time.
+- `lon` (float): The longitude in degrees.
+
+**Returns:**
+- datetime: The solar time at the given longitude.
+
+### `solar_to_UTC(time_solar: datetime, lon: float) -> datetime`
+
+Converts solar apparent time to Coordinated Universal Time (UTC) at given longitude for single time.
+
+**Parameters:**
+- `time_solar` (datetime): The solar time.
+- `lon` (float): The longitude in degrees.
+
+**Returns:**
+- datetime: The UTC time at the given longitude.
+
+### `UTC_offset_hours(geometry: rasters.RasterGeometry) -> rasters.Raster`
+
+Calculates the UTC offset in hours for an area defined by a `RasterGeometry` object from the `rasters` package.
+
+**Parameters:**
+- `geometry` (rasters.RasterGeometry): The raster geometry.
+
+**Returns:**
+- rasters.Raster: The UTC offset in hours.
+
+### `day_of_year(time_UTC: datetime, geometry: rasters.RasterGeometry) -> rasters.Raster`
+
+Calculates the day of the year for a given UTC time and an area defined by a `RasterGeometry` object from the `rasters` package.
+
+**Parameters:**
+- `time_UTC` (datetime): The UTC time.
+- `geometry` (rasters.RasterGeometry): The raster geometry.
+
+**Returns:**
+- rasters.Raster: The day of the year.
+
+### `hour_of_day(time_UTC: datetime, geometry: rasters.RasterGeometry) -> rasters.Raster`
+
+Calculates the hour of the day for a given UTC time and an area defined by a `RasterGeometry` object from the `rasters` package.
+
+**Parameters:**
+- `time_UTC` (datetime): The UTC time.
+- `geometry` (rasters.RasterGeometry): The raster geometry.
+
+**Returns:**
+- rasters.Raster: The hour of the day.
+

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=60", "setuptools-scm>=8.0", "wheel"]
 
 [project]
 name = "solar_apparent_time"
-version = "1.0.2"
+version = "1.1.0"
 description = "methods to translate Python datetime between solar apparent time and Coordinate Universal Time (UTC)"
 readme = "README.md"
 authors = [
@@ -14,10 +14,14 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "numpy"
+    "numpy",
+    "rasters"
 ]
 
 requires-python = ">=3.11"
 
 [tool.setuptools.package-data]
 solar_apparent_time = ["*.txt"]
+
+[project.urls]
+"Homepage" = "https://github.com/JPL-Evapotranspiration-Algorithms/solar_apparent_time"

solar_apparent_time/solar_apparent_time.py

@@ -1,8 +1,81 @@
 from datetime import datetime, timedelta
 import numpy as np
+import rasters as rt
 
 def UTC_to_solar(time_UTC: datetime, lon: float) -> datetime:
+    """
+    Converts Coordinated Universal Time (UTC) to solar time.
+
+    Parameters:
+    time_UTC (datetime): The UTC time.
+    lon (float): The longitude in degrees.
+
+    Returns:
+    datetime: The solar time at the given longitude.
+    """
     return time_UTC + timedelta(hours=(np.radians(lon) / np.pi * 12))
 
 def solar_to_UTC(time_solar: datetime, lon: float) -> datetime:
+    """
+    Converts solar time to Coordinated Universal Time (UTC).
+
+    Parameters:
+    time_solar (datetime): The solar time.
+    lon (float): The longitude in degrees.
+
+    Returns:
+    datetime: The UTC time at the given longitude.
+    """
     return time_solar - timedelta(hours=(np.radians(lon) / np.pi * 12))
+
+def UTC_offset_hours(geometry: rt.RasterGeometry) -> rt.Raster:
+    """
+    Calculates the UTC offset in hours for a given raster geometry.
+
+    Parameters:
+    geometry (rt.RasterGeometry): The raster geometry.
+
+    Returns:
+    rt.Raster: The UTC offset in hours.
+    """
+    return rt.Raster(np.radians(geometry.lon) / np.pi * 12, geometry=geometry)
+
+def day_of_year(time_UTC: datetime, geometry: rt.RasterGeometry) -> rt.Raster:
+    """
+    Calculates the day of the year for a given UTC time and raster geometry.
+
+    Parameters:
+    time_UTC (datetime): The UTC time.
+    geometry (rt.RasterGeometry): The raster geometry.
+
+    Returns:
+    rt.Raster: The day of the year.
+    """
+    doy_UTC = time_UTC.timetuple().tm_yday
+    hour_UTC = time_UTC.hour + time_UTC.minute / 60 + time_UTC.second / 3600
+    UTC_offset_hours = UTC_offset_hours(geometry=geometry)
+    hour_of_day = hour_UTC + UTC_offset_hours
+    doy = doy_UTC
+    doy = rt.where(hour_of_day < 0, doy - 1, doy)
+    doy = rt.where(hour_of_day > 24, doy + 1, doy)
+
+    return doy
+
+def hour_of_day(time_UTC: datetime, geometry: rt.RasterGeometry) -> rt.Raster:
+    """
+    Calculates the hour of the day for a given UTC time and raster geometry.
+
+    Parameters:
+    time_UTC (datetime): The UTC time.
+    geometry (rt.RasterGeometry): The raster geometry.
+
+    Returns:
+    rt.Raster: The hour of the day.
+    """
+    hour_UTC = time_UTC.hour + time_UTC.minute / 60 + time_UTC.second / 3600
+    UTC_offset_hours = UTC_offset_hours(geometry=geometry)
+    hour_of_day = hour_UTC + UTC_offset_hours
+    hour_of_day = rt.where(hour_of_day < 0, hour_of_day + 24, hour_of_day)
+    hour_of_day = rt.where(hour_of_day > 24, hour_of_day - 24, hour_of_day)
+
+    return hour_of_day

solar_apparent_time/version.txt

@@ -1 +1 @@
-1.0.2
+1.1.0