R: Spectral-object constructors

source_spct {photobiology}

R Documentation

Spectral-object constructors

Description

These constructor functions can be used to create spectral objects derived from generic_spct. They take as arguments numeric vectors for the wavelengths and spectral data, and numeric, character, and logical values for metadata attributes to be saved to the objects created and options controlling the creation process.

Usage

source_spct(
  w.length = NULL,
  s.e.irrad = NULL,
  s.q.irrad = NULL,
  ...,
  time.unit = c("second", "day", "exposure"),
  bswf.used = c("none", "unknown"),
  comment = NULL,
  strict.range = getOption("photobiology.strict.range", default = FALSE),
  multiple.wl = 1L,
  idfactor = NULL
)

calibration_spct(
  w.length = NULL,
  irrad.mult = NA_real_,
  ...,
  comment = NULL,
  instr.desc = NA,
  multiple.wl = 1L,
  idfactor = NULL
)

raw_spct(
  w.length = NULL,
  counts = NA_real_,
  ...,
  comment = NULL,
  instr.desc = NA,
  instr.settings = NA,
  multiple.wl = 1L,
  idfactor = NULL
)

cps_spct(
  w.length = NULL,
  cps = NA_real_,
  ...,
  comment = NULL,
  instr.desc = NA,
  instr.settings = NA,
  multiple.wl = 1L,
  idfactor = NULL
)

generic_spct(
  w.length = NULL,
  ...,
  comment = NULL,
  multiple.wl = 1L,
  idfactor = NULL
)

response_spct(
  w.length = NULL,
  s.e.response = NULL,
  s.q.response = NULL,
  ...,
  time.unit = c("second", "day", "exposure"),
  response.type = c("response", "action"),
  comment = NULL,
  multiple.wl = 1L,
  idfactor = NULL
)

filter_spct(
  w.length = NULL,
  Tfr = NULL,
  Tpc = NULL,
  Afr = NULL,
  A = NULL,
  ...,
  Tfr.type = c("total", "internal"),
  Rfr.constant = NA_real_,
  thickness = NA_real_,
  attenuation.mode = NA,
  comment = NULL,
  strict.range = getOption("photobiology.strict.range", default = FALSE),
  multiple.wl = 1L,
  idfactor = NULL
)

reflector_spct(
  w.length = NULL,
  Rfr = NULL,
  Rpc = NULL,
  ...,
  Rfr.type = c("total", "specular"),
  comment = NULL,
  strict.range = getOption("photobiology.strict.range", default = FALSE),
  multiple.wl = 1L,
  idfactor = NULL
)

solute_spct(
  w.length = NULL,
  K.mole = NULL,
  K.mass = NULL,
  attenuation.XS = NULL,
  ...,
  log.base = 10,
  K.type = c("attenuation", "absorption", "scattering"),
  name = NA_character_,
  mass = NA_character_,
  formula = NULL,
  structure = grDevices::as.raster(matrix()),
  ID = NA_character_,
  solvent.name = NA_character_,
  solvent.ID = NA_character_,
  comment = NULL,
  strict.range = getOption("photobiology.strict.range", default = FALSE),
  multiple.wl = 1L,
  idfactor = NULL
)

object_spct(
  w.length = NULL,
  Rfr = NULL,
  Tfr = NULL,
  Afr = NULL,
  ...,
  Tfr.type = c("total", "internal"),
  Rfr.type = c("total", "specular"),
  comment = NULL,
  strict.range = getOption("photobiology.strict.range", default = FALSE),
  multiple.wl = 1L,
  idfactor = NULL
)

chroma_spct(
  w.length = NULL,
  x,
  y,
  z,
  ...,
  comment = NULL,
  strict.range = getOption("photobiology.strict.range", default = FALSE),
  multiple.wl = 1L,
  idfactor = NULL
)

Arguments

