actinometric {colorSpec}

convert a colorSpec object to be actinometric

Description

Convert a radiometric colorSpec object to have quantity that is actinometric (number of photons). Test an object for whether it is actinometric.

Usage

## S3 method for class 'colorSpec'
actinometric( x, multiplier=1, warn=FALSE )

## S3 method for class 'colorSpec'
is.actinometric( x )

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 actinometric() is called from another colorSpec function.

Details

If the quantity of x does not start with 'energy' then the quantity is not radiometric and so x is returned unchanged. Otherwise x is radiometric (energy-based), and must be converted.

If type(x) is 'light' then the most common radiometric energy unit is joule.
The conversion equation is:

Q = E * \lambda * 10^6 / (N_A * h * c)

wher Q is the photon count, E is the energy of the photons, N_A is Avogadro's constant, h is Planck's constant, c is the speed of light, and \lambda is the wavelength. The output unit of photon count is (\mumole of photons) = (6.02214 * 10^{17} photons). If a different unit for Q is desired, then the output should be scaled appropriately. For example, if the desired unit of photon count is exaphotons, then set multiplier=0.602214.

If the quantity(x) is 'energy->electrical', then the most common radiometric unit of responsivity to light is coulombs/joule (C/J) or amps/watt (A/W). The conversion equation is:

QE = R_e * ((h * c)/e) / \lambda

where QE is the quantum efficiency, R_e is the energy-based responsivity, and e is the charge of an electron (in C).
If the unit of x is not C/J, then multiplier should be set appropriately.

If the quantity(x) is 'energy->neural' or 'energy->action', the most common radiometric unit of energy is joule (J).

The conversion equation is:

R_p = R_e * 10^{-6} * ( N_A * h * c) / \lambda

where R_p is the photon-based responsivity, and R_e is the energy-based responsivity, The output unit of photon count is (\mumole of photons) = (6.02214 * 10^{17} photons). This essentially the reciprocal of the first conversion equation.

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

Value

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

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

Note

To log the executed conversion equation, execute cs.options(loglevel='INFO').

Source

Wikipedia. Photon counting. https://en.wikipedia.org/wiki/Photon_counting

See Also

quantity, type, cs.options, radiometric

Examples

colSums( solar.irradiance ) # step size is 1nm, from 280 to 1000 nm. organized as a matrix
# AirMass.0  GlobalTilt AirMass.1.5 
#  944.5458    740.3220    649.7749  # irradiance, watts*m^{-2}


colSums( actinometric(solar.irradiance) )
# AirMass.0  GlobalTilt AirMass.1.5 
#  4886.920    3947.761    3522.149  # photon irradiance, (umoles of photons)*sec^{-1}*m^{-2}

colSums( actinometric(solar.irradiance,multiplier=0.602214) )
# AirMass.0  GlobalTilt AirMass.1.5 
#  2942.972    2377.397    2121.088  # photon irradiance, exaphotons*sec^{-1}*m^{-2}