colorSpec: constructing and testing colorSpec Objects

In colorSpec: Color Calculations with Emphasis on Spectral Data

constructing and testing colorSpec Objects

Description

The function colorSpec() is the constructor for colorSpec objects.

is.colorSpec() tests whether an object is a valid colorSpec object.
as.colorSpec() converts other variables to a colorSpec object, and is designed to be overridden by other packages.

Usage

colorSpec( data, wavelength, quantity='auto', organization='auto', specnames=NULL )

is.colorSpec(x)

## Default S3 method:
as.colorSpec( ... )

Arguments

data	a vector or matrix of the spectrum values. In case data is a vector, there is a single spectrum and the number of points in that spectrum is the length of the vector. In case data is a matrix, the spectra are stored in the columns, so the number of points in each spectrum is the number of rows in data, and the number of spectra is the number of columns in data. It is OK for the matrix to have only 0 or 1 column.
wavelength	a numeric vector of wavelengths for all the spectra, in nm. The length of this vector must be equal to NROW(data). The sequence must be increasing. The wavelength vector can be changed after construction.
quantity	a character string giving the quantity of all spectra in data; see quantity for a list of possible values. In case of 'auto', a guess is made from the specnames. The quantity can be changed after construction.
organization	a character string giving the desired organization of the returned colorSpec object. In case of 'auto', the organization is 'vector' or 'matrix' depending on data. Other possible organizations are 'df.col' or 'df.row'; see organization for discussion of all 4 possible organizations. The organization can be changed after construction.
specnames	a character vector with length equal to the number of spectra, and with no duplicates. If specnames is NULL and data is a vector, then specnames is set to deparse(substitute(data)). If specnames is NULL and data is a matrix, then specnames is set to colnames(data). If specnames is still not a character vector with the right length, or if there are duplicate names, then specnames is set to 'S1', 'S2', ... with a warning message. The specnames vector can be changed after construction.
x	an R object to test for being a valid colorSpec object.
...	arguments for use in other packages.

Details

Under the hood, a colorSpec object is either a vector, matrix, or data.frame. It is of S3 class 'colorSpec' with these extra attributes:

wavelength

a numeric vector of wavelengths for all the spectra. If the organization of the object is 'df.col', then this is absent.

quantity

a character string that gives the physical quantity of all spectra, see quantity() for a list of possible values.

metadata

a named list for user-defined data. The names 'path', 'header' and 'date' are already reserved; see metadata().

step.wl

step between adjacent wavelengths in nm. This is assigned only when the wavelengths are regular; see is.regular().

specname

only assigned when the organization is 'vector', in which case it is equal to the single character string name of the single spectrum. Note that the word specname is singular. Also see specnames().

And there are a few more attributes that exist only in special cases; see the colorSpec User Guide.

Value

colorSpec() returns a colorSpec object, or NULL in case of ERROR. Compare this function with stats::ts().

is.colorSpec() returns TRUE or FALSE. It does more than check the class, and also checks wavelength, quantity, and organization. If FALSE, it logs (at loglevel='DEBUG') the reason that x is invalid.

as.colorSpec.default() issues an ERROR message and returns NULL

See Also

wavelength, quantity, organization, metadata, step.wl, specnames, is.regular, coredata

Examples

#  make a synthetic Gaussian bandpass filter

center = 600
wave   = 400:700
trans  = exp( -(wave-center)^2 / 20^2 )

filter.bp   = colorSpec( trans, wave, quantity='transmittance', specnames='myfilter' )

organization( filter.bp )  # returns:  "vector"

# and now plot it
plot( filter.bp )

colorSpec documentation built on May 29, 2024, 6 a.m.