.\" Automatically generated by Pod::Man version 1.02
.\" Sun Nov 28 13:13:41 2004
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` `
.    ds C' '
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
.    .
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "FITSIO_COMBINE 1"
.TH FITSIO_COMBINE 1 "November 2004" "0.4" "CASU"
.UC
.SH "NAME"
fitsio_combine \- pixel-based robust clipped median of scaled \s-1FITS\s0 images
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBfitsio_combine\fR \fIinputfiles\fR \fIoutputfile\fR [\fBcomb\fR=\fImult(iplicative) or 
add(itive)\fR] [\fBextra\fR=\fIyes or no\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBfitsio_combine\fR scales and combines the given set of input \s-1FITS\s0 images 
to form a single clipped \*(L"median\*(R" image, writing the output to \fIoutputfile\fR.  
It is intended to perform the same function as \fIcombine\fR in \s-1IRAF\s0, 
eg. for stacking instrument calibration frames.
.PP
The input \s-1FITS\s0 images \fIinputfiles\fR can be either a comma-separated list 
on the command-line, or if this parameter begins with an \f(CW@character\fR, the file 
named is read as an \s-1ASCII\s0 list of input files, one per line (see 
\&\s-1EXAMPLES\s0, below).
.PP
The first \s-1FITS\s0 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.
.PP
Single or multi-extension \s-1FITS\s0 images may be processed, with the
restriction that all input \s-1FITS\s0 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. 
.PP
During the combining process all input images for the
extension being processed are stored in \s-1RAM\s0.  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 \*(L"chunks\*(R" during the stacking process, loading only a subset of
the input images to save memory.  This is controlled by a threshold
parameter \s-1INMAXMEM\s0 in \fIfitsio_combine.c\fR, which specifies a \*(L"target\*(R"
memory usage.  The default value of 200MB is appropriate for a
computer with 512MB \s-1RAM\s0, and should be changed proportionately on
other systems.
.PP
The following options are supported:
.Ip "[\fBcomb\fR=\fImult(iplicative) or add(itive)\fR]" 4
.IX Item "[comb=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.
.Ip "[\fBextra\fR=\fIyes or no\fR]" 4
.IX Item "[extra=yes or no]"
If not specified the default is \fBextra\fR=\fIno\fR and gives the clipped
\&\*(L"median\*(R" described above. If \fBextra\fR=\fIyes\fR is specified a further
iteration is included in the combining process whereby the first pass
scaled combined frame is used to \*(L"correct\*(R" each individual frame
according to the scaling.  The clipping is then repeated using the
\&\*(L"corrected\*(R" frames.  The noise levels of the \*(L"corrected\*(R" 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.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Combine \s-1FITS\s0 images \fI1.fit\fR, \fI2.fit\fR, \fI3.fit\fR, writing the result
to \fIoutput.fit\fR \- default multiplicative scaling is used.
.PP
.Vb 1
\&  fitsio_combine 1.fit,2.fit,3.fit output.fit
.Ve
Combine the files listed in \fIlist\fR, writing the result to
\&\fIoutput.fit\fR and use additive scaling.
.PP
.Vb 1
\&  fitsio_combine @list output.fit comb=add
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Mike Irwin (mike@ast.cam.ac.uk), Jonathan Irwin (jmi@ast.cam.ac.uk)