next up previous contents pdf.png
Next: 4 dataset_1d Tool Up: User's Guide for the Previous: 2 What's New?

Subsections


3 Event Browser

Event Browser (EB) is an IDL widget application which is used to analyze x-ray event lists. EB provides users with a graphical user interface for doing such things as selecting data files, filtering event lists in numerous ways, and displaying and printing results.


3.1 Starting Event Browser

At the IDL prompt, start Event Browser with the command eb. The current directory must be writable by you.

You will be presented with a standard file selection widget for the purpose of selecting an input file which will help to define the domain dataset, which is the set of x-ray events that will be read into Event Browser. This process is described in the next section.


3.2 Defining the Domain Dataset


3.2.1 Choosing Input Files

The user must define for Event Browser the set of FITS event list files that should be read in from disk - this set of events is called the domain dataset and represents the ``universe'' of events that the user will later filter to define the working dataset. There are three ways to specify the event files you wish to use:

  1. The simplest method is to select a single FITS event list file directly. If the file selection widget is not already up, press the Input File button and select a file. Event Browser reads in the single file immediately.

  2. The second method of selecting data files is to specify an index file, which is simply a text file which contains the names of FITS event files, one per line. Such index files are often created by programs that generate event lists when data from a single experiment are stored in multiple event files. For example, the ATICA telemetry processor writes out an event list file every 100,000 events or so and writes an index file which ties those checkpoint files together. When an index file is selected, the FITS filenames it contains are displayed on the left side of the Domain Dataset Widget. Use the Add, Add All, Remove, etc. buttons to select which of the displayed FITS files you wish to read in - your selections are displayed on the right side of the Domain Dataset Widget. Press the Assemble button, and Event Browser reads the selected files.

  3. The third method for selecting data files is used for real-time analysis situations, e.g. 2nd floor of the XRCF. Event Browser has the capability of continuously polling for new event list files, automatically reading them in, and updating displays. In such situations, the program creating event lists, e.g. ATICA, creates a catalog file which contains the names of index files, which in turn contain the names of FITS files. When you select a catalog file, the index filenames it contains are displayed on the left side of the Domain Dataset Widget. Use the widget controls to select one index file, which will be displayed on the right side. When you press the Assemble button, Event Browser reads all the FITS filenames contained in the index file you selected.

    Furthermore, Event Browser begins polling the index file to look for new entries appended to the end. A status message on the Domain Dataset widget will indicate when such polling is enabled. When new FITS event lists are noticed by Event Browser, they are automatically read in and the displays are updated (see Section 3.2.3). If the automatic updating of displays annoys you, use method 2 (above), i.e. select an index file directly, which does not enable polling.

The IDL mouse cursor will change to an hourglass shape while event list files are being read. Status information is printed to the shell window containing the IDL prompt.

3.2.1.1 Notes on the File Selection Dialog Box

Event Browser uses the standard file selection dialog box supplied by IDL, which is virtually identical to the one used by netscape. This is not the best file selector yet invented, but it's better than some. You can navigate to the desired directory either by clicking on directory names or by typing a directory name (WITH a trailing slash) in the field with the silly name Filter. The reason this field is named Filter is that it controls which files in the selected directory are displayed in the right-hand panel. The field named Selection contains the full pathname of the file you are trying to select. You may not change directories by typing in this field.


3.2.2 Defining Derived Event Properties

The columns of the FITS event list constitute the intrinsic properties of the events. The set of intrinsic properties depends on the instrument mode and the software that produced the event list. For example, in graded mode the instrument grade of an event would be an intrinsic property whereas in faint mode it would not. The analysis tools in Event Browser work not with these intrinsic properties but with a standard set of derived properties: x_position, y_position, timestamp, pha, energy, wavelength, grating_order, instrument_grade, asca_grade, ccd_id, amp_id, exposure, qualcode, island, center_pix, up_pix, down_pix, left_pix, right_pix, ul_pix, ur_pix, ll_pix, lr_pix, generic1, generic2, & generic3. This set of derived properties form a common nomenclature for the event properties of usual interest, hiding distracting details such as the particular FITS column names used in the event list.

Sometimes a derived property will be defined as a simple copy of a FITS column, e.g

\begin{displaymath}x\_position \Leftrightarrow TDETX. \end{displaymath}

Other times a derived property will be derived from one or more FITS columns. For example the timestamp property can be defined as

\begin{displaymath}timestamp \Leftrightarrow TIME - min(TIME). \end{displaymath}

Finally, a derived property can be defined in terms of other derived properties, e.g.

