`day_night.Rd`

Functions for calculating the timing of solar positions, given geographical coordinates and dates. They can be also used to find the time for an arbitrary solar elevation between 90 and -90 degrees by supplying "twilight" angle(s) as argument.

day_night(date = lubridate::now(tzone = "UTC"), tz = lubridate::tz(date), geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"), twilight = "none", unit.out = "hours") day_night_fast(date, tz, geocode, twilight, unit.out) noon_time(date = lubridate::today(), tz = lubridate::tz(date), geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"), twilight = "none", unit.out = "datetime") sunrise_time(date = lubridate::today(), tz = lubridate::tz(date), geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"), twilight = "sunlight", unit.out = "datetime") sunset_time(date = lubridate::today(), tz = lubridate::tz(date), geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"), twilight = "sunlight", unit.out = "datetime") day_length(date = lubridate::now(), tz = "UTC", geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"), twilight = "sunlight", unit.out = "hours") night_length(date = lubridate::now(), tz = "UTC", geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"), twilight = "sunlight", unit.out = "hours")

date | "vector" of POSIXct times or Date objects, any valid TZ is allowed, default is current date at Greenwich. |
---|---|

tz | character vector indicating time zone to be used in output. |

geocode | data frame with one or more rows and variables lon and lat as numeric values (degrees). If present, address will be copied to the output. |

twilight | character string, one of "none", "rim", "refraction",
"sunlight", "civil", "nautical", "astronomical", or a |

unit.out | character string, One of "datetime", "day", "hour", "minute", or "second". |

A tibble with variables day, tz, twilight.rise, twilight.set, longitude, latitude, address, sunrise, noon, sunset, daylength, nightlength or the corresponding individual vectors.

`noon_time`

, `sunrise_time`

and `sunset_time`

return a
vector of POSIXct times

`day_length`

and `night_length`

return numeric a vector
giving the length in hours

Twilight names are interpreted as follows. "none": solar elevation =
0 degrees. "rim": upper rim of solar disk at the horizon or solar elevation
= -0.53 / 2. "refraction": solar elevation = 0 degrees + refraction
correction. "sunlight": upper rim of solar disk corrected for refraction,
which is close to the value used by the online NOAA Solar Calculator.
"civil": -6 degrees, "naval": -12 degrees, and "astronomical": -18 degrees.
Unit names for output are as follows: "day", "hours", "minutes" and
"seconds" times for sunrise and sunset are returned as times-of-day since
midnight expressed in the chosen unit. "date" or "datetime" return the same
times as datetime objects with TZ set (this is much slower than "hours").
Day length and night length are returned as numeric values expressed in
hours when `"datetime"' is passed as argument to `unit.out`

. If
twilight is a numeric vector of length two, the element with index 1 is
used for sunrise and that with index 2 for sunset.

This function is an implementation of Meeus equations as used in NOAAs on-line web calculator, which are very precise and valid for a very broad range of dates. For sunrise and sunset the times are affected by refraction in the atmosphere, which does in turn depend on weather conditions. The effect of refraction on the apparent position of the sun is only an estimate based on "typical" conditions. The more tangential to the horizon is the path of the sun, the larger the effect of refraction is on the times of visual occlusion of the sun behind the horizon---i.e. the largest timing errors occur at high latitudes. The computation is not defined for latitudes 90 and -90 degrees, i.e. at the poles.

There exists a different R implementation of the same algorithms called
"AstroCalcPureR" available as function `astrocalc4r`

in package
'fishmethods'. Although the equations used are almost all the same, the
function signatures and which values are returned differ. In particular,
the present implementation splits the calculation into two separate
functions, one returning angles at given instants in time, and a separate
one returning the timing of events for given dates.

In the current implementation functions `sunrise_time`

,
`noon_time`

, `sunset_time`

and `day_length`

are wrappers
on `day_night`

, so if more than one quantity is needed it is
preferable to directly call `day_night`

as it will be faster.

`night_length`

returns the length of night-time conditions in one
day (00:00:00 to 23:59:59), rather than the length of the night between two
consecutive days.

Be aware that R's `Date`

class does not save time zone
metadata. This can lead to ambiguities in the current implementation
based on time instants. The argument passed to `date`

should be
of class `POSIXct`

, in other words an instant in time, from which
the correct date will be computed based on the `tz`

argument.

The primary source for the algorithm used is the book: Meeus, J. (1998) Astronomical Algorithms, 2 ed., Willmann-Bell, Richmond, VA, USA. ISBN 978-0943396613.

A different implementation is available at
https://www.nefsc.noaa.gov/AstroCalc4R/ and in R paclage
`astrocalc4r`

. In 'fishmethods' (= 1.11-0) there
is a bug in function astrocalc4r() that affects sunrise and sunset times.

An interactive web page using the same algorithms is available at https://www.esrl.noaa.gov/gmd/grad/solcalc/. There are small differences in the returned times compared to our function that seem to be related to the estimation of atmospheric refraction (about 0.1 degrees).

Other astronomy related functions: `format.solar_time`

,
`is.solar_time`

,
`print.solar_time`

, `solar_time`

,
`sun_angles`

library(lubridate)#> #>#>#> #>#> # A tibble: 1 x 12 #> day tz twilight.rise twilight.set longitude latitude address sunrise #> <date> <chr> <dbl> <dbl> <dbl> <dbl> <chr> <dbl> #> 1 2015-05-30 UTC 0 0 25 60 NA 1.38 #> # ... with 4 more variables: noon <dbl>, sunset <dbl>, daylength <dbl>, #> # nightlength <dbl>#> # A tibble: 10 x 12 #> day tz twilight.rise twilight.set longitude latitude address #> <date> <chr> <dbl> <dbl> <dbl> <dbl> <chr> #> 1 2015-05-31 UTC -6 -6 25 60 NA #> 2 2015-06-01 UTC -6 -6 25 60 NA #> 3 2015-06-02 UTC -6 -6 25 60 NA #> 4 2015-06-03 UTC -6 -6 25 60 NA #> 5 2015-06-04 UTC -6 -6 25 60 NA #> 6 2015-06-05 UTC -6 -6 25 60 NA #> 7 2015-06-06 UTC -6 -6 25 60 NA #> 8 2015-06-07 UTC -6 -6 25 60 NA #> 9 2015-06-08 UTC -6 -6 25 60 NA #> 10 2015-06-09 UTC -6 -6 25 60 NA #> # ... with 5 more variables: sunrise <dbl>, noon <dbl>, sunset <dbl>, #> # daylength <dbl>, nightlength <dbl>#> [1] "2015-05-30 01:12:23 UTC"#> [1] "2015-05-30 10:17:30 UTC"#> [1] "2015-05-30 19:22:37 UTC"#> [1] 18.17045#> [1] 0.757102