HISTORY:

29-Apr-2010: Babar Ali    First write-up

PhotGlobalDriftCorrTask
User Manual

version: 1.0

-1- Purpose:
The task is designed to estimate and remove correlated signal drifts in the
PACS bolometer readouts.  The drift for this purpose is defined as systematic,
monotonic, and (usually) decreasing change in the value of the signal that 
has similar magnitude and direction for all bolometer pixels.  It is assumed
to be correlated because all pixels exhibit this change in synch with each
other.
The purpose of the PhotGlobalDriftCorrTask is to identify and remove this
drift in the signal, which is not due to an astrophysical source but is 
purely (likely) an instrument artifact.

-2- Methodology
PhotGlobalDriftCorrTask assumes there is a drift present.  It will not try
to second guess the user even if there is no drift present in the data.
There are two different options for identifying the drifts.  HOWEVER, ONLY
ONE model is supported and documented here.  In all cases, the attempt 
is to find the "sky" or background level and assume this is
constant.  Under this constancy assumption, any change in the sky or 
background level is taken to be due to error or signal drift.

Model    Description
 1  The algorithm will compute the MEDIAN values for each readout (entire
    array).  The MEDIAN values are then binned in intervals specified 
    by the user with the parameter binsize.  
    Within these bins, the MININUM(median) is taken to represent an actual
    "sky" value.  The MINIMUM option is used to reject signal that may be
    astrophysical.  WARNING: depending on your source, you may never 
    see the sky so the MINIMUM trick may not work at all!
2   For data which are dominated by "sky"/telescope emission, further
    liberties can be taken about the drift correction.  In model=2, we
    take the readout of the individual pixels and fit a baseline to
    their history.  This baseline is then subtracted to remove the
    signal drift.  This assumes that the signal drift is not affected
    by actual astrophysical sources; thus, if you see sources in the
    time streams of the pixels, you should not use this method.
3   An alternative approach is to MEDIAN of the entire array itself and
    either fit a trend to these median values or simply subtract the 
    array median from each of the detector pixels.  This approach has
    the same caveat about not seeing the source in individual readouts
    as for model=2.


-3- Summary of usage:

out_frames = photGlobalDriftCorr( in_frames, model, copy=True|False, \
             binsize=, datadir=, outprefix=, doPlot=True|False, \
             slowMedian=True|False, useMedian=True|False, order=, \
             verbose=True|False )

in_frames   Input, Mandatory
            This is the input PACS Frames object.


model       INPUT, Integer, Optional, default value: 1
            Determine which  model to use for the global drift correction.
            see above discussion.

copy       INPUT, Integer, Optional, default value: 0
           Indicates if the new frames should be copied and returned 
           (copy=1) or if the input frame is changed (copy=0)

binsize    INPUT, Integer, Optional, default value: 1000 
           The size of the bin to use for MIN/MEDIAN estimate

datadir    INPUT, String, Optional, default value: "./"
           Specify where to store the plot.

outprefix  INPUT, String, Optional, default value: "plot"
           Prefix to add to the filename for the plot when saving.

doPlot     INPUT, Boolean, Optional, default value: False
           Show and save a plot of the baseline signal drift correction.
  
slowMedian INPUT, Boolean, Optional, default value: False
           Compute the median by looping in jython.  The alternative 
           implementation is faster but crashes HIPE (SPR has been raised)
 
useMedian  INPUT, Boolean, Optional, default value: False
           Use MEDIAN instead of MIN.  Only applicable to data where most of 
           the signal is sky not source.
  
subFit     INPUT, Boolean, Optional, default value: False
           For model 3.  Can either subtract the FIT or optionally the data 
           itself.

order      INPUT, Integer, Optional, default value: 3
           Order of the polynomial to fit to the baseline in all applicable 
           models.

verbose    INPUT, Integer, Optional, default value: 0
           Set verbose mode.

outFrames  OUT, Frames, Optional, NO default value
           Returned Frames object