Class CalibrateOD

java.lang.Object
  extended by CalibrateOD

public class CalibrateOD
extends java.lang.Object

CalibrateOD handles grayscale to OD calibrations for images. Some of this code is derived from GELLAb-II GELLAB-II. Gellab was first described in Lipkin L.E, Lemkin P.F. (1980) Database techniques for multiple two-dimensional polyacrylamide gel electrophoresis analyses. Clinical Chemistry 26, 1403-1412. See http://www.lecb.ncifcrf.gov/gellab for more info.

This work was produced by Peter Lemkin of the National Can cer Institute, an agency of the United States Government. As a work of the United States Government there is no associated copyright. It is offered as open source software under the Mozilla Public License (version 1.1) subject to the limitations noted in the accompanying LEGAL file. This notice must be included with the code. The Flicker Mozilla and Legal files are available on http://open2dprot.sourceforge.net/Flicker

Version:
$Date$ $Revision$
Author:
P. Lemkin (LECB/NCI), G. Thornwall (SAIC), Frederick, MD
See Also:
Flicker Home

Field Summary
 java.lang.String calFileDate
          Date associated with the .cal file.
static int calibCtr
          Master Calibration counter
 java.lang.String calImageFile
          Image file associated with the .cal file.
private static boolean DBUG_CALIB
          Local debugging flag set in CalibrateOD.main() test code
private  Flicker flk
          Global instances
 boolean hasODmapFlag
          Indicates that there is an valid mapGrayToOD map else if it was set to 1:1 the flag is set false.
 boolean hasPrevCALflag
          Had a valid ND wedge ROI when came into the wizard
 int[] hist
          histogram of pixel data in ND computing window of [0:255]
 int initialMaxPeaks
          the value of maxPeaks BEFORE running the peak finder
 java.lang.String manufacturerPartNbr
          optional manufacturer part number for the step wedge
 float[] mapGrayToOD
           
(package private) static int MAX_GRAY
          Maximum gray value possible in 8-bits
(package private) static int MAX_ND_STEPS
          Maximum # of OD and peak values in the peak table
 int maxGrayValue
          max gray value found in the image and it is <= 255
 int maxNDsteps
          eg.
 int maxPeaks
          eg.
 int nbr
          Calibration instance counter.
 int ndcwx1
          ULHC Neutral Density calibration strip computing window
 int ndcwx2
          LRHC Neutral Density calibration strip computing window
 int ndcwy1
          ULHC Neutral Density calibration strip computing window
 int ndcwy2
          LRHC Neutral Density calibration strip computing window
 int[] ndWedgeGrayValues
          Gray value for corresponding wedge point [0:maxPeaks-1].
 float[] ndWedgeODvalues
          od value for corresponding wedge point [0:maxNDsteps-1].
 java.lang.String units
          full name units used in the step wedge.
 java.lang.String unitsAbbrev
          abbreviation of units name used in the step wedge E.g., "od"
private  Util util
           
 
Constructor Summary
CalibrateOD(CalibrateOD clone)
          CalibrateOD() - constructor clone a CalibrateOD instance when you want to save the clone state.
CalibrateOD(Flicker flk, int maxGray)
          CalibrateOD() - constructor to set up the initial map.
CalibrateOD(int maxGray)
          CalibrateOD() - constructor to set up the initial map.
 
