solar_time()
computes the time of day expressed in seconds since the
astronomical midnight using and instant in time and a geocode as input. Solar
time is useful when we want to plot data according to the local solar time
rather than the local time in use at a time zone. How the returned instant in
time is expressed depends on the argument passed to unit.out
.
Value
In all cases solar time is expressed as time since local astronomical
midnight and, thus, lacks date information. If unit.out = "time"
, a
numeric value in seconds with an additional class attribute
"solar_time"; if unit.out = "datetime"
, a "POSIXct" value in seconds
from midnight but with an additional class attribute "solar_date"; if
unit.out = "hour"
or unit.out = "minute"
or unit.out =
"second"
, a numeric value.
Details
Solar time is determined by the position of the sun in the sky and it almost always differs from the time expressed in the local time coordinates in use. The differences can vary from a few minutes up to a couple of hours depending on the exact location within the time zone and the use or not of daylight saving time.
Note
The algorithm is approximate, it calculates the difference between
local solar noon and noon in the time zone of time
and uses this
value for the whole day when converting times into solar time. Days are not
exactly 24 h long. Between successive days the shift is only a few seconds,
and this leads to a small jump at midnight.
Warning!
Returned values are computed based on the time zone of the argument for parameter time. In the case of solar time, this timezone does not affect the result. However, in the case of solar dates the date part may be off by one day, if the time zone does not match the coordinates of the geocode value provided as argument.
See also
Other Local solar time functions:
as.solar_date()
,
is.solar_time()
,
print.solar_time()
Examples
BA.geocode <-
data.frame(lon = -58.38156, lat = -34.60368, address = "Buenos Aires, Argentina")
sol_t <- solar_time(lubridate::dmy_hms("21/06/2016 10:00:00", tz = "UTC"),
BA.geocode)
sol_t
#> [1] "06:04:35"
class(sol_t)
#> [1] "solar_time" "numeric"
sol_d <- solar_time(lubridate::dmy_hms("21/06/2016 10:00:00", tz = "UTC"),
BA.geocode,
unit.out = "datetime")
sol_d
#> [1] "2016-06-21 06:04:35 solar"
class(sol_d)
#> [1] "solar_date" "POSIXct" "POSIXt"