Version:	1.0.1
Date:	2024-11-20
Title:	Calculate Sun Position, Sunrise, Sunset, Solar Noon and Twilight
Encoding:	UTF-8
Depends:	R (≥ 2.10)
Imports:	methods, sf, stats
Description:	Provides a set of convenient functions for calculating sun-related information, including the sun's position (elevation and azimuth), and the times of sunrise, sunset, solar noon, and twilight for any given geographical location on Earth. These calculations are based on equations provided by the National Oceanic & Atmospheric Administration (NOAA) https://gml.noaa.gov/grad/solcalc/calcdetails.html as described in "Astronomical Algorithms" by Jean Meeus (1991, ISBN: 978-0-943396-35-4).
License:	GPL (≥ 3)
URL:	https://github.com/adokter/suntools/
BugReports:	https://github.com/adokter/suntools/issues
RoxygenNote:	7.3.2
Suggests:	testthat (≥ 3.0.0)
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2024-11-20 19:53:02 UTC; amd427
Author:	Roger Bivand [aut], Adriaan M. Dokter [ctb, cre], Pieter Huybrechts [ctb], Sebastian Luque [aut], Greg Pelletier [ctb], Alexander Tedeschi [ctb]
Maintainer:	Adriaan M. Dokter <amd427@cornell.edu>
Repository:	CRAN
Date/Publication:	2024-11-20 20:20:02 UTC

suntools: calculate sun position, sunrise, sunset, solar noon and twilight

Description

Provides a set of convenient functions for calculating sun-related information, including the sun's position (elevation and azimuth), and the times of sunrise, sunset, solar noon, and twilight for any given geographical location on Earth. These calculations are based on equations provided by the National Oceanic & Atmospheric Administration (NOAA) https://gml.noaa.gov/grad/solcalc/calcdetails.html as described in "Astronomical Algorithms" by Jean Meeus (1991, ISBN: 978-0-943396-35-4).

Details

suntools provides functions for calculating the sun's position, sunrise, sunset, solar noon, and crepuscular (twilight) times for any given geographical location and time on earth.

Main package functions:

• crepuscule(): Calculates crepuscular (twilight) times, i.e. the time of dawn or dusk.

• sunriset(): Calculates the times of sunrise and sunset at a given location.

• solarpos(): Calculates the solar position (elevation and azimuth) at a given location and time.

• solarnoon(): Calculates solar noon time at a given location.

Author(s)

Maintainer: Adriaan M. Dokter amd427@cornell.edu (ORCID) [contributor]

Authors:

• Roger Bivand Roger.Bivand@nhh.no (ORCID)

• Sebastian Luque

Other contributors:

• Pieter Huybrechts pieter.huybrechts@inbo.be (ORCID) [contributor]

• Greg Pelletier [contributor]

• Alexander Tedeschi at744@cornell.edu (ORCID) [contributor]

References

This package uses algorithms provided by the National Oceanic & Atmospheric Administration (NOAA), for more information see

• NOAA's Sunrise/Sunset Calculator

• NOAA's Solar Position Calculator

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

See Also

Useful links:

• https://github.com/adokter/suntools/

• Report bugs at https://github.com/adokter/suntools/issues

Balance coordinates and times

Description

Ensures that the 'crds' and 'dateTime' inputs have the same number of rows. If 'crds' has a single row but 'dateTime' has multiple rows, 'crds' is replicated to match 'dateTime'. Similarly, if 'dateTime' has a single row but 'crds' has multiple rows, 'dateTime' is replicated to match 'crds'. If 'crds' and 'dateTime' have different numbers of rows and neither has just one row, an error is thrown.

Usage

.balanceCrdsTimes(crds, dateTime)

Arguments

Value

A list with 'crds' and 'dateTime' matrices, both with the same number of rows.

Compute crepuscular time

Description

Calculates the crepuscular time, i.e., the time of dawn or dusk at a specific geographical location and time.

Usage

crepuscule(crds, dateTime, ...)

## S4 method for signature 'sf,POSIXct'
crepuscule(
  crds,
  dateTime,
  solarDep,
  direction = c("dawn", "dusk"),
  POSIXct.out = FALSE
)

## S4 method for signature 'matrix,POSIXct'
crepuscule(
  crds,
  dateTime,
  crs = sf::st_crs(4326),
  solarDep,
  direction = c("dawn", "dusk"),
  POSIXct.out = FALSE
)

## S4 method for signature 'SpatialPoints,POSIXct'
crepuscule(
  crds,
  dateTime,
  solarDep,
  direction = c("dawn", "dusk"),
  POSIXct.out = FALSE
)

Arguments

Details

Methods are available for different classes of geographical coordinates, including:

• sf: an object of class sf.

• matrix: An unnamed matrix of coordinates, with each row containing a pair of geographical coordinates in c(lon, lat) order. See the example below.

• SpatialPoints: an object of class SpatialPoints. Input can consist of one location and at least one POSIXct time, 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.

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.

Solar position calculation

Details for the calculations are provided by NOAA here, which we repeat below as a reference.