Method Summary
 float[] calcCalib()
          calcCalib() - continuous piecewise linear calibration od(gray)
 boolean calcHistFindPeaksAndExtrapolate(ImageData iData)
          calcHistFindPeaksAndExtrapolate() - set up histogram, peaks and extrpolate map for the current ROI.
 void clean()
          clean() - clean up before init or when kill instance before GC
 boolean demo_setDefaultWedgeData_LeukemiaGels(ImageData iData)
          demo_setDefaultWedgeData_LeukemiaGels() - setup the ND wedge data for the 4 demo GELLAB-II PPX leukemia gels release with Flicker.
 java.lang.String extrapolateNDwedgeMap()
          extrapolateNDwedgeMap() - extrapolate the maxNDsteps ND wedge peaks in ndWedgeODvalues[0:maxNDsteps-1] with corresponding gray values ndWedgeGrayValues[0:maxNDsteps-1] into a piecewise linear mapGrayToOD[0:maxGray] array.
 java.lang.String extrapolateNDwedgeMap(int maxGray, int maxNDsteps, int maxPeaks, int[] ndWedgeGrayValues, float[] ndWedgeODvalues)
          extrapolateNDwedgeMap() - extrapolate the maxNDsteps ND wedge peaks in ndWedgeODvalues[0:maxNDsteps-1] with corresponding gray values ndWedgeGrayValues[0:maxNDsteps-1] into a piecewise linear mapGrayToOD[0:maxGray] array.
 int[] findPeaks(int maxGray, int maxPeaksAllowed, int[] sHist, int startRange, int avgDist, int minDist, int lookBackWidth, float freqStoN, int minHistFreqPeakValue, boolean smoothpeakIdxListFlag, boolean useShrinkingMinDistanceFlag)
          findPeaks() - Find the peaks in the histogram sHist[].
 boolean findPeakTableSizes()
          findPeakTableSizes() - find the current maxPeaks and maxNDvalues from non-zero values in the peaks table.
 int[] getGrayValueTable()
          getGrayValueTable() - get Wedge calibration grayscale[0:maxPeaks-1]
 boolean getHasODmapFlag()
          getHasODmapFlag() - return the status of the Gray to OD map.
 float[] getMapGrayToOD()
          getMapGrayToOD() - return the mapGrayToOD[0:maxGray-1].
 float[] getODtable()
          getODtable() - get Wedge calibration odTable[0:maxNDsteps-1] OD values
(package private)  java.lang.String getStateStr(ImageData iData, java.lang.String fileName)
          getStateStr() - get this calibration state as a string
 java.lang.String getUnits()
          getUnits() - get Wedge units, e.g.
 java.lang.String getUnitsAbbrev()
          getUnitsAbbrev() - get Wedge units abbreviation, e.g.
 java.lang.String getUnitsManufacturerPartNbr()
          getUnitsManufacturerPartNbr() - get Wedge manufacturerPartNbr
 boolean inheritNDwedgeODvalues(ImageData iData)
          inheritNDwedgeODvalues() - if current calibration does NOT have ND wedge OD values, but the paired gel DOES, then inherit its OD wedge values and units to avoid having to type it.
 boolean isValidWedgeROI()
          isValidWedgeROI() - check if Wedge ROI is valid
static void main(java.lang.String[] args)
          main() - for testing and optimizing parameters for findPeak method using preset data from GELLAb-II Leukemia-AML gel image (gel 0324.1).
(package private)  void readState()
          readState() - Read calibration state from .cal state file for this image.
 boolean restoreFromClone(CalibrateOD clone)
          restoreFromClone() - restore this.
 void setDefaultUnits()
          setDefaultUnits() - set the default to units to "Optical density", unitsAbbrev to "od" and unitsManufacturerPartNbr to "< opt.
 void setMapGrayToOD(float[] newGrayToODMap, int maxGray)
          setMapGrayToOD() - change the mapGrayToOD to the specified Gray to OD map.
 void setNDwedgeTable(int[] ndWedgeGrayValues, float[] ndWedgeODvalues, int maxNDsteps, int maxPeaks, int maxGrayValue)
          setNDwedgeTable() - set ND step wedge calibration set of (grayscale,OD) wedge values, # of steps and max grayvalue [CHECK] we may want to copy the data to fixed size arrays [0:MAX_ND_STEPS-1].
 void setUnits(java.lang.String units)
          setUnits() - set Wedge units, e.g.
 void setUnitsAbbrev(java.lang.String unitsAbbrev)
          setUnitsAbbrev() - set Wedge units abbreviation, e.g.
 void setUnitsManufacturerPartNbr(java.lang.String manufacturerPartNbr)
          setUnitsManufacturerPartNbr() - set Wedge manufacturerPartNbr
 void setWedgeROI(int roiX1, int roiY1, int roiX2, int roiY2)
          setWedgeROI() - set ND step Wedge region of interest
 int[] smoothHistogram(int[] hDataOrig, int nTimes, int windowWidth, int noiseThreshold)
          smoothHistogram() - Compute smoothed histogram of hist[0:maxGray] into hData[0:maxGray] using 'Disaster Analysis'.
