# sun-methods

##### Methods for sun ephemerides calculations

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).

##### Usage

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

##### Arguments

- 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.

##### Details

NOAA used the reference below to develop their Sunrise/Sunset

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.

##### Value

`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.

##### Note

NOAA notes that

##### Warning

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.

##### References

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

##### Examples

```
## 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))
```

*Documentation reproduced from package maptools, version 0.6-15, License: GPL version 2 or later (R and interface code), MIT (shapelib code)*