Skip to contents

Relative Air Mass (AM)

Source: R/relative-am.r
relative_AM.Rd

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.

Value

A numeric vector with the relative air mass values.

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.

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. doi:10.1364/AO.28.004735 .

Young, A. T. (1994) Air mass and refraction. Applied Optics, 33, 1108-1110. 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))
#> [1]  0.999  1.150  1.990 26.300     NA
relative_AM(elevation.angle = c(90, 60, 30, 1, -10),
            occluded.value = Inf)
#> [1]  0.999  1.150  1.990 26.300    Inf
relative_AM(zenith.angle = 0)
#> [1] 0.999

# using the true or astronomical sun elevation
relative_AMt(elevation.angle = c(90, 60, 30, 1, -10))
#> [1]  1.00  1.15  1.99 23.50    NA
relative_AMt(elevation.angle = c(90, 60, 30, 1, -10),
            occluded.value = Inf)
#> [1]  1.00  1.15  1.99 23.50   Inf
relative_AMt(zenith.angle = 0)
#> [1] 1

# 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)
#> [1] 1.04
relative_AMt_geotime(ymd_hms("2014-06-23 12:00:00",
                             tz = "America/Argentina/Buenos_Aires"),
                    geocode = baires.geo)
#> [1] 1.04
relative_AM_geotime(ymd_hms("2014-06-23 12:00:00",
                            tz = "America/Argentina/Buenos_Aires") +
                      hours(0:12),
                    geocode = baires.geo)
#>  [1]  1.04  1.02  1.05  1.14  1.33  1.69  2.43  4.59 23.70    NA    NA    NA
#> [13]    NA