(package private)  void writeState(java.lang.String imageFile, java.lang.StringBuffer sBuf)
          writeState() - Write this calibration state to string buffer sBuf
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

flk

private Flicker flk
Global instances


util

private Util util

DBUG_CALIB

private static boolean DBUG_CALIB
Local debugging flag set in CalibrateOD.main() test code


calibCtr

public static int calibCtr
Master Calibration counter


MAX_ND_STEPS

static final int MAX_ND_STEPS
Maximum # of OD and peak values in the peak table

See Also:
Constant Field Values

MAX_GRAY

static final int MAX_GRAY
Maximum gray value possible in 8-bits

See Also:
Constant Field Values

nbr

public int nbr
Calibration instance counter. Note: Not copied in the clone.


ndWedgeGrayValues

public int[] ndWedgeGrayValues
Gray value for corresponding wedge point [0:maxPeaks-1]. It is allocated as [0:MAX_ND_STEPS-1].


ndWedgeODvalues

public float[] ndWedgeODvalues
od value for corresponding wedge point [0:maxNDsteps-1]. It is allocated as [0:MAX_ND_STEPS-1].


maxNDsteps

public int maxNDsteps
eg. # of values in the Neutral density step wedge


maxPeaks

public int maxPeaks
eg. # of gray value peaks corresponding to steps in the Neutral density step wedge. Note you can have 0 peaks but a non-zero # of OD steps in an uncalibrated sample.


initialMaxPeaks

public int initialMaxPeaks
the value of maxPeaks BEFORE running the peak finder


units

public java.lang.String units
full name units used in the step wedge. E.g., "Optical density"


unitsAbbrev

public java.lang.String unitsAbbrev
abbreviation of units name used in the step wedge E.g., "od"


manufacturerPartNbr

public java.lang.String manufacturerPartNbr
optional manufacturer part number for the step wedge


hist

public int[] hist
histogram of pixel data in ND computing window of [0:255]


hasPrevCALflag

public boolean hasPrevCALflag
Had a valid ND wedge ROI when came into the wizard


ndcwx1

public int ndcwx1
ULHC Neutral Density calibration strip computing window


ndcwy1

public int ndcwy1
ULHC Neutral Density calibration strip computing window


ndcwx2

public int ndcwx2
LRHC Neutral Density calibration strip computing window


ndcwy2

public int ndcwy2
LRHC Neutral Density calibration strip computing window


mapGrayToOD

public float[] mapGrayToOD

hasODmapFlag

public boolean hasODmapFlag
Indicates that there is an valid mapGrayToOD map else if it was set to 1:1 the flag is set false.


maxGrayValue

public int maxGrayValue
max gray value found in the image and it is <= 255


calImageFile

public java.lang.String calImageFile
Image file associated with the .cal file. This extra info that we may not use, but that documents the .cal file. The cal file key is "imageFile".


calFileDate

public java.lang.String calFileDate
Date associated with the .cal file. This extra info that we may not use, but that documents the .cal file. The cal file key is "date".

Constructor Detail

CalibrateOD

public CalibrateOD(Flicker flk,
                   int maxGray)
CalibrateOD() - constructor to set up the initial map. Note: use setMapGrayToOD() to force a particular calibration map. Use setNDwedgeTable() to force the calibration input data prior to extrapolation. Use extrapolateNDwedgeMap() to extrapolate the calibration into the map.

Parameters:
flk - is instance of Flicker
maxGray - is maximum number of gray values possible in image
See Also:
clean(), setMapGrayToOD(float[], int), setNDwedgeTable(int[], float[], int, int, int)

CalibrateOD

public CalibrateOD(CalibrateOD clone)
CalibrateOD() - constructor clone a CalibrateOD instance when you want to save the clone state. Use restoreFromClone() to restore it.

Parameters:
clone - is the CalibrateOD instance to clone in the new instance
See Also:
restoreFromClone(CalibrateOD)

CalibrateOD

public CalibrateOD(int maxGray)
CalibrateOD() - constructor to set up the initial map. Note: use setMapGrayToOD() to force a particular calibration map. Use setNDwedgeTable() to force the calibration input data prior to extrapolation. Use extrapolateNDwedgeMap() to extrapolate the calibration into the map.

