Skip to contents

Normalize spectral data

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

This method returns a spectral object of the same class as the one supplied as argument but with the spectral data normalized to 1.0 at a specific wavelength. When the object contains multiple spectra, the normalisation is applied to each spectrum individually.

Usage

normalize(x, ...)

normalise(x, ...)

# Default S3 method
normalize(x, ...)

# S3 method for class 'source_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  unit.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'response_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  unit.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'filter_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  qty.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'reflector_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  qty.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'solute_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  qty.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'raw_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'cps_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'generic_spct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  col.names,
  keep.scaling = FALSE,
  na.rm = FALSE
)

# S3 method for class 'source_mspct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  unit.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'response_mspct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  unit.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'filter_mspct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  qty.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'reflector_mspct'
normalize(
  x,
  ...,
  range = x,
  norm = "max",
  qty.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'raw_mspct'
normalize(
  x,
  ...,
  range = x,
  norm = "max",
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'cps_mspct'
normalize(
  x,
  ...,
  range = x,
  norm = "max",
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'solute_mspct'
normalize(
  x,
  ...,
  range = x,
  norm = "max",
  qty.out = NA,
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

# S3 method for class 'generic_mspct'
normalize(
  x,
  ...,
  range = NULL,
  norm = "max",
  col.names,
  keep.scaling = FALSE,
  na.rm = FALSE,
  .parallel = FALSE,
  .paropts = NULL
)

Arguments

x

An R object

...

not used in current version

range

An R object on which range() returns a numeric vector of length 2 with the limits of a range of wavelengths in nm. See Details.

norm

numeric Normalization wavelength (nm) or character string "max", or "min" for normalization at the corresponding wavelength, "update" to update the normalization with previous criterion, "undo" to revert an existing normalization or "skip" to force return of x unchanged. See Details.

unit.out

No longer supported and is ignored with a warning.

keep.scaling

logical or numeric Flag to indicate if any existing scaling should be preserved or not. The default, FALSE, preserves the behaviour of 'photobiology' (<= 0.10.9). See Details.

na.rm

logical indicating whether NA values should be stripped before calculating the summary (e.g. max()) used for normalization.

qty.out

No longer supported and is ignored with a warning..

col.names

character vector containing the names of columns of x to be normalized. Other columns are retained unchanged.

.parallel

if TRUE, apply function in parallel, using parallel backend provided by packege '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 values of the spectral quantity rescaled to 1 at the normalization wavelength. If the normalization wavelength is not already present in x, it is added by interpolation—i.e. the returned value may be one row longer than x for each spectrum. Attributes normalized and normalization are set to keep a log of the computations applied. Other attributes are preserved.

Details

By default normalization is done based on the maximum of the spectral data. It is possible to also do the normalization based on a user-supplied wavelength expressed in nanometres or the minimum. An existing normalization can be updated for a different unit of expression or after a conversion to a related spectral quantity. The accepted arguments for parameter norm are:

"max"

Scale all spectral values so that the value at the tallest peak is 1.0.

"min"

Scale all spectral values so that the value at the deepest valley is 1.0.

<number>

Scale all spectral values so that the value at w.length == <number> is 1.0, interpolating nearest wavelengths.

"update"

Normalise the data reusing the normalization criteria stored as metadata in attribute normalization.

"undo"

Reverse the normalisation of x restoring the original values of the spectral variable using the normalization metadata stored in attribute normalization.

"skip"

Return x unmodified.

In 'photobiology' (>= 0.10.8) detailed information about the normalization is stored in attribute normalization. In the case objects normalized using 'photobiology' (< 0.10.8), norm actions "update" and "undo" are not supported.

In 'photobiology' (>= 0.10.10) applying a new normalization to an already normalized spectrum recomputes the multiplier factors stored in attribute normalization if it present. This ensures that the data in the returned object is the original one when undoing multiple previous normalizations. Loss of precision due to floating-point arithmetic is possible, as well as in the format of attributes.

By default max() or min() are applied to the whole spectrum, but by passing a range of wavelengths as argument to parameter tange, they are applied to within this range of wavelengths. However, in all cases the normalization multipliers are applied to the whole spectrum.

By default the argument passed to x contains one or more NA values and the normalization is based on a summary quantity, the returned spectrum will contain only NA values. If na.rm == TRUE then the summary quantity will be calculated after striping NA values, and only the values that were NA in x will be NA values in the returned spectrum.

When the spectrum passed as argument to x had been previously scaled, in 'photobiology' (<= 0.10.9) the scaling attribute was always removed and no normalization factors returned. In 'photobiology' (>= 0.10.10) scaling information can be preserved by passing keep.scaling = TRUE.

When a numeric value is passed as argument to keep.scaling, the scaling uses f = "total" or f = "mean" depending on the class of x. Rescaling is only occasionally needed.

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

Methods (by class)

  • normalize(default): Default for generic function

  • normalize(source_spct): Normalize a source_spct object.

  • normalize(response_spct): Normalize a response spectrum.

  • normalize(filter_spct): Normalize a filter spectrum.

  • normalize(reflector_spct): Normalize a reflector spectrum.

  • normalize(solute_spct): Normalize a solute spectrum.

  • normalize(raw_spct): Normalize a raw spectrum.

  • normalize(cps_spct): Normalize a cps spectrum.

  • normalize(generic_spct): Normalize a raw spectrum.

  • normalize(source_mspct): Normalize the members of a source_mspct object.

  • normalize(response_mspct): Normalize the members of a response_mspct object.

  • normalize(filter_mspct): Normalize the members of a filter_mspct object.

  • normalize(reflector_mspct): Normalize the members of a reflector_mspct object.

  • normalize(raw_mspct): Normalize the members of a raw_mspct object.

  • normalize(cps_mspct): Normalize the members of a cps_mspct object.

  • normalize(solute_mspct): Normalize the members of a solute_mspct object.

  • normalize(generic_mspct): Normalize the members of a solute_mspct object.

Note

The second formal argument is ellipsis, thus all parameters except x have to be always passed by name.

normalise() is another name for normalize().

See also

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

Examples

norm_sun.spct <- normalize(sun.spct, norm = "max")
str(is_normalized(norm_sun.spct))
#>  logi TRUE
str(getNormalization(norm_sun.spct))
#> List of 5
#>  $ norm.type   : chr [1:2] "max" "max"
#>  $ norm.wl     : num [1:2] 451 531
#>  $ norm.factors: num [1:2] 1.22 2.96e+05
#>  $ norm.cols   : chr [1:2] "s.e.irrad" "s.q.irrad"
#>  $ norm.range  : num [1:2] 280 800

norm_sun.spct <- normalize(sun.spct, norm = 500)
str(is_normalized(norm_sun.spct))
#>  logi TRUE
str(getNormalization(norm_sun.spct))
#> List of 5
#>  $ norm.type   : chr "wavelength"
#>  $ norm.wl     : num [1:2] 500 500
#>  $ norm.factors: num [1:2] 1.38 3.30e+05
#>  $ norm.cols   : chr [1:2] "s.e.irrad" "s.q.irrad"
#>  $ norm.range  : num [1:2] 280 800

norm_sun_evening.mspct <- normalize(sun_evening.mspct[1:3])
str(is_normalized(norm_sun_evening.mspct))
#> List of 3
#>  $ time.01: logi TRUE
#>  $ time.02: logi TRUE
#>  $ time.03: logi TRUE
#>  - attr(*, "comment")= chr "Applied function: 'is_normalized'.\n"
str(getNormalization(norm_sun_evening.mspct))
#> List of 3
#>  $ time.01:List of 5
#>   ..$ norm.type   : chr "max"
#>   ..$ norm.wl     : num 451
#>   ..$ norm.factors: num 13.3
#>   ..$ norm.cols   : chr "s.e.irrad"
#>   ..$ norm.range  : num [1:2] 290 1000
#>  $ time.02:List of 5
#>   ..$ norm.type   : chr "max"
#>   ..$ norm.wl     : num 451
#>   ..$ norm.factors: num 13.7
#>   ..$ norm.cols   : chr "s.e.irrad"
#>   ..$ norm.range  : num [1:2] 290 1000
#>  $ time.03:List of 5
#>   ..$ norm.type   : chr "max"
#>   ..$ norm.wl     : num 451
#>   ..$ norm.factors: num 13.9
#>   ..$ norm.cols   : chr "s.e.irrad"
#>   ..$ norm.range  : num [1:2] 290 1000
#>  - attr(*, "comment")= chr "Applied function: 'getNormalization'.\n"