NAME

batid2xy - read in the detector number (either block, dm, side, detector numbers or single detector ID) and output the x/y position in the BAT array --OR-- input the x/y position in the BAT array and output the detector identification.

USAGE

batid2xy infile [block] [dm] [side] [det] [detid] [detx] [dety] [outfile]

DESCRIPTION

This code can either read in an input FITS file containing a list of detector identifications or x/y positions, or it can read these values from the command line (with the input file given as NONE).

The program calls batidconvert to figure out the X (column) and Y (row) numbers associated with the particular detector or does the reverse transformation. The output is always the full identification of the detector by DETID Block DM SIDE DET X Y.

There are three basic modes of conversion, which are abbreviated BDSD, DETID and DETXY. The mode is selected either by including a "BATIDMOD" keyword in the input file, or by supplying valid ( > -1) values of the detid, detx or dety parameters.

BDSD: In this mode, the conversion goes from detector identification to BAT X and Y (location in the detector plane). The detector is identified by, respectively, block (0:15), detector module (0:7), side (0:1), detector (0:127). In the input file, these are supplied in columns named "BLOCK","DM","SIDE" and "DET." The keyword "BATIDMOD" is set to "BDSD." On the command line, these are supplied through the block, dm, side and det parameters. See example below.

DETID: In this mode, the conversion goes from detector identification to BAT X and Y (location in the detector plane). The detector is identified by detector ID, which is derived from the formula: detid = block*2048 + dm*256 + side*128 + detector. In the input file, this is supplied in a column name "DETID." The keyword "BATIDMOD" is set to "DETID." On the command line, this is supplied by setting the detid parameter equal to the detector ID. See example below.

DETXY: In this mode, the conversion goes from BAT X and Y (location in the detector plane) to detector identificaiton. The detector location is given by BATX and BATY. In the input file, these are supplied in columns named "DETX" and "DETY." The keyword "BATIDMOD" is set to "DETXY." On the command line, these are supplied through the detx and dety parameters. See example below.

PARAMETERS

infile [filename]
Input file name. The input file must have an extension called "DETID" and columns commensurate with the "BATIDMOD" keyword (see general description above). If this keyword is missing, the code assumes that it is set to the value "BDSD." See a description of how to create an input file under Example 1 below.

If the input file is given as NONE, then the detector values to be converted are supplied on the command line.

(block) [integer, 0 - 15]
Specify the block number. Ignored if a valid input file is specified or if any of the detid, detx, or dety parameters are greater than -1.

(dm) [integer, 0 - 7]
Specify the detector module number. Ignored if a valid input file is specified or if any of the detid, detx, or dety parameters are greater than -1.

(side) [integer, 0 - 1]
Specify the detector module side. Ignored if a valid input file is specified or if any of the detid, detx, or dety parameters are greater than -1. 0 is equivalent to A and 1 to B.

(det) [integer, 0 - 127]
Specify the detector number. Ignored if a valid input file is specified or if any of the detid, detx, or dety parameters are greater than -1.

(detid) [integer, -1 to 32767]
Specify the detector id (block*2048 + dm*256 + side*128 + detector). If a different identification of detectors is desired, then this parameter should be set to -1. Ignored if a valid input file is specified.

(detx) [integer, -1 to 285]
Specify the detector X location in detector units, starting from 0. If a different identification of detectors is desired, then this parameter should be set to -1. Ignored if a valid input file is specified. If the value provided corresponds to a gap in the detector array, then the code returns a TNULL value for each detector identification.

(dety) [integer, -1 to 1273]
Specify the detector Y location in detector units, starting from 0. If a different identification of detectors is desired, then this parameter should be set to -1. Ignored if a valid input file is specified. If the value provided corresponds to a gap in the detector array, then the code returns a TNULL value for each detector identification.

(outfile) [filename]
Output file name. It is not currently implemented to write the output to a FITS file.

(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.

(history = NO) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the specified HDU in the output file to record the value of all the ftcopy task parameters that were used to produce the output file.

EXAMPLES

Note that when commands are issued on the Unix command line, strings containing special characters such as '[' or ']' must be enclosed in single or double quotes.

The following examples illustrate ways in which batid2xy can be used.

1. With an input file ("BDSD" mode). 

         batid2xy infile='detids.fits' 
    -or- batid2xy detids.fits

An input file can be created from an ascii table containing the block, dm, side, and detector values in columns 1-4, respectively. A template to create the proper column names can be found in the batid2xy directory as the file bdsd_mode.lis. A header template is bdsd_mode.hdr.

If the data is in a file called data.lis, then the input file detids.fits is created using one of the following commands. Both of these assume that the template files are in the current directory. 

         create_input.pl infile="data.lis" outfile="detids.fits"         
   -or-
         fcreate bdsd_mode.lis data.lis detids.fits extname="DETID" 
	 headfile=bdsd_mode.hdr clobber=yes
2. With no input file ("BDSD" mode). 

         batid2xy NONE 7 3 1 67
3. With an input file ("DETID" mode). 

         batid2xy infile='detids.fits' 
    -or- batid2xy detids.fits

An input file can be created from an ascii table containing the detector ID values in column 1. A template to create the proper column names can be found in the batid2xy directory as the file detid_mode.lis. A header template is detid_mode.hdr.

If the data is in a file called data.lis, then the input file detids.fits is created using one of the following commands. Both of these assume that the template files are in the current directory. 

       create_input.pl infile="data.lis" outfile="detids.fits" batidmod="detid"
   -or-
         fcreate detid_mode.lis data.lis detids.fits extname="DETID" 
	 headfile=detid_mode.hdr clobber=yes
4. With no input file ("DETID" mode). 

         batid2xy NONE detid=15299
5. With an input file ("DETXY" mode). 

         batid2xy infile='detids.fits' 
    -or- batid2xy detids.fits

An input file can be created from an ascii table containing the detector X and Y values in columns 1 and 2, respectively. A template to create the proper column names can be found in the batid2xy directory as the file detxy_mode.lis. A header template is detxy_mode.hdr.

If the data is in a file called data.lis, then the input file detids.fits is created using one of the following commands. Both of these assume that the template files are in the current directory. 

      create_input.pl infile="data.lis" outfile="detids.fits" batidmod="detxy"
   -or-
         fcreate detxy_mode.lis data.lis detids.fits extname="DETID" 
	 headfile=detxy_mode.hdr clobber=yes
6. With no input file ("DETXY" mode). 

         batid2xy NONE detx=259 dety=102

SEE ALSO

fcreate

LAST MODIFIED

Dec 2007