\begin{displaymath}center\_pix \Leftrightarrow island[0]. \end{displaymath}

Derived property definitions can involve user-supplied parameters, for example a split threshold parameter is required when the instrument_grade property is defined as a function of center_pix, up_pix, down_pix, ...

Each derived property has multiple potential definitions. It's often the case that while a particular event list is loaded only one of the potential definitions is valid - the other definitions exist so that EB can handle different input file formats and instrument modes. Sometimes however there are more than one valid definition for a property, e.g.

\begin{displaymath}x\_position \Leftrightarrow X \end{displaymath}


\begin{displaymath}x\_position \Leftrightarrow TDETX \end{displaymath}


\begin{displaymath}x\_position \Leftrightarrow CHIPX. \end{displaymath}

At any time the user can see all the valid definitions for a property and choose the one he wishes to use by pressing the Derived Properties button. Analysis parameters can be changed by pressing the Analysis Parameters menu.

The five derived properties generic1-5 have special uses. The analysis widgets (described later) can directly access only the derived properties of usual interest plus generic1-5. If, for example, you wanted to plot the property ccd_id (something not usually done) you would first have to establish the definition

\begin{displaymath}generic1 \Leftrightarrow ccd\_id \end{displaymath}

and then select generic1 in an analysis widget. Similarly, if you wanted to plot an odd FITS column that does not already correspond to a derived property then you would first establish the definition

\begin{displaymath}generic1 \Leftrightarrow MYCOLUMN. \end{displaymath}

The derived properties x_position & y_position can be defined as TDETX/Y sinusoidally dithered by exposure number. Such a dithering of TDETX/Y can be used to very roughly de-dither AXAF observations when aspect-corrected data are not available. Normally you would spatially filter on a bright point source which shows a clear sinusoidal motion, then select Positions->Fit X Dither and Positions->Fit Y Dither which performs a fit of TDETX/Y to derive the dither parameters. The dither parameters can also be set by hand in the Analysis Parameters menu.


3.2.3 Automatic Updates to Analysis Displays

When the domain dataset is changed - as a result of reading event files, changing the definition of derived properties, or changing analysis parameters - the new data is sent to all existing filter widgets (described in the next section) and the Apply Filter button is enabled. Pressing that button recomputes the working dataset which is then sent to all existing top-level analysis widgets. Note, however, that some analysis products derived from widgets, such as fits to a spectrum or cuts across an image, are not updated.


3.3 Defining & Analyzing the Working Dataset

Once the domain dataset is established (input files are selected and the Assemble button has been pressed), you are ready to define and analyze the working dataset, a filtered version of the domain dataset, using widgets created by pressing buttons and choosing menu items found on the Event Browser Manager widget.

Only one Working Dataset exists in Event Browser. However some of the analysis tools described below can work with multiple datasets. Each dataset contained in an analysis tool is identified by a unique dataset name. Thus, although you cannot define two Working Datasets simultaneously, you can compare analysis plots & images from multiple Working Datasets by getting the individual analysis tools to ``remember'' previous datasets.

For example, suppose you have loaded a Domain Dataset and have named the Working Dataset ``WDS''. If you wanted to overplot the single event spectrum and the spectrum for all events you would do the following.

  1. Bring up a Univariate Analysis widget displaying a spectrum.

  2. Press the Edit button on the Univariate widget and change the name of the dataset to ``all events''.

  3. Bring up a grade filter and configure to select only singles.

  4. Press the Apply Filter button. The Working Dataset is recomputed (using the grade filter) and the resulting vector of event energies is sent to the existing Univariate Analysis widget. The named attached to this dataset is the named of the Working Dataset, ``WDS''.

  5. The Univariate Analysis widget now contains two datasets named ``all events'' and ``WDS'', overplotted, with a legend. You may change the names, descriptions, binning, line styles, colors, etc. for those datasets.

If you want to work with multiple datasets in several analysis widgets, it will be more efficient to change the name of the Working Dataset itself (an editable field in the Manager Widget) rather than changing dataset names in each of the analysis widgets. Normally, if you type a new name in the Working Dataset Name field the manager widget first asks all the analysis widgets to destroy the datasets they are are holding under the old name, then it sends new data to those analysis widgets under the new name. If, however, you enable the ``Retain plots for old working datasets'' checkbox on the Manager widget, then the manager widget will skip the step of destroying data under the old name. Thus, each analysis widget will end up with two datasets under the old and new names. The steps for overplotting single and all grade spectra (from our previous example) using this method would be:

  1. Give the Working Dataset an appropriate name, e.g. type ``all events'' in the field Working Dataset Name on the Manager widget.

  2. Bring up whatever analysis widgets you desire.

  3. Enable the ``Retain plots for old working datasets'' checkbox on the Manager widget.

  4. Rename the Working Dataset to ``single events''. At this point all analysis widgets will contain two datasets named ``all events'' and ``single events''. For the moment the two contain the same data.

  5. Now, bring up a grade filter and configure to select only singles.

  6. Press the Apply Filter button. The Working Dataset (named ``single events'') is recomputed and all analysis widgets now contain the two datasets desired (all events and single events).


