.help xtcoeff Aug00 mscred
.ih
NAME
xtcoeff -- compute crosstalk coefficients
.ih
SYNOPSIS
Crosstalk coefficients between pairs of source and victim CCDs, specified
as extensions in an MEF file, are computed.  The output is a file suitable
for use with XTALKCOR or CCDPROC.  There is an option to examine and
interact with the data.
.ih
USAGE	
xtcoeff input output victim source
.ih
PARAMETERS
.ls input
List of mosaic exposures in multiextension format (MEF).  The crosstalk
coefficient for a pair of extensions is computed combining all the input
exposures.
.le
.ls output
Optional output crosstalk file.  The format of this file is that used by
\fBxtalkcor\fR or \fBccdproc\fR provided each victim extensions is
specified once and only once (and generally in the same order as in
the input MEF file).  One may measure with more than one source
extension for each victim extension to estimate errors but to use the file
for input to the calibration tasks the extra measurements would then need
to be deleted.  If the \fIverbose\fR option is set the same information in
the crosstalk file will also be written to the terminal.
.le
.ls victim = "im1,im2,im3,im4,im5,im6,im7,im8"
List of victim extension names in the MEF input files.  This list is
matched with the list of source extension names specified by the
\fIsource\fR parameter.  A crosstalk coefficient will be measured for each
extension specified in the list.  The same extension may be specified more
than once to compare with source extensions that should not contribute to
the crosstalk.  Large lists may be specified with an @file.

If the specified @file is not found in the current directory it is sought
in xtcoeff$.  Use "page xtcoeff$README" for available lists.
.le
.ls source = "im2,im1,im4,im3,im6,im5,im8,im7"
List of source extension names in the MEF input files.  This list is
matched with the list of victim extension names specified by the
\fIvictim\fR parameter.  The same extension may be specified more than
once.  Large lists may be specified with an @file.

If the specified @file is not found in the current directory it is sought
in xtcoeff$.  Use "page xtcoeff$README" for available lists.
.le
.ls smin = 20000, smax = INDEF
Range of pixel values in the source extension that are used in measuring
the crosstalk.  These values should be those which cause a crosstalk
visible above the background in the victim extension.  Typically these will
be values near and above saturation.  The number of pixels considered has
an impact on the computation speed and memory so the values should also be
such as to select only a small percent of the data in the source
extension.  A value of INDEF for the maximum selects all source pixels
above the minimum value.  The minimum value should be explicitly specified
but a value of INDEF defaults to 10000.
.le
.ls medfactor = 0.5
Median factor for defining the background in the victim extensions.  The
background for each pair of source and victim pixels is computed by taking
the Nth brightest pixel in the same line.  N is computed as the \fImedfactor\fR
parameter times the number of pixels in the line.  A value of 0.5
selects the standard median (half the pixel values are above and half below).
This factor may be adjusted from 0.5 to account for biases from objects
by considering pairs of extensions where no crosstalk is expected and
adjusting this factor to make the crosstalk coefficients scatter around
zero.
.le
.ls maxcoeff = 0.01
A coefficient estimate is computed for each pair of source and victim
pixels as (victim-background)/source.  To reject victim pixels which
have contaminating objects other than the crosstalk ghosts at that
position, all estimates above this value are rejected immediately.  Note
that computation of the final coefficient from all the individual estimates
uses iterative rejection.  However, grossly invalid values will
adversely affect the iterative rejection.  This parameter value need
only be set approximately.
.le
.ls niterate = 3, low = 3., high = 3.
The number of rejection fitting iterations and the lower and upper sigma
thresholds used when combining the individual pixel coefficient estimates
into a final estimate.  These parameters are from \fBicfit\fR.
.le
.ls interactive = no
The determination of a single coefficient from all the
estimates of the individual pixels consists of fitting a constant function
(effectively an average) with iterative rejection.  When this parameter
is yes the pixel coefficient estimates are plotted against the source
pixel values and the \fBicfit\fR interactive fitting routine is entered.
This allows interactive examination of the data, rejection of points, and
selection of sample regions.  When this parameter is no the same fitting
routine is used in non-interactive mode.
.le
.ls verbose = yes
Print the measurement results to the terminal?
.le

