Match Structures

Once more than one calibrated list for a given field is available, these lists are compiled into a ``match structure''; a data structure that enables us to monitor the intensity variations of celestial objects, as well as filter out candidate objects that do not appear at the same location in sequential observations. Although match structures are automatically produced for sets of images taken in response to GRB alerts received over the GCN, they are primarily constructed manually, often combining many days' of sky patrol data to create light curves for the sources within the wide-field survey region. In this section, we summarize the properties of match structures and describe how to create them.

A match structure identifies objects by matching their celestial coordinates from observation to observation. The telescope aspect is shifted through a small, random vector between observations. This ensures that hot CCD pixels and cosmic ray events are unlikely to be mistaken for celestial objects, as their CCD locations will change relative to the sky. One can then apply a relative photometry algorithm (Section 8.3.3) to stabilize the magnitude estimates and calibrate the systematic errors. This reduces the scatter in light curves for stable bright objects to $<$1%, and allows us to reliably identify variable sources. We can also flag known distractions such as asteroids (that move from night to night) and ``masked'' stars (stars that appear in ROTSE images but are too close to bright stars for sensitive cataloged surveys to resolve).

Match structures are saved in FITS files that consist of two extensions: the first extension contains the match structure itself; a structure of arrays that hold astrometric, photometic and ancillary data about the sources within the field of view (for the gory details of the contents of match structures, see Section C.5). The second extension contains a array of structures that carry all the information from the header of each cobj file, preserving information about the original image from which it was produced, as well as which processes were run in order to create it (Section C.4).

A match structure consists of a set of arrays that contain information on each object per observation (like magnitude), as well as some mean properties of each object over all observations (like celestial location), and a few quantities that apply to each observation (like limiting magnitude). These arrays are defined in Table C.3. As each new calibrated object list is added to the match structure, each array is expanded to include the new data. Object magnitudes are copied from the cobj file. A $-1$ is assigned as the magnitude if an object already in the match structure is not detected in the new list. If a known object is outside the field of the new image, a $-2$ is assigned. As new objects are added to an existing list, their magnitudes in prior observations are also assigned values of $-1$ or $-2$, as appropriate. Mean and RMS quantities are recalculated as each observation is added.

The primary program to construct a match structure is regmatch3_list.pro. There is another program, update_match.pro, which is intended to process large numbers of fields into sets of match structures. The main workhorse, regmatch3_list.pro, is a flexible program that is called with this sequence:

IDL$>$ regmatch3_list, match, stat, list=list, namelist=namelist, pair=pair, limits=limits,

save=save, over=over, append=append, archive=archive, error=error, template=template

The final match structure is stored in match, and an array of structures that convey the header variables for the included observations is stored in stat. Either list or namelist must be set. The former is a single string: the name of a file that contains the list of the cobj files to be included. The latter is an array of strings in which each element is the name of a cobj file.

The other variables and keywords are optional. /pair will activate pair-matching: that only objects that appear in sequential pairs of images are included^8.1. If this option is activated, the program expects an even number of cobj files. If an odd number is input, the last will be ignored and an error will be logged. If /append is activated, the program will assume that match is not empty to begin with, and the cobj files in the list will be appended to what is already in match. limits is a four-element array that gives the coordinates of a limited region ([R.A. min, R.A. max, Decl. min, Decl. max]), if the whole field is not desired. Sources outside these limits will be discarded. template is an array of coordinates for sources of interest. Sources whose celestial locations in the cobj files do not match any coordinates in template will be discarded.

The other keywords instruct the program what to do with the match structure when it is complete. Files are named according to the naming convention outlined in Section A.5. save will save the contents of match and stat into a FITS file in the working directory, but not if a file of that name is present already. over will overwrite any currently present file with the same name. archive is the same as save, only instead of the working directory, the standardized archival directory is used (see Section A.6). Saved match structures are FITS files with two extensions. The first extension contains the match structure itself, while the second contains the stats structure.

If you have a large number of images from different fields that you would like to compile into match structures, update_match.pro may be more useful. It is called as follows:

IDL$>$ update_match, all, dir=dir, pair=pair, archive=archive, startroot=startroot, sky=sky,

init=init, relphot=relphot, matchdir=matchdir

The first variable, all, is a required output variable. When the program exits, the file names (minus the first and fourth name extension, see Appendix A) will be stored as a string array in this variable. If startroot is defined (it should be an array of strings), only files whose root names match the elements of this array will be considered. If /sky is set, only Sky Patrol images will be processed. Otherwise, all images in any subdirectories of the working directory will be processed. If dir is defined, the working directory is changed to dir before beginning. The final match structures are saved as defined above in the working directory, unless /archive is set, in which case they will be saved in the standardized archival directory (if you don't want them to go in either the working directory or the archival directory, you can define an output directory with matchdir). If /init is set, the program will start from scratch, otherwise it will look to see if match structures already exist, and will only append new files to them if they are not already included. If /relphot is set, the program will also apply the relative photometry procedure, as described in Section 8.3.3.