## ComputeCIEConeFundamentals

##### >Psychtoolbox>PsychColorimetricData

[T_quantalAbsorptionsNormalized,T_quantalAbsorptions,T_quantalIsomerizations,adjIndDiffParams,params,staticParams] = …

ComputeCIEConeFundamentals(S,fieldSizeDegrees,ageInYears,pupilDiameterMM,[lambdaMax],[whichNomogram],[LserWeight], …

[DORODS],[rodAxialDensity],[fractionPigmentBleached],[indDiffParams])

Function to compute normalized cone quantal sensitivities

from underlying pieces, as specified in CIE 170-1:2006.

IMPORTANT: This routine returns quantal sensitivities. You

may want energy sensitivities. In that case, use EnergyToQuanta to convert

T_energy = EnergyToQuanta(S,T_quantal’)’

and then renormalize. (You call EnergyToQuanta because you’re converting

sensitivities, which go the opposite direction from spectra.)

The routine also returns two quantal sensitivity functions. The first gives

the probability that a photon will be absorbed. The second is the probability

that the photon will cause a photopigment isomerization. It is the latter

that is what you want to compute isomerization rates from retinal illuminance.

See note at the end of function FillInPhotoreceptors for some information about

convention. In particular, this routine takes pre-retinal absorption into

account in its computation of probability of absorptions and isomerizations,

so that the relevant retinal illuminant is one computed without accounting for

those factors. This routine does not account for light attenuation due to

the pupil, however. The only use of pupil size here is becuase of its

slight effect on lens density as accounted for in the CIE standard.

This standard allows customizing the fundamentals for

field size, observer age, and pupil size in mm.

To get the Stockman-Sharpe/CIE 2-deg fundamentals, use

fieldSizeDegrees = 2;

ageInYears = 32;

pupilDiameterMM = 3;

and don’t pass the rest of the arguments.

To get the Stockman-Sharpe/CIE 10-deg fundamentals, use

fieldSizeDegrees = 10;

ageInYears = 32;

pupilDiameterMM = 3;

and don’t pass the rest of the arguments.

Although this routine will compute something over any wavelength

range, I’d (DHB) recommend not going lower than 390 or above about 780 without

thinking hard about how various pieces were extrapolated out of the range

that they are specified in the standard. Indeed, the lens optical

density measurements only go down to 400 nm and these are extropolated

to go below 400.

This routine will compute from tabulated absorbance or absorbance based on a nomogram, where

whichNomogram can be any source understood by the routine PhotopigmentNomogram. To obtain

the nomogram behavior, pass a lambdaMax vector. You can then also optionally pass a nomogram

source (default: StockmanSharpe)). This option (using shifted nomograms) is not part of the

CIE standard. See NOTE below for another way to handle individual differences

The nominal values of lambdaMax to fit the CIE 2-degree fundamentals with the

Stockman-Sharpe nomogram are 558.9, 530.3, and 420.7 nm for the LMS cones respectively.

These in fact do a reasonable job of reconstructing the CIE 2-degree fundamentals, although

there are small deviations from what you get if you simply read in the tabulated cone

absorbances. Thus starting with these as nominal values and shifting is one way to

produce fundamentals tailored to observers with different known photopigments.

If you pass lambaMax and its length is 4, then first two values are treated as

the peak wavelengths of the ser/ala variants of the L cone pigment, and these

are then weighted according to LserWeight and (1-LserWeight)). The default

for LserWeight is 0.56. After travelling it for a distance to try to get better

agreement between the nomogram based fundamentals and the tabulated fundamentals

I (DHB) gave up and decided that using a single lambdaMax is as good as anything

else I could come up with. If you are interested, see FitConeFundamentalsTest.

NOTE 1: When we first implemented the CIE standard, adding this shifting feature

seemed like a good idea to allow exploration of individual differences in photopigments.

But, with 0 shift, none of the nomograms exactly reproduce the tabulated photopigment absorbance

spectral sensitivities, and this is not so good. We are phasing out our

use of this feature in favor of simply shifting the tabulated

photopigment absorbances, and indeed in favor of adopting the method

published by Asano, Fairchild, & Blonde (2016), PLOS One, doi: 10.1371/journal.pone.0145671

to tailor the CIE fundamentals to individual observers. This is done by

passing the argument indDiffParams, which is a structure as follows.

indDiffParams.dlens - deviation in % from CIE computed peak lens density

indDiffParams.dmac - deviation in % from CIE peak macular pigment density

indDiffParams.dphotopigment - vector of deviations in % from CIE photopigment peak density.