.ls clobber
This is a query parameter which is typically not set before hand.  It is
used only when the specified output crosstalk file already exists.  If it
is not specified on the command line then a query will occur if the output
crosstalk file exists.  To avoid a query and force a specific action
specify the parameter on the command line.
.le
.ih
DESCRIPTION
XTCOEFF measures crosstalk coefficients relating the signals from pairs
of extensions in multiextension format (typically pairs of CCDs in mosaic
exposures).  The coefficient is defined by the relation

.nf
    crosstalk signal - victim background = coefficient * source signal
.fi

where the quantity on the right is the excess signal in the victim
extension (measured above the background in the victim extension)
caused by the source signal in the source extension.

The ideal calibration exposures for computing the crosstalk coefficients
consist of fields with many bright stars exposed to near saturation but
without a dense background of objects.  The background level should be
low if possible  Because several exposures can be combined in the crosstalk
determination and it may not be possible to get many highly exposed stars
without too much background, a field might be dithered to move the bright
stars around.  The crosstalk correction based on the crosstalk coefficients
is typically applied to raw exposures (before bias and flatfielding) so
XTCOEFF should be run on unprocessed exposures.  However, if the victim
background is too highly variable because of flat field variations for the
median background estimate to be accurate one might process the exposures
to flatten the background.  Provided only very bright source pixels are
used the coefficient estimates should still be fine.

The pairs of extensions are specified by the parameters \fIvictim\fR
and \fIsource\fR.  The lists may be comma separate extension names
(note that extension positions may also be used) or an @file.  When
the \fBmscred\fR package is loaded the logical directory xtcoeff$ is
defined.  This may be reset by the user if desired.  If a specified
@file is not found the directory prefix xtcoeff$ is added.  This allows
using a library of @files without having to use the directory path.
To check the contents use

.nf
    ms> dir xtcoeff
    ms> page xtcoeff$README
.fi

The second command depends on there being a descriptive file in the
directory.

The coefficient for a particular pair of extensions is estimated by
collecting measurements of

.nf
    (victim value - victim background estimate) / source value
.fi

for all source values within the range specified by \fIsmin\fR and \fIsmax\fR.
The victim background estimate is obtained by taking the Nth brightest
value in same line as the victim pixel being considered.  N is computed
by taking the specified \fImedfactor\fR value times the number of pixels
in the line.  A value of 0.5 for the factor is the classical median but
the value may be adjusted to compensate for biases from objects.  This
can be done by using source extensions which are known not to contribute
crosstalk and running this task with adjustments to the factor until
the coefficient values are zero within the uncertainties of the calculation.

Coefficient values above that specified by the \fImaxcoeff\fR value
are excluded as being too high to be caused by crosstalk signal alone.
In other words the victim pixel value contains signal from a contaminating
object.

The set of coefficients from individual pairs of pixels are combined into a
single coefficient estimate by fitting a constant to the coefficients
verses the source pixel value.  This is equivalent to computing the average.
However, a fitting algorithm is used to allow examining
the data graphically to check for trends away from the assumed crosstalk
relation given earlier.  The fitting approach also allows using the
standard ICFIT routines for examining the data interactively if the
\fIinteractive\fR parameter is set.  During interactive fitting, points may
be explicitly deleted and sample regions in the source intensity axes may
be defined.  The fitting, both interactive and non-interactive, includes
iterative rejection of outlyers.  The iterative rejection is is controled
by the parameters \fIniterate\fR, \fIlow\fR, and \fIhigh\fR which are the
number of iterations and the sigma clipping factors.

