| Title: | Utilities Dealing with Solar Time Such as Sun Position and Time of Sunrise |
|---|---|
| Description: | Provide utilities to work with solar time, i.e. where noon is exactly when sun culminates. Provides functions for computing sun position and times of sunrise and sunset. |
| Authors: | Thomas Wutzler [aut, cre] |
| Maintainer: | Thomas Wutzler <[email protected]> |
| License: | GPL-3 |
| Version: | 0.0.4 |
| Built: | 2024-11-25 15:26:03 UTC |
| Source: | https://github.com/earthyscience/solartime |
Provide utilities to work with solar time, i.e. where noon is exactly when sun culminates. Provides functions for computing sun position and times of sunrise and sunset.
Most fundamental functions are
corrected fractional hour getSolarTimeHour
based on computeSolarToLocalTimeDifference
computing position of the sun computeSunPosition
On this basis, properties are computed such as
hour of sunrise and sunset:
computeSunriseHour,computeSunsetHour
daylength in hours: computeDayLength
flagging times as day or night:
computeIsDayByHour and
computeIsDayByLocation and
More utils provide
get the hours ahead UTC: getHoursAheadOfUTC
get fractional hour of the day: getFractionalHours
Also have a look at the package vignettes.
Thomas Wutzler
Compute the Day-length in hours for given time and coordinates
computeDayLength(timestamp, latDeg, ...)computeDayLength(timestamp, latDeg, ...)
timestamp |
POSIXt vector |
latDeg |
Latitude in (decimal) degrees |
... |
further arguments to |
result of computeDayLengthDoy
Thomas Wutzler
Compute the Day-length in hours for given time and coordinates
computeDayLengthDoy(doy, latDeg)computeDayLengthDoy(doy, latDeg)
doy |
integer vector with day of year [DoY, 1..366], same length as Hour or length 1 |
latDeg |
Latitude in (decimal) degrees |
numeric vector of length(doy) giving the time between sunrise and sunset in hours
Thomas Wutzler
doy <- 1:366 plot( computeDayLengthDoy(doy, latDeg = 51) ~ doy) # north pole: daylength 0 and 24 hours plot( computeDayLengthDoy( doy, latDeg = +80) ~ doy ) plot( computeDayLengthDoy( doy, latDeg = -80) ~ doy )doy <- 1:366 plot( computeDayLengthDoy(doy, latDeg = 51) ~ doy) # north pole: daylength 0 and 24 hours plot( computeDayLengthDoy( doy, latDeg = +80) ~ doy ) plot( computeDayLengthDoy( doy, latDeg = -80) ~ doy )
tell for each date, whether its daytime
computeIsDayByHour(date, sunriseHour = 7, sunsetHour = 18, duskOffset = 0)computeIsDayByHour(date, sunriseHour = 7, sunsetHour = 18, duskOffset = 0)
date |
POSIXct vector |
sunriseHour |
sunrise as fractional hour (0..24) (vector of length date or length 1) |
sunsetHour |
sunset as fractional hour (vector of length date or length 1) |
duskOffset |
integer scalar: time in hours after dusk for which records are still regarded as day |
logical vector (length(date)): true if its daytime
Thomas Wutzler
tell for each timestamp, whether its daytime
computeIsDayByLocation(timestamp, latDeg, longDeg, timeZone = getHoursAheadOfUTC(timestamp), duskOffset = 0, isCorrectSolartime = TRUE)computeIsDayByLocation(timestamp, latDeg, longDeg, timeZone = getHoursAheadOfUTC(timestamp), duskOffset = 0, isCorrectSolartime = TRUE)
timestamp |
POSIXct vector |
latDeg |
Latitude in (decimal) degrees |
longDeg |
Longitude in (decimal) degrees |
timeZone |
Time zone (in hours) ahead of UTC (Central Europe is +1) |
duskOffset |
integer scalar: time in hours after dusk for which records are still regarded as day |
isCorrectSolartime |
set to FALSE to omit correction between local time and solar time, e.g. if coordinates cannot be provided |
computes hour of sunrise and sunset from given date in timezone hour (assuming dates are given in timezone instead of solartime)
logical vector (length(date)): true if its daytime
Thomas Wutzler
dateSeq <- seq( as.POSIXct("2017-03-20", tz = "Etc/GMT-1") ,as.POSIXct("2017-03-21", tz = "Etc/GMT-1") , by = "30 min") tmp <- computeIsDayByLocation( dateSeq, latDeg = 50.93, longDeg = 11.59, timeZone = 1) plot( tmp ~ dateSeq ) yday <- as.POSIXlt(dateSeq[1])$yday + 1L sunrise <- computeSunriseHourDoy( yday, latDeg = 50.93, longDeg = 11.59, timeZone = 1) sunset <- computeSunsetHourDoy( yday, latDeg = 50.93, longDeg = 11.59, timeZone = 1) abline( v = trunc(dateSeq[1], units = "days") + c(sunrise,sunset)*3600L )dateSeq <- seq( as.POSIXct("2017-03-20", tz = "Etc/GMT-1") ,as.POSIXct("2017-03-21", tz = "Etc/GMT-1") , by = "30 min") tmp <- computeIsDayByLocation( dateSeq, latDeg = 50.93, longDeg = 11.59, timeZone = 1) plot( tmp ~ dateSeq ) yday <- as.POSIXlt(dateSeq[1])$yday + 1L sunrise <- computeSunriseHourDoy( yday, latDeg = 50.93, longDeg = 11.59, timeZone = 1) sunset <- computeSunsetHourDoy( yday, latDeg = 50.93, longDeg = 11.59, timeZone = 1) abline( v = trunc(dateSeq[1], units = "days") + c(sunrise,sunset)*3600L )
computes the time difference in hours between (apparent) solar time and local time
computeSolarToLocalTimeDifference(longDeg, timeZone, doy = NA, fracYearInRad = 2 * pi * (doy - 1)/365.24)computeSolarToLocalTimeDifference(longDeg, timeZone, doy = NA, fracYearInRad = 2 * pi * (doy - 1)/365.24)
longDeg |
Longitude in (decimal) degrees |
timeZone |
Time zone (in hours) ahead of UTC (Berlin is +1) |
doy |
integer vector with day of year [DoY, 1..366], Specify NA get mean solar time across the year instead of apparent solar time (i.e. with differences throughout the year due to eccentricity of earth orbit) |
fracYearInRad |
may specify instead of doy for efficiency. |
time difference in hours to be added to local winter time to get solar time
Thomas Wutzler
# Jena: 50.927222, 11.586111 longDeg <- 11.586 doi <- 1:366 # due to longitude: west of timezone meridian: sun culminates later, # solar time is less than local time (localDiff <- computeSolarToLocalTimeDifference(longDeg, 1L)*60) # taking into account shift during the year due to earth orbit eccentricity plot( computeSolarToLocalTimeDifference(longDeg, 1L, doi)*60 ~ doi ) abline(h = localDiff)# Jena: 50.927222, 11.586111 longDeg <- 11.586 doi <- 1:366 # due to longitude: west of timezone meridian: sun culminates later, # solar time is less than local time (localDiff <- computeSolarToLocalTimeDifference(longDeg, 1L)*60) # taking into account shift during the year due to earth orbit eccentricity plot( computeSolarToLocalTimeDifference(longDeg, 1L, doi)*60 ~ doi ) abline(h = localDiff)
Calculate the position of the sun
computeSunPosition(timestamp, latDeg, longDeg)computeSunPosition(timestamp, latDeg, longDeg)
timestamp |
POSIXct having a valid tzone attribute, |
latDeg |
Latitude in (decimal) degrees |
longDeg |
Longitude in (decimal) degrees |
as returned by computeSunPositionDoyHour
Thomas Wutzler
Compute the position of the sun (solar angle)
computeSunPositionDoyHour(doy, hour, latDeg, longDeg = NA, timeZone = NA, isCorrectSolartime = TRUE)computeSunPositionDoyHour(doy, hour, latDeg, longDeg = NA, timeZone = NA, isCorrectSolartime = TRUE)
doy |
integer vector with day of year [DoY, 1..366], same length as Hour or length 1 |
hour |
numeric vector with local winter time as decimal hour [0..24) |
latDeg |
Latitude in (decimal) degrees |
longDeg |
Longitude in (decimal) degrees |
timeZone |
Time zone (in hours) ahead of UTC (Central Europe is +1) |
isCorrectSolartime |
by default corrects hour (given in local winter time) for latitude to solar time (where noon is exactly at 12:00). Set this to FALSE if times are specified already as solar times. |
This code assumes that Hour is given in local winter time zone.
By default, it corrects by longitude to solar time (where noon
is exactly at 12:00).
Set argument isCorrectSolartime to FALSE to use the given
local winter time instead.
named numeric matrix with one row for each time with entries
hour |
Solar time in fractional hours after midnight, (or given hour if isCorrectSolartime = FALSE). |
declination |
Solar declination (rad) |
elevation |
Solar elevation (rad) with 0 at horizon increasing towards zenith |
azimuth |
Solar azimuth (rad) with 0 at North increasing eastwards |
Thomas Wutzler
computeSunPositionDoyHour( 160, hour = 0:24, latDeg = 51, longDeg = 13.6, timeZone = 1L)computeSunPositionDoyHour( 160, hour = 0:24, latDeg = 51, longDeg = 13.6, timeZone = 1L)
Compute the hour of sunrise for given day and coordinates
computeSunriseHour(timestamp, latDeg, longDeg = NA, timeZone = getHoursAheadOfUTC(timestamp), ...)computeSunriseHour(timestamp, latDeg, longDeg = NA, timeZone = getHoursAheadOfUTC(timestamp), ...)
timestamp |
POSIXt vector |
latDeg |
Latitude in (decimal) degrees |
longDeg |
Longitude in (decimal) degrees (not required if solar time is sufficient) |
timeZone |
Time zone (in hours) ahead of UTC (Central Europe is +1) (not required if solar time is sufficient) |
... |
further arguments to |
result of computeSunriseHourDoy
Thomas Wutzler
Compute the hour of sunrise for given day and coordinates
computeSunriseHourDoy(doy, latDeg, longDeg = NA, timeZone = NA, isCorrectSolartime = TRUE)computeSunriseHourDoy(doy, latDeg, longDeg = NA, timeZone = NA, isCorrectSolartime = TRUE)
doy |
integer vector with day of year [DoY, 1..366] |
latDeg |
Latitude in (decimal) degrees |
longDeg |
Longitude in (decimal) degrees (not required if solar time is sufficient) |
timeZone |
Time zone (in hours) ahead of UTC (Central Europe is +1) (not required if solar time is sufficient) |
isCorrectSolartime |
sunrise hour is computed first for solar time (where noon is exactly at 12:00) If TRUE (default) then sunrise hour is converted to local winter time, based on timeZone and longitude. |
numeric vector of length(doy) giving the time of sunrise in hours after midnight. Polar night is indicated by 12h, polar day by 0h.
Thomas Wutzler
today <- as.POSIXlt(Sys.Date())$yday (sunrise <- computeSunriseHourDoy(today, latDeg = 51, isCorrectSolartime = FALSE)) (sunrise <- computeSunriseHourDoy(today, latDeg = 51, longDeg = 11.586, timeZone = +1)) # elevation near zero computeSunPositionDoyHour(160, sunrise, latDeg = 51, isCorrectSolartime = FALSE) # doy <- 1:366 plot( computeSunriseHourDoy(doy, latDeg = 51, isCorrectSolartime = FALSE) ~ doy ) # north pole: daylength 0 and 24 hours plot( computeSunriseHourDoy( doy, latDeg = +80, isCorrectSolartime = FALSE) ~ doy ) plot( computeSunriseHourDoy( doy, latDeg = -80, isCorrectSolartime = FALSE) ~ doy )today <- as.POSIXlt(Sys.Date())$yday (sunrise <- computeSunriseHourDoy(today, latDeg = 51, isCorrectSolartime = FALSE)) (sunrise <- computeSunriseHourDoy(today, latDeg = 51, longDeg = 11.586, timeZone = +1)) # elevation near zero computeSunPositionDoyHour(160, sunrise, latDeg = 51, isCorrectSolartime = FALSE) # doy <- 1:366 plot( computeSunriseHourDoy(doy, latDeg = 51, isCorrectSolartime = FALSE) ~ doy ) # north pole: daylength 0 and 24 hours plot( computeSunriseHourDoy( doy, latDeg = +80, isCorrectSolartime = FALSE) ~ doy ) plot( computeSunriseHourDoy( doy, latDeg = -80, isCorrectSolartime = FALSE) ~ doy )
Compute the hour of sunrise for given day and coordinates
computeSunsetHour(timestamp, latDeg, longDeg = NA, timeZone = getHoursAheadOfUTC(timestamp), ...)computeSunsetHour(timestamp, latDeg, longDeg = NA, timeZone = getHoursAheadOfUTC(timestamp), ...)
timestamp |
POSIXt vector |
latDeg |
Latitude in (decimal) degrees |
longDeg |
Longitude in (decimal) degrees (not required if solar time is sufficient) |
timeZone |
Time zone (in hours) ahead of UTC (Central Europe is +1) (not required if solar time is sufficient) |
... |
further arguments to |
result of computeSunsetHourDoy
Thomas Wutzler
Compute the hour of sunrise for given day and coordinates
computeSunsetHourDoy(doy, latDeg, longDeg = NA, timeZone = NA, isCorrectSolartime = TRUE)computeSunsetHourDoy(doy, latDeg, longDeg = NA, timeZone = NA, isCorrectSolartime = TRUE)
doy |
integer vector with day of year [DoY, 1..366] |
latDeg |
Latitude in (decimal) degrees |
longDeg |
Longitude in (decimal) degrees (not required if solar time is sufficient) |
timeZone |
Time zone (in hours) ahead of UTC (Central Europe is +1) (not required if solar time is sufficient) |
isCorrectSolartime |
sunrise hour is computed first for solar time (where noon is exactly at 12:00) If TRUE (default) then sunrise hour is converted to local winter time, based on timeZone and longitude. |
numeric vector of length(doy) giving the time of sunset in hours after midnight. Polar night is indicated by 12h, polar day by 24h.
Thomas Wutzler
today <- as.POSIXlt(Sys.Date())$yday (sunset <- computeSunsetHourDoy(today, latDeg = 51, isCorrectSolartime = FALSE)) (sunset <- computeSunsetHourDoy(today, latDeg = 51, longDeg = 11.586, timeZone = +1)) # doy <- 1:366 plot( computeSunsetHourDoy(doy, latDeg = 51, isCorrectSolartime = FALSE) ~ doy ) # north pole: daylength 0 and 24 hours plot( computeSunsetHourDoy( doy, latDeg = +80, isCorrectSolartime = FALSE) ~ doy ) plot( computeSunsetHourDoy( doy, latDeg = -80, isCorrectSolartime = FALSE) ~ doy )today <- as.POSIXlt(Sys.Date())$yday (sunset <- computeSunsetHourDoy(today, latDeg = 51, isCorrectSolartime = FALSE)) (sunset <- computeSunsetHourDoy(today, latDeg = 51, longDeg = 11.586, timeZone = +1)) # doy <- 1:366 plot( computeSunsetHourDoy(doy, latDeg = 51, isCorrectSolartime = FALSE) ~ doy ) # north pole: daylength 0 and 24 hours plot( computeSunsetHourDoy( doy, latDeg = +80, isCorrectSolartime = FALSE) ~ doy ) plot( computeSunsetHourDoy( doy, latDeg = -80, isCorrectSolartime = FALSE) ~ doy )
get the time difference to previous midnight in fractional hours
getFractionalHours(timestamp)getFractionalHours(timestamp)
timestamp |
POSIXt vector |
numeric vector of fractional hours
Thomas Wutzler
get the time difference to UTC in hours
getHoursAheadOfUTC(timestamp)getHoursAheadOfUTC(timestamp)
timestamp |
POSIXt vector |
integer vector of how many hours noon of timestamp is ahead of noon in UTC
Thomas Wutzler
Get the fractional hour of solar time
getSolarTimeHour(timestamp, longDeg)getSolarTimeHour(timestamp, longDeg)
timestamp |
POSIXt vector in local time |
longDeg |
Longitude in (decimal) degrees |
fractional hour corrected by difference to local time
Thomas Wutzler
modify tzone attribute of timestamp to 'GMT+x' for local to given longitude
setLocalTimeZone(timestamp, longDeg)setLocalTimeZone(timestamp, longDeg)
timestamp |
POSIXct |
longDeg |
Longitude in (decimal) degrees |
timestamp with modified tzone attribute. Its the same time
point expressed in another time zone. E.g. "2019-04-04 00:00:00 UTC"
becomes "2019-04-04 10:00:00 +10" for a longitude of +150 (Sydney, Australia)
Thomas Wutzler