Name
       flat - create linear gain maps out of twilight data cubes

Synopsis
       flat [flags] <twilight> [basename]

Description
       flat is used to process twilight data cubes to create lin-
       ear gain maps and bad pixel maps. Twilight data cubes  are
       a  slowly increasing/decreasing signal that may be used to
       record pixels' responses. In this way, it is mainly possi-
       ble  to  see which pixels have a linear response, in which
       domain, and if the response is linear, a simple regression
       gives  the  pixel  gain,  relative to the mean (or median)
       gain.

Algorithm
       flat makes a computation of linear regression  factors  on
       every pixel, outputting the value of the fitted slope. The
       overall luminosity in each image is  approximated  by  the
       median  flux. This assumes a majority of pixels are valid,
       a valid assumption for standard detectors.

       A rejection is applied on the time line  to  avoid  taking
       into  accounts  stellar objects which are seen in twilight
       frames. This is done by applying a robust linear fit.
       Byproducts of this computation are the y-intercept map, an
       error  map,  a bad pixel map. So far, the only used crite-
       rion to declare a pixel as bad is to tag all  pixels  out-
       side a [0.5, 2.0] gain interval as invalid. Some more cri-
       teria could be derived from a close  study  of  the  slope
       fit.

       Output  file names are all named according to a base name.
       The gain map is called base_flat.fits, the  intercept  map
       is base_intercept.fits, the error map is base_errmap.fits,
       the bad pixel map is base_badpix.fits.  The base  name  is
       either  given  on  the  command-line  after the input file
       name, or it can be omitted on the  command-line.  In  that
       case,  the  input  file  base  name (i.e. without .FITS or
       .fits extension) will be used.

       A proportional fit (y=ax) can be requested  instead  of  a
       full slope (y=ax+b), in which case no intercept map can be
       produced. The proportional fit will compute every possible
       value  of  y/x,  then  take  the median one. This has been
       found to be quite robust.

       If you provide a dark frame to  subtract  from  all  input
       twilight  frames,  the proportional fit mode will be acti-
       vated automatically.

Options
       -o or --intercepts
              Output a y-intercepts map. This is a  byproduct  of
              the slope fit (see above).

       -e or --errmap
              Output an error map from the linear fit. This image
              contains for each pixel the residual sum of squared
              errors for all fitted points.

       -b or --pixmap
              Output  a bad pixel map. This is a byproduct of the
              gain map. All pixels outside of a fixed [0.5,  2.0]
              (inclusive) interval are tagged as bad.  The output
              is a pixel map (i.e. a FITS file). If you  are  not
              satisfied with these threshold settings, use thresh
              to set other thresholds on the gain map.

       -p or --prop
              Instead of trying to fit  a  full  slope  (y=ax+b),
              only  a  proportional  slope (y=ax) will be fitted.
              This option will be activated when dark subtraction
              is requested.

       -d filename or --dark filename
              Provide  a  dark  frame  to subtract from all input
              twilight frames. Check that the dark frame you pro-
              vide  uses  the  same exposure time as the twilight
              frames. Proportional fit is activated in that case.

Files
       Input files shall all comply with FITS format.

See Also
       thresh, deadpix