Parameters:
maxGray - is the maximum number of gray values possible in image
See Also:
clean(), setMapGrayToOD(float[], int), setNDwedgeTable(int[], float[], int, int, int)
Method Detail

clean

public void clean()
clean() - clean up before init or when kill instance before GC


restoreFromClone

public boolean restoreFromClone(CalibrateOD clone)
restoreFromClone() - restore this. instance from a CalibrateOD clone

Parameters:
clone - is the CalibrateOD clone

setWedgeROI

public void setWedgeROI(int roiX1,
                        int roiY1,
                        int roiX2,
                        int roiY2)
setWedgeROI() - set ND step Wedge region of interest

Parameters:
roiX1 - - ULHC x coordinate
roiY1 - - ULHC y coordinate
roiX2 - - LRHC x coordinate
roiY2 - - LRHC y coordinate

isValidWedgeROI

public boolean isValidWedgeROI()
isValidWedgeROI() - check if Wedge ROI is valid

Returns:
true if valid

setDefaultUnits

public void setDefaultUnits()
setDefaultUnits() - set the default to units to "Optical density", unitsAbbrev to "od" and unitsManufacturerPartNbr to "< opt. part # >".


setUnits

public void setUnits(java.lang.String units)
setUnits() - set Wedge units, e.g. "Optical density", "Counts Per Minute", etc.

Parameters:
units - to use. It is "gray-value" if never defined.

getUnits

public java.lang.String getUnits()
getUnits() - get Wedge units, e.g. "Optical density", "Counts Per Minute", etc.

Returns:
units, it is "gray-value" if never defined.

setUnitsAbbrev

public void setUnitsAbbrev(java.lang.String unitsAbbrev)
setUnitsAbbrev() - set Wedge units abbreviation, e.g. "od", "CPM", etc.

Parameters:
units - to use. It is "gray-value" if never defined.

getUnitsAbbrev

public java.lang.String getUnitsAbbrev()
getUnitsAbbrev() - get Wedge units abbreviation, e.g. "od", "CPM", etc.

Returns:
unitsAbbrev, it is "gray" if never defined.

setUnitsManufacturerPartNbr

public void setUnitsManufacturerPartNbr(java.lang.String manufacturerPartNbr)
setUnitsManufacturerPartNbr() - set Wedge manufacturerPartNbr

Parameters:
units - to use. It is "gray-value" if never defined.

getUnitsManufacturerPartNbr

public java.lang.String getUnitsManufacturerPartNbr()
getUnitsManufacturerPartNbr() - get Wedge manufacturerPartNbr

Returns:
unitsAbbrev, it is "gray" if never defined.

setMapGrayToOD

public void setMapGrayToOD(float[] newGrayToODMap,
                           int maxGray)
setMapGrayToOD() - change the mapGrayToOD to the specified Gray to OD map. However, if the map does not exist then make a (MAX_GRAY+1) level 1:1 map.

Parameters:
newGrayToODMap - is the new map [0:maxGray] or null
maxGray - is the number of gray values in the 1:1 map to create if the newGrayToODMap is null.

getMapGrayToOD

public float[] getMapGrayToOD()
getMapGrayToOD() - return the mapGrayToOD[0:maxGray-1].

Returns:
mapGrayToOD map.

getHasODmapFlag

public boolean getHasODmapFlag()
getHasODmapFlag() - return the status of the Gray to OD map.

Returns:
true if it exists

getGrayValueTable

public int[] getGrayValueTable()
getGrayValueTable() - get Wedge calibration grayscale[0:maxPeaks-1]

Returns:
gray value list from gray to OD calibration

getODtable

public float[] getODtable()
getODtable() - get Wedge calibration odTable[0:maxNDsteps-1] OD values

Returns:
OD list values

setNDwedgeTable

public void setNDwedgeTable(int[] ndWedgeGrayValues,
                            float[] ndWedgeODvalues,
                            int maxNDsteps,
                            int maxPeaks,
                            int maxGrayValue)
setNDwedgeTable() - set ND step wedge calibration set of (grayscale,OD) wedge values, # of steps and max grayvalue [CHECK] we may want to copy the data to fixed size arrays [0:MAX_ND_STEPS-1].

