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, ...)
# S3 method for default
fscale(x, ...)
# S3 method for 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 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 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 reflector_spct
fscale(
x,
range = NULL,
f = "mean",
target = 1,
qty.out = NULL,
set.scaled = target == 1,
...
)
# S3 method for solute_spct
fscale(
x,
range = NULL,
f = "mean",
target = 1,
qty.out = NULL,
set.scaled = target == 1,
...
)
# S3 method for raw_spct
fscale(x, range = NULL, f = "mean", target = 1, set.scaled = target == 1, ...)
# S3 method for cps_spct
fscale(x, range = NULL, f = "mean", target = 1, set.scaled = target == 1, ...)
# S3 method for generic_spct
fscale(
x,
range = NULL,
f = "mean",
target = 1,
set.scaled = target == 1,
col.names,
...
)
# S3 method for 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 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 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 reflector_mspct
fscale(
x,
range = NULL,
f = "mean",
target = 1,
qty.out = NULL,
set.scaled = target == 1,
...,
.parallel = FALSE,
.paropts = NULL
)
# S3 method for solute_mspct
fscale(
x,
range = NULL,
f = "mean",
target = 1,
set.scaled = target == 1,
...,
.parallel = FALSE,
.paropts = NULL
)
# S3 method for raw_mspct
fscale(
x,
range = NULL,
f = "mean",
target = 1,
set.scaled = target == 1,
...,
.parallel = FALSE,
.paropts = NULL
)
# S3 method for cps_mspct
fscale(
x,
range = NULL,
f = "mean",
target = 1,
set.scaled = target == 1,
...,
.parallel = FALSE,
.paropts = NULL
)
# S3 method for 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
xas 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 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, 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.
Methods (by class)
fscale(default): Default for generic functionfscale(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):
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.
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.
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
#> Time unit 1s
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
#>
#> # 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
#> Time unit 1s
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
#>
#> # 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
#> Time unit 1s
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 280-800 nm
#>
#> # 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
#> Time unit 1s
#> Rescaled to 'mean of s.e.irrad' = 1 for wavelengths in 400-700 nm
#>
#> # 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
#> Time unit 1s
#> Rescaled to 'a user supplied R function of s.e.irrad' = 1 for wavelengths in 400-700 nm
#>
#> # 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
#> Time unit 1s
#>
#> # 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"