3.3.1 General Notes About Filters

Detailed descriptions of the various filters are given in the sections below. You may define as many filters as you wish, including multiple instances of a filter type if that makes sense. An event is included in the working dataset if it is accepted by all the filters defined, i.e. the filters are AND'd together.

Note that there are often several ways to filter along one property of the data and a careless user might reach erroneous conclusions. For example, a user might create one filter widget that accepts events from one CCD amplifier and a second widget that filters spatially. That's fine - events are accepted if they are on the correct amp AND fall in the spatial region specified. However, a careless user might forget about the second filter and erroneously conclude that the collecting area appropriate for the working dataset is the area associated with one CCD amp. Similar confusion could result if a user thinks he's accepting a set of ASCA grades but he forgot about an additional filtering operation he's defined on an ACIS grade display.

The Dismiss button on each filter widget destroys that filter (i.e. the working dataset is no longer filtered in that way). If you simply want to close a filter widget you've configured so that you don't have to look at it, then you should close the window using your window manager, for example by pressing the Open button on the keyboard.

When any filter widget's configuration is changed, the working dataset is made invalid and the Apply Filter button is enabled. A message appears on the status bar of the Event Browser Manager widget. You must press the Apply Filter button to re-compute the working dataset. This apparently needless extra step exists because of the finite speed of the computer. If EB attempted to recompute the working dataset each time any of the filter widgets was altered in any way, the user would suffer annoying delays. Instead, the user should configure all the filters as desired and then press the Apply Filters button.

When the working dataset is valid, the status line at the top of the Event Browser Manager widget reports the size of the working dataset. An editable field in the Event Browser Manager widget, Working Dataset Name, allows the user to give the working dataset a name which describes the data - this name is passed down to several of the analysis widgets for use in plot titles and legends.


3.3.2 Univariate Analysis with the dataset_1d Tool

Many analysis tasks involve studying the distribution of a single property of events. For example a spectrum is the distribution of event amplitudes and a light curve is the distribution of event timestamps. The Univariate Analysis widget, also known as the dataset_1d tool, shown in Figure 1, is used to display all such distributions. This widget provides optional controls for selecting a region-of-interest in the range of the property to serve as a domain dataset filter. The Event Property droplist at the bottom of the widget controls which event property is analyzed.

The capabilities of dataset_1d are described in Section 4.

Figure 1: Univariate Analysis widget
\includegraphics[height=5.0in]{dataset_1d}

3.3.2.1 Notes on Spectra

You may display spectra in either DN or eV units (property pha or energy). Spectra in DN have a default binsize of 1. Spectra in eV arbitrarily have a default binsize of 10, since there is no obvious binsize to use when multiple CCD amplifiers are used.

3.3.2.2 Notes on Light Curves

Light curves may be computed using either real-valued timestamps or integer-valued exposure numbers. The disadvantage of the timestamp light curve is that the bins of the histogram can beat against the natural periodicities of the timestamps, resulting in a jagged display. Event Browser does NOT currently attempt to set the bin size by looking for periodicity in the data or by using ACIS-specific knowledge of the CCD readout rate. Event Browser does not know anything about good time intervals or the exposure time of your observation - it simply histograms the timestamps in the working dataset.


3.3.3 Univariate Trend Analysis with the Trend_1d Tool

Pressing the Trend-1D button on the Manager widget brings up a tool that lets you analyze how the distribution on one event property varies with the value of a second property. The range of the Trend Property is divided into a number of bins or samples, then the subset of the Measurement Property corresponding to each sample is sent to a dataset_1d tool (Section 4) as a separate dataset. The user can control the bin size, and can set a minimum number of data points that will constitute a sample. The phase of the bins is at present beyond your control - the first bin starts at the smallest trend data value. You can of course limit the range of the trend property in another widget if you wish.