The output of this program includes a banner with the images used and
a table with the victim extension, the source extension, the estimated
coefficient value, the estimated uncertainty in the coefficient, and
the number of sigma from zero (the absolute value of the ratio of the
coefficient and the uncertainty).  The latter two values are in parentheses
and will be ignored by the calibration tasks that uses the crosstalk
file.  The output is may be written to a specified file, if one is given
with the \fIoutput\fR parameter, and to the terminal, if the \fIverbose\fR
parameter is set to yes.  If the specified file exists you are given
the option to clobber the file or exit the program.

The output is in a format which may be used by the calibration tasks
\fIxtalkcor\fR or \fIccdproc\fR.  Normally CCDPROC is used and it calls
XTALKCOR if the correction is selected and it has not been done yet.
It is applied before any other calibration.  Note that the crosstalk
calibration file must consist of each extension in the MEF file given
only once and in the order in the file.  The second column is the
extension to be scaled and subtracted, followed by the crosstalk
coefficient.  If only the input extension is given it will be copied
to the output calibrated exposure without a crosstalk correction.
See the help for \fBxtalkcor\fR for more.
.ih
EXAMPLES
The following examples use some data (not taken specifically for this
purpose) from the NOAO Mosaic2 camera.  Pairs of CCDs are controlled
by a single box of electronics.  Unfortunately there is crosstalk from
those pairs in this data.  One would probably want to have several exposures
to combine and then the list of exposures would include them all.

There are some standard extension lists in the xtcoeff$ logical directory.

.nf
ms> show xtcoeff
mscred$lib/xtcoeff/
ms> dir xtcoeff
README       snoao16ref   snoao8ref    vnoao16ref   vnoao8ref    
snoao16      snoao8       vnoao16      vnoao8       
ms> type xtcoeff$README
This directory contains extension lists for use with the XTCOEFF task.
The lists are paired with the 'v' files being for the victim and the
's' files being for the source.

vnoao8/snoao8           NOAO Mosaics with 8 amplifiers
                        All pairs sharing the same Arcon box

vnoao8ref/snoao8ref     NOAO Mosaics with 8 amplifiers
                        All pairs not sharing the same Arcon box

vnoao16/snoao16         NOAO Mosaics with 16 amplifiers
                        All pairs sharing the same Arcon box

vnoao16ref/snoao16ref   NOAO Mosaics with 16 amplifiers
                        All pairs not sharing the same Arcon box
.fi

1. Check coefficients when there is no crosstalk by pairing the extensions
where no crosstalk is expected.  The @files used in this example contain
all combinations which are not expected to have crosstalk.  The @files
are just the two columns of extensions shown in the output.  No output
crosstalk file is specified.

.nf
ms> xtcoeff
List of mosaic exposures: obj110
Output crosstalk file: 
List of victim extensions (im1,im2,im3,im4,im5,im6,im7,im8): @vnoao8ref
List of source extensions (im2,im1,im4,im3,im6,im5,im8,im7): @snoao8ref

# XTCOEFF: NOAO/IRAF V2.11.3EXPORT valdes@puppis Fri 10:06:12 18-Aug-2000
#   Images: obj110

