# SS.RGBcalib: Self-Start Functions for Fitting Luminance vs Grey Level... In psyphy: Functions for Analyzing Psychophysical Data in R

## Description

This `selfStart` model evaluates the parameters for describing the luminance vs grey level relation of the R, G and B guns of a CRT-like display, fitting a single exponent, gamma, for each of the 3 guns. It has an initial attribute that will evaluate initial estimates of the parameters, `Blev`, `Br`, `Bg`, `Bb` and `gamm`. In the case of fitting data from a single gun or for a combination of guns, as in the sum of the three for calibrating the white, the parameter `k` is used for the coefficient. Both functions include gradient and hessian attributes.

## Usage

 ```1 2``` ```SS.calib(Blev, k, gamm, GL) SS.RGBcalib(Blev, Br, Bg, Bb, gamm, Rgun, Ggun, Bgun) ```

## Arguments

 `Blev` numeric. The black level is the luminance at the 0 grey level `k` numeric, coefficient of one gun for fitting single gun `Br` numeric, coefficient of the R gun `Bg` numeric, coefficient of the G gun `Bb` numeric, coefficient of the B gun `gamm` numeric, the exponent, gamma, applied to the grey level `GL` numeric, is the grey level for the gun tested, covariate in model matrix in one gun case `Rgun` numeric, is a covariate in the model matrix that indicates the grey level for the R gun. See the example below. `Ggun` numeric, is a covariate in the model matrix that indicates the grey level for the G gun `Bgun` numeric, is a covariate in the model matrix that indicates the grey level for the B gun

## Details

The model

Lum(GL) = Blev + β_i * GL^γ

where i is in {R, G, B}, usually provides a reasonable description of the change in luminance of a display gun with grey level, `GL`. This `selfStart` function estimates γ and the other parameters using the `nls` function. It is assumed that grey level is normalized to the interval [0, 1]. This results in lower correlation between the linear coefficients of the guns, β_i , than if the actual bit-level is used, e.g., [0, 255], for an 8-bit graphics card (see the example). Also, with this normalization of the data, the coefficients, β_i, provide estimates of the maximum luminance for each gun. The need for the arguments `Rgun`, `Ggun` and `Bgun` is really a kludge in order to add gradient and hessian information to the model.

## Value

returns a numeric vector giving the estimated luminance given the parameters passed as arguments and a gradient matrix and a hessian array as attributes.

## Author(s)

Kenneth Knoblauch

## References

~put references to the literature/web site here ~

`nls`
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31``` ```data(RGB) #Fitting a single gun W.nls <- nls(Lum ~ SS.calib(Blev, k, gamm, GL), data = RGB, subset = (Gun == "W")) summary(W.nls) #curvature (parameter effect) is greater when GL is 0:255 Wc.nls <- nls(Lum ~ SS.calib(Blev, k, gamm, GL*255), data = RGB, subset = (Gun == "W")) MASS::rms.curv(W.nls) MASS::rms.curv(Wc.nls) pairs(profile(Wc.nls), absVal = FALSE) pairs(profile(W.nls), absVal = FALSE) #Fitting 3 guns with independent gamma's RGB0.nls <- nlme::nlsList(Lum ~ SS.calib(Blev, k, gamm, GL) | Gun, data = subset(RGB, Gun != "W")) summary(RGB0.nls) plot(nlme::intervals(RGB0.nls)) # Add covariates to data.frame for R, G and B grey levels gg <- model.matrix(~-1 + Gun/GL, RGB)[ , c(5:7)] RGB\$Rgun <- gg[, 1] RGB\$Ggun <- gg[, 2] RGB\$Bgun <- gg[, 3] RGB.nls <- nls(Lum ~ SS.RGBcalib(Blev, Br, Bg, Bb, gamm, Rgun, Ggun, Bgun), data = RGB, subset = (Gun != "W") ) summary(RGB.nls) confint(RGB.nls) ```