fscale {photobiology}

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. When the object contains multiple spectra, the rescaling is applied separately to each spectrum.

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, calling the function passed as argument to f with the scaled spectrum as argument, will return the value passed as argument to target. The default for set.scaled depends dynamically on the value 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, the default argument for 'set.scaled' is TRUE when target == 1, assuming the first of these two situations, and false otherwise, assuming the second situation. These defaults can be overriden with an explicit logical argument passed to set.scaled. Scaling overrides any previous normalization with the spectrum tagged as not normalized.

Method fscale is implemented for solute_spct objects but as the spectral data stored in them are a description of an intensive property of a substance, scaling is unlikely to useful. To represent solutions of specific concentrations of solutes, filter_spct objects should be used instead.

Value

A copy of the object passed as argument to 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 history 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.

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