For example to study CTI select event energy as the Measurement Property and CHIPY as the Trend Property. To study the benefits of grade selection select event energy as the Measurement Property, grade as the Trend Property, and a bin size of 1. To study aspect drive select a spatial coordinate as the Measurement Property and time as the Trend Property.

Once the N datasets are in dataset_1d you can perform N fits to them by choosing Analysis->Fit All Datasets (after first setting up a model with Analysis->Define Model). A window is creating plotting each of the fit parameters versus sample number. Just try it - it's hard to explain in words.


3.3.4 Bivariate Analysis with the dataset_2d Tool

Sometimes it is helpful to see two event properties plotted against each other. For example plotting x_position against y_position helps to visualize the spatial distribution of events, and plotting event energy against timestamp can be helpful for datasets taken with a source that scans in energy. The Bivariate Analysis widget, shown in Figure 2, is used to display all such plots. This widget also provides optional controls for selecting a region-of-interest in the plot to serve as domain dataset filter. For example, the user could define a spatial filter by drawing a rectangle on an x_position verses y_position plot - the working dataset would include only those events whose locations fall within the range corresponding to the rectangle. Droplists at the bottom of the widget control which event properties are analyzed.

The capabilities of dataset_2d are described in Section 5.

Figure 2: Bivariate Analysis Widget
\includegraphics[height=5.0in]{dataset_2d}

3.3.4.1 Rotation of Coordinate System

Edit the field Rotation Angle to apply a rotation to the bivariate dataset before it is passed to the analysis tool. Rotating the data is an inelegant, but effective method for defining region-of-interest filters which are rectangles angled in the original coordinate system, e.g. for accepting events from just one arm of a gratings image. Rotating the data is also an inelegant, but effective method for plotting cuts through a 2-D density function which are angled in the original coordinate system.

3.3.4.2 Notes on Spatial Filters

Each Bivariate Analysis widget allows you to define only one ROI, however you may define as many Bivariate Analysis widgets as you wish. Using two spatial filters can sometimes help you define complex regions. For example, say you wanted to include only the region around a PSF, but within that region there was a chip defect that you'd like to exclude. You could set up one large ROI that includes the area around the PSF, then set up a second ROI that excludes only the small area around the defect. This exclusion-type ROI could be the exterior of a box-style ROI, or could be an annulus-style ROI with the inner radius non-zero and the outer radius very large.

Figure 3 shows the position of the ACIS CCD's in the DETX/DETY coordinate system.

Figure 3: ACIS Cooridinate Systems
\begin{figure}\centerline{\epsfig{file=det,width=5.0in}}\end{figure}


3.3.5 Trivariate Analysis with dataset_3d Tool

To examine the relationship of three event properties (.e.g. to create a ``movie'' of sky images taken over a set of time bins, or to make a median energy map) use the dataset_3d tool described in Section 6.


3.3.6 Filtering By Grade

The menu selection Grades $\Rightarrow$ ASCA Grade Filter brings up a grade filtering widget that uses the ASCA grade names. The ACIS grades that correspond to each ASCA grade are shown. A droplist at the bottom of the widget lets you independently control how ACIS grade 255 is handled.

ASCA grades are defined in Section 4.5.1 of the ASCA ABC Guide, which is reproduced in Appendix A. The relationship between ASCA and ACIS grades is described in an document by Kenny Glotfelty at the AXAF Science Center which is reproduced in Appendix B. Figure 4 shows cartoons of the 256 grade codes used for ACIS.

Figure 4: ACIS Grade Definitions
\begin{figure}\centerline{\epsfig{file=grades,height=7.0in}}\end{figure}


3.3.7 Filtering By Amplifier ID

The menu selection Detector $\Rightarrow$ CCD/Amp Filter brings up a widget that allows you to accept specific CCD amplifiers.


3.3.8 Filtering Bad Rows and Columns

Use the menu selection Detector $\Rightarrow$ Row/Column Filter to filter out bad rows or columns. Note that Event Browser and this widget understand only one X/Y coordinate system for events. You need to be aware of the coordinate system used in the FITS files you've read. Cameras with multiple CCD's will use a detector coordinate system which will NOT correspond to the row and column numbers of a CCD, limiting the usefulness of this filter widget.

To add a column to the bad row/column list, type the column number in the Add Row/Column field, press the Column toggle button, and press the Add To List button. The bad column appears in the list. Repeat for additional rows and columns. To delete an entry from the list, select one of the list entries by clicking on it, and press the Delete From List button.

Note that this filter excludes only events whose central pixel falls on the specified row or column. An event island whose edges fall on an excluded row or column is still accepted.


