.help xtalkcor Aug00 mscred
.ih
NAME
xtalkcor -- apply crosstalk corrections to mosaic exposures.
.ih
SYNOPSIS
XTALKCOR reads a file containing coefficients for a simple crosstalk
interaction between extensions in a mosaic exposure and applies
the correction.  The correction takes the form

.nf
    corrected = victim - (scale1 * source1 + scale2 * source2 + ...) 
.fi

where the arithmetic is done on each pixel in the victim image extension
with the matching pixels in the source image extensions and the scales are
numerical coefficients.  Alternatively or in addition, bad pixel masks may
be generated flagging pixels which have corrections greater than a
specified threshold or which have source pixels greater than a theshold.
This task is normally executed as part of \fBccdproc\fR.
.ih
USAGE	
xtalkcor input output bpmasks xtalkfiles
.ih
PARAMETERS
.ls input
List of input mosaic exposures to be corrected.  Mosaic files in which
the the extensions contain the keyword XTALKCOR, indicating file
has been previously corrected, are silently skipped. 
.le
.ls output
List of output corrected mosaic exposures.  The list must match the input
list in number or be empty.  If an empty list is specified
then no output crosstalk corrected files are created.

When the \fIsplit\fR parameter is used the output will be single images
for each extension with _<extname> appended to the specified output
name, where <extename> is the extension name.
.le
.ls bpmasks
List of output bad pixel masks.  The list must match the input list in
number or be empty.  No bad pixel masks are created if the list is empty.
Currently the bad pixel mask name is a rootname to which the extension
name is appended.
.le
.ls xtalkfiles = ""
List of crosstalk coefficient files or header keywords containing the file
name.  A header keyword reference is specified by preceding the keyword
with '!'.  Note that only the first extension of the input file is used to
resolve the keyword reference.  The list may consist of a single crosstalk
file reference, in which case it applies to all the elements of the input
list, of a list which matches the input list in number.  The format of the
file has three as explained in the DESCRIPTION section.  This is the same
format produced by the \fBxtcoeff\fR task.
.le
.ls bpmthreshold = -10.
Threshold for identifying pixels in the output bad pixel masks.  A positive
value flags pixels where any of the contributing source pixels exceeds
the specified threshold.  A negative value flags pixels where the
absolute value of the correction exceeds the absolute value of the
threshold.
.le
.ls split = no
Output the corrected extension images as separate single images.  Since
the procedure produces single images as part of the operation this option
saves the time needed to rebuild a final multiextension file.
.le
.ls fextn = "fits"
File extension for the input and output exposure files.
.le
.ls noproc = no
Do no processing but simply print whether the operation is to be done or
not based on the presence of an XTALKCOR header keyword?  This is
intended for use when this task is executed as part of \fBccdproc\fR.
.le

The following package parameters are also used.
.ls pixeltype
The output pixel type for the corrected exposures.
.le
.ls logfile
Log file to record the operations.
.le
.ls verbose
Print processing information to the terminal.
.le
.ls im_bufsize
File buffering size in megabytes per read or write operation.
.le
.ih
DESCRIPTION
\fBXtalkcor\fR reads a file containing coefficients for a simple crosstalk
interaction between extensions in a mosaic exposure and creates a
corrected copy of the input exposure and/or a bad pixel mask identifying
pixels affected by crosstalk.  The crosstalk correction takes the form

.nf
    corrected = victim - (scale1 * source1 + scale2 * source2 + ...) 
.fi

where the arithmetic is done on each pixel in the victim image extension
with the matching pixels in the source image extensions and the scales are
numerical coefficients.  Bad pixel masks may be generated by flagging
pixels which have corrections greater than a specified threshold or which
have source pixels greater than a theshold.  This task is normally executed
as part of \fBccdproc\fR.

The crosstalk occurs during the simultaneous readout of multiple
amplifiers.  Thus the victim and source pixels must be matched in
"amplifier coordinates".  This version assumes the extensions are matched
by flips of lines or columns.  The flips are identified by the signs of the
keywords ATM1_1 for line flips and ATM2_2 for column flips.

The crosstalk coefficient file is specified either explicitly or by 
reference to a header keyword containing the name of the file.  To
reference a keyword precede the keyword name with '!'.  Note the only
the first extension is used to find the referenced keyword.

A crosstalk file consists of lines

.nf
    victim source scale
.fi

where "victim" is an extension name for the victim image to be corrected,
"source" is the extension name for a source image, and scale is the scale
coefficient.  When more than one source extension affects a victim
extension there will be multiple lines.  Any lines where the first three
fields are not in this format are ignored.  Also any line beginning with
'#' is treated as a comment and ignored.  This format is generated by the
task \fBxtcoeff\fR though it can be created or modified with any text
editor as well.  Examples are given in the EXAMPLE section.

The crosstalk corrected output image extensions will contain the keyword
XTALKCOR giving the time the correction was applied and the source
extensions and coefficients used.  Any extension in the input image which
does not have an entry in the crosstalk file will be copied to the
crosstalk corrected file without change.  It will also contain the XTALKCOR
keyword with the time followed by an indication that no crosstalk
correction was required.  In addtion to the XTALKCOR keyword, the keyword
XTALKFILE is added giving the name of the crosstalk file used.

