Find wavelengths values corresponding to a target spectral value

Find wavelength values corresponding to a target spectral value in a spectrum. The name of the column of the spectral data to be used is inferred from the class of x and the argument passed to unit.out or filter.qty or their defaults that depend on R options set.

Usage

wls_at_target(
  x,
  target = NULL,
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  ...
)

# Default S3 method
wls_at_target(
  x,
  target = NULL,
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  ...
)

# S3 method for class 'data.frame'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  x.var.name = NULL,
  y.var.name = NULL,
  ...
)

# S3 method for class 'generic_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  col.name = NULL,
  y.var.name = col.name,
  ...
)

# S3 method for class 'source_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  ...
)

# S3 method for class 'response_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  unit.out = getOption("photobiology.radiation.unit", default = "energy"),
  ...
)

# S3 method for class 'filter_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  filter.qty = getOption("photobiology.filter.qty", default = "transmittance"),
  ...
)

# S3 method for class 'reflector_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  ...
)

# S3 method for class 'solute_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  ...
)

# S3 method for class 'cps_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  ...
)

# S3 method for class 'raw_spct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  ...
)

# S3 method for class 'generic_mspct'
wls_at_target(
  x,
  target = "0.5max",
  interpolate = FALSE,
  idfactor = length(target) > 1,
  na.rm = FALSE,
  ...,
  .parallel = FALSE,
  .paropts = NULL
)

Arguments

x: data.frame or spectrum object.
target: numeric or character vector. A numeric value indicates the spectral quantity value for which wavelengths are to be searched. A character string representing a number is converted to numeric. A character value representing a number followed by a function name, will be also accepted and decoded, such that "0.1max" is interpreted as targeting one tenth of the maximum value in the column. The character strings "half.maximum" and "HM" are synonyms for "0.5max" while "half.range" and "HR" are synonyms for "0.5range".
interpolate: logical Indicating whether the nearest wavelength value in x should be returned or a value calculated by linear interpolation between wavelength values straddling the target.
idfactor: logical or character Generates an index column of factor type. If idfactor = TRUE then the column is auto named target.idx. Alternatively the column name can be directly passed as argument to idfactor as a character string.
na.rm: logical indicating whether NA values should be stripped before searching for the target.
...: currently ignored.
x.var.name, y.var.name, col.name: character The name of the columns in which to search for the target value. Use of col.name is deprecated, and is a synonym for y.var.name.
unit.out: character One of "energy" or "photon"
filter.qty: character One of "transmittance" or "absorbance"
.parallel: 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 data.frame, a spectrum object or a collection of spectra object of the same class as x with fewer rows, possibly even no rows. If FALSE is passed to interpolate a subset of x is returned, otherwise a new object of the same class containing interpolated wavelengths for the target value is returned. As `target` accepts a vector or list as argument, a factor can be added to the output with the corresponding target value.

Methods (by class)

wls_at_target(default): Default returning always an empty object of the same class as x.
wls_at_target(data.frame): Method for "data.frame" objects.
wls_at_target(generic_spct): Method for "generic_spct" objects.
wls_at_target(source_spct): Method for "source_spct" objects.
wls_at_target(response_spct): Method for "response_spct" objects.
wls_at_target(filter_spct): Method for "filter_spct" objects.
wls_at_target(reflector_spct): Method for "reflector_spct" objects.
wls_at_target(solute_spct): Method for "solute_spct" objects.
wls_at_target(cps_spct): Method for "cps_spct" objects.
wls_at_target(raw_spct): Method for "raw_spct" objects.
wls_at_target(generic_mspct): Method for "generic_mspct" objects.

Note

When interpolation is used, only column w.length and the column against which the target value was compared are included in the returned object, otherwise, all columns in x are returned. We implement support for data.frame to simplify the coding of 'ggplot2' stats using this function.

Examples

wls_at_target(sun.spct, target = 0.1)
#> Object: source_spct [1 x 2]
#> Wavelength range 314-314 nm, step NA 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: 1 × 2
#>   w.length s.e.irrad
#>      <dbl>     <dbl>
#> 1      314     0.105
wls_at_target(sun.spct, target = 2e-6, unit.out = "photon")
#> Object: source_spct [6 x 2]
#> Wavelength range 400-765 nm, step 3-327 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.q.irrad: Spectral photon irradiance [mol s-1 m-2 nm-1] 
#> --
#> # A tibble: 6 × 2
#>   w.length  s.q.irrad
#>      <dbl>      <dbl>
#> 1      400 0.00000203
#> 2      410 0.00000192
#> 3      429 0.00000197
#> 4      432 0.00000233
#> 5      759 0.00000247
#> 6      765 0.00000189
wls_at_target(polyester.spct, target = "HM")
#> Object: filter_spct [1 x 2]
#> Wavelength range 322-322 nm, step NA nm 
#> Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new 
#> Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
#> Variables:
#>  w.length: Wavelength [nm]
#>  Tfr: Total spectral transmittance [/1] 
#> --
#> # A tibble: 1 × 2
#>   w.length   Tfr
#>      <int> <dbl>
#> 1      322 0.462
wls_at_target(polyester.spct, target = "HM", interpolate = TRUE)
#> Object: filter_spct [1 x 2]
#> Wavelength range 322.0241-322.0241 nm, step NA nm 
#> Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new 
#> Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
#> Variables:
#>  w.length: Wavelength [nm]
#>  Tfr: Total spectral transmittance [/1] 
#> --
#> # A tibble: 1 × 2
#>   w.length   Tfr
#>      <dbl> <dbl>
#> 1     322. 0.463
wls_at_target(polyester.spct, target = "HM", idfactor = "target")
#> Object: filter_spct [1 x 3]
#> Wavelength range 322-322 nm, step NA nm 
#> Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new 
#> Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
#> Variables:
#>  w.length: Wavelength [nm]
#>  Tfr: Total spectral transmittance [/1] 
#> --
#> # A tibble: 1 × 3
#>   w.length   Tfr target
#>      <int> <dbl> <fct> 
#> 1      322 0.462 0.5max
wls_at_target(polyester.spct, target = "HM", filter.qty = "absorbance")
#> Object: filter_spct [1 x 2]
#> Wavelength range 313-313 nm, step NA nm 
#> Label: Polyester, clear film, 0.000125 m thick, Autostat CT5 from McDermit Autotype; new 
#> Rfr (/1): 0.074, thickness (mm): 0.125, attenuation mode: absorption.
#> Variables:
#>  w.length: Wavelength [nm]
#>  A: Spectral absorbance log10 based [a.u.] 
#> --
#> # A tibble: 1 × 2
#>   w.length     A
#>      <int> <dbl>
#> 1      313  1.34