3.3.9 Filtering By Event Quality

Some FITS event lists include a column named Quality which has a non-zero value for events which have been marked as corrupt in some way by whatever system created the event list file. The Event Browser Manager widget includes a droplist which controls how that Quality property is us used to filter the Domain Dataset. Normally this droplist is set to accept only high-quality events, meaning that events with a non-zero Quality property are excluded from the Working Dataset.


3.3.10 Displaying Event Island Values

The menu selection Detector $\Rightarrow$ Event Island Values displays a distribution of user-specified pixels from the event neighborhoods in the working dataset. For example, the user could estimate the read-noise of the CCD by displaying a histogram of the corner pixels.


3.3.11 Dispersion Histogram Tool

The menu selection Gratings $\Rightarrow$ Histogram of Dispersions displays a histogram of the distance from each event to an arbitrary, user-defined point. This display is useful in combination with spatial and amplitude filters when analyzing gratings datasets.

Because of the geometry of the AXAF High Energy Transmission Gratings and the Medium Energy Transmission Gratings, the dispersion pattern forms an X across the detector. One arm of the X is HETG-dispersed data, and the other arm is METG-dispersed data. Users may want to analyze data from one leg of the X by using a spatial filter to select a Region of Interest around the desired data. Filter out higher-order photons by defining a DDS filter ROI on a spectrum display. Typically, diffraction order positions are given as distances from the zeroth order position, so users may want to bring up an X/Y display and find the centroid of the zeroth order spot. You are now ready to display a diffraction pattern for the selected data.

When you start this widget, a dialog box appears prompting you for a reference point from which to compute distances. Enter the x and y values of the zeroth order position as calculated above. A histogram of distances from each event to the reference point you entered is calculated and displayed. To change the reference point, simply click on the Change Reference Point button, and enter a new reference point.


3.4 Saving the Working Dataset

The working dataset may be saved via a button on the Event Browser Manager widget, either as a FITS event list (similar to the input file format) or as an XSPEC-compatible spectrum. When saving an event list you may choose which event properties (FITS columns you read in and/or derived properties computed by EB) you wish to save. The FITS column names used for derived properties are specified in the property definition dialog box (section 3.2.2).


3.5 Customizing Event Browser

EB may be customized with a user-supplied filter for the domain dataset. This filter takes the form of an IDL procedure named eb_custom_filter which has a single output parameter that is a domain dataset mask. A mask is a byte vector of length equal to the number of events in the domain dataset. Events whose mask value is 0B will be omitted from the working dataset. Those whose mask value is 1B may join the working dataset if they are accepted by all other filteres defined. If all events are to be accepted eb_custom_filter may either return a mask of all ones or may return an undefined variable.

An example of such a procedure is shown in Figure 5. You must arrange for the procedure eb_custom_filter to be loaded into IDL, either by using the .run command to compile the file containing the procedure, or by placing the procedure in a file named eb_custom_filter.pro in a directory that is in the IDL search path.

Figure 5: A fairly complex example of a custom filter routine. Please contact the people listed in Section 1 for assistance in writing your own custom filter routines.
\begin{figure}\begin{verbatim};;; This filter accepts 5x5 events that have any... ... mask = (total(crossings, 1) GT 0) endifreturn end\end{verbatim} \end{figure}

EB may be also be customized with user-supplied property definitions which take the form of IDL procedures named eb_custom_property1, eb_custom_property2, eb_custom_property3, eb_custom_property4, eb_custom_property5, & eb_custom_property6. These procedures unfortunately have fairly complex interfaces (parameters and rules of behavior). The example in Figure6 can hopefully serve as a template for writing your own custom property definitions. Please contact the people listed in Section 1 for assistance.

In Event Browser, if the procedure eb_custom_property1 exists then the last option for the definition of the property generic1 will be that supplied by eb_custom_property1. (See Section 3.2.2.)

You must arrange for the procedure eb_custom_property6 to be loaded into IDL, either by using the .run command to compile the file containing the procedure, or by placing the procedure in a file named eb_custom_property6.pro in a directory that is in the IDL search path.

Figure 6: A fairly simple example of a custom property definition.
\begin{figure}\begin{verbatim};; A custom definition of the Event Browser prop... ...'generic6' ;; is valid (i.e. computable). return end\end{verbatim} \end{figure}


3.6 Hints on Using Event Browser

next up previous contents pdf.png
Next: 4 dataset_1d Tool Up: User's Guide for the Previous: 2 What's New?
Patrick Broos
Penn State Department of Astronomy
2008-02-15