A bad pixel mask is created when a file name is specified.  Currently the
specified name is used as a rootname to which the extension is append
preceded by '_'; i.e. a filename of the form root_extension.pl will be
used.  The crosstalk affect pixels for each victim extension are flagged
either by the magnitude of the correction or by source pixel values
exceeding a positive threshold.  The \fIbpmthreshold\fR parameter specifies
the threshold and the type of flagging.  A positive value will flag any
victim pixel in which any of the source pixels exceed the threshold.  Note
that only one source exceeding the threshold is needed in the case where
there are multiple sources.  A negative value of the threshold parameter
compares the magnitude of the correction (computed even if no output
corrected file is generated) to the absolute value of the specified
threshold.  Note that the bad pixel mask is not merged with to any
other bad pixel mask nor is the name added to the header.  This must
be done separately if desired.
.ih
KEYWORDS
.ls XTALKCOR
Added to all extensions in an output crosstalk corrected file.  The value
includes a time stamp and the crosstalk coefficients and extensions.  If
this keyword is present (the value is ignored) in the input file then the
file will be silently skipped by the task.  To force a second round of
correction would require this keyword to be manually deleted.
.ls XTALKFILE
Added to all extensions in an output crosstalk corrected file.  The
value is the crosstalk file used.
.le
.ls ATM1_1, ATM2_2
The sign of these keywords define the amplifier readout direction.
.le
.ih
EXAMPLES
1. A crosstalk coeffient file created by \fBxtcoeff\fR is shown below.

.nf
ms> page xtalk.dat
# XTCOEFF: NOAO/IRAF V2.11.3EXPORT valdes@puppis Fri 10:15:45 18-Aug-2000
#   Images: obj110

im1	im2	 0.001546 (0.000010, 153.7)
im2	im1	 0.000426 (0.000006, 75.1)
im3	im4	 0.001613 (0.000091, 17.8)
im4	im3	 0.001672 (0.000014, 116.4)
im5
im6	im5	 0.001382 (0.000016, 86.1)
im7	im8	 0.000244 (0.000022, 11.2)
im8	im7	 0.001696 (0.000011, 161.1)
.fi

Note that the comments and the parts in paraenthesis will be ignored.
This will cause the following operations to be performed.

2.  The above crosstalk correction is applied with the following
command.

.nf
ms> xtalkcor obj110 xtcor110 xtalkfile=xtalk.dat
obj110[im1]: Aug 22 10:05 Crosstalk is 0.00155*im2
obj110[im2]: Aug 22 10:05 Crosstalk is 4.26E-4*im1
obj110[im3]: Aug 22 10:06 Crosstalk is 0.00161*im4
obj110[im4]: Aug 22 10:06 Crosstalk is 0.00167*im3
obj110[im5]: Aug 22 10:07 No crosstalk correction required
obj110[im6]: Aug 22 10:07 Crosstalk is 0.00138*im5
obj110[im7]: Aug 22 10:08 Crosstalk is 2.44E-4*im8
obj110[im8]: Aug 22 10:08 Crosstalk is 0.0017*im7
.fi

3.  The header information added by the previous example can be
examined with the following commands.

.nf
ms> imhead xtcor110[im1] l+ |match XTALKCOR
XTALKCOR= 'Aug 22 10:05 Crosstalk is 0.00155*im2'
ms> msccmd "hselect $input xtalkcor yes" xtcor110
"Aug 22 10:05 Crosstalk is 0.00155*im2"
"Aug 22 10:05 Crosstalk is 4.26E-4*im1"
"Aug 22 10:06 Crosstalk is 0.00161*im4"
"Aug 22 10:06 Crosstalk is 0.00167*im3"
"Aug 22 10:07 No crosstalk correction required"
"Aug 22 10:07 Crosstalk is 0.00138*im5"
"Aug 22 10:08 Crosstalk is 2.44E-4*im8"
"Aug 22 10:08 Crosstalk is 0.0017*im7"
.fi

Attempting to apply the crosstalk correction again will do nothing because
of the presence of the XTALKCOR keywords.

4.  To execute a correction using a header keyword giving the
coefficient file use the following modification to example 2.

.nf
ms> xtalkcor obj110 xtcor110 xtalkfile=!xtalkfil
.fi

5.  An example of a crosstalk file where there are multiple sources is
shown below.

.nf
ms> page xtalk.dat
# XTCOEFF: NOAO/IRAF V2.11.3EXPORT valdes@puppis Fri 10:15:45 18-Aug-2000
#   Images: obj110

im1	im2	 0.001546 (0.000010, 153.7)
im1	im3	 0.000426 (0.000006, 75.1)
im1	im4	 0.001613 (0.000091, 17.8)
im2	im1	 0.001672 (0.000014, 116.4)
im2	im3	 0.001382 (0.000016, 86.1)
im2	im4	 0.000244 (0.000022, 11.2)
...
.fi

The correction output would then show

.nf
obj614[im1]: Jan  5  9:31 Crosstalk is 0.001546*im2+0.000426*im3+0.001613*im4
obj614[im2]: Jan  5  9:31 Crosstalk is 0.001672*im1+0.001382*im3+0.000244*im4
...
.fi

.ih
REVISIONS
.ls XTALKCOR - V4.1: January 6, 2001
Extension changes to support readouts with multiple amplifiers.  The script
version was replaced by a compiled task which efficiently deals with multiple
sources and with different amplifier readout directions.  The new version
supports creation of output bad pixel masks.
.le
.ls XTALKCOR - V3.2: August 27, 1999
The crosstalk file can be specified through a keyword.
.le
.ls XTALKCOR - V3.0: April 1999
First release.
.le
.ih
SEE ALSO
xtcoeff, ccdproc
.endhelp