Skip to contents

Rescale a spectrum using a summary function

Source: R/spct.fscale.r
fscale.Rd

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.

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.

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.

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)
#> Object: source_spct [522 x 2]
#> Wavelength range 280-800 nm, step 0.9230769-1 nm 
#> Label: sunlight, simulated 
#> Measured on 2010-06-22 09:51:00 UTC 
#> Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [scaled] 
#> --
#> # A tibble: 522 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280          0
#>  2     281.         0
#>  3     282.         0
#>  4     283.         0
#>  5     284.         0
#>  6     285.         0
#>  7     286.         0
#>  8     286.         0
#>  9     287.         0
#> 10     288.         0
#> # ℹ 512 more rows
fscale(sun.spct, f = "mean") # same as default
#> Object: source_spct [522 x 2]
#> Wavelength range 280-800 nm, step 0.9230769-1 nm 
#> Label: sunlight, simulated 
#> Measured on 2010-06-22 09:51:00 UTC 
#> Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [scaled] 
#> --
#> # A tibble: 522 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280          0
#>  2     281.         0
#>  3     282.         0
#>  4     283.         0
#>  5     284.         0
#>  6     285.         0
#>  7     286.         0
#>  8     286.         0
#>  9     287.         0
#> 10     288.         0
#> # ℹ 512 more rows
fscale(sun.spct, f = "mean", na.rm = TRUE)
#> Object: source_spct [522 x 2]
#> Wavelength range 280-800 nm, step 0.9230769-1 nm 
#> Label: sunlight, simulated 
#> Measured on 2010-06-22 09:51:00 UTC 
#> Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [scaled] 
#> --
#> # A tibble: 522 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280          0
#>  2     281.         0
#>  3     282.         0
#>  4     283.         0
#>  5     284.         0
#>  6     285.         0
#>  7     286.         0
#>  8     286.         0
#>  9     287.         0
#> 10     288.         0
#> # ℹ 512 more rows
fscale(sun.spct, range = c(400, 700)) # default is whole spectrum
#> Object: source_spct [522 x 2]
#> Wavelength range 280-800 nm, step 0.9230769-1 nm 
#> Label: sunlight, simulated 
#> Measured on 2010-06-22 09:51:00 UTC 
#> Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 400-700 nm
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [scaled] 
#> --
#> # A tibble: 522 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280          0
#>  2     281.         0
#>  3     282.         0
#>  4     283.         0
#>  5     284.         0
#>  6     285.         0
#>  7     286.         0
#>  8     286.         0
#>  9     287.         0
#> 10     288.         0
#> # ℹ 512 more rows
fscale(sun.spct, f = "e_irrad", range = c(400, 700))
#> Object: source_spct [522 x 2]
#> Wavelength range 280-800 nm, step 0.9230769-1 nm 
#> Label: sunlight, simulated 
#> Measured on 2010-06-22 09:51:00 UTC 
#> Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
#> Rescaled to 'e_irrad of s.e.irrad' = 1 for wavelengths in 400-700 nm
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [scaled] 
#> --
#> # A tibble: 522 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280          0
#>  2     281.         0
#>  3     282.         0
#>  4     283.         0
#>  5     284.         0
#>  6     285.         0
#>  7     286.         0
#>  8     286.         0
#>  9     287.         0
#> 10     288.         0
#> # ℹ 512 more rows
s400.spct <- fscale(sun.spct,
                    f = e_irrad,
                    range = c(400, 700),
                    target = 400) # a target in W m-2
s400.spct
#> Object: source_spct [522 x 2]
#> Wavelength range 280-800 nm, step 0.9230769-1 nm 
#> Label: sunlight, simulated 
#> Measured on 2010-06-22 09:51:00 UTC 
#> Measured at 60.20911 N, 24.96474 E; Kumpula, Helsinki, FI 
#> Variables:
#>  w.length: Wavelength [nm]
#>  s.e.irrad: Spectral energy irradiance [W m-2 nm-1] 
#> --
#> # A tibble: 522 × 2
#>    w.length s.e.irrad
#>       <dbl>     <dbl>
#>  1     280          0
#>  2     281.         0
#>  3     282.         0
#>  4     283.         0
#>  5     284.         0
#>  6     285.         0
#>  7     286.         0
#>  8     286.         0
#>  9     287.         0
#> 10     288.         0
#> # ℹ 512 more rows
e_irrad(s400.spct, c(400, 700))
#> E_range.400.700 
#>             400 
#> attr(,"time.unit")
#> [1] "second"
#> attr(,"radiation.unit")
#> [1] "total energy irradiance"