View source: R/read-tuv-file.r
qtuv_s.e.irrad | R Documentation |
Call the Quick TUV calculator web server and return a source_spct
object with the simulated spectral energy irradiance data.
qtuv_s.e.irrad(
w.length = list(wStart = 280, wStop = 420, wIntervals = 140),
sun.elevation = NULL,
geocode = data.frame(lon = 0, lat = 51.5, address = "Greenwich"),
time = lubridate::now(),
tz = NULL,
locale = readr::default_locale(),
ozone.du = 300,
albedo = 0.1,
ground.altitude = 0,
measurement.altitude = 0,
clouds = data.frame(optical.depth = 0, base = 4, top = 5),
aerosols = data.frame(optical.depth = 0.235, ssaaer = 0.99, alpha = 1),
num.streams = 2,
spectra = list(direct = 1, diffuse.down = 1, diffuse.up = 0),
added.vars = NULL,
label = "",
server.url = "https://www.acom.ucar.edu/cgi-bin/acom/TUV/V5.3/tuv",
file = NULL
)
qtuv_m_s.e.irrad(
w.length = list(wStart = 280, wStop = 420, wIntervals = 140),
sun.elevation = NULL,
geocode = data.frame(lon = 0, lat = 51.5, address = "Greenwich"),
time = lubridate::now(),
tz = NULL,
locale = readr::default_locale(),
ozone.du = 300,
albedo = 0.1,
ground.altitude = 0,
measurement.altitude = 0,
clouds = data.frame(optical.depth = 0, base = 4, top = 5),
aerosols = data.frame(optical.depth = 0.235, ssaaer = 0.99, alpha = 1),
num.streams = 2,
spectra = list(direct = 1, diffuse.down = 1, diffuse.up = 0),
added.vars = NULL,
label = "",
server.url = "https://www.acom.ucar.edu/cgi-bin/acom/TUV/V5.3/tuv",
file = NULL
)
w.length |
list of parameters describing the wavelengths, or a numeric vector from which the parameters will be constructed. |
sun.elevation |
numeric Angle in degrees above the horizon. If NULL its
value is computed from |
geocode |
data.frame with variables |
time |
A "vector" of POSIXct time, with any valid time zone (TZ) is allowed, default is current time. |
tz |
character Time zone is by default read from the file. |
locale |
The locale controls defaults that vary from place to place. The
default locale is US-centric (like R), but you can use
|
ozone.du |
numeric Ozone column in Dobson units. |
albedo |
numeric Surface albedo (= reflectance) as a fraction of one. |
measurement.altitude , ground.altitude |
numeric Altitudes above sea level expressed in km. |
clouds |
data.frame Parameters |
aerosols |
data.frame Parameters |
num.streams |
integer Number of streams used in computations, 2 or 4. |
spectra |
named list with weights for the different components of the spectrum. |
added.vars |
character vector Accepted member values are |
label |
character string, but if |
server.url |
character The URL used to access the Quick TUV calculator server. |
file |
character The name under which the file returned by the server is
locally saved. If |
The Quick TUV calculator, is an on-line freely accessible server
running the TUV atmospheric chemistry and radiation transfer model with a
simplified user interface. In this case, version 5.3 is called passing the
parameter values passed as arguments in the call to
qtuv_s.e.irrad()
. The response is saved in a text file that is
subsequently read with function read_qtuv_txt()
into a
source_spct
object.
Function qtuv_m_s.e.irrad()
calls qtuv_s.e.irrad()
repeatedly
accepting a numeric vector longer than one as argument, for parameters:
sun.elevation
, time
or ozone.du
, and data frames with
nrow >= 1. In a given call, only one parameter at a time can obey multiple
values, with others currently truncated to the first value.
The formal parameter names are informative and consistent with other
functions in the R for Photobiology Suite and differ from the short names
used for the parameters in the FORTRAN code of the TUV model. In the case
of w.length
two ways of specifying wavelengths are supported. Some
defaults also differ from those of the Quick TUV calculator.
In the case of qtuv_s.e.irrad()
, a source_spct object obtained
by finding the center of each wavelength interval in the Quick TUV output
file, and adding the variables listed in added.vars
. In the case of
qtuv_m_s.e.irrad()
, a source_mspct object containing a collection of
spectra.
If a file name is passed as argument, the data as downloaded are saved into persistent files, one file per spectrum. The names of the saved files always end in '.txt'.
This function connects to a server managed by UCAR, the
University Corporation for Atmospheric Research located in the U.S.A. to
obtain simulated spectral data. UCAR manages the U.S. National Science
Foundation National Center for Atmospheric Research (NSF NCAR) on behalf of
NSF. As any download with the HTTPS protocol, using this function entails
some risk. To minimize the risk, the returned page is saved as plain text,
checked for conformity with the expected content, and if valid decoded into
an R data object. When using the default argument file = NULL
, the
file used is a temporary one and is deleted before the function returns the
call, irrespective of it being conformant or not.
The administrators of the Quick TUV Calculator at UCAR suggest a maximum load of approximately 100 spectral simulations per day and user. For larger workloads they encourage the local installation of the TUV model which is open-source and freely available. A local installation, also allows access to the full set of input parameters and outputs. Currently a local instance of the TUV model can be called from R with package 'foqat'.
The Quick TUV calculator has multiple output modes that return different types of computed values. The use of output mode 5 is hard-coded in this function as other modes return summary values rather than spectral data. Package 'foqat' provides a more flexible alternative supporting other output modes in addition to mode 5.
If the argument passed to w.length
is a numeric vector, the range
and length are used to reconstruct the accepted parameters. The returned
spectrum has always a uniformly spaced wavelengths.
When using this function, more detailed metadata are available than when reading an output file, as not all the simulation input parameters are listed in the output text.
In interactive use of the Quick TUV Calculator, the same parameters as
accepted by qtuv_s.e.irradiance()
as arguments are
entered through the web interface at
https://www.acom.ucar.edu/Models/TUV/Interactive_TUV/. This page
together with its documentation, can be consulted for additional
information on the parameters and the model.
https://www.acom.ucar.edu/Models/TUV/Interactive_TUV/. This
URL could change in the future as well as the server URL. The formal
parameter server.url
was included only for use in such a case.
Sasha Madronich (2017-2021) Tropospheric Ultraviolet and Visible radiation (TUV) model. https://www2.acom.ucar.edu/modeling/tropospheric-ultraviolet-and-visible-tuv-radiation-model. Visited on 2024-08-29.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.