Ahelp: filtwin - CIAO 3.4

Jump to: Description Examples Parameters CHANGES IN CIAO 3.0 XPA ACCESS POINT AND COMMANDS ANALYSIS MENU, THE SESSION, AND COMMAND-LINE OPTIONS Bugs See Also

AHELP for CIAO 3.4

filtwin

Context: gui

Synopsis

GUI to perform interactive filtering of data

Syntax

filtwin [-help] [filename]

Filter window (filtwin) is a graphical user interface (GUI) that facilitates the filtering of Chandra data. The tool may be run stand-alone, but its full benefit comes from interactivity with other ciao session tools (prism, the imager). It can not only handle data filtering, but can also be used to restore a CIAO analysis session from a save file. Filtwin may be initialized with data in many different ways:

Specify the filename on the command line when the tool is invoked.
Load a file with the "Open Data" command in the "File" menu.
Type the name of the datafile in the "file" text field in the GUI.
Retrieve the file specification from the imager, ChIPS, or prism via the [Update From] button in conjunction with the "Window" selection toggle.

When filtwin is provided a filename, it attempts to display the "interesting" block of data - e.g. the EVENTS block of an event file or the SPECTRUM block of a PHA file. If the data is a table, the names of the columns are printed in a scrollable display which contains text fields so that individual columns may contain their own filter specifications. Vector columns are listed both as the vector itself and as individual components to allow filtering on either form. If the data is an image, three entries are displayed in the filter display: X axis, Y axis, and Other Filter.

As with prism, a small status window is situated at the bottom of the application to provide the user with various feedback messages.

Filtwin Settings

The Filtwin tool has a parameter file which can be edited either by using the CIAO command-line tools such as plist and pset or via the "Preference" option of the "Edit" menu. The parameter file is read each time the "Preference" option is chosen.

Filtwin and other applications

The default behaviour when Filtwin is started is for it to automatically initialize itself with data from another application in the session - either the imager (ds9), chips, or prism.

If the filtwin_init parameter in ciao.par is set to

imager, chips, or prism

filtwin will attempt to get its initialization data from that application. If that application is not running but a single copy of one of the other two applications is running, then Filtwin will use that application.

This means that if you have run Filtwin after creating the following plot in ChIPS,

  chips> curve "/data/Chandra/evt2.fits[cols x,y]"

then Filtwin will start up with its input file set to "/data/Chandra/evt2.fits" and with the column selection set to "x,y".

This behaviour is configurable, so to stop it you can use one of the following techniques:

Set filtwin_init in ciao.par to "none". If filtwin detects a single chips, ds9, or prism process when it it started it will bring up a dialog asking if it should use that application to initialize itself.
Use the -nosession command-line option so that Filtwin is not part of the session. This means that this copy of Filtwin will not be able to communicate with prism or chips but should be able to interact with ds9 or its own plot window.
Have more than 1 copy of prism, chips, or ds9 running, since if the preferred initialization point is not running and more than one other application is detected, Filtwin will not try to initialize itself.

Example 1

The following examples are also described (with images) in the Introductory Threads section of the CIAO website.

FILTERING EVENTS FROM AN EVENT FILE IN PRISM

First, update the data in filtwin from the appropriate instance of prism. Set the value of the "Window" toggle to the correct value: if the title bar of the instance of prism to be used specifies "prism-2 filename", then set the selection to "Prism-2". Click on [Update From]. The file field of filtwin will be updated to specify the name of the file in prism and the scrollable display will list the columns of the event file.

To filter out events where the status is non-zero or the fltgrade is 208, set the filter values for the appropriate fields. Scroll down in the display until the column label "status" is visible. In the text field following the label, type "=0". Adjust the display so that the fltgrade label is visible and add the text "!=208" to its field.

Set the cols/bin toggle to bin and provide the binning instructions, e.g. "sky=16" or "x=16,y=16".

Click on the [Apply To] button. The imager should update to display an image of the event file, binned with a block factor of 16, consisting of events whose status is zero and whose fltgrade is not 208.

Example 2

FILTER COLUMN INFO AND PLOT DATA

By leaving the cursor over a column label in the scrollable display when tooltips are on, the tlmin and tlmax values of a column in a fits file are displayed. If the range is too large an explicit filter may be applied to the file. For instance, adding the text "54543000:54543100" to the "time" field will cause the data to be filtered to that interval when the [Apply To] button is pressed.

To plot two columns, set the bin/col toggle to "Cols" and enter the two columns as as x-axis,y-axis, e.g. "chipx,chipy". For a vector column, the two axes may be specified by the name of the vector column - "chip" in this case. Clicking on [Apply To] should result in a plot of the chip coordinate pairs for the input event file within the filtered time interval.

To see a plot of chip coordinates for a specific ccd, set the text after the "ccd_id" label to the desired ccd. Entering "4" will result in the elimination of all events that did not occur on ccd 4.

By changing the bin/col toggle to bin, setting the text to "chip=2" or "chipx=2,chipy=2" and clicking on [Apply To], the imager will display the chip coordinates for the filtered data binned to a factor of 2.

Example 3

RESTORE A SAVED SESSION

Launch filtwin specifying the name of the restore file:

  unix% filtwin /data/save1.fits

