relative_AM: Relative Air Mass (AM)

In SunCalcMeeus: Sun Position and Daylight Calculations

Relative Air Mass (AM)

Description

Approximate relative air mass (AM) computed from the sun's apparent or true position (sun elevation or sun zenith angle) or from geographic and time coordinates.

Usage

relative_AM(
  elevation.angle = NULL,
  zenith.angle = NULL,
  occluded.value = NA_real_
)

relative_AMt(
  elevation.angle = NULL,
  zenith.angle = NULL,
  occluded.value = NA_real_
)

relative_AM_geotime(
  time = lubridate::now(tzone = "UTC"),
  tz = lubridate::tz(time),
  geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"),
  occluded.value = NA_real_
)

relative_AMt_geotime(
  time = lubridate::now(tzone = "UTC"),
  tz = lubridate::tz(time),
  geocode = tibble::tibble(lon = 0, lat = 51.5, address = "Greenwich"),
  occluded.value = NA_real_
)

Arguments

elevation.angle, zenith.angle	numeric vector Angle in degrees for the sun position. An argument should be passed to one and only one of elevation_angle or zenith_angle.
occluded.value	numeric Value to return when elevation angle is negative (sun below the horizon).
time	A "vector" of POSIXct Time, with any valid time zone (TZ) is allowed, default is current time.
tz	character string indicating time zone to be used in output.
geocode	data frame with variables lon and lat as numeric values (degrees), nrow > 1, allowed.

Details

Function relative_AM() implements equation (3) in Kasten and Young (1989). This equation is only an approximation to the tabulated values in the same paper and based on the apparent position of the sun as observed from Earth surface. relative_AMt() implements equation (5) in Young (1994). This equation is only an approximation to the tabulated values based on the true or astronomical position of the sun.

In both cases returned values are rounded to three significant digits.

Function relative_AM_geotime() is a wrapper on relative_AM() that calls function sun_elevation() to obtain the apparent position of the sun from the geographic and time coordinates. Function relative_AMt_geotime() is a wrapper on relative_AMt() that calls function sun_elevation() to obtain the true position of the sun from the geographic and time coordinates. At very low sun elevations the values returned by these two functions differ slightly because of the use of different approximations to correct for atmospheric refraction.

Value

A numeric vector with the relative air mass values.

Note

Although relative air mass is not defined when the sun is not visible, returning a value different from the default NA might be useful in some cases and made possible by passing an argument to parameter occluded.value.

References

F. Kasten, A. T. Young (1989) Revised optical air mass tables and approximation formula. Applied Optics, 28, 4735-4738. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1364/AO.28.004735")}.

Young, A. T. (1994) Air mass and refraction. Applied Optics, 33, 1108-1110. \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1364/AO.33.001108")}

See Also

sun_angles

Examples

# using the apparent sun elevation
relative_AM(elevation.angle = c(90, 60, 30, 1, -10))
relative_AM(elevation.angle = c(90, 60, 30, 1, -10),
            occluded.value = Inf)
relative_AM(zenith.angle = 0)

# using the true or astronomical sun elevation
relative_AMt(elevation.angle = c(90, 60, 30, 1, -10))
relative_AMt(elevation.angle = c(90, 60, 30, 1, -10),
            occluded.value = Inf)
relative_AMt(zenith.angle = 0)

# Define example geographic and time coordinates
baires.geo <-
  data.frame(lat = 34.60361, lon = -58.38139, address = "Buenos Aires")

# using time and geographic coordinates
library(lubridate)
relative_AM_geotime(ymd_hms("2014-06-23 12:00:00",
                            tz = "America/Argentina/Buenos_Aires"),
                    geocode = baires.geo)
relative_AMt_geotime(ymd_hms("2014-06-23 12:00:00",
                             tz = "America/Argentina/Buenos_Aires"),
                    geocode = baires.geo)
relative_AM_geotime(ymd_hms("2014-06-23 12:00:00",
                            tz = "America/Argentina/Buenos_Aires") +
                      hours(0:12),
                    geocode = baires.geo)

SunCalcMeeus documentation built on April 4, 2025, 1:43 a.m.