The calculations in the NOAA Sunrise/Sunset and Solar Position Calculators are based on equations from Astronomical Algorithms, by Jean Meeus. The sunrise and sunset results are theoretically accurate to within a minute for locations between +/- 72° latitude, and within 10 minutes outside of those latitudes. However, due to variations in atmospheric composition, temperature, pressure and conditions, observed values may vary from calculations.

For the purposes of these calculators the current Gregorian calendar is extrapolated backward through time. When using a date before 15 October, 1582, you will need to correct for this. The year preceding year 1 in the calendar is year zero (0). The year before that is -1. The approximations used in these programs are very good for years between 1800 and 2100. Results should still be sufficiently accurate for the range from -1000 to 3000. Outside of this range, results may be given, but the potential for error is higher.

Atmospheric refraction correction

For sunrise and sunset calculations, we assume 0.833° of atmospheric refraction. In the solar position calculator, atmospheric refraction is modeled as:

The effects of the atmosphere vary with atmospheric pressure, humidity and other variables. Therefore the solar position calculations presented here are approximate. Errors in sunrise and sunset times can be expected to increase the further away you are from the equator, because the sun rises and sets at a very shallow angle. Small variations in the atmosphere can have a larger effect.

Value

data.frame with the time of crepuscular light as a fraction of a day; if POSIXct.out=TRUE returns an additional POSIXct timestamp column (default = FALSE)

References

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

• NOAA's sunrise/sunset calculator. These algorithms include corrections for atmospheric refraction effects.

• NOAA's solar calculations details

Examples

#Civil dawn in Ithaca, NY on June 1, 2023

crepuscule(
       matrix(c(-76.4511, 42.4800), nrow = 1),
       as.POSIXct("2023-06-01", tz = "America/New_York"),
       solarDep = 6,
       direction = "dawn",
       POSIXct.out = TRUE
     )

Compute solar noon time

Description

Calculates the solar noon, i.e., the time when the sun is at its highest point in the sky at a specific geographical location and time.

Usage

solarnoon(crds, dateTime, ...)

## S4 method for signature 'sf,POSIXct'
solarnoon(crds, dateTime, POSIXct.out = FALSE)

## S4 method for signature 'matrix,POSIXct'
solarnoon(crds, dateTime, crs = sf::st_crs(4326), POSIXct.out = FALSE)

## S4 method for signature 'SpatialPoints,POSIXct'
solarnoon(crds, dateTime, POSIXct.out = FALSE)

Arguments

Details

Methods are available for different classes of geographical coordinates, including:

• sf: an object of class sf.

• matrix: An unnamed matrix of coordinates, with each row containing a pair of geographical coordinates in c(lon, lat) order. See the example below.

• SpatialPoints: an object of class SpatialPoints. Input can consist of one location and at least one POSIXct time, 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.

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.

Solar position calculation

Details for the calculations are provided by NOAA here, which we repeat below as a reference.

The calculations in the NOAA Sunrise/Sunset and Solar Position Calculators are based on equations from Astronomical Algorithms, by Jean Meeus. The sunrise and sunset results are theoretically accurate to within a minute for locations between +/- 72° latitude, and within 10 minutes outside of those latitudes. However, due to variations in atmospheric composition, temperature, pressure and conditions, observed values may vary from calculations.

For the purposes of these calculators the current Gregorian calendar is extrapolated backward through time. When using a date before 15 October, 1582, you will need to correct for this. The year preceding year 1 in the calendar is year zero (0). The year before that is -1. The approximations used in these programs are very good for years between 1800 and 2100. Results should still be sufficiently accurate for the range from -1000 to 3000. Outside of this range, results may be given, but the potential for error is higher.

Atmospheric refraction correction

For sunrise and sunset calculations, we assume 0.833° of atmospheric refraction. In the solar position calculator, atmospheric refraction is modeled as:

The effects of the atmosphere vary with atmospheric pressure, humidity and other variables. Therefore the solar position calculations presented here are approximate. Errors in sunrise and sunset times can be expected to increase the further away you are from the equator, because the sun rises and sets at a very shallow angle. Small variations in the atmosphere can have a larger effect.

Value

data.frame with the time of solar noon as a fraction of a day; if POSIXct.out=TRUE returns an additional POSIXct timestamp column (default = FALSE)

References

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

• NOAA's solar position calculator. These algorithms include corrections for atmospheric refraction effects.

• NOAA's solar calculations details

Examples

# Solar noon in Ithaca, NY, USA on June 1, 2023

solarnoon(
 matrix(c(-76.4511, 42.4800), nrow = 1),
 as.POSIXct("2023-06-01", tz = "America/New_York"),
 POSIXct.out=TRUE
)

Compute solar position

Description

Calculates the solar position, i.e., the sun's elevation and azimuth, at a specific geographical location and time.

Usage

solarpos(crds, dateTime, ...)

## S4 method for signature 'sf,POSIXct'
solarpos(crds, dateTime, ...)

## S4 method for signature 'matrix,POSIXct'
solarpos(crds, dateTime, crs = sf::st_crs(4326), ...)

## S4 method for signature 'SpatialPoints,POSIXct'
solarpos(crds, dateTime, ...)

Arguments

Details