Parameters:
ndWedgeGrayValues - of calibration step wedge [0:maxNDsteps-1]
ndWedgeODvalues - of calibration step wedge [0:maxNDsteps-1]
maxNDsteps - of Step wedge calibration
maxGrayValue - is max grayvalue of calibration

findPeakTableSizes

public boolean findPeakTableSizes()
findPeakTableSizes() - find the current maxPeaks and maxNDvalues from non-zero values in the peaks table.

Returns:
true if maxNDvalues and maxPeaks are > 0.

calcCalib

public float[] calcCalib()
calcCalib() - continuous piecewise linear calibration od(gray)

Returns:
piecewise linear OD calibration, null if failed. [TODO]

extrapolateNDwedgeMap

public java.lang.String extrapolateNDwedgeMap()
extrapolateNDwedgeMap() - extrapolate the maxNDsteps ND wedge peaks in ndWedgeODvalues[0:maxNDsteps-1] with corresponding gray values ndWedgeGrayValues[0:maxNDsteps-1] into a piecewise linear mapGrayToOD[0:maxGray] array. If the Wedge data is not well formed, the mapGrayToOD[0:maxGray] contains a 1:1 mapping of grayscale data. Otherwise, it computes the PWL interpolation of Grayvalue to OD between successive peaks.

NOTE: Use setNDwedgeTable() to set the calibration input data prior to doing the extrapolation.

This code was drived from GELLAB-II, Lemkin etal., NCI.

Returns:
null if succeed and setup the mapGrayToOD [0:maxGray] lookup table in the class instance. If not null, it is the error message.
See Also:
setNDwedgeTable(int[], float[], int, int, int)

extrapolateNDwedgeMap

public java.lang.String extrapolateNDwedgeMap(int maxGray,
                                              int maxNDsteps,
                                              int maxPeaks,
                                              int[] ndWedgeGrayValues,
                                              float[] ndWedgeODvalues)
extrapolateNDwedgeMap() - extrapolate the maxNDsteps ND wedge peaks in ndWedgeODvalues[0:maxNDsteps-1] with corresponding gray values ndWedgeGrayValues[0:maxNDsteps-1] into a piecewise linear mapGrayToOD[0:maxGray] array. If the Wedge data is not well formed, the mapGrayToOD[0:maxGray] contains a 1:1 mapping of grayscale data. Otherwise, it computes the PWL interpolation of Grayvalue to OD between successive peaks.

This code was drived from GELLAB-II, Lemkin etal., NCI.

Parameters:
maxGray - is max # of gray values (i.e. MAX_GRAY)
maxNDsteps - is number of OD steps
maxPeaks - is current number of peaks
ndWedgeGrayValues - is the gray value peak [0:maxPeaks -1]
ndWedgeODvalues - is the OD wedge value [0:maxNDsteps -1]
Returns:
null if succeed and setup the mapGrayToOD [0:maxGray] lookup table in the class instance. If not null, it is the error message.

findPeaks

public int[] findPeaks(int maxGray,
                       int maxPeaksAllowed,
                       int[] sHist,
                       int startRange,
                       int avgDist,
                       int minDist,
                       int lookBackWidth,
                       float freqStoN,
                       int minHistFreqPeakValue,
                       boolean smoothpeakIdxListFlag,
                       boolean useShrinkingMinDistanceFlag)
