fix issue #180

Author: adokter

NEWS.md

@@ -4,6 +4,8 @@
 
 * new option `keep_timestamp` in `regularize_vpts()`, which allows individual profiles to keep there original timestamp instead of the timestamp of the regularized grid
 
+* improved documentation of sunrise/sunset functions (#180) and new option `force_tz` (4968019)
+
 # bioRad 0.5.1
 
 Minor bugfixes. All issues included in this release can be found [here](https://github.com/adokter/bioRad/pull/334). This release primarily fixes a bug that will become effective once R version 4.0 is released.

R/sunrise_sunset.R

@@ -13,7 +13,15 @@
 #' @return The moment of sunrise or sunset for the date set by \code{date}and time zone as specified
 #' (by \code{date} and \code{tz}) or in UTC if not specified.
 #'
-#' @details The angular diameter of the sun is about 0.536 degrees,
+#' @details
+#' The day for which sunrise and sunset are calcuated is given by the input date.
+#' Sunrise and sunset are calculated relative to the moment of solar noon for that date,
+#' i.e. the first sunrise before the moment of solar noon, and the first sunset after the
+#' moment of solar noon. Therefore, depending on the timezone provided, it is possible that
+#' the nearest sunrise prior to solar noon occurs a day earlier than the input date.
+#' Similarly, sunset may occur a day later than the input date. See examples for details.
+#'
+#' The angular diameter of the sun is about 0.536 degrees,
 #' therefore the moment of sunrise/sunset corresponds to half that elevation
 #' at -0.268 degrees.
 #'
@@ -22,9 +30,6 @@
 #' Approximate astronomical formula are used, therefore the moment of
 #' sunrise / sunset may be off by a few minutes
 #'
-#' Sunrise and sunset is given for the day specified by \code{date}, with sunset always
-#' later than sunrise given the same \code{date}.
-#'
 #' If \code{force_tz} is \code{TRUE}, the input date is converted to the timezone
 #' set by \code{tz} prior to calculating the sunrise/sunset time, resulting in a shift by +/-1 day
 #'
@@ -35,8 +40,38 @@
 #' # sunset in the Netherlands
 #' sunset("2016-01-01", 5, 53)
 #'
-#' # civil twilight in Ithaca, NY, today
-#' sunrise(Sys.time(), -76.5, 42.4, elev = -6)
+#' # civil twilight in Ithaca, NY
+#' sunrise("2016-01-01", -76.5, 42.4, elev = -6)
+#'
+#' # next sunset in South Dakota, USA
+#' sunset("2016-11-15", -98, 45)
+#'
+#' # Beware that some days have two sunsets, or
+#' # two sunrises! E.g. on 5 Oct (local timezone) at
+#' # this location  sunset is actually on the 6 Oct
+#' # in UTC time zone, i.e. the next day
+#' sunset("2016-10-5", -98, 45)
+#' # One day later, sunset is again on 6 Oct:
+#' sunset("2016-10-6", -98, 45)
+#'
+#' # working in local time zones typically avoids such ambiguities:
+#' sunset(as_datetime("2016-06-05",tz="America/Chicago"), -98, 45)
+#' sunset(as_datetime("2016-06-06",tz="America/Chicago"), -98, 45)
+#'
+#' # use force_tz to force output to a specific time zone, by default UTC:
+#' sunset(as_datetime("2016-06-05",tz="America/Chicago"), -98, 45, force_tz=T)
+#' sunset(as_datetime("2016-06-06",tz="America/Chicago"), -98, 45, force_tz=T)
+#'
+#' # Also beware of jumps in sunrise and sunset date with longitude:
+#' sunrise("2016-11-01", 100, 45)
+#' sunrise("2016-11-01", 102, 45)
+#'
+#' # sunrise date can even be two days earlier in specific cases:
+#' # e.g. "2016-10-31 00:00" in Asia/Ulaanbaatar time zone is converted to
+#' # 2016-10-30 16:00 UTC when force_tz=TRUE. Solar noon on 2016-10-30 at this
+#' location in Mongolia is at 04:55 UTC, and the first sunrise prior to this
+#' is on 2016-10-29:
+#' sunrise(as_datetime("2016-10-31",tz="Asia/Ulaanbaatar"), 120, 45, tz="UTC", force_tz=T)
 #' @name sunrise_sunset
 NULL