Methods are available for different classes of geographical coordinates, including:

• sf: an object of class sf.

• matrix: An unnamed matrix of coordinates, with each row containing a pair of geographical coordinates in c(lon, lat) order. See the example below.

• SpatialPoints: an object of class SpatialPoints. Input can consist of one location and at least one POSIXct time, 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.

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.

Solar position calculation

Details for the calculations are provided by NOAA here, which we repeat below as a reference.

The calculations in the NOAA Sunrise/Sunset and Solar Position Calculators are based on equations from Astronomical Algorithms, by Jean Meeus. The sunrise and sunset results are theoretically accurate to within a minute for locations between +/- 72° latitude, and within 10 minutes outside of those latitudes. However, due to variations in atmospheric composition, temperature, pressure and conditions, observed values may vary from calculations.

For the purposes of these calculators the current Gregorian calendar is extrapolated backward through time. When using a date before 15 October, 1582, you will need to correct for this. The year preceding year 1 in the calendar is year zero (0). The year before that is -1. The approximations used in these programs are very good for years between 1800 and 2100. Results should still be sufficiently accurate for the range from -1000 to 3000. Outside of this range, results may be given, but the potential for error is higher.

Atmospheric refraction correction

For sunrise and sunset calculations, we assume 0.833° of atmospheric refraction. In the solar position calculator, atmospheric refraction is modeled as:

The effects of the atmosphere vary with atmospheric pressure, humidity and other variables. Therefore the solar position calculations presented here are approximate. Errors in sunrise and sunset times can be expected to increase the further away you are from the equator, because the sun rises and sets at a very shallow angle. Small variations in the atmosphere can have a larger effect.

Value

matrix with the solar azimuth (in degrees from North), and elevation.

References

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

• NOAA's solar position calculator. These algorithms include corrections for atmospheric refraction effects.

• NOAA's solar calculations details

Examples

# Solar position in Ithaca, NY, USA on June 1, 2023 at 08:00:00

solarpos(
 matrix(c(-76.4511, 42.4800), nrow = 1),
 as.POSIXct("2023-06-01 08:00:00", tz = "America/New_York")
)

Calculate sunrise/sunset

Description

Calculates sunrise or sunset at a specific geographical location and time depending on the direction parameter.

Usage

sunriset(crds, dateTime, ...)

## S4 method for signature 'sf,POSIXct'
sunriset(
  crds,
  dateTime,
  direction = c("sunrise", "sunset"),
  POSIXct.out = FALSE
)

## S4 method for signature 'matrix,POSIXct'
sunriset(
  crds,
  dateTime,
  crs = sf::st_crs(4326),
  direction = c("sunrise", "sunset"),
  POSIXct.out = FALSE
)

## S4 method for signature 'SpatialPoints,POSIXct'
sunriset(
  crds,
  dateTime,
  direction = c("sunrise", "sunset"),
  POSIXct.out = FALSE
)

Arguments

Details

Methods are available for different classes of geographical coordinates, including:

• sf: an object of class sf.

• matrix: An unnamed matrix of coordinates, with each row containing a pair of geographical coordinates in c(lon, lat) order. See the example below.

• SpatialPoints: an object of class SpatialPoints. Input can consist of one location and at least one POSIXct time, 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.

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.

Solar position calculation

Details for the calculations are provided by NOAA here, which we repeat below as a reference.

The calculations in the NOAA Sunrise/Sunset and Solar Position Calculators are based on equations from Astronomical Algorithms, by Jean Meeus. The sunrise and sunset results are theoretically accurate to within a minute for locations between +/- 72° latitude, and within 10 minutes outside of those latitudes. However, due to variations in atmospheric composition, temperature, pressure and conditions, observed values may vary from calculations.

For the purposes of these calculators the current Gregorian calendar is extrapolated backward through time. When using a date before 15 October, 1582, you will need to correct for this. The year preceding year 1 in the calendar is year zero (0). The year before that is -1. The approximations used in these programs are very good for years between 1800 and 2100. Results should still be sufficiently accurate for the range from -1000 to 3000. Outside of this range, results may be given, but the potential for error is higher.

Atmospheric refraction correction

For sunrise and sunset calculations, we assume 0.833° of atmospheric refraction. In the solar position calculator, atmospheric refraction is modeled as:

The effects of the atmosphere vary with atmospheric pressure, humidity and other variables. Therefore the solar position calculations presented here are approximate. Errors in sunrise and sunset times can be expected to increase the further away you are from the equator, because the sun rises and sets at a very shallow angle. Small variations in the atmosphere can have a larger effect.

Value

data.frame with the time of sunrise as a fraction of a day; if POSIXct.out=TRUE returns an additional POSIXct timestamp column (default = FALSE)

References

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

• NOAA's sunrise/sunset calculator. These algorithms include corrections for atmospheric refraction effects.

• NOAA's solar calculations details

Examples

#Sunset in Ithaca, NY, USA on June 1, 2023

sunriset(
 matrix(c(-76.4511, 42.4800), nrow = 1),
 as.POSIXct("2023-06-01", tz = "America/New_York"),
 direction='sunset',
 POSIXct.out=TRUE
)