indDiffParams.lambdaMaxShift - vector of values (in nm) to shift lambda max of each photopigment absorbance by.

indDiffParams.shiftType - ‘linear’ (default) or ‘log’. ‘linear’ gets the Asano et al. behavior

You also can shift the absorbances along a wavenumber axis after you have

obtained them. To do this, pass argument lambdaMaxShift with the same

number of entries as the number of absorbances that are used.

The adjIndDiffParams output is a struct which is populated by ComputeRawConeFundamentals.

It contains the actual parameter values for the parameters adjusted using the indDiffParams

input. It contains the following fields:

adjIndDiffParams.mac - the adjusted macular pigment transmittance as a function of wavelength

as calculated in line 151 of ComputeRawConeFundamentals.

adjIndDiffParams.lens - the adjusted lens transmittance as a function of wavelength as calculated

in line 41 of ComputeRawConeFundamentals.

adjIndDiffParams.dphotopigment - 3-vector of the adjusted photopigment axial density for

L, M and S cones (in that order), as calculated in lines

200-202 of ComputeRawConeFundamentals; or rods, as calculated

in line 216 of ComputeRawConeFundamentals if params.DORODS is true.

adjIndDiffParams.absorbance - Photopigment absorbance as given in line 188 of ComputeRawConeFundamentals

adjIndDiffParams.absorptance - Photopigment absorptance as given in line 230 of ComputeRawConeFundamentals

For both adjIndDiffParams.mac and adjIndDiffParams.lens, the wavelength

spacing is the same as in the S input variable of this function.

The params and staticParams outputs are the argument strucutures that

were passed to ComputeRawConeFundamentals by this routine to do the work.

These can be useful if you’d like, say, to susequently use

ComputeRawConeFundamentals to produce estimates for (e.g.) melanopsin or

the rods, where you keep everything else as consistent as possible to

what this routine does. Note that this is all a bit klugy for historical

reasons, as there is redundancy between what you can/might do with

adjIndDiffParams and with these two return outputs. In particular, these

two return outputs would let you call ComputeRawConeFundamentals and get

adjIndDiffParams directly from there.

This function also has an option to compute rod spectral sensitivities, using

the pre-retinal values that come from the CIE standard. Set DORODS to true on

call. You then need to explicitly pass a single lambdaMax value. You can

also pass an optional rodAxialDensity value. If you don’t pass that, the

routine uses the ‘Alpern’ estimate for ‘Human’/’Rod’ embodied in routine

PhotopigmentAxialDensity. The default nomogram for the rod spectral

absorbance is ‘StockmanSharpe’, but you can override with any of the

others available in routine PhotopigmentNomogram. Use of this requires

good choices for lambdaMax, rodAxialDensity, and the nomogram. We are

working on identifying those values more precisely.

Finally, you can adjust the returned spectral sensitivities to account for

the possibility that some of the pigment in the cones is bleached. Pass

a column vector with same length as number of spectral sensitivities beingt

computed. You need to estimate the fraction elsewhere.

Relevant to individual differences, S & S (2000) estimate the wavelength difference

between the ser/ala variants to be be 2.7 nm (ser longer).

NOTE 2. The CIE standard is specified for field sizes between 1 and 10

degrees. Our code will extrapolate using the given formulae to larger

field sizes without complaining. We think this is reasonable; see

CIEConeFundamentalsFieldSizeTest and its header comments, but be aware

that you have sailed into little charted territory if you do this.

See also: ComputeRawConeFundamentals, CIEConeFundamentalsTest, CIEConeFundamentalsFieldSizeTest,

FitConeFundamentalsTest, FitConeFundamentalsWithNomogram, StockmanSharpeNomogram,

ComputePhotopigmentBleaching.

8/13/11 dhb Wrote it.

8/14/11 dhb Clean up a little.

12/16/12 dhb, ms Add rod option.

08/10/13 dhb Test for consistency between what’s returned by FillInPhotoreceptors and

what’s returned by ComputeRawConeFundamentals.

05/24/14 dhb Add fractionPigmentBleached optional arg.

05/26/14 dhb Comment improvements.

02/08/16 dhb, ms Add lambdaMaxShift argument.

ms Don’t do two way check when lambdaMax is shifted.

02/24/16 dhb, ms Started to implement Asano et al. individual difference model

3/30/17 ms Added output argument returning adjusted ind differences

8/1/17 dhb, ms Added return of params and staticParams.

`Psychtoolbox/PsychColorimetricData/ComputeCIEConeFundamentals.m`