Utilities

 

In Table 4.8 the Utilities command syntax is briefly outlined.

  
Table 4.8: Utilities -- Curly brackets indicate optional entries

                                                   

The function of each command will be described in the following:

• MAKE/PEM: to define a sky maps structure in the indicated       photon event table, in order to allow next fast access to the table.
• READ/RANGES: read from the descriptor header of the specified EXSAS table the parameters ranges of the photons selections performed on the data.  
• TUTORIAL/PROJECTION: teacher of Data Preparation basics. A photon list must be indicated in input. The expert flag has to be used only for demos -- no explanatory comments will be displayed to terminal in this case.  
• SET/PROJECTION: set Projection mode for images   and/or light curve creation. Define also the correction files to be optionally used while running Projection (applicable for PSPC data only).

  Various flags can be specified here, at any arbitrary order: when set to INTENSITY the BIN/IMAGE command generates intensity images; when set to ENERGY the BIN/IMAGE command generates energy images (the default is INTENSITY); when set to POINTING the BIN TIME command creates light curves where the time bins which are not entirely exposed to be rejected; contrariwise, when set to SURVEY mode, partially exposed bins in light curves are not rejected, and an EXPOSURE column is created to record the actual exposure times for each time bin (nevertheless in this mode still some time bins are rejected, i.e. those bins where the exposure times are consisting of more than one continuous time interval).        

• SHOW/PROJECTION: show Projection status.  
• TEST/PROJECTION: tester of Projection command files. Messages about (possible) syntax errors are displayed to terminal. When the output flag is set to S, the results of the command file interpretation are displayed too. When the flag is set to any other string, the results of the interpretation are written to an ASCII file with that name.      
• MAKE/PROJECTION: execute Projection command files. If in the command file no INPUT command was specified, an input photon list must be indicated at the second parameter.      
• TEST/CORRECTION: tester of Correction parameter files.   The results of the interpretation and possible error messages are displayed to terminal.
• PLOT/SPECTRUM: plot the results from the command     PREPARE/SPECTRUM. The name of the table created by the PREPARE/SPECTRUM command must be indicated, together with the spectrum to be plotted and the error flag. The spectra to be plotted are indicated with the character strings either source+background, or source, or background (they can be abbreviated respectively with +, s and b). When the error flag is set to Y also the error bars will be plotted. In the following example it is shown how to plot the source spectrum with error bars from table table.tbl:

  Midas 001> PLOT/SPECTRUM table s y

• PLOT/LIGHT_CURVE: plot light curves from EXSAS tables.     In the following example a light curve contained at the column :COUNTS of the table rates.tbl is plotted. The time interval 10000-20000 (in the units of the table data) is previously selected (via a general MIDAS command). The plot is split in three elongated frames. Error bars are also plotted from data in column :ERR. The default histogram plot is here used.

  Midas 001> SET/GRAPH XAXIS=10000,20000
  Midas 002> PLOT/LIGHT rates 3 :COUNTS :ERR