im1     im3     -0.000007 (0.000010,  0.6)
im1     im4      0.001422 (0.000295,  4.8)
im1     im5     -0.000014 (0.000014,  1.0)
im1     im6      0.000017 (0.000013,  1.3)
im1     im7      0.000031 (0.000012,  2.5)
im1     im8      0.000006 (0.000018,  0.4)
im2     im3     -0.000014 (0.000010,  1.4)
im2     im4      0.000128 (0.000072,  1.8)
im2     im5     -0.000010 (0.000015,  0.7)
im2     im6      0.000008 (0.000012,  0.6)
im2     im7     -0.000005 (0.000013,  0.4)
im2     im8      0.000026 (0.000020,  1.4)
im3     im1      0.000005 (0.000006,  0.8)
im3     im2      0.000065 (0.000013,  5.1)
im3     im5      0.000085 (0.000015,  5.6)
im3     im6     -0.000041 (0.000015,  2.7)
im3     im7      0.000136 (0.000015,  9.1)
im3     im8      0.000013 (0.000022,  0.6)
im4     im1      0.000008 (0.000006,  1.3)
im4     im2      0.000013 (0.000013,  1.0)
im4     im5      0.000048 (0.000014,  3.4)
im4     im6     -0.000018 (0.000018,  1.0)
im4     im7      0.000036 (0.000013,  2.7)
im4     im8     -0.000018 (0.000021,  0.9)
im5     im1      0.000012 (0.000005,  2.2)
im5     im2      0.000019 (0.000011,  1.8)
im5     im3      0.000007 (0.000011,  0.6)
im5     im4      0.002339 (0.000709,  3.3)
im5     im7     -0.000006 (0.000010,  0.5)
im5     im8      0.000027 (0.000020,  1.3)
im6     im1     -0.000020 (0.000006,  3.1)
im6     im2     -0.000023 (0.000013,  1.8)
im6     im3      0.000015 (0.000013,  1.2)
im6     im4      0.000038 (0.000057,  0.7)
im6     im7     -0.000014 (0.000014,  1.0)
im6     im8      0.000024 (0.000024,  1.0)
im7     im1      0.000000 (0.000006,  0.1)
im7     im2      0.000005 (0.000014,  0.4)
im7     im3      0.000008 (0.000012,  0.7)
im7     im4     -0.000017 (0.000064,  0.3)
im7     im5      0.000023 (0.000014,  1.7)
im7     im6     -0.000015 (0.000012,  1.2)
im8     im1     -0.000002 (0.000005,  0.4)
im8     im2     -0.000020 (0.000012,  1.7)
im8     im3     -0.000030 (0.000011,  2.7)
im8     im4     -0.000030 (0.000057,  0.5)
im8     im5      0.000002 (0.000014,  0.2)
im8     im6     -0.000022 (0.000014,  1.5)
.fi

2.  In the above example we want to examine the 9.9 sigma case interactively.

.nf
ms> xtcoeff interactive+
List of mosaic exposures (obj110): 
Output crosstalk file (xtalk.dat): ""
List of victim extensions (@vnoao8ref): im3
List of source extensions (@snoao8ref): im7

# XTCOEFF: NOAO/IRAF V2.11.3EXPORT valdes@puppis Fri 10:21:55 18-Aug-2000
#   Images: obj110

.fi
An ICFIT graph is shown.  It is likely most of the power is coming from one
saturated source star where the victim has a faint object.  Set a
sample region (with the 's' key) to exclude the clump of points at high
source values and refit with 'f'.  The fit is still above zero but with
high scatter.  Finish with 'q'.
.nf

im3     im7      0.000104 (0.000031,  3.4)
.fi

The 3.4 sigma is probably not significant compared to the real crosstalk
shown in the next example.

3. Now pair the extensions where crosstalk is expected and record the
results to a crosstalk file.  The xtalk.dat file already exists so this
example illustrates the clobber parameter.

.nf
ms> unlearn xtcoeff
ms> xtcoeff
List of mosaic exposures: obj110
Output crosstalk file: xtalk.dat
List of victim extensions (im1,im2,im3,im4,im5,im6,im7,im8): @vnoao8
List of source extensions (im2,im1,im4,im3,im6,im5,im8,im7): @snoao8
Warning: Operation would overwrite existing file (xtalk.dat)
Clobber existing crosstalk file? (no): yes

# 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      0.000098 (0.000015,  6.6)
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

Most of the coefficients are highly significant.  If one wanted to assume
there was no crosstalk in some of the pairs, which speeds applying the
calibration step,  the file could be edited to one of the following forms.

.nf
# 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     im7      0.001696 (0.000011, 161.1)
.fi

or

.nf
# 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      0		# 0.000098 (0.000015,  6.6)
im6     im5      0.001382 (0.000016, 86.1)
im7     im8      0		# 0.000244 (0.000022, 11.2)
im8     im7      0.001696 (0.000011, 161.1)
.fi
.ih
REVISIONS
.ls XTCOEFF - V4.0: August 22, 2000
First release.
.le
.ih
SEE ALSO
xtalkcor, ccdproc, icfit
.endhelp
