Matching Statistics
The routines setObjectStatus,
selfMergeQA, and
runMergeQA all generate
a chain of TSMATCHSTATS, one entry per field. The
TSMATCHSTATS structure is defined in the include file
ts/include/tsMatchStats.h.
The statistics count only GOOD objects (those considered eligible for either
the primary or secondary samples) of class STAR or GALAXY.
Many of the statistics are for the sample of "bright" objects. For the
tasks "setObjectStatus" and "selfMergeQA", "bright" is defined as any object
which is at least an N sigma detection in r' (where N, the number of sigma, is
an argument to the task). For "runMergeQA", "bright" is defined as any object
within a user specified magnitude range in the user specified filter.
For the tasks "setObjectStatus" and "selfMergeQA", the matching statistics
discussed below are for objects which match between adjacent fields in the same
Frames Pipeline Run (that is, they lie in the overlap region between those
fields). For "runMergeQA", the matching statistics are for objects which match
between that field and another Frames Pipeline Run specified by the user.
The first set of statistics are:
- field
- Field ID.
- nOverlap
- Number of objects in the field which are not OK_RUN (primary detection
for that Frames Pipeline Run) and do not match an object in an adjacent field.
Ideally, in the overlap region between adjacent fields within the same
Frames Pipeline Run, the Frames Pipeline would detect the exact same set of
objects with the exact same set of measured parameters in each field.
In this case, every object which is not an OK_RUN object would match an OK_RUN
object in an adjacent field. An object which is not OK_RUN and does not match
an OK_RUN object in the adjacent field may thus represent an object "missed"
by the survey. This number should, therefore, be small, though we can expect
some differences at the detection limit.
- nOverlapBright
- The number of "bright" objects in the "nOverlap" sample.
This number should be very very small (preferably 0).
If the "-noBlends" flag was specified when the task which generated the
statistics was run, then objects with either their BLENDED or CHILD flag set
are excluded from the following statistics (such blended objects are always
included in the first set of statistics listed above).
- nMisMatches
- The total number of objects in the field which match a STAR or GALAXY
in the adjacent field/run, but which have differing classifications.
- nMismatchedBright
- The number of "bright" objects in the "nMisMatches" sample. This number
should be very very small (preferably 0).
- nUnknown
- The total number of objects in the field which are classified UNK
(unknown).
- nUnknownBright
- The number of "bright" objects in the "nUnknown" sample.
The next set of statistics are compiled separately for stars and galaxies.
- nObjects
- The total number of objects of this class (star or galaxy) in the field.
- nMatches
- The total number of objects of this class in the field which match a
star or galaxy in the adjacent field/run. The ratio of this number
to "nObjects" should be what you would expect from the amount of overlap.
- nObjectsBright
- The number of "bright" objects in the "nObjects" sample.
- nMatchesBright
- The number of "bright" objects in the "nMatches" sample. The ratio of
this number to "nObjectsBright" should be what you would expect from the
amount of overlap.
The remaining statistics are compiled separately for stars and galaxies, and
are based
on the sample counted in the "nMatchesBright" statistics (that is, based on
all bright matches):
- row.av
- The average difference in the "row" coordinate (frame row, in pixels, for
tasks "setObjectStatus" and "selfMergeQA"; great circle longitude, in arcsecs,
for task "runMergeQA").
- row.rms
- The RMS difference in the "row" coordinate (frame row, in pixels, for
tasks "setObjectStatus" and "selfMergeQA"; great circle longitude, in arcsecs,
for task "runMergeQA").
- row.nPairs
- The number of pairs used in deriving the average and RMS row statistics.
This may differ from "nObjectsBright", as for some GOOD objects a given measure
may be undefined and thus would not be used.
- col.av
- The average difference in the "column" coordinate (frame column, in
pixels, for
tasks "setObjectStatus" and "selfMergeQA"; great circle latitude, in arcsecs,
for task "runMergeQA").
- col.rms
- The RMS difference in the "column" coordinate (frame column, in
pixels, for
tasks "setObjectStatus" and "selfMergeQA"; great circle latitude, in arcsecs,
for task "runMergeQA").
- col.nPairs
- The number of pairs used in deriving the average and RMS col statistics.
This may differ from "nObjectsBright", as for some GOOD objects a given measure
may be undefined and thus would not be used.
- mag<i>.av
- The average difference in magnitude (PSF magnitudes for stars, petrosian
magnitudes for galaxies) in the filter (order ugriz);
uncalibrated magnitude for tasks "setObjectStatus" and "selfMergeQA",
calibrated magnitudes for task "runMergeQA").
- mag<i>.rms
- The RMS difference in magnitude (PSF magnitudes for stars, petrosian
magnitudes for galaxies) in the filter (order ugriz);
uncalibrated magnitude for tasks "setObjectStatus" and "selfMergeQA",
calibrated magnitudes for task "runMergeQA").
- mag<i>.nPairs
- The number of pairs used in deriving the average and RMS mag statistics
(order ugriz).
This may differ from "nObjectsBright", as for some GOOD objects a given measure
may be undefined and thus would not be used.
- color<i>.av
- The average difference in model color (order u-g, g-r, r-i, i-z);
uncalibrated magnitude for tasks "setObjectStatus" and "selfMergeQA",
calibrated magnitudes for task "runMergeQA").
- color<i>.rms
- The RMS difference in model color (order u-g, g-r, r-i, i-z);
uncalibrated magnitude for tasks "setObjectStatus" and "selfMergeQA",
calibrated magnitudes for task "runMergeQA").
- color<i>.nPairs
- The number of pairs used in deriving the average and RMS color statistics
(order u-g, g-r, r-i, i-z).
This may differ from "nObjectsBright", as for some GOOD objects a given measure
may be undefined and thus would not be used.
Chains generated by
setObjectStatus,
selfMergeQA, and
runMergeQA have one entry per field.
There are few bright stars per field, and even fewer bright galaxies, so the
matching statistics are based on small samples. The statistics may be binned
using the proc mergeQABin.
For example, to bin a matching statisitcs chain over 20 fields:
ts> mergeQABin $chain 20
For this example, the output chain will contain 1/20th as many entries as the
input chain, with each entry containing the statistics for a bin of 20 fields.
The field number in each entry will be set to the middle field in the bin.
The proc dbMatchPlot may be used to generate
plots from the matching statistics chain. For chains generated by the tasks
"setObjectStatus" and "selfMergeQA":
ts> dbMatchPlot $chain
For chains generated using the "runMergeQA" task, we need to inform the proc
that the quantities are calibrated using the "-calib" flag:
ts> dbMatchPlot $chain -calib
The range of fields plotted may be limited using the arguments "-fieldField"
and "-lastField". For example, to plot fields 120 through 130:
ts> dbMatchPlot $chain -firstField 120 -lastField 130
By default, counts are plotted in linear units. Due to the range in values,
its better to plot them in log units, using the "-log" flag:
ts> dbMatchPlot $chain -log
A default range is used when plotting the magnitude differences. A different
value may be specified using the "-dmag" argument. For example, to plot counts
in log units and magnitude differences in the range +-0.3 mag:
ts> dbMatchPlot $chain -log -dmag 0.3
By default, plots are sent to the terminal screen. Use the "-file" flag to
send them to a file, or the "-pg" flag to send them to an open PGSTATE. For
example, to send the previous plot to the file "plots.ps":
ts> dbMatchPlot $chain -log -dmag 0.3 -file plots.ps
A subset of the plots may be plotted by specifying the option plots you want.
Choose from the list "counts", "pos", "mag", and "color". Similar, the plots
for stars or galaxies can be supressed using the "-nostars" and "-nogalaxies"
flags, respectively. For example, to plot just the positon and magnitude
differences for stars:
ts> dbMatchPlot $chain "pos mag" -log -dmag 0.3 -file plots.ps -nogalaxies
The statistics can be printed to the screen using the
dbMatchPrint proc. For example, to print
the differences in positions:
ts> dbMatchPrint $stats pos
You can specify "mag" or "color" in place of "pos" for those statistics. The
"-nostars" and "-nogalaxies" flags may be used to suppress printing of
statistics for stars and galaxies, respectively. See the proc documentation
for other options.
A TCL proc is provided to create plots for all overlapping columns between two
runs. For example, to do so for runs 1140 and 1231:
ts> runMatchPlot 1140 1231 30 mag -file all.ps -calib