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.).

See Also

setFilterProperties

setSoluteProperties

Other constructors of spectral objects: as.calibration_spct(), as.chroma_spct(), as.cps_spct(), as.filter_spct(), as.generic_spct(), as.object_spct(), as.raw_spct(), as.reflector_spct(), as.response_spct(), as.solute_spct(), as.source_spct()


[Package photobiology version 0.11.2 Index]