fscale: Rescale a spectrum using a summary function

In photobiology: Photobiological Calculations

Rescale a spectrum using a summary function

Description

These methods return a spectral object of the same class as the one supplied as argument but with the spectral data rescaled based on a summary function f applied over a specific range of wavelengths and a target value for the summary value.

Usage

fscale(x, ...)

## Default S3 method:
fscale(x, ...)

## S3 method for class 'source_spct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  set.scaled = target == 1,
  ...
)

## S3 method for class 'response_spct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  set.scaled = target == 1,
  ...
)

## S3 method for class 'filter_spct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  qty.out = getOption("photobiology.filter.qty", default = "transmittance"),
  set.scaled = target == 1,
  ...
)

## S3 method for class 'reflector_spct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  qty.out = NULL,
  set.scaled = target == 1,
  ...
)

## S3 method for class 'solute_spct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  qty.out = NULL,
  set.scaled = target == 1,
  ...
)

## S3 method for class 'raw_spct'
fscale(x, range = NULL, f = "mean", target = 1, set.scaled = target == 1, ...)

## S3 method for class 'cps_spct'
fscale(x, range = NULL, f = "mean", target = 1, set.scaled = target == 1, ...)

## S3 method for class 'generic_spct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  set.scaled = target == 1,
  col.names,
  ...
)

## S3 method for class 'source_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  set.scaled = target == 1,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'response_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  set.scaled = target == 1,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'filter_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  qty.out = getOption("photobiology.filter.qty", default = "transmittance"),
  set.scaled = target == 1,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'reflector_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  qty.out = NULL,
  set.scaled = target == 1,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'solute_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  set.scaled = target == 1,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'raw_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  set.scaled = target == 1,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'cps_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  set.scaled = target == 1,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

## S3 method for class 'generic_mspct'
fscale(
  x,
  range = NULL,
  f = "mean",
  target = 1,
  set.scaled = target == 1,
  col.names,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

Arguments

x	An R object
...	additional named arguments passed down to f.
range	numeric. An R object on which range() returns a numeric vector of length 2 with the limits of a range of wavelengths in nm, with min and max wavelengths (nm)
f	character string. "mean" or "total" for scaling so that this summary value becomes 1 for the returned object, or the name of a function taking x as first argument and returning a numeric value.
target	numeric A constant used as target value for scaling.
unit.out	character. Allowed values "energy", and "photon", or its alias "quantum".
set.scaled	logical or NULL Flag indicating if the data is to be marked as "scaled" or not.
qty.out	character. Allowed values "transmittance", and "absorbance".
col.names	character vector containing the names of columns or variables to which to apply the scaling.
.parallel	logical if TRUE, apply function in parallel, using parallel backend provided by foreach.
.paropts	a list of additional options passed into the foreach function when parallel computation is enabled. This is important if (for example) your code relies on external data or packages: use the .export and .packages arguments to supply them so that all cluster nodes have the correct environment set up for computing.

Details

After scaling, applying the function passed as argument to f to the scaled spectrum will return the value passed as argument to target. The default for set.scaled depends dynamically on the passed to target. Sometimes we rescale a spectrum to a "theoretical" value for the summary, while in other cases we rescale the spectrum to a real-world target value of e.g. a reference energy irradiance. In the first case we say that the data are expressed in relative units, while in the second case we retain actual physical units. To indicate this, this package uses an attribute, which will by default be set assuming the first of these two situations when target == 1 and not set assuming the second situation. These defaults can be overriden with an explicit logical argument passed to set.scaled. When present, normalization metadata is filled with NA values, and the spectrum tagged as not normalized.

Value

A copy of x with the original spectral data values replaced with rescaled values, and the "scaled" attribute set to a list describing the scaling applied.

a new object of the same class as x.

Methods (by class)

• fscale(default): Default for generic function

• fscale(source_spct):

• fscale(response_spct):

• fscale(filter_spct):

• fscale(reflector_spct):

• fscale(solute_spct):

• fscale(raw_spct):

• fscale(cps_spct):

• fscale(generic_spct):

• fscale(source_mspct):

• fscale(response_mspct):

• fscale(filter_mspct):

• fscale(reflector_mspct):

• fscale(solute_mspct):

• fscale(raw_mspct):

• fscale(cps_mspct):

• fscale(generic_mspct):

Important changes

Metadata describing the rescaling operation are stored in an attribute only if set.scaled = TRUE is passed to the call. The exact format and data stored in the attribute "scaled" has changed during the development of the package. Spectra re-scaled with earlier versions will lack some information. To obtain the metadata in a consistent format irrespective of this variation use accessor getScaling(), which fills missing fields with NA.

Note

Method fscale is not implemented for solute_spct objects as the spectral data stored in them are a description of an intensive property of a substance. To represent solutions of specific concentrations of solutes, filter_spct objects can be used.

See Also

Other rescaling functions: fshift(), getNormalized(), getScaled(), is_normalized(), is_scaled(), normalize(), setNormalized(), setScaled()

Examples

fscale(sun.spct)
fscale(sun.spct, f = "mean") # same as default
fscale(sun.spct, f = "mean", na.rm = TRUE)
fscale(sun.spct, range = c(400, 700)) # default is whole spectrum
fscale(sun.spct, f = e_irrad, range = c(400, 700))
s400.spct <- fscale(sun.spct,
                    f = e_irrad,
                    range = c(400, 700),
                    target = 400) # a target in W m-2
s400.spct
e_irrad(s400.spct, c(400, 700))

photobiology documentation built on Oct. 21, 2023, 1:06 a.m.