sun-methods             package:maptools             R Documentation

_M_e_t_h_o_d_s _f_o_r _s_u_n _e_p_h_e_m_e_r_i_d_e_s _c_a_l_c_u_l_a_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Functions for calculating sunrise, sunset, and times of dawn and
     dusk, with flexibility for the various formal definitions. They
     use algorithms provided by the National Oceanic & Atmospheric
     Administration (NOAA).

_U_s_a_g_e:

     ## S4 method for signature 'SpatialPoints, POSIXct':
     crepuscule(crds, dateTime, solarDep, direction=c("dawn", "dusk"),
                POSIXct.out=FALSE)
     ## S4 method for signature 'matrix, POSIXct':
     crepuscule(crds, dateTime,
                proj4string=CRS("+proj=longlat +datum=WGS84"), solarDep,
                direction=c("dawn", "dusk"), POSIXct.out=FALSE)
     ## S4 method for signature 'SpatialPoints, POSIXct':
     sunriset(crds, dateTime, direction=c("sunrise", "sunset"),
              POSIXct.out=FALSE)
     ## S4 method for signature 'matrix, POSIXct':
     sunriset(crds, dateTime,
              proj4string=CRS("+proj=longlat +datum=WGS84"),
              direction=c("sunrise", "sunset"), POSIXct.out=FALSE)
     ## S4 method for signature 'SpatialPoints, POSIXct':
     solarnoon(crds, dateTime, POSIXct.out=FALSE)
     ## S4 method for signature 'matrix, POSIXct':
     solarnoon(crds, dateTime, proj4string=CRS("+proj=longlat +datum=WGS84"),
               POSIXct.out=FALSE)
     ## S4 method for signature 'SpatialPoints, POSIXct':
     solarpos(crds, dateTime, ...)
     ## S4 method for signature 'matrix, POSIXct':
     solarpos(crds, dateTime, proj4string=CRS("+proj=longlat +datum=WGS84"), ...)

_A_r_g_u_m_e_n_t_s:

    crds: a 'SpatialPoints' or 'matrix' object, containing x and y
          coordinates (in that order).

dateTime: a POSIXct object with the date and time associated to
          calculate ephemerides for points given in crds.

solarDep: numeric vector with the angle of the sun below the horizon in
          degrees.

direction: one of "dawn", "dusk", "sunrise", or "sunset", indicating
          which ephemerides should be calculated.

POSIXct.out: logical indicating whether POSIXct output should be
          included.

proj4string: string with valid projection string describing the
          projection of data in 'crds'.

     ...: other arguments passed through.

_D_e_t_a_i_l_s:

     NOAA used the reference below to develop their Sunrise/Sunset

     <URL: http://www.srrb.noaa.gov/highlights/sunrise/sunrise.html>
     and Solar Position 

     <URL: http://www.srrb.noaa.gov/highlights/sunrise/azel.html>
     Calculators.  The algorithms include corrections for atmospheric
     refraction effects.

     Input can consist of one location and at least one POSIXct times,
     or one POSIXct time and at least one location.  solarDep is
     recycled as needed.

     Do not use the daylight savings time zone string for supplying
     dateTime, as many OS will not be able to properly set it to
     standard time when needed.

_V_a_l_u_e:

     'crepuscule', 'sunriset', and 'solarnoon' return a numeric vector
     with the time of day at which the event occurs, expressed as a
     fraction, if POSIXct.out is FALSE; otherwise they return a data
     frame with both the fraction and the corresponding POSIXct date
     and time. 'solarpos' returns a matrix with the solar azimuth (in
     degrees from North), and elevation.

_W_a_r_n_i_n_g:

     Compared to NOAA's original Javascript code, the sunrise and
     sunset estimates from this translation may differ by +/- 1 minute,
     based on tests using selected locations spanning the globe. This
     translation does not include calculation of prior or next
     sunrises/sunsets for locations above the Arctic Circle or below
     the Antarctic Circle.

_N_o_t_e:

     NOAA notes that "for latitudes greater than 72 degrees N and S,
     calculations are accurate to within 10 minutes.  For latitudes
     less than +/- 72 degrees accuracy is approximately one minute."

_A_u_t_h_o_r(_s):

     Sebastian P. Luque spluque@gmail.com, translated from Greg
     Pelletier's gpel461@ecy.wa.gov VBA code (available from <URL:
     http://www.ecy.wa.gov/programs/eap/models.html>), who in turn
     translated it from original Javascript code by NOAA (see Details).
     Roger Bivand roger.bivand@nhh.no adapted the code to work with
     'sp' classes.

_R_e_f_e_r_e_n_c_e_s:

     Meeus, J.  (1991)  Astronomical Algorithms.  Willmann-Bell, Inc.

_E_x_a_m_p_l_e_s:

     ## Location of Helsinki, Finland, in decimal degrees,
     ## as listed in NOAA's website
     hels <- matrix(c(24.97, 60.17), nrow=1)
     Hels <- SpatialPoints(hels, proj4string=CRS("+proj=longlat +datum=WGS84"))
     d041224 <- as.POSIXct("2004-12-24", tz="EET")
     ## Astronomical dawn
     crepuscule(hels, d041224, solarDep=18, direction="dawn", POSIXct.out=TRUE)
     crepuscule(Hels, d041224, solarDep=18, direction="dawn", POSIXct.out=TRUE)
     ## Nautical dawn
     crepuscule(hels, d041224, solarDep=12, direction="dawn", POSIXct.out=TRUE)
     crepuscule(Hels, d041224, solarDep=12, direction="dawn", POSIXct.out=TRUE)
     ## Civil dawn
     crepuscule(hels, d041224, solarDep=6, direction="dawn", POSIXct.out=TRUE)
     crepuscule(Hels, d041224, solarDep=6, direction="dawn", POSIXct.out=TRUE)
     solarnoon(hels, d041224, POSIXct.out=TRUE)
     solarnoon(Hels, d041224, POSIXct.out=TRUE)
     solarpos(hels, as.POSIXct(Sys.time(), tz="EET"))
     solarpos(Hels, as.POSIXct(Sys.time(), tz="EET"))
     sunriset(hels, d041224, direction="sunrise", POSIXct.out=TRUE)
     sunriset(Hels, d041224, direction="sunrise", POSIXct.out=TRUE)
     ## Using a sequence of dates
     Hels_seq <- seq(from=d041224, length.out=365, by="days")
     up <- sunriset(Hels, Hels_seq, direction="sunrise", POSIXct.out=TRUE)
     down <- sunriset(Hels, Hels_seq, direction="sunset", POSIXct.out=TRUE)
     day_length <- down$time - up$time
     plot(Hels_seq, day_length, type="l")

     ## Using a grid of spatial points for the same point in time
     grd <- GridTopology(c(-179,-89), c(1,1), c(359,179))
     SP <- SpatialPoints(coordinates(grd),
                         proj4string=CRS("+proj=longlat +datum=WGS84"))
     wint <- as.POSIXct("2004-12-21", tz="GMT")
     win <- crepuscule(SP, wint, solarDep=6, direction="dawn")
     SPDF <- SpatialGridDataFrame(grd,
      proj4string=CRS("+proj=longlat +datum=WGS84"),
      data=data.frame(winter=win))
     image(SPDF, axes=TRUE, col=cm.colors(40))