• REBIN/LIGHT_CURVE: with this command it is possible to rebin light curves created via the command BIN TIME, without running again Projection. This is useful in particular when several short time gaps are present in the data, and too many time bins (especially if large) would be rejected by Projection. By running Projection specifying a very small bin size, and setting Projection in ``survey'' mode (see the utility command SET/PROJECTION), the number of rejected time bins would be reduced virtually to zero. Next, the resulting light curve may be rebinned (using REBIN/LIGHT_CURVE) and none of the (larger) output bins would be rejected (an EXPOSURE column in the output table would record the exposure times corresponding to each time bin).
• OUTTAPE/XSPEC: Convert a spectrum (output of PREPARE_SPECTRUM into the XSPEC ASCII format.  

  To prepare the spectrum, follow all the usual EXSAS steps in order to be able to run the command MODEL/SPECTRUM, included the binning of the detector response matrix (BIN/DETECTOR command). Then you can run

  Midas 001> OUTTAPE/XSPEC spectrum matrix eff_area output

  where: spectrum is the name of the input table containing the spectrum (output from PREPARE/SPECTRUM).

  matrix is the detector response matrix binned according to the binning of the spectrum (output from BIN/DETECTOR).

  eff_area is the effective area table (output from CORRECT/SPECTRUM if you used that type of correction or the standard effective area table if you worked with the projection set in CORRECTION mode).

  output is the filename for the output files (DO NOT use any extension). This command will produce three ASCII files (check if they all exist):

  output.pha_sou is the source+background spectrum

  output.pha_bkg is the background spectrum

  output.rsp_sou is the detector response matrix

  You can then convert the output files (source+bkg spectrum, bkg spectrum and detector response matrix) to XSPEC binary format. In order to ensure that the background and matrix are automatically loaded by XPEC when you load the source spectrum, it is advised to use the following naming convention:

  $ mkpha output.pha_sou output

  $ mkpha output.pha_bkg output_b

  $ mkrsp output.rsp_sou output

  This will create the three files output.pha, output_b.pha and output.rsp, containing source + bkg, bkg and response respectively.

  In the XSPEC package is NOT possible to rebin spectra. Therefore, the spectra that you move to that system must be rebinned in EXSAS. This means that if you rebinned by a factor of 4 a PSPC spectrum, the XSPEC spectrum will correspond to a ``binned'' PSPC with only 64 bins. Thus, the XSPEC command plot data will produce nonsense: always use plot ecdata   to look at the spectrum in counts.

  If you follow the naming convention used in the above description (of course, you can replace output with any string), the background spectrum and the detector response matrix will be automatically loaded as you load the source + background spectrum.

  Contrary to the XSPEC prescriptions, the detector response matrix produced by OUTTAPE/XSPEC contains all the information about the effective area. This means that XSPEC considers the detector to have area 1 cm , and therefore for our case cts/s/cm  and cts/s will always be the same (corresponding to cts/s).  

• LOAD/RGB: Build and load to the image     display a real color (RGB) image from specified red, green and blue images. The output is a matrix of ``pointers to color'', to be viewed through the special LUT rgb2.lut, at the specific cut values (0,255). The special LUT contains all of the possible 216 color blends which are made from all the combinations of 6 intensity levels of red, 6 of green and 6 of blue. Because this is a coded image, the output matrix cannot be used for any task like, for instance, source detection algorithms, smoothings, computations or any other (common) image handling. It can nevertheless be used as a reference image for Projection commands involving cursor input. Also the command GET/CURSOR will return the appropriate coordinates, but no intensities (it would return the value of a pointer-to-color instead). The MIDAS command VIEW/IMAGE will only work properly in the "looking glass" mode (the default mode is changing the cuts of the image according to the local range, destroying the color addressing).
• COMPUTE/LIFE_TIME: this is calculating the life time factor     for any EXSAS data table having the header descriptor TIM_SEL (accepted times). The name of the table containing the house-keeping data, necessary for the computation of the life time factor, is defaulted to eventrates.tbl. If the name of a MIDAS table or image is specified at the last parameter, the computed life time factor is written to its descriptor LIF_TIM. The output life time factor is written in any case to the first element of the MIDAS keyword OUTPUTR.
• MERGE/FILES: This command allows to merge two events or two attitude         tables having two different reference pointing directions into one output events or attitude table having as pointing direction the one specified in the command line. The command can also be used to merge orbit and eventrates files (which are independent on pointing direction).

  Please notice: as to merge PETs it is easy, to merge their descriptor headers (especially the ones containing spatial selections) it is not. Data correction could easily bring wrong results if the user are not perfectly aware of how correction is working! As a general rule, keep always in mind that the descriptor header is valid for those spatial area common to all the merged datasets. To be on the safe side it is suggested, as a first step after merging, to select (via Projection) from the merged PET another PET containing ONLY the photons coming from the spatial portions which are common to ALL the contributing tables. Under this condition, data correction becomes again safe.

• CREATE/PSF: create the correction image   which is required in the PSF (Point Spread Function) correction for the ROSAT-PSPC data. A standard PSF correction image is also stored in the EXSAS calibration file EXSAS_CAL:psf_pspc.bdf.

  The PSF correction is meant to correct for the photon loss due to the limited extraction radius which was defined in the spatial selection of photons from a point-like source. This photon loss depends on the PSF shape and on the defined extraction radius. Moreover, the PSF shape is a function of the photon energy too.

  This correction is applicable only in the case of point-like sources and only for circular spatial selections centered on the source itself.

  The PSF correction image contains the photon-loss factor for a grid of values of the off axis angle, the extraction radius and the photon energy. The image is created according to a realistic model of the PSF.

  In general the command used in default mode generates a good all-purpose image. The number of off axis angles in the grid is defaulted to 60, ranging from 0 to 60 arcminutes, while the number of extracted radius values is defaulted to 10, ranging from 0 to 300 arcseconds. Only in special cases these values need to be modified.

• COMPUTE/ROSAT_NAME: this command may be used to determine   the ROSAT name of a source at some equatorial coordinates. Either the Right Ascension and the Declination or a table name containing a list of coordinates may be specified. The ROSAT name is defined as RX JHHMM.m+DDMM, where J stands for coordinates at equinox 2000.0 and m is the cut (not rounded) decimal value for minutes of Right Ascension.