radiometric: convert a colorSpec object from actinometric to radiometric

Description

Convert a colorSpec object to have quantity that is radiometric (energy of photons) - to prepare it for colorimetric calculations. Test an object for whether it is radiometric.

Usage

# S3 method for colorSpec
radiometric( x, multiplier=1, warn=FALSE )
# S3 method for colorSpec
is.radiometric( x )

Value

radiometric() returns a colorSpec object with quantity that is radiometric (energy-based) and not actinometric (photon-based). If type(x) is a material type ('material' or 'responsivity.material') then x is returned unchanged.

If quantity(x) starts with 'energy', then is.radiometric() returns TRUE, and otherwise FALSE.

Arguments

x: a colorSpec object
multiplier: a scalar which is multiplied by the output, and intended for unit conversion
warn: if TRUE and a conversion actually takes place, the a WARN message is issued. This makes the user aware of the conversion, so units can be verified. This can be useful when radiometric() is called from another colorSpec function.

Details

If the quantity of x does not start with 'photons' then the quantity is not actinometric and so x is returned unchanged. Otherwise x is actinometric (photon-based).

If type(x) is 'light' then the most common actinometric unit of photon count is ($\mu$mole of photons) = ($6.02214 x 10^{17}$ photons). The conversion equation is: $$ E = Q * 10^{-6} * N_A * h * c / \lambda $$ where $E$ is the energy of the photons, $Q$ is the photon count, $N_A$ is Avogadro's constant, $h$ is Planck's constant, $c$ is the speed of light, and $\lambda$ is the wavelength in meters. The output energy unit is joule.
If the unit of Q is not ($\mu$mole of photons), then the output should be scaled appropriately. For example, if the unit of photon count is exaphotons, then set multiplier=1/0.602214.

If the quantity(x) is 'photons->electrical', then the most common actinometric unit of responsivity to light is quantum efficiency (QE). The conversion equation is: $$ R_e = QE * \lambda * e / (h * c) $$ where $R_e$ is the energy-based responsivity, $QE$ is the quantum efficiency, and $e$ is the charge of an electron (in C). The output responsivity unit is coulombs/joule (C/J) or amps/watt (A/W).
If the unit of x is not quantum efficiency, then multiplier should be set appropriately.

If the quantity(x) is 'photons->neural' or 'photons->action', the most common actinometric unit of photon count is ($\mu$mole of photons) = ($6.02214 x 10^{17}$ photons). The conversion equation is: $$ R_e = R_p * \lambda * 10^6 / ( N_A * h * c) $$ where $R_e$ is the energy-based responsivity, $R_p$ is the photon-based responsivity. This essentially the reciprocal of the first conversion equation.

The argument multiplier is applied to the right side of all the above conversion equations.

Examples

Run this code

sum( F96T12 )    # the step size is 1nm, from 300 to 900nm
# [1] 320.1132  photon irradiance, (micromoles of photons)*m^{-2}*sec^{-1}

sum( radiometric(F96T12) )
# [1] 68.91819  irradiance, watts*m^{-2}