findPeaks() - Find the peaks in the histogram sHist[]. This is used for finding the gray scale values for the ND wedge peaks. Set the peaks (indices of the sHist[]) into histPeaksFound[0:#peaks-1].
NOTE this assumes a decreasing distance between the peaks for higher gray values indices.
This code was drived from GELLAB-II, Lemkin et al., NCI. NOTE: This was optimized for scans from the RTPP and probably needs to be retuned when looking at different data.
 Suggested parameter values:
   startRange                  = 15   
   avgDist                     = 3
   minDist                     = 5
   lookBackWidth=              = 2
   freqStoN                    = 10.0
   minHistFreqPeakValue = 100 (for CCD camera, 20 for VIDICON)
   smoothpeakIdxListFlag     = true
   useShrinkingMinDistanceFlag = true

Parameters:
maxGray - is max gray value in the histogram
maxPeaksAllowed - is max # steps allowed
sHist - is the smoothed histogram of the data [0:maxGray-1]. For example, you could use the smoothHistogram() method to smooth them.
startRange - is 1st gray value to search from. If was 0, then we might pick up false noise peaks
avgDist - is expected distance between peaks in sHist[]
minDist - is minimum distance allowed between peaks in sHist[]
lookBackWidth - is the number of bins to look back in sHist[] when tracking a peak so as to ignore a few noisy data when "climbing" a peak. The min is 1, max is minDist-1.
freqStoN - is the frequency signalToNoise (S/N) used in computing the minHistFreqPeakValue if the user specified it as > 0.0. If the user specifies 1.0, it defaults freqStoN is 10.0. I.e., if maxFreq is 400, then the default estimated minHistFreqPeakValue is computed as 40. The actual value of minHistFreqPeakValue used is the max of the S/N estimated value and the value specified by the user in the next parameter.
minHistFreqPeakValue - is minimum histogram peak value for it to be considered as a peak
smoothpeakIdxListFlag - is do local smoothing optimization
useShrinkingMinDistanceFlag - to shrink the minimum distance between peaks as we find more peaks in going from min gray to max gray values. We may need this for some scanner data (e.g., CCD scanners since they a log response).
Returns:
list of gray value peaks in the histogram histPeaksFound[]

smoothHistogram

public int[] smoothHistogram(int[] hDataOrig,
                             int nTimes,
                             int windowWidth,
                             int noiseThreshold)
smoothHistogram() - Compute smoothed histogram of hist[0:maxGray] into hData[0:maxGray] using 'Disaster Analysis'.

This code was drived from GELLAB-II, Lemkin etal., NCI.

Parameters:
hDataOrig - histogram of size [0:maxGray] to be smoothed.
nTimes - is number of times to iterate
windowWidth - smoothing window width
noiseThreshold - noise threshold to ensure just find the peaks
Returns:
the smoothed histogram [0:maxGray]

readState

void readState()
readState() - Read calibration state from .cal state file for this image.


writeState

void writeState(java.lang.String imageFile,
                java.lang.StringBuffer sBuf)
writeState() - Write this calibration state to string buffer sBuf

Parameters:
imageFile - is the name of the image file
sBuf - is the string buffer to write to.

getStateStr

java.lang.String getStateStr(ImageData iData,
                             java.lang.String fileName)
getStateStr() - get this calibration state as a string

Parameters:
iData - is the image data to use
fileName - associated with the iData
Returns:
state string

calcHistFindPeaksAndExtrapolate

public boolean calcHistFindPeaksAndExtrapolate(ImageData iData)
calcHistFindPeaksAndExtrapolate() - set up histogram, peaks and extrpolate map for the current ROI. Only extrapolate the # of OD values > 0.0. There may be more gray peaks than OD values, but leave them there since we may want to delete false-peaks in the middle which would move valid-peaks down (to the proper place) in the gray peaks list.

Returns:
true if success, false if ND CW ROI does not exist.

inheritNDwedgeODvalues

public boolean inheritNDwedgeODvalues(ImageData iData)
inheritNDwedgeODvalues() - if current calibration does NOT have ND wedge OD values, but the paired gel DOES, then inherit its OD wedge values and units to avoid having to type it.

Parameters:
iData - is the current gel
Returns:
true if we are using the inherited OD data

demo_setDefaultWedgeData_LeukemiaGels

public boolean demo_setDefaultWedgeData_LeukemiaGels(ImageData iData)
demo_setDefaultWedgeData_LeukemiaGels() - setup the ND wedge data for the 4 demo GELLAB-II PPX leukemia gels release with Flicker. Setup the ROI for the ND wedge for the gel. Only extrapolate the # of OD values > 0.0. There may be more gray peaks than OD values, but leave them there since we may want to delete false-peaks in the middle which would move valid-peaks down (to the proper place) in the gray peaks list.

Returns:
true if it is a valid leukemia gel

main

public static void main(java.lang.String[] args)
main() - for testing and optimizing parameters for findPeak method using preset data from GELLAb-II Leukemia-AML gel image (gel 0324.1).

Parameters:
args - is the command line arg list