This example illustrates how to use filtwin to resume an analysis session which was saved to the file /data/save1.fits. Filtwin utilizes the file to re-create the work environment that existed when the session was saved. All instances of applications such as ChIPS and prism that were running when the session was saved are opened with the data they contained at the time the save was performed; see "ahelp session" for more information.

Parameters

name	type	def
quickhints	boolean	yes
updatefirst	boolean	no
allcolumns	boolean	no
clearall	boolean	yes
clobber	boolean	yes

Detailed Parameter Descriptions

Parameter=quickhints `(boolean default=yes)`

Display tool tips?

This parameter controls the state of whether or not filtwin displays tool tips when the user leaves the cursor over a widget in the gui for a few seconds. If set to "yes", filtwin will display brief instructions for the various components of the GUI. If a table file is being examined, the user may get column information (eg. type, tlmin, tlmax, and units) by placing the cursor over the column name/label in the filter scroll window.

Parameter=updatefirst `(boolean default=no)`

Update from imager before applying a filter specification?

This parameter controls whether filtwin attempts to load information from the imager before it applies the current filter description.

Parameter=allcolumns `(boolean default=no)`

Display all data columns (including filtered-out columns)?

When this parameter is set to "yes", all of the data columns from the relevant block of the specified file are displayed. This is regardless of whether or not the columns have been specifically filtered out.

Parameter=clearall `(boolean default=yes)`

Clear all data fields?

This parameter is used to specify whether filtwin should delete only the filter information in the scrollable window or all information, including the filename, when the [clear] button is pushed.

Parameter=clobber `(boolean default=yes)`

Overwrite existing file on save command

Should an output file be overwritten by the "Save Data" and "Save Desc" commands?

CHANGES IN CIAO 3.0

Change in name of XPA access point

The names of XPA access points has been simplified in CIAO 3.0 as described in "ahelp session".

XPA ACCESS POINT AND COMMANDS

As with most of the CIAO GUIs, Filtwin has an XPA access point which can be used to control its behaviour and query its state - e.g. get it to load a specific file or ask it what columns are selected. This is used by the CIAO session handling ("ahelp session") to provide an integrated analysis environment.

The default name is "filtwin", with further instances being called "filtwin2", "filtwin3", ... (the "-xpa" command-line option can be used to override this naming scheme). Filtwin understands the following commands when sent via XPA:

  unix% xpaget filtwin

  apply:          trigger an Apply in filter window
                  options: None
  bin:            set or get bin field in filter window
                  options: [ <DataModel binning specification> ]
  block:          set or get block name in filter window
                  options: [ <block name> | <block number> ]
  col:            set or get column field in filter window
                  options: [ <DataModel columns specification> ]
  file:           set or get filename in filter window
                  options: [ <filename> ]
  filter:         set or get filter in filter window
                  options: [ spatial <filter> | <filter> |
                             static <filter> | clearall ]
  print:          write out postscript file of plot window
                  options: [ <filename> ]
  title:          set the title of generated plots
                  options: [ <titlestring> ]
  update: update file from specified location
                  options: [ <application> ]
                  NOTE: title will be visible only after an apply
  exit:           Exit the current application
                  options: None
  quit:           Synonym for "exit"

Note that many of these commands are intended for use by other GUIs, and so may not be of much use to users.

The following code - which makes use of the S-Lang XPA bindings described in "ahelp xpa" - starts filtwin and then uses the XPA interface to load the file "/data/Chandra/evt2.fits" after applying the DM filter "sky=circle(4000,4000,100)", and then sets the selected columns to "time" and "x":

  chips> require("xpa")
  chips> !filtwin &
  chips> xpaset("filtwin","file","/data/chandra/evt2.fits[sky=circle(4000,4000,100)]")
  1
  chips> print( xpaget("filtwin","file") )
  /data/Chandra/evt2.fits[sky=circle(4000,4000,100)]
  chips> xpaset("filtwin","col","time,x")
  1

ANALYSIS MENU, THE SESSION, AND COMMAND-LINE OPTIONS

The Analysis menu can be configured using a simple text file which uses the same format as the DS9 Analysis menu; for more details see "ahelp analysis-menu". For details of the session support in filtwin see "ahelp session". As described in that file, filtwin has a number of command-line options that can be listed by calling 'filtwin -help'. These options are not needed by most users and include:

Option	Description
-iconic	Starts filtwin in an iconified/hidden state, if allowed by the window manager.
-nosession	Do not attatch this Filtwin to the current CIAO session.
-toolmenu <file>	Use <file> rather than the system default file for defining the Analysis menu.
-xpa <name>	Sets the XPA access point of Filtwin to <name>.

Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

Parameter=quickhints (boolean default=yes)

Parameter=updatefirst (boolean default=no)

Parameter=allcolumns (boolean default=no)

Parameter=clearall (boolean default=yes)

Parameter=clobber (boolean default=yes)

Parameter=quickhints `(boolean default=yes)`

Parameter=updatefirst `(boolean default=no)`

Parameter=allcolumns `(boolean default=no)`

Parameter=clearall `(boolean default=yes)`

Parameter=clobber `(boolean default=yes)`