=head1 NAME

fitsio_combine - pixel-based robust clipped median of scaled FITS images

=head1 SYNOPSIS

B<fitsio_combine> I<inputfiles> I<outputfile> [B<comb>=I<mult(iplicative) or 
add(itive)>] [B<extra>=I<yes or no>]

=head1 DESCRIPTION

B<fitsio_combine> scales and combines the given set of input FITS images 
to form a single clipped "median" image, writing the output to F<outputfile>.  
It is intended to perform the same function as I<combine> in IRAF, 
eg. for stacking instrument calibration frames.

The input FITS images F<inputfiles> can be either a comma-separated list 
on the command-line, or if this parameter begins with an @character, the file 
named is read as an ASCII list of input files, one per line (see 
EXAMPLES, below).

The first FITS image is used as a reference.  A pixel-based stack of
the input images is made, storing the clipped estimate of the scaled input
pixels in the corresponding output pixel.  The frame-to-frame scaling is 
computed via a robust iteratively clipped median estimator of the frame 
backgrounds.  All frames are scaled either multiplicatively or additively
to the same average background level.  A 3-sigma upper clipped (on the 
average frames noise) modified median is used as the default output pixel 
estimator.  The modified median is an average of the central two frames 
(if an even number survive clipping) and a 1-2-1 weighted average of the 
central three frames (if an odd number >= 3 survive clipping).  The weighting,
in general, ensures the flux values in the original frames do not appear in 
the output frame, a well-known problem with straightforward medians.

Single or multi-extension FITS images may be processed, with the
restriction that all input FITS images must have the same numbers of
extensions and sizes of their image arrays.  In the case of a
multi-extension input, each extension is combined separately, writing
out the result to the corresponding extensions in the output image. 

During the combining process all input images for the
extension being processed are stored in RAM.  For the F77-version this leads 
to a limit of 12 files as the maximum that can reasonably be combined in one 
go.  If there are more than this, simply split the list into several large 
chunks, combine each separately, and then combine the outputs.
For the C-version, with large input images or large lists, extensions are 
split into "chunks" during the stacking process, loading only a subset of
the input images to save memory.  This is controlled by a threshold
parameter INMAXMEM in F<fitsio_combine.c>, which specifies a "target"
memory usage.  The default value of 200MB is appropriate for a
computer with 512MB RAM, and should be changed proportionately on
other systems.

The following options are supported:

=over

=item [B<comb>=I<mult(iplicative) or add(itive)>] 

If not specified the default scaling operation is assumed to be 
multiplicative, as used for example in combining flatfield or fringe frames.
The sky/background level in each frame is used to define the scaling prior
to the combinatorial part. Specifying the additive option switches the
scaling to the alternative as used in, say, bias frame combining.

=item [B<extra>=I<yes or no>]

If not specified the default is B<extra>=I<no> and gives the clipped
"median" described above. If B<extra>=I<yes> is specified a further
iteration is included in the combining process whereby the first pass
scaled combined frame is used to "correct" each individual frame
according to the scaling.  The clipping is then repeated using the
"corrected" frames.  The noise levels of the "corrected" frames may be
considerably smaller than the originals leading to more effective clipping
and hence less sensitivity to corrupting faint features.  This option
may be useful in, for example, crowded regions, or where few frames
are available for combining.


=back



=head1 EXAMPLES

Combine FITS images F<1.fit>, F<2.fit>, F<3.fit>, writing the result
to F<output.fit> - default multiplicative scaling is used.

  fitsio_combine 1.fit,2.fit,3.fit output.fit

Combine the files listed in F<list>, writing the result to
F<output.fit> and use additive scaling.

  fitsio_combine @list output.fit comb=add

=head1 AUTHOR

Mike Irwin (mike@ast.cam.ac.uk), Jonathan Irwin (jmi@ast.cam.ac.uk)

=cut