This task produces plots of selected input periodic housekeeping (HK) data columns as a function of that file's TIME column. It also produces plots of selected auxiliary file data columns for selected CCDs as a function of a time value derived from the FRAME column of the AUX files for either EPIC or RGS. This FRAME column can be converted to real time by this task, which calls the oal Frame to onboard time (OBT) conversion subroutine OAL_getPosition (though this is not strictly necessary; y-axis values can be plotted versus Frame Number). This task has the flexibility to accept ANY valid column name for either the x or y-axis and make a simple plot, making it useful as a general plotting package (e.g. it is possible to plot a simple lightcurve by selecting the TIME and COUNTS columns in a lightcurve FITS file).
When plotting either HK or AUX data, this task allows the plotting of GTI intervals that correspond to the column data plotted. These GTI intervals are plotted underneath each individual plot window so they can be viewed better in context. The GTI plot simply shows which interval of the input data columns values occurred during a Good Time Interval. Also, when plotting either HK or AUX data, this task allows the selection of CCDs and/or GTIs individually. For example: one may plot an RGS1 Auxiliary File NACCEPTC and NREJECTC columns versus TIME (converted from Frame number) for ONLY CCDs 1, 2, and 3. Another example would be that one may plot a set of EMOS1 HK data file columns, but only plot GTIs for CCD 3.
The user may select the number of input file columns to plot, whether to plot Good Time Intervals (STDGTInn) with the input data columns (if applicable), the number of points to plot per page, the output device (eg. PS, PDF, GIF, XW, depending on which drivers are available), whether to offset the x-axis start point to zero (if the x-axis value is a TIME), the first and last row of a subinterval of a file to plot, whether to plot a subset of the available CCDs or all of them, and whether to convert Frame Number to time using the OAL conversion functions.
The user can plot as many parameters as he wishes, though if one is plotting many columns, many CCDs, and many points, the output (in MB's) of this task can get large (however, the task will not allow more than 18 plots per page for aesthetic reasons). For example: if one plotted 20 columns of an RGS1 file with 10000 points, and all 9 GTIs, at 600 points per page, this would result in 168 pages. It is also important to note that selecting the parameter ``useccds'' when running this task has a dual purpose. In the case of HK data, selecting on CCDs will open a separate GTI file and plot below the data columns selected the STDGTInn values corresponding to the CCDs selected (e.g. if ccds 1, 2, and 3 are selected, each data column is plotted three times, with each of STDGTI01, STDGTI02 and STDGTI03 data plotted beneath it). In the case of AUX data, selecting on CCDs will plot ONLY the contribution by the CCDs selected to the total data (i.e. the frames in the AUX file contributed by CCDs selected will be plotted). In addition, if the task is called with the parameter ``usegtiset'', only the GTI's corresponding to the CCDs selected will be plotted.
Each page will contain a plot, with a common time x-axis, covering the range of points per page selected (the default is 600, or the total number of rows in the file if less than 600). The number of points covered on a single page will be fixed, so that if the number of points extends beyond this, each plot will be extended to multiple pages (e.g. if an input file has 10000 points and 1000 points per page is selected, the task will plot the data on 10 pages. If the number of CCDs/GTIs times the number of columns selected exceeds 18, all the columns and GTIs/CCDs will be plotted for a 1000 point subinterval on multiple pages before starting a new subinterval).
An offset can be selected that converts a TIME x-axis column to seconds since the first time bin (the default is the native form of the TIME column, ie: seconds from the beginning of the observation), so the x-axis appearing at the bottom of each page will be the raw x-axis value (if non-TIME), the raw TIME (presumably in seconds since MJDREF), or an offset TIME (in seconds since TSTART from the file OR the value of the first row of the file if TSTART is not found as a keyword).
The y-axis will be divided into equal size strips, one for each input parameter plotted on that page. Each strip will have its own y-axis scale, covering the range of values relevant for the parameter being plotted. Besides the range label for each parameter, a title for each strip will be plotted (which will be simply the FITS column name) as well as the units derived from the TUNIT column value.
If selected for plotting, the GTIs will appear as an additional strip at the bottom of each individual plot and will correspond exactly to the time range plotted for each column. This GTI strip will simply have the value of 0 or 1 depending on whether a time bin is a GOOD time interval. Contiguous GTI areas will be filled with hatched lines for clarity and will this appear to be histograms whereby if shading appears this region is a ``Good Time Interval'' and if no shading appears this region is a ``Bad Time Interval''.
The title of each page of the plot will contain identifying information for the instrument, target, proposal and observation. Each page will also be numbered.
This task is specifically designed for producing the PPS summary plot data products. By default output files will be written in postscript, but the user will have the option of selecting an alternative output device, subject to availability in the package pgplot. It can, however, be used as a general plotting package because the task simply issues warnings if HK or AUX data or a GTI file and extension are not input, then completes a plot with whatever input (if valid for plotting) IS given.
The user is reminded to set the SAS_ODF environment variable if accessing HK and/or AUX data directly from an ODF.
XMM-Newton SOC/SSC -- 2014-11-04