`w.length`	numeric vector with wavelengths in nanometres [`nm`].
`s.e.irrad`	numeric vector with spectral energy irradiance in [`W\,m^{-2}\,nm^{-1}`] or [`J\,d^{-1}\,m^{-2}\,nm^{-1}`].
`s.q.irrad`	numeric A vector with spectral photon irradiance in [`mol\,s^{-1}\,m^{-2}\,nm^{-1}`] or [`mol\,d^{-1}\,m^{-2}\,nm^{-1}`].
`...`	other arguments passed to `tibble()` such as vectors or factors to be added as additional columns.
`time.unit`	character string indicating the time unit used for spectral irradiance or exposure (`"second"`, `"day"` or `"exposure"`) or an object of class duration as defined in package lubridate.
`bswf.used`	character A string indicating the BSWF used, if any, for spectral effective irradiance or exposure (`"none"` or the name of the BSWF).
`comment`	character A string to be added as a comment attribute to the object created.
`strict.range`	logical Flag indicating whether off-range values result in an error instead of a warning.
`multiple.wl`	numeric Maximum number of repeated `w.length` entries with same value. (As with multiple spectra stored in long from).
`idfactor`	character Name of factor distinguishing multiple spectra when stored longitudinally (required if `multiple.wl` > 1).
`irrad.mult`	numeric vector with multipliers for each detector pixel expressed in units of `W\,m^{-2}\,nm^{-1}\,n^{-1}\,s`, where `n\,s^{-1}` are detector counts per second.
`instr.desc`	a list describing the spectrometer used to acquire the data.
`counts`	numeric vector with raw counts expressed per scan.
`instr.settings`	a list describing the settings used to acquire the data.
`cps`	numeric vector with linearized raw counts expressed per second [`n\,s^{-1}`]
`s.e.response`	numeric vector with a biological, chemical or physical response expressed per unit spectral energy irradiance [`W\,m^{-2}\,nm^{-1}` or `J\,d^{-1}\,m^{-2}\,nm^{-1}`].
`s.q.response`	numeric vector with a biological, chemical or physical response expressed per unit spectral photon irradiance in [`mol\,s^{-1}\,m^{-2}\,nm^{-1}` or `mol\,d^{-1}\,m^{-2}\,nm^{-1}`].
`response.type`	a character string, either `"response"` or `"action"`.
`Tfr`	numeric vector with spectral transmittance as fraction of one [`/1`].
`Tpc`	numeric vector with spectral transmittance as percent values
`Afr`	numeric vector of absorptance as fraction of one [`/1`].
`A`	numeric vector of absorbance values (`log_{10}`-base a.u.)
`Tfr.type`	character string indicating whether transmittance and absorptance values are `"total"` or `"internal"` values
`Rfr.constant`	numeric The value of the reflection factor [`/1`].
`thickness`	numeric The thickness of the material.
`attenuation.mode`	character One of `"reflection"`, `"absorption"` or `"mixed"`.
`Rfr`	numeric vector with spectral reflectance as fraction of one [`/1`].
`Rpc`	numeric vector with spectral reflectance as percent values.
`Rfr.type`	character A string, either `"total"` or `"specular"`.
`K.mole`	numeric vector with molar attenuation coefficient in SI units [`m^2\,mol^-1`].
`K.mass`	numeric vector with mass attenuation coefficient in SI units [`m^2\,g^-1`].
`attenuation.XS`	numeric vector with attenuation cross section values (Converted during object construction into `K.mole`.)
`log.base`	numeric Normally one of `e` or `10`. Data are stored always on base 10 corresponding to decadal absorbance as used in chemistry.
`K.type`	character A string, either `"attenuation"`, `"absorption"` or `"scattering"`.
`name`, `solvent.name`	character The names of the substance and of the solvent. A named character vector, with member names such as "IUPAC" for the authority.
`mass`	numeric The molar mass in Dalton [Da] (`Da = g\,mol^{-1}`).
`formula`	character The molecular formula.
`structure`	raster A bitmap of the structure.
`ID`, `solvent.ID`	character The ID of the substance and of the solvent. A named character vector, with member names such as "ChemSpider" or "PubChem" for the authority.
`x`, `y`, `z`	numeric colour coordinates

Details

Constructors can be used to create spectral objects from spectral quantities expressed on a single base or unit. Some of the functions have different formal parameters accepting a quantity expressed in different units, however, an argument can be passed to only one of these formal parameters in a given call. The constructors object_spct() and chroma_spct() require arguments to be passed for multiple but distinct spectral quantities.

Value

A object of class generic_spct or a class derived from it, depending on the function used. In other words an object of a class with the same name as the constructor function.

Warning for filter_spct!

Not entering metadata when creating an object will limit the available operations! While "internal" transmittance is defined as the transmittance of the material body itself, "total" transmittance includes the effects of surface reflectance on the amount of light transmitted. For non-diffusing materials like glass an approximate Rfr.constant value can be used to convert "total" into "internal" transmittance values and vice versa. Use NA if not known, or not applicable, e.g., for materials subject to internal scattering.

Warning for solute_spct!

You should always set the base for logarithms to match that on which the absorbance data are expressed. Failing to do this will result in bad data and all further computation will be wrong. Not entering metadata when creating an object will limit the available operations! Mass should be indicated in daltons or g\,mol^{-1}. The SI unit of molar attenuation coefficient is the square metre per mole (m^2\,mol^{1}), but in practice, quantities are usually expressed in terms of M^{-1}\,cm^{-1} or l\,mol^{-1}\,cm^{-1} (the latter two units are both equal to 0.1 m^2\,mol^{-1} and quantities expressed in them need to be divided by 10 when passed as arguments to K.mole.).