\documentclass [11pt,titlepage]{book}

\oddsidemargin=0.50in
\evensidemargin=-0.50in
\textwidth=6.25in
\topmargin=-0.25in
\textheight=9.00in
\topsep=2pt


\parindent=0pt
\parskip=9pt plus1pt minus1pt
\pagenumbering{roman}
\usepackage{html}
\begin{document} 
\pagestyle {empty}
\begin{titlepage}

\vspace*{5.0cm}

\centerline{{\LARGE {\bf The Xselect User's Guide}}}
\bigskip
\centerline{{\Large {\bf Version 2.4}}}

\vskip 2.75cm

\centerline{J. Ingham, K.A. Arnaud \& M.F. Corcoran}
\centerline{Jul 17, 2006}

\vfill
{\obeylines\parskip=1pt plus1pt minus1pt
HEASARC
Astrophysics Science Division
Goddard Space Flight Center, NASA
Greenbelt, Maryland, 20771
USA
}

\end{titlepage}

% the extra titlepage is here to force a blank page.

\begin{titlepage}

\end{titlepage}

\tableofcontents

\cleardoublepage

\pagestyle{headings}
\pagenumbering{arabic}

\chapter{Introduction}

Xselect is a command line interface to the Ftools, for X-ray
astrophysical analysis.  It has four major functions:

\medskip
\begin{itemize}

\item
to organize the input of data through the observation catalogue, and
store it internally for easy use.

\item
to enter intensity, phase, region, detector, grade, event file column,
spectral, and timing filters, which will be  applied to the event data.  

\item
to make good time intervals (GTI) by applying selection criteria to
the Housekeeping and auxiliary filter data.

\item
to extract images, light curves and spectra from the event data, using the
entered filters, as well as the GTI created by the applied selections.  

\end{itemize}
\medskip

Xselect also contains routines of importance for specific missions.
Currently, there are only ASCA specific commands, namely sisclean,
gisclean, faint and fast. Xselect can be set up to support any new
mission or instrument that does not require mission-specific routines
simply by editing the mission database file (xselect.mdb). The mission
database file distributed with xselect v2.4 contains complete support
for ASCA, BBXRT, Chandra (ACIS and HRC), EINSTEIN (IPC and HRI),
EXOSAT, INTEGRAL, ROSAT, BeppoSAX (LECS, MECS, and PDS), 
Swift (XRT and UVOT), Suzaku, XMM-Newton (EPIC) and XTE PCA standard2.

In addition, there are routines to plot up various aspects of the
event data, and of the HK and auxiliary filter data.

There are also general utility commands to view the internal state of
Xselect, to view the raw data files, to clear various selections, data
choices, etc., and to save the products of the analysis.

After v2.0 xselect comes in three flavors. The old interface is available
by running the command xselect as before however for the adventurous we
are also supplying xseltcl, running Tcl as its user interface, and ixselect,
a graphical user interface to xseltcl. Both these new variants run exactly
the same commands as the standard version except that the commands list,
load, read, and set are renamed to xlist, xload, xread, and xset to avoid
conflicts with native Tcl commands.

This users' guide has two main sections. The overview provides a brief
tutorial on the use of Xselect while the commands section describes
the individual commands in more detail. The appendices describe how
to add new missions to Xselect, how the command line parser works,
any features/bugs, and the names of the temporary files created by
Xselect.

A note on the usage of this manual before we proceed: each Xselect
session is given a session prefix, which is prepended to the names of
the product files, and appears in the prompts.  In the rest of this
manual, we will use the default session name: xsel.  Replace this with
your own session name for all the Xselect temporary files.

\chapter { Overview } 

This is a brief tutorial for Xselect.  Only the general outlines of
the analysis are sketched. For the specifics of analysis of any given
mission consult the documentation for that mission (eg the ASCA guide
to data analysis issued by the ASCA GOF).

\section{ Generalities } 

Xselect is a controlling shell for the Ftools.  This means that rather
than reading all events data into memory, Xselect holds the data as
well as its temporary products in disk files, and processes them by
piping these files through various ftools.  Though this means more
I/O, the core size of the program is kept fairly small.    

One consequence of this method of operation is that Xselect performs
markedly better if the data is stored on a disk that is directly
connected to the cpu that is running Xselect, and can perform very
badly over slow networks.

If you want to gain more insight into how Xselect uses the Ftools, and
what temporary files are produced, use the ECHO command, which writes
all the spawned commands back to the terminal before running them.

Xselect keeps track of five directories.  The data directory is the
place where the event data is stored.  The HK files can be stored in a
separate directory, the hk directory.  There can be a seperate directory
for the auxillary filter files (MKF files), the MKF directory.
Xselect will not alter any of these files, and can run when the user
has only read access to these directories.

Xselect's scratch files are stored in the current working directory.
This is also where the product files go, when they are saved.
Finally, there is a directory for storing the user's observation
catalogues, which initially defaults to the current working directory.
The user must have write access to both these directories for Xselect
to function. All these directories can be the same directory although
we do not recommend that.

The first stage in the analysis is to set up Xselect's internal state
for the particular mission-instrument-datamode combination you are
going to study, and the directory wherein your data resides.  This is
done with the various SET commands. 

The next step is to enter some data into the program.  The observation
catalogue (obscat) is the easiest way to do this.  If you do not
already have an obscat made, MAKE OBSCAT will create one for you.  If
you do already have one made, use the LOAD OBSCAT command to use it. 

Then you use the CHOOSE command to read data from the obscat list into
Xselect's internal list.

You can short-cut these steps by reading the event files directly using
READ EVENT. In this case Xselect will automatically set the appropriate 
mission-instrument-datamode combination.

If the data needs some preliminary conversion, such as Faint to Bright
conversion or Fast mode time corrections, this should be done next.
These commands process the original files, and produce temporary files
that Xselect will work on.  If you want to return to the original
data, you can CLEAR the conversion, and Xselect will use your
originally chosen data.  Again, Xselect will not alter your original
data, and in fact will even work when you have only read access to the
data directory.

Next, you may want to clean your data.  There are three sets of
commands that perform this function in Xselect.  The first are the
instrument specific cleaning methods, of which SISCLEAN for the ASCA
SIS and GISCLEAN for the ASCA GIS instruments are the only examples.

The second set of commands are the FILTER commands.  These commands do
no work, they merely enter filters (region, column, detector, grade, timing, 
phase, pha{\_}cutoff and intensity ) that will be applied to the next 
run of the extract command.

The third set are the SELECT MKF, HK and EVENTS, FAST, and CHIP commands.
These commands all work by applying some Boolean expression to one of the
data files. These can be either the event, the HK or the MKF
files. Note that FILTER MKF/HK and SELECT MKF/HK are synonyms.

In SELECT EVENTS, the events files are directly reduced, and Xselect
will continue to use the products of the selection until you give the
command CLEAR SELECTION.  An example of this is selecting only one of
the four chips of the ASCA SIS, which is accomplished with the command

\begin{verbatim}
xsel:ASCA- SIS1 > select event "CCDID==1" 
\end{verbatim}

In SELECT MKF and SELECT HK, GTI's are produced by applying the selection
expression to parameters in the MKF or HK files, which GTI's will be
applied on the next run of EXTRACT.  More insight into the nature of
these parameters can be gained using the MKFBIN/HKBIN and PLOT MKF/HK commands
to examine them.

SELECT FAST and CHIP are special cases. The former selects events based
on the ASCA SIS FAST mode area discrimination and the latter selects
events for the requested Chandra ACIS or XMM EPIC chips and creates the 
appropriate GTI extension. Note that SELECT runs the ftool fselect
which does not update datamodel subspace keywords for the selection 
performed.

Next, the filters are applied and the product files produced with the
EXTRACT command.  The possible products are images, spectra, and
lightcurves.  You can also output the event list that is the result of
all the filtering and selections that were entered.

Finally, these product files can be PLOTted, and SAVEd for input into
other analysis packages.

After dispensing with a few odd points, we will take up these topics in 
more detail.

\section{ Aids to the User } 


Xselect has several on-line features to help the user.  The first is
the on-line help. To get help on a particular topic, just type

\begin{verbatim}
xsel > help topic
\end{verbatim}

The only detail of note is that to get help on a compound command, you
must surround the command name in double quotes to protect the spaces.
For example:

\begin{verbatim}
xsel > help "command show events"
\end{verbatim}

will give you the "events" subtopic of the help topic "show".

If you type ??, you will get a list of all the available commands.

The next useful command is the XPI command LPARM.  This will list all
the parameters that a given command takes, as well as their types, and
current default values.  It is very useful for reminding yourself of
what options any given command has.

All the commonly used parameters will be prompted for, if not entered
on the command line.  It is often best, when you are not sure of the
order of parameters in a command, to just type the command name and
let Xselect prompt you for the values it wants.  Whenever a given
command has a number of subcommands (e.g. SHOW STATUS, SHOW DATA,\ldots ),
Xselect will list the available subcommands before giving the prompt.

On UNIX systems, Xselect uses the READLINE command line interpreter.
This supports command line editing, filename completion ( use the tab
key, hit once it makes the longest unique completion, and if there is
more than one completion, a second tab will show you all the possible
options) and up and down arrow keys for command recall.

Finally, if you cannot remember the name of some file, or what exactly
you called the directory where you stored your data, the \$ command, with
no arguments, will always break to the shell.  You return to Xselect
by typing exit, and you will come back at the point you left.

\section{ Reserved names } 


When Xselect exits, it deletes all files of the form (session
name){\_}*.xsl and (session name){\_}*.tmp in the work directory, unless you
save the session. Therefore, you cannot use names of this form, unless
you are willing to have them deleted on exit.

\section{ Sessions } 

Xselect supports multiple sessions in the same directory, which can
even run simultaneously, provided they have distinct names.  On entry
into Xselect, you will be prompted for a session name.  Then all the
temporary and product files written out by Xselect will have this
session name as a prefix. The default session name is xsel.  So for
instance the light curve output qdp file is called xsel{\_}curve.xsl.
You can also enter the session name when launching Xselect:

\% xselect prefix=myown  

will start up a session with the name myown.  

When you exit Xselect, you are prompted whether you wish to save the
session or not.  If you respond yes, all the temporary files are
saved, otherwise they are all removed.  Do not erase any of
these files on your own if you wish to restore the session at a later
date, or Xselect will no longer be able to do so.

To restore a saved session, simply give your new session the same name
as that of the session, and you will be prompted whether to restore
the saved session.  One caution, if you respond no to this prompt, the
previous session will be cleared before Xselect proceeds and you will
loose all the product files (except of course those you saved with
your own filenames, with the SAVE command).


\section{ Data Entry } 


There are two ways to enter data into Xselect, by the observation
catalogue (obscat), and the read command.  We take these up in order.

\subsection{ Obscats } 

The obscat is a fits file containing event file names and other
pertinent information about the files, such as on-time, datamode,\ldots ,
gathered from keywords in the primary extension of the events files.
The user can specify the items to be included in the obscat, and there
are a set of built in defaults for each supported mission.

The data files must all be contained in the same directory, the data
directory.  The obscat is constructed by doing a directory listing on
this directory, using a mission dependent regular expression for the
file names.  There is also the provision for user supplied regular
expressions.

Although the catalogues are limited to the contents of one directory,
the HK files can be kept in a separate directory.

Currently the MAKE OBSCAT command is designed primarily for the ASCA
mission. It assumes the naming conventions of FRFREAD for the Event,
HK and GTI files.  However, the read command makes an obscat that can
be SAVEd, LOADed and all the other functions the created catalogues
admit.  

If no observation catalogues are present, then one can be made by
specifying the mission, the instrument, and the data directory ( and
optionally the datamode), then issuing the MAKE OBSCAT command:

\medskip
\begin{verbatim}
xsel > set mission ASCA
xsel:ASCA > set inst sis1
xsel:ASCA-SIS1 > set datamode BRIGHT
xsel:ASCA-SIS1-BRIGHT > set datadir ../../data/20019000
xsel:ASCA-SIS1-BRIGHT > make obscat
\end{verbatim}
\medskip

The first step is unnecessary if you always use the same mission,
since Xselect stores a default mission that it loads at startup.  To
change this default, you can start up xselect with the command

\% xselect default{\_}mission=ROSAT

This will cause Xselect to load the ROSAT mission at startup, rather
than ASCA which is the default Xselect is shipped with.

A catalogue will be made in the obscat directory (or the current
working directory if no obscat directory is set) with the default name
xsel{\_}(instru).cat, where (instru) is s0, s1, g2, g3 for the ASCA
mission.  It is saved when the Xselect session is exited, regardless
of whether the rest of the session is saved.

When a catalogue is made, it is automatically loaded into xselect and
the contents displayed.

To view the contents of the catalogue again, use the command  

\begin{verbatim}
xsel >  show obscat  
\end{verbatim}

Note that the plain SHOW OBSCAT command will usually only show you a
subset of the parameters that are in the obscat.  To see all the
parameters, record by record, use the command:

\begin{verbatim}
xsel > show obscat list
\end{verbatim}

Or, if you have a different list of parameters that you want to view
in the column form, use the command

\begin{verbatim}
xsel > show obscat displist="@myparam.list"
\end{verbatim}

where myparam.list is a list of the parameters you want to view.

If you have already made some catalogues, you can get a listing of
them with the command

\begin{verbatim}
xsel > list obscat  
\end{verbatim}

This will list the catalogues in the current working directory (or
obscat directory if one is set), and the data directory if one has
been set.

You can load an already created catalogue with the command  

\begin{verbatim}
xsel:ASCA > load obscat  
\end{verbatim}

You can either specify, by name, the obscat that you want to load, or
if you give no arguments Xselect will display the catalogues present
in the obscat directory and the data directory, and prompt you for a
choice.

This command will also set the datadir, mission, instrument, and
datamode (provided they are unique) from the catalogue, if you have
not already done so.

To read data in from the catalogue, use the choose command.  Choose
works in two modes, you can say

\begin{verbatim}
xsel:ASCA >  choose 1-15
\end{verbatim}

which will select the files 1-15 from the obscat.   Or you can say

\begin{verbatim}
xsel:ASCA-SIS0 >  choose "datamode=='BRIGHT'"
\end{verbatim}

which will select all the files from the obscat with BRIGHT datamode.  

If you have a catalogue with the default name corresponding to the
currently selected instrument, then choose and show will act on that
catalogue automatically.

To apply selection criteria to the current catalogue to produce a new
catalogue, rather than to just extract data from it, use the command

\begin{verbatim}
xsel >  select obscat  "datamode=='BRIGHT'"
\end{verbatim}

This selection will not overwrite the previous catalogue, but it will
rename it to move it out of the way.  Since load obscat will give a
brief description of each catalogue it finds, this should not be a
problem, however if you want to save the current obscat with a name of
your own choosing, you can do so with the command

\begin{verbatim}
xsel >  save obscat  
\end{verbatim}

Finally, the process of selection may result in many obscats that you
don't want to keep.  The CLEAR OBSCAT command will give you the
same listing of the obscats as LIST and LOAD, and prompt you to remove
those catalogues you no longer need.

\subsection{ Read } 

After all this, if you want to read in data without the aid of a
catalogue, there is the command

\begin{verbatim}
xsel >  read event filename
\end{verbatim}

If no data directory has been set you will be prompted for one.
You can enter the files by hand on the command line, or dump their
names to a file, say file.lis, and give @file.lis as the filename to
the read command:

\begin{verbatim}
xsel > read event "@file.lis"
\end{verbatim}

The double quotes are necessary to keep XPI from expanding file.lis onto the
command line (q.v. @ in XPI section).

There are several other functions which give more information about
the data.  To view the contents of the Event, or GTI files that have
been entered, use the command

\begin{verbatim}
xsel >  show event,gti  
\end{verbatim}

To see a list of the data read in, use the command  

\begin{verbatim}
xsel >  show data  
\end{verbatim}

To view the contents of the work or data directories, use the commands

\begin{verbatim}
xsel > list workdirectory
\end{verbatim}

and

\begin{verbatim}
xsel > list datadirectory
\end{verbatim}

Finally, to clear the data use  

\begin{verbatim}
xsel >  clear data  
\end{verbatim}


\section{ Xselect's files } 


Once you have chosen the data, the list of files chosen is stored,
along with the associated HK and GTI files, by Xselect.  All further
operations will act on these files, or on product files made in the
course of analysis, where that is appropriate.

Xselect has one workspace for product files (e.g. from the FAINT or
the SELECT EVENT commands).  When this is filled by some command, say
FAINT, then Xselect will point to the files in it, rather than the
original files.  However, the original file list is not lost, so by
clearing the workspace (done by CLEAR FAINT, if the workspace was
filled by FAINT, and similarly for the other commands, or as a last
resort by CLEAR WORKSPACE), you get back to your original selection.

It is important to note that there is only one workspace, so if you
give two commands that both use the workspace, for example a FAINT
command, and then a SELECT EVENTS, the results of the FAINT command
will be used in the SELECT command, but then will be overwritten.  If
you want to retain these files, then you should do the following:

\medskip
\begin{verbatim}
xsel >  faint  
xsel >  save faint  
xsel >  select events  
\end{verbatim}
\medskip

The saved workspace is duplicated, so that Xselect can continue to
operate on the copy it keeps.  The saved workspace files can be
reloaded later, using the read command.  Because the workspace is
duplicated in the SAVE FAINT command, if you are short on disk space,
it is a good practice to save these files, clear the workspace, and
then read them in again using the READ command.

The commands that use the workspace are: FAINT, FAST, GISCLEAN,
SELECT EVENTS, SELECT FAST, SELECT CHIP, and SELECT EXPREF.

There are also some commands which produce a single product event file
that is automatically used in future extract commands, again without
losing the original data list.  The two examples of this are the
SISCLEAN command, and the EXTRACT EVENTS command.  

When you save this filtered event list, you will be given the option
to read it back into Xselect. Doing this will clear the previous data,
and reset the data directory to the current working directory.

Xselect also stores the extracted lightcurves, spectra and images
until you decide to save them (e.g. with SAVE CURVE, \ldots  ).  If you do
not save them, however, they will be erased when you exit the session.

\section{ Entering Filters } 

Xselect supports region, detector, grade, phase and timing filters,
pha upper and lower bounds, as well as a general filter on event
attributes (ie columns in the event file). These filters are not immediately 
applied to the events data, but stored and used in the next run of the 
extract command.

The filters are entered with the commands  

\begin{verbatim}
xsel > filter time  
\end{verbatim}
\begin{verbatim}
xsel > filter region
\end{verbatim}
\begin{verbatim}
xsel > filter phase  
\end{verbatim}
\begin{verbatim}
xsel > filter pha_cutoff  
\end{verbatim}
\begin{verbatim}
xsel > filter detector
\end{verbatim}
\begin{verbatim}
xsel > filter grade
\end{verbatim}
\begin{verbatim}
xsel > filter column
\end{verbatim}
\begin{verbatim}
xsel > filter mkf
\end{verbatim}
\begin{verbatim}
xsel > filter hk
\end{verbatim}

The timing filters can be entered in any of three formats, ASCII, or
FITS GTI files, with start and stop columns, and Xronos window format
files, with the command FILTER TIME FILE.

Timing filters can also be entered graphically using the FILTER TIME
CURSOR command, after a light curve has been made.  

Finally, you can enter GTI's by hand in either MJD, SpaceCraft Clock
or UT with the commands FILTER TIME MJD, SCC, and UT.

The region filter is in ds9 format. Region filters for the
filter region command can be created graphically via the plot image
command, which spawns a ds9 session. However the resultant
regions have to be read back into Xselect by hand with the filter
region command.  

A very important point to note about the region filters is that they
must either be in WCS or Physical coordinates. Regions created in
Image coordinates will not work correctly if image binning is not 1.

At this point, only a lower and upper cutoff for the PHA are allowed.

The phase information is written into a Xronos-format window file (the
sort created by the Xronos win command) by the FILTER PHASE command.
You enter the epoch and period in days, then you can choose phase
windows.  Then Xselect will filter the events based on the union of
all these phase windows.

You can save this phase information.  To read it back into Xselect at
a later time, use the FILTER TIME FILE command (which supports Xronos
window timing files).

There are a few other filters created within Xselect which are
automatically entered into the EXTRACT command.  These are the GTI
files (in FITS format) created by the SELECT/FILTER MKF, and the SELECT/FILTER HK
commands, and the GTI files created in the selections made in the PLOT
CURVE command.

The filters that have been entered can be listed by the command  

\begin{verbatim}
xsel >  show filter  
\end{verbatim}

They can also be cleared by the various CLEAR commands (see clear
under the Xselect{\_}Commands subheading)

\begin{verbatim}
xsel >  clear region  
\end{verbatim}

\ldots   


\section{ Making Selections } 


The user can also apply selection criteria to the data itself, as well
as the HK or auxiliary filter files, to filter the data.  There are
two provisions for selections based on data:

a) To apply a general selection expression based on the columns in the
event files, use the command

\begin{verbatim}
xsel >  select event  
\end{verbatim}

This command produces a set of reduced events files, one for each
input file, which are stored in the workspace.  To save these files,
use

\begin{verbatim}
xsel > save select  
\end{verbatim}

To aid in building up these expressions, the command  

\begin{verbatim}
xsel >  show params event  
\end{verbatim}

will display the column names in the event list files.  You can also
use the command

\begin{verbatim}
xsel > show event
\end{verbatim}

to look at the event data itself.  

b) To apply a selection based on the columns of the auxiliary filter
files, use the command

\begin{verbatim}
xsel >  select mkf  
\end{verbatim}

To see the columns available in the auxiliary files, use the command  

\begin{verbatim}
xsel >  show parameters mkf
\end{verbatim}

To gain insight into the behavior of these parameters, use the commands

\begin{verbatim}
xsel > mkfbin
\end{verbatim}
\begin{verbatim}
xsel > plot mkf
\end{verbatim}

The first will bin up a user supplied list of the mkf parameters.  The
second will plot up these binned curves.  They can be plotted either
against time, or against each other. If an event lightcurve has been
extracted then this can also be plotted with the mkf parameters to
look for correlations between the event rate and other information.

\section{ Saving clearing and setting } 


The SET, SHOW and CLEAR commands allow the user to control the
parameters for EXTRACT and other commands.

The SET commands allow the user to set the bin sizes, and the column
names for PHA, X and Y in the event list, which will be used in the
EXTRACT command.  You can also set the mission, instrument, datamode,
as well as the plot device through the SET command.  To restore the
defaults for the missions currently supported by Xselect use the set
mission command.

The clear command clears the various filters, and it can also clear
product files, like those from FAINT and FAST, and return Xselect to
the original data.  There is currently no multistep undo, however; you
can only return to the original list.

The SAVE command saves the various product files. Also, the SAVE
SESSION command will save the state of the session on exit. This can
then be restored at the start of the next session.

Finally the SHOW command is useful for displaying various elements of
Xselect.  In particular, the SHOW STATUS command gives a thumbnail
sketch of the current state of Xselect.  SHOW FILTER shows the
currently entered filters.  And, as mentioned above, the SHOW command
also allows you to inspect the event and MKF files in your data.



\section{ Extracting products and applying filters } 


Extract is the command that actually extracts light curves, spectra
and images from the event lists.  Additionally, you can output the
filtered events lists, which will speed up later analysis (this is not
currently supported for ASCA GIS MPC data).  Any combination of the
possible outputs is allowed.

All the entered intensity, region, detector, grade, timing, pha and 
phase filters are automatically applied.  The GTI's created by the 
SELECT MKF commands will be used.  Also the binsize for light curves, 
and the rebinning factors for the spectra and the image, which have 
been entered with the SET command, are applied.  If any product files 
have been made, for example the output files from the select event 
commands, they will be used in place of the original files.

The output of the extract image command is an image in the primary
extension of the FITS file xsel{\_}image.xsl.  It has all the keywords
necessary for input into SAOimage, SAOtng, or XIMAGE.

The output of the extract curve command is both an ascii QDP format,
and a FITS format light curve file, xsel{\_}curve.xsl.  The former also
contains, as comments, the accumulated spatial, timing and pha
selections.  This is primarily intended for a quick look, and to aid
in further timing selection.

The output of the extract spec command is a spectrum, contained in the
first extension of the FITS file xsel{\_}hist.xsl, which also contains a
weighted map image in the primary extension of the file.  All the
keywords necessary for XSPEC are written into the spectrum file.

The output of the extract events command is a FITS event list.  The
resultant GTI's are contained in the second extension of the file.
This events list is suitable for input to the new, FITS-reading
Xronos.  However, if the input data to Xselect is not time ordered,
this events list will not be either, so you will need to process it
through the FMEMSORT ftool before passing it to Xronos. By default
only the events and GTI extensions are written. If the copyall=yes
option is set then the extra extensions from the (first) input events
file are appended to the output file.

As mentioned above, Xselect will continue to use this filtered event
list in future work.  If you want to save it, the command

\begin{verbatim}
xsel >  save events  
\end{verbatim}

The extractor also outputs an ascii and a Xronos window format file
containing the resultant timing selections.  The former can be viewed
with the command

\begin{verbatim}
xsel >  show goodtime  
\end{verbatim}

These resultant timing selections, in ASCII and Xronos format, as well
as the event list, the spectrum, light curve and image, can be saved
with the save command.


\section{ Plotting } 


Xselect provides the facility to view the image (and to smooth it),
the spectrum and the light curve output by the EXTRACT command, as
well at to bin up and view the MKF parameters.  Two of the plot
commands, plot image and plot curve allow the graphical entry of
selections.

The image most recently produced by the EXTRACT command can be viewed
with the command

\begin{verbatim}
xsel >  plot image  
\end{verbatim}

Xselect uses the imagedisp parameter to determine which image display
program to use. The default is ds9. If you want to change this to
SAOtng then outside Xselect use the command

\begin{verbatim}
unix>  pset xselect imagedisp=saotng
\end{verbatim}

If you want to smooth the image before viewing, use the SMOOTH
command.  Currently there are BOXCAR, GAUSSIAN and LORENTZIAN
smoothing methods available. 

The light curve most recently produced can be viewed with the command  

\begin{verbatim}
xsel >  plot curve  
\end{verbatim}

You can plot the spectrum with  

\begin{verbatim}
xsel >  plot spectrum  
\end{verbatim}

Also, to aid in the SELECT MKF command, the columns in the MKF file
can be plotted.  This must be done in two steps, first bin them (more
than one parameter can be binned at a time) using

\begin{verbatim}
xsel >  mkfbin  
\end{verbatim}

Then you plot the parameters with the command

\begin{verbatim}
xsel >  plot mkf  
\end{verbatim}

Again, you can see more than 1 parameter per plot.  

\chapter { Xselect Commands } 

\section{ Summary  } 

The following is a list of the Xselect commands that are currently 
available.  For the XPI commands, see the XPI Commands heading.  

\medskip
\begin{itemize}

\item
bin	   -	Old name for extract  
\item
choose   -	Choose observations from catalogue by number  
\item
cpd	   -	Equivalent to set device  
\item
echo	   -	Toggles echoing of Xselect command files to the screen  
\item
extract  -	Extract image, spectrum or light curve from data  
\item
filter   -	Set filters for the bin command  
\item
faint	   -	Do faint-to-bright conversion  
\item
fast	   -	Apply the SIS fast mode timing correction
\item
gisclean -	Filter data using a PI-Rise Time window
\item
hkbin	   -	Bin up an HK parameter(s)  
\item
hksel	   -	Create a GTI file using HK data  
\item
(x)list  -	List the obscats or the work and data directories. The command
		name is xlist in xseltcl and ixselect.
\item
(x)load	 -	Load an extant observation catalogue. The command name is
		xload in xseltcl and ixselect.
\item
mkfbin   -	Bin up parameters from the Mkfilter output file  
\item
make	   -	Make observation catalogue  
\item
plot	   -	Plot spectrum, light curve, image, HK parameter, or other  
\item
(x)read  -	Read in filename(s) of FITS file(s) to be used. The command
		name is xread in xseltcl and ixselect.
\item
save	   -	Save current session, product FITS file, spectrum, light curve,
		image	
\item
select   -	Apply Boolean expressions for data selection, for creating GTI
		intervals from HK or filter files, and for filtering the 
		observation catalogue.  
\item
(x)set	   -	Sets the mission, instrument and plot device, and the
		column names, and binsizes for extract. The command name 
		is xset in xseltcl and ixselect.
\item
show	   -	Show data files, obscat, parameters, selections, or status  
\item
sisclean -	Remove hot pixels from ASCA SIS data  
\item
sispi    -    Fill the PI column for ASCA SIS data.
\item
clear	   -	Clear input files, filters, selections, or everything  
\item
echo	   -	Toggles echoing of command files to the screen  
\item
help	   -	Obtain help on commands and syntax  
\item
exit	   -	Exit from Xselect  
\item
quit	   -	Exit from Xselect  
\item
stop	   -	Exit from Xselect 
\end{itemize}
\medskip

\section{ bin  } 
\smallskip
{\bf \hskip 5em Old name for extract   }
\medskip

See extract.   


\section{ choose  } 
\smallskip
{\bf \hskip 5em Choose data from Obscat   }
\medskip

Choose enables the user to select data by number or selection
expression from an observation catalogue (see MAKE OBSCAT). It is an
alternative to typing in the full filenames in the read command.  The
call to CHOOSE clears the previously chosen or read in data, a READ
called after a call to choose will add data to the list.

If you have read in filters, (e.g. by SELECT MKF, or FILTER
\ldots  commands) then you will be asked whether you want to clear the
filters.  If you say no, you will retain the filters, but the old data
will still be cleared.

You can use a Boolean expression or a range as the argument to
choose.  If you give a Boolean expression, which must be based on
columns in the currently loaded obscat, all those files matching
the selection expression will be chosen.  The selection expression
follows the same syntax as in the select command.  

If you give a range, then those rows in the obscat will be chosen.
The syntax for the range is that commas delimit ranges, and dashes
include all numbers within their termini.  One element ranges are
legal, and there is one special character: ** = last legal value. 

Syntax: 

\begin{verbatim}
xsel >  choose > <choose_which> <choose_clear>  [quiet]
\end{verbatim}

Examples:   

You can choose by position in the current obscat:

\begin{verbatim}
xsel >  choose  1-4,7,8-16,25-**  
\end{verbatim}

Or by a Boolean expression applied to the current obscat:

\begin{verbatim}
xsel >  choose  "EXPOSURE > 100"  
\end{verbatim}



\section{ clear  } 
\smallskip
{\bf \hskip 5em Clears variables, etc.   }
\medskip

Clears various states of XSELECT. 

Syntax:

\begin{verbatim}
xsel > clear <clear_what>
\end{verbatim}

\subsection{clear all }

Clears all data and logicals, and removes all the product files.
Since this command removes all temporary files, you will be asked to
confirm the clear.

Syntax:

\begin{verbatim}
xsel > clear all [proceed]
\end{verbatim}

Example:

\begin{verbatim}
xsel > clear  all proceed=yes
\end{verbatim}

This does a clear all, and does not prompt for confirmation.


\subsection{clear clean}

Clears the region selection file produced by sisclean, and the cleaned
events list.

Syntax:

\begin{verbatim}
xsel > clear clean
\end{verbatim}


\subsection{clear column}

Clears the column filter.

\subsection{clear data}

Clears the data read in, but not the instrument name, plot device and 
other defaults.  


\subsection{clear datamode}

Clears the datamode, resetting it to 'NONE' which is its initial
value.

\subsection{clear detector}

Clears the detector filter. A subset of the filter can be cleared
using the same syntax as for the filter detector command.

\subsection{clear events}

Deletes the output event list from extract, and points back to the
data entered with the CHOOSE or READ commands.  If you give an EXTRACT
EVENTS, then Xselect will use the resultant events file in future
computations, until you give the command CLEAR EVENTS.

\subsection{clear faint}

Removes the products of the faint to bright conversion, and points
back to the original data.

\subsection{clear fast}

Removes the timing corrected files, and points back to the original 
data.   

\subsection{clear grade}

Clears the grade filter.

\subsection{clear intensity}

Clears the current intensity selection.  Again, you can choose 'all', or last,
or give a file list.  The files are all named
xsel{\_}intensity{\_}gtinnn.xsl.

There is one slightly non-obvious point here: the following sequence 

\medskip
\begin{verbatim}
xsel > extract curve
xsel > filter intensity 0.5-0.9
xsel > extract all
...
xsel > clear intensity
xsel > filter intensity 1.0-1.5
\end{verbatim}
\medskip

will result in all the data being eliminated.  The reason is that the
clear intensity clears the GTI's, but the next filter intensity acts
upon the lightcurve which was produced with these GTI's.

To produce the desired effect, instead do

\medskip
\begin{verbatim}
xsel > extract curve
xsel > filter intensity 0.5-0.9
xsel > extract all
...
xsel > clear intensity
xsel > extract curve
xsel > filter intensity 1.0-1.5
\end{verbatim}
\medskip

\subsection{clear hksel}

Removes the GTI files produced by the select/filter hk command.  

\subsection{clear intensity}

Clears the intensity selection entered by filter intensity.

\subsection{clear mkfsel}

Removes the GTI file produced by the select/filter mkf command.  

\subsection{clear obscats}

This command physically removes obscats.  When given with a filename
argument, the named obscat is deleted.  If no argument is given on the
command line, you are given the same obscat listing as for LOAD or
LIST OBSCAT, and then you can specify the obscats you want to remove
by index from the listing.

\subsection{clear pha{\_}cutoff}

Clears the PHA lower and upper cutoff selections.  


\subsection{clear phase}

Clears the phase selection.  

\subsection{clear region}

Clears the spatial region filters.  You can give a file list, or
``all'' or ``last''.

\subsection{clear selection}

Removes the event list output by the select event, select chip, or
select expref commands.  

\subsection{clear smooth}

Removes the smoothed image, so that the next call to plot image will
show you the unsmoothed image.  You do not have to clear the smoothed
image to make another one, however.  Smooth only acts on the
unsmoothed image.

\subsection{clear time}

This clears the various timing filters.  The clear{\_}what values are
the same as the argument to filter time.  All these commands will take
``last'' and ``all'' as well as a filename.  The only ambiguity is that
clear time file last clears the last Fits GTI entered.

\subsection{clear workspace}

Clears the workspace, and unsets all relevant logicals.


d\section{ echo  } 
\smallskip
{\bf \hskip 5em Echo ftools command lines   }
\medskip

This toggles on and off the echoing to the screen of the command files
spawned by Xselect.


\section{ exit  } 
\smallskip
{\bf \hskip 5em Exit Xselect   }
\medskip

End the current XSELECT run and return to the UNIX operating system.
Note that exiting will cause all the temporary files and filter
information to be lost if they haven't been explicitly SAVE-d.  You
will be prompted whether you wish to save the current session.

Syntax:

\begin{verbatim}
xsel > exit <save_session> 
\end{verbatim}



\section{ extract  } 
\smallskip
{\bf \hskip 5em Extract light curve, image or spectrum }
\medskip

Extract product files from the entered data, using the entered filters
and selections.  Extract is the new name for the old bin command.  Bin
still works for the nonce.

The extract command works on the latest set of product event files
that you have produced.  So if you have run GISCLEAN, SISCLEAN, or
SELECT EVENTS, extract will operate on the cleaned or selected files,
not the original files.  Similarly, if you have done a EXTRACT EVENTS,
a later extract will use the output events list.

The possible products are a light curve (EXTRACT CURVE), in either QDP
or FITS format (or both), a spectrum (EXTRACT SPEC), an image (EXTRACT
IMAGE), or a filtered FITS events list (EXTRACT EVENTS).  Any
combination of these is also possible simultaneously.  Also, EXTRACT
ALL is equivalent to EXTRACT ``CURVE IMAGE SPEC''

Extract assumes that there is a GTI extension (whose extname is set in
the mission database file) in the same fits file which stores the event 
data.  It accepts timing filters in three forms, ASCII or FITS GTI form, and 
Xronos window format.  It also accepts SAOIMAGE format region descriptor
files, which are concatenated into one file called xsel{\_}region.xsl,
and fed to the extractor program.

If sisclean has been run, then the cleaned events list (stored in
xsel{\_}in{\_}events.xsl) will be used.  To clear this use clear sisclean.

If select hk or select mkf have been run, the resulting GTI's will be
applied automatically.  To clear this use clear hksel, or clear
mkfsel.

If a timing selection has been made using filter time cursor, this too will 
be applied automatically.

The various bin sizes, etc, are inherited from the set command.  Some
of them can also be changed on the fly, by entering hidden parameters,
but these values only apply to this invocation of extract.

When extracting events only the events and GTI extensions are written
by default. If the copyall=yes option is set then the extra extensions 
from the (first) input events file are appended to the output file.

If offset is set to no then the lightcurve written will have times in 
spacecraft units. If offset is yes (the default) then the lightcurve times
are written relative to the first bin.

Binned spectra, images and lightcurves can be plotted with the PLOT 
command.  

Syntax:

\begin{verbatim}
xsel >  extract <bin_what> [use_qdp] [binsize_t] [pharebin_t]
               [xybinsize_t] [phalcut_t] [phahcut_t]  
               [xcenter_t] [ycenter_t] [xysize_t] [exposure]
               [use_qdp] [wmapcalfile] [offset]
\end{verbatim}

Examples :

a)

\begin{verbatim}
xsel >  extract "CURVE EVENT"
\end{verbatim}

Produces a light curve, and also a filtered event list.
To use this filtered event list for the next run of extract, say

\begin{verbatim}
xsel >  save event my_evtlist.fits yes  
\end{verbatim}

This is equivalent to saving the event list, and re-entering it using
the read command.

b)

\begin{verbatim}
xsel >  extract ALL  
\end{verbatim}

this is equivalent to  

\begin{verbatim}
xsel >  extract "CURVE IMAGE SPECTRUM"  
\end{verbatim}

c)

\begin{verbatim}
xsel >  extract "CURVE SPECT" bins = 30 pharebin = 4  
\end{verbatim}

Extracts a light curve and a spectrum, and temporarily resets the
binsize and pha- rebinning factors.

d)

\begin{verbatim}
xsel >  extract "CURVE SPECT" exposure=0.0
\end{verbatim}

The {\bf exposure} parameter controls the rejection of bins from the
light curve (only), based on how much of the bin lies within the
GTI's.  If exposure=1, then a bin is only written to the light curve
if it lies wholly within a GTI.  If exposure=0, then bins are written
to the light curve if any portion of them lies within a GTI.  Exposure
can have any value between these two extremes.  Of course, if a bin
does not fall inside any of the GTI's, it will not be written to the
light curve, no matter what the value of exposure is.

\begin{verbatim}
xsel >  extract "CURVE SPECT" bins = 30 pharebin = 4  
\end{verbatim}

\section{ faint  } 
\smallskip
{\bf \hskip 5em ASCA SIS faint to bright conversion   }
\medskip

Perform faint-to-bright conversion on all files currently read into
XSELECT.  If the datamode is set to faint, then the EXTRACT command
will run FAINT before extracting the spectra,\ldots , provided of course
you have not already done so.

For more details see the faint help page (i.e. from Xselect type
\$fhelp faint).

If you specify that you want to convert to bright2 mode, then you can
either input (dfefile=your{\_}filename), or have xselect create for you,
(dfefile=MAKE) a Dark Frame Error file (see the help page for faintdfe
for more details), which will be fed to the ftool faint.  dfefile=NONE
turns this option off.

If you set sispi=yes (the default) faint will fill the PI columns of the 
resultant BRIGHT or BRIGHT2 mode data files.

Syntax:

\begin{verbatim}
xsel >  faint <bright> <split> <dfefile> <echo> <maxgrade>  
              [sis01echo] [sis02echo] [sis03echo] [sis11echo] 
              [sis12echo] [sis13echo] [binsec] [sispi] [zerodef]
\end{verbatim}

\section{ fast } 
\smallskip
{\bf \hskip 5em Apply timing corrections to time column }
\medskip

ASCA fast mode data has no positional information, but the RAWY column
contains corrections to the time column.  The fast task applies these
timing corrections to the time column of the file.  The output is
written to the workspace, and can be used in further calls to
extract,\ldots 

To use fast, you need to have made an unbinned image in one of the
other detectors, or in the detector you are analysing if there is some
bright mode data available as well as the fast mode data.  Fast will
ask you for the X-position of the source, and for the instrument from
which you got this information.

Syntax:

\begin{verbatim}
xsel > fast <x_image_center> <from_instrument> [save_file]
\end{verbatim}

\section{ filter  } 
\smallskip
{\bf \hskip 5em Enter filters for extract command   }
\medskip

This is the command for entering filters to be passed to EXTRACT. Each
filter command builds on the list set up by the previous ones. For all
the filter commands, a file name proceeded by a - indicates that that
file should be removed from the list.

There are nine filter{\_}what values (besides quit), INTENSITY, TIME,
REGION and PHA\_CUTOFF, PHASE, DETECTOR, GRADE, MKF, and HK which will be
treated in their own subheadings.

Syntax:

\begin{verbatim}
xsel >  filter <filter_what>  
\end{verbatim}

\subsection{filter column}

This filter enables events to be extracted based on other attributes present
as columns in the event file. At present a series of ranges can be given
with the lower and upper limits separated by a column. For instance, suppose
an event file has a column PIXEL then a column filter "PIXEL=1:2 6:7" will
give events with PIXEL values of 1,2,6 or 7. More than one column can be
given eg "PIXEL=1:2 FLAGS=0:0". If the filter is given on the command line
then it should be enclosed in double quotes.

\subsection{filter detector}

This filter is only for the XTE PCA data. You can specify which PCUs,
layers, and anode sides you want by a series of three character strings. 
In each string the first character is the PCU (0-4), the second the
layer (1-3), and the third the anode side (L or R). If you use a *
for any character then xselect selects all the possibilities. So

\begin{verbatim}
xsel> filter detector "*1*"
\end{verbatim}

will pass layer 1 in all 5 PCU and both anode sides.

\subsection{filter grade}

This filter is for missions with CCD detectors whose events are assigned
a grade (or pattern). The grade can be specified as a single number
(eg 0), a range (eg 0:2 or 0-2), an upper limit (eg $<$ 4), or a lower limit (eg
$>$ 3). Specifications should be separated by commas (eg 0,2-6) and enclosed
in double quotes if given on the command line instead of when prompted.

\subsection{filter hk}

This is an alias for select hk.

\subsection{filter intensity}

After you have made a light curve, you can enter intensity selections,
given as a range of acceptable values.  The scale for intensity is
read from the plot given in PLOT CURVE.  The task converts this
intensity selection to a set of GTI's, which are passed to the next
EXTRACT run.

So

\begin{verbatim}
xsel > filter intensity .1-1.5
\end{verbatim}

will PASS only those bins with an intensity between .1 and 1.5.

\subsection{filter time}

This allows the entry of timing selections.  There are three entry
methods for timing filters, by the mouse cursor (FILTER TIME CURSOR),
from a file (FILTER TIME FILE), or by the keyboard (FILTER TIME UT,
SCC, MJD). 

FILTER TIME FILE supports three formats : ascii and fits GTI, and the
Xronos window format.  They can be used in any combinations, and the
GTI forms allow multiple files.  Xselect automatically senses the file
type, so there is no need to specify this.

FILTER TIME CURSOR requires that a light curve has been made.  You
will be provided with instructions when you give the command on how to
use the mode\ldots 

The other three commands (UT, SCC and MJD) are for entering the timing
filters from the keyboard.  The command names specify the timing
system : Universal Time, Modified Julian Days, or SpaceCraft Clock.
If a light curve has been made, then these commands will put up the
curve, and you will see your selections as you enter them. Start and
stop times must be separated by a comma. The UT should be given in
form yyyy-mm-ddThh:mm:ss.sss. These GTI's are then written to FITS
files, which can be saved for later use with the SAVE TIME KEYBOARD 
command.

These timing filters are not immediately applied to the data, but
rather stored for use in the next run of the extract command.

Some care must be taken in combining timing files.  The way it is done
is the following: The intervals within each file are ORed together,
then all the separate input files are ANDed together to make up the
resultant GTI file.

Consequently, if you wish to OR two ascii or fits GTI files, you have
to put them together into one file.  There is no requirement that they
be time ordered, so for ascii files this is as simple as cat'ing the
files.  For FITS files the fmerge task will do the trick, or if you
want to be fancier, the mgtime task.  Xselect does not do this for you
however.

To see that the extract comand has done what you expected, you can use
the show goodtime command after you run extract to see the resultant
GTI's.

Syntax:

\begin{verbatim}
xsel >  filter time file <file list>  
\end{verbatim}

Examples:

To enter two ascii files (ascii1.flt, and ascii2.flt), and two fits
files (fits1.flt and fits2.flt) you would say:

\begin{verbatim}
xsel >  filter time file "ascii1.flt ascii2.flt fits1.flt  fits2.flt"  
\end{verbatim}

To remove the file ascii1.flt, you can say  

\begin{verbatim}
xsel >  filter time file "-ascii1.flt"
\end{verbatim}

Though CLEAR TIME FILE is more straightforward.  

The list of files can be put in a file, say time.lis, one on a line, and 
entered via  

\begin{verbatim}
xsel >  filter time file "@time.lis"  
\end{verbatim}

The quotes are required (see the XPI magic subheading).  

\subsection{filter pha}

Currently you can only enter a pha lower and upper bound.  

Syntax:

\begin{verbatim}
xsel >  filter pha <phalcut> <phahcut> 
\end{verbatim}

Example: 

To restrict the extract command to 100 $<=$ PHA $<=$ 1000, say  

\begin{verbatim}
xsel >  filter pha 100 1000  
\end{verbatim}

\subsection{filter mkf}

This is an alias for select mkf.

\subsection{filter phase}

This allows you to enter one epoch-period combination, and up to ten
phases.  The subsequent extract command will use the union of all
these phases to filter the data.  If there is a phase file already
present, you are given the chance to save it before proceeding.

\begin{verbatim}
xsel > filter phase epoch period phase save_file
\end{verbatim}

The epoch is in MJD (in the same time system as the data), the period
in days, and the phase(s) run from 0-1.

So to filter using the epoch 40000, period of .5 days, and the first
and third quarters of the period, say

\begin{verbatim}
xsel > filter 40000 .5 "0.0-.25,0.5-0.75"
\end{verbatim}

The double quotes are necessary to protect the comma.

\subsection{filter region}

Syntax:

\begin{verbatim}
xsel >  filter region <region>  
\end{verbatim}

This allows you to enter SAOIMAGE format region descriptor
files. Multiple files are supported.  The region parameter takes a
list of files, which are added to the current list.  If a file
proceeded by a - in the list it is removed from the list.  So to enter
the regions reg1.flt, and reg2.flt, and remove the file reg.flt, give
the command

\begin{verbatim}
xsel >  filter region "reg1.flt reg2.flt -reg.flt"  
\end{verbatim}

Indirection with the @filename command is also allowed.  

A very important point to note about the region filters is that they
must either be in WCS or Physical coordinates. Regions created in
Image coordinates will not work correctly if image binning is not 1.

Some care must be taken in entering multiple regions, if you wish to
get the result you expect.  First off, note that the extractor takes
in only one region file, so Xselect cat's them all together before
passing them to extract.  Since the order of the regions is important,
you need to know that Xselect cats them in the order that they appear
in the input list, appending the second file to the first, and the
third to the end of these two, \ldots 

Each region specification is treated independently of the
others.  SAOimage has no syntax to specify AND/OR so each region
stands on it's own.  They are processed sequentially as the region
file is read in, with the current region possibly overriding the
previous selections.  If the first region is an excluded region then
the effect is to have an included region of the whole image inserted
before any other region is processed.

Now, since that summary wasn't very understandable, let's do some
examples with explanations.

Let's assume a 1000X1000 pixel image.   1 means the pixel is on, O 
means it is off.  

Case 1:  

An included box at 105,105 with a radius of 5,5.  So, all the pixels  


\medskip
\begin{verbatim}
        (110,100)
   1111111111
   1111111111
   1111111111
   1111111111
   1111111111
   1111111111
   1111111111
   1111111111
   1111111111
   1111111111
  (100,100)
\end{verbatim}
\medskip

Now, if the same box was an excluded region then the exact opposite would 
happen.  


\medskip
\begin{verbatim}
         (110,100)
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO
   OOOOOOOOOO       
  (100,100)
\end{verbatim}
\medskip


with all the other pixels on.  

An output from SISCLEAN is a collection of excluded points, so the image 
looks like\ldots   


\medskip
\begin{verbatim}
   1111111111111111111111111111111111111111111111111111111111111111111
   1111111111111111111111111111111111111111111111111111111111111111111
   1111111111111111111111111111111111111111111111111111111111111111111
   111111111111111111111111O111111111111111111111111111111111111111111
   11O1111111111111111111111111111111111111111111111111111111111111111
   11111111111O1111111111111111111111111111111111111111111111111111111
   1111111111111111111111111111111111111111111111111111111111111111111
   1111111111111111111111111111111111111111111111111111111111111111111
   1111111111111111111111111O11111111111111111111111111111111111111111
   111111111111111111111111111111111111111O111111111111111111111111111
   1111111111111111111111111111111111111111111111111111111111111111111
   1111111111111111111111111111111111111111O11111111111111111111111111
   11111111111111111111111111111111111111111O1111111111111111111111111
\end{verbatim}
\medskip


What happens when two regions overlap?  

Two boxes with corners overlapping.  If they are both included then\ldots   


\medskip
\begin{verbatim}
   0000000000000
   0111100000000
   0111111000000
   0111111000000
   0001111000000
   0001111000000
   0000000000000
\end{verbatim}
\medskip


The region file would look like  


\medskip
\begin{verbatim}
   BOX(   )
   BOX(   )
\end{verbatim}
\medskip


If they are both excluded then  


\medskip
\begin{verbatim}
    1111111111111
    1000011111111
    1000000111111
    1000000111111
    1110000111111
    1110000111111
    1111111111111
\end{verbatim}
\medskip


The region file would look like  


\medskip
\begin{verbatim}
   -BOX(  )
   -BOX(  )
\end{verbatim}
\medskip


Now, if one is excluded and one is included, how should it look?  

One way is  


\medskip
\begin{verbatim}
    0000000000000
    0111100000000
    0110000000000
    0110000000000
    0000000000000
    0000000000000
    0000000000000
\end{verbatim}
\medskip

This means that the first box is the included box, and then there is
an excluded box.  The region file looks like


\medskip
\begin{verbatim}
    BOX(  )
   -BOX(  )
\end{verbatim}
\medskip

The other way is  


\medskip
\begin{verbatim}
    1111111111111
    1000011111111
    1001111111111
    1001111111111
    1111111111111
    1111111111111
    1111111111111
\end{verbatim}
\medskip
This means that there is an excluded box, followed by an included
box. The region file looks like

\medskip
\begin{verbatim}
   -BOX( )
    BOX( )
\end{verbatim}
\medskip

So, the order is significant.  The overall way of looking at region
files is that if the first region is an excluded region then a dummy
included region of the whole detector is inserted in the front.  Then
each region specification as it is processed overrides any selections
inside of that region specified by previous regions.  Another way of
thinking about this is that if a previous excluded region is
completely inside of a subsequent included region the excluded region
is ignored.


\section{ gisclean } 
\smallskip
{\bf \hskip 5em Clean GIS data using RTI-PHA window }
\medskip

This task uses the RTI-PHA window contained in the calibration files
rti{\_}gis{\_}nnnnn.fits, from the CALDB (or ftools refdata area) to 
reject background events.  You can also enter your own copy of the
file with the parameter rti{\_}table{\_}user.  The filtered output is 
placed in the workspace, and will be used in further calls to extract,\ldots 

Some ASCA data has the parameter RISEBINS=0.  This data has no RISE
TIME information, and you cannot run GISCLEAN on it.  Xselect will
warn you that you have this kind of data.

Also note that MPC mode data has no rise time information.  So
GISCLEAN is not appropriate for it either.

\section{ help  } 
\smallskip
{\bf \hskip 5em Get help on Xselect commands   }
\medskip

Obtain help on the XSELECT commands, their syntax, and examples.  Help
uses the IHF interactive help facility.  The optional topic list can
be used to go directly to a particular topic and sub-topic. Once in
help, typing ?? will summarise extra features and special characters
that can be used within the IHF system.

To exit back to XSELECT, use an EOF, a /*, or type $<$CR$>$ until you leave 
the help facility.  

Syntax:

\begin{verbatim}
xsel >  help <topic list>  
\end{verbatim}

Examples:

\begin{verbatim}
xsel >  help help
\end{verbatim}

gives the text you are reading.  

\begin{verbatim}
xsel >  help "commands extract"
\end{verbatim}

gives the text for the extract command.

\section{ hkbin  } 
\smallskip
{\bf \hskip 5em Bin up HK parameters   }
\medskip

Bins a curve of selected parameters from an HK file.  If the files are
in unexpanded form, they will be expanded as well.

Syntax:

\begin{verbatim}
xsel >  hkbin <param> [<dtime>]  
\end{verbatim}

If an event lightcurve has been extracted (using extract curve) then
hkbin will bin up the selected parameters using the same binning as
the lightcurve and copy the event RATE column into the output file. In
this case the <dtime> argument is not required.

Example:

\begin{verbatim}
xsel >  hkbin "RBM_MON GASX" 120.0  
\end{verbatim}

This bins the relevant parameters  in 120-sec bins.  


\section{ (x)list  } 
\smallskip
{\bf \hskip 5em List the extant obscats, work and data directories   }
\medskip

Lists the obscats in the obscat directory, and in the data directory, if 
one has been set.  Or the files in these directories. In xseltcl and ixselect
the command name is xlist to avoid conflict with a native Tcl command.

Syntax:

\begin{verbatim}
xsel >  list <list_what>
\end{verbatim}


\subsection{list obscat}


Syntax:

\begin{verbatim}
xsel >  list obscat [brief] [all] [only_datadir]
\end{verbatim}

If brief is yes, a brief description of each obscat will be given.  

If all is yes, then all obscats in the obscat and data directories
will be listed.  Otherwise, only those from the currently set mission,
instrument (if set) and data directory (if set) will be listed.

If only{\_}datadir is yes, only the data directory obscats will be listed.

Example:

This will display a full listing of the ASCA SIS0 catalogues in the obscat 
directory:

\begin{verbatim}
xsel > set mission ASCA
\end{verbatim}
\begin{verbatim}
xsel:ASCA > set instrument sis0
\end{verbatim}
\begin{verbatim}
xsel:ASCA-SIS0 > list obscat brief=no all=no
\end{verbatim}

\subsection{list datadir}
Lists the files in the set data directory

\subsection{list workdir}
Lists the files in the current working directory


\section{ (x)load  } 
\smallskip
{\bf \hskip 5em Load an extant obscat   }
\medskip

Syntax:

\begin{verbatim}
xsel >  load <load_what> <cat_name> [brief] [all] [only_datadir]
\end{verbatim}

Loads an externally saved catalogue.  This catalogue is then used for
choose, select obs and show obscat. In xseltcl and ixselect
the command name is xload to avoid conflict with a native Tcl command.

The command load obscat, with no catalogue name argument, will display
a list of the catalogues in the obscat directory, and the data
directory if one is set.  The user can then choose from this list.
Xselect will be automatically set for the mission, instrument and data
directory of the loaded catalogue.

Otherwise the named obscat will be loaded.

The other parameters control the search for obscats, and the display.
They work the same as for list obscat.

Example:

This loads the catalogue her{\_}x1{\_}sis0.cat:

\begin{verbatim}
xsel > load obscat her_x1_sis0.cat
\end{verbatim}

\section{ make  } 
\smallskip
{\bf \hskip 5em Make an obscat   }
\medskip

Makes an observation catalogue for the current mission and instrument.
If no instrument is set, you will be prompted for one.
You can keep one catalogue per instrument per session prefix, and they
can be accessed by switching the instrument name.

The catalogue is composed of the values, from the primary header of each
specified file, of the keywords listed in the parameter obslist (or in
the file filename if obslist has the value @filename).  For ASCA the
obscat includes all the 'Modal' keywords present in the event files.

Make can also use a selection critereon on the keywords in obslist to
filter the catalogue as it is made.  This selection string is stored
in the parameter cat{\_}filt, and follows the same syntax as in the
select command.  If cat{\_}filt = DEF then the default expression is
used, which is, for the SIS,

EXPOSURE$>$100\&\&NEVENTS$>$0  

and for the GIS,  

EXPOSURE$>$100\&\&NEVENTS$>$0\&\&HV{\_}RED=='OFF'

If a datamode has been set, then the default filter will also include
the datamode.

This observation catalogue is not deleted on exit from XSELECT.  It is
the user's responsibility to remake the catalogue if the contents of
the data directory change.  This means that you do not have to remake
the catalogue every time you enter Xselect.  Further if it is present,
the choose and show obscat commands will act on the catalogue
specified by the session prefix, and instrument name.

The user option for the make{\_}inst allows the user to enter his/her own
list string with which the catalogue will be created.  The format is
the same as for the ls command in UNIX.

You do not have to be in the directory which contains the data. You
will be prompted for the directories containing the Event
data. Further, if you end the directory string with a ?, e.g.

\begin{verbatim}
xsel > make obs " /asca/data? "  
\end{verbatim}

then you will be shown an ls of this directory and prompted for the
data directory again.

The catalogue is automatically displayed once it is made.  However,
this feature can be toggled on and off with the command

\begin{verbatim}
xsel > set DUMPCAT  
\end{verbatim}

This is useful for scripts, since the prompt to page the catalogue is
an Ftool prompt, and so cannot be read from the script file.

Additionally, the catalogues can be viewed using show obscat.  Another
parameter, displist, lists the columns to be displayed in both cases.
Both these parameters understand the @filename syntax for indirection.

The point of making obslist and displist seperate parameters is that
it may be convenient to put more information in the catalogue than you
want to see listed.

Data files can be selected from the observation catalogue by number
using the choose command, as an alternative to using read and typing
in the filenames.

Further, the catalogue does not need to be remade from session to
session, but can be accessed straightaway using choose.

Syntax:

\begin{verbatim}
xsel >  make <make_what> <cat_filt> <data_dir> <make_inst>  
\end{verbatim}

Examples:

\begin{verbatim}
xsel >  make obs "/asca/data/100010"  
\end{verbatim}

\begin{verbatim}
xsel >  make obs "/asca/data/100010" sis0  
\end{verbatim}


\section{ mkfbin  } 
\smallskip
{\bf \hskip 5em Bin up auxillary filter files   }
\medskip

Bins a curve of selected parameters from an Mkfilter output file.  

\begin{verbatim}
xsel >  mkfbin <param> [<dtime>] [mkf_name]
\end{verbatim}

If no value of mkf{\_}name is given, then Xselect will look for the mkf
file using the standard regular expression for the mission in use. If
an event lightcurve has been extracted (using extract curve) then
mkfbin will bin up the selected parameters using the same binning as
the lightcurve and copy the event RATE column into the output file. In
this case the <dtime> argument is not required.

\begin{verbatim}
xsel >  mkfbin "RBM_MON GASX" 120.0  
\end{verbatim}

This bins the relevant parameters  in 120-sec bins.  


\section{ plot  } 
\smallskip
{\bf \hskip 5em Plot light curve, images, spectra,\ldots    }
\medskip

Plots spectra, light curves, images, HK and MKF parameters.  

\begin{verbatim}
xsel >  plot <plot_what>  
\end{verbatim}

Plot curve also allows the user to enter timing selections
graphically.  Plot image allows you to construct region files.


\subsection{plot curve}

This will put up a light curve. 

\subsection{plot HK}

Plots the HK parameters.  These parameters must first be binned with
the hkbin command.  You can plot any or all of these parameters.  By
specifying the hidden parameter curves{\_}per{\_}plot, you can change the
number of curves shown on each plot.  8 is the maximum, but is pretty
hard to read.  5 is quite legible.


\subsection{plot image}

Plots the accumulated image by spawning SAOImage.  You can also
construct SAOImage regions here. If you have reset the imagedisp
keyword (by pset xselect imagedisp=whatever) then whatever image
display program you specified is used.


\subsection{plot MKF}

Plots the MKF parameters.  These parameters must first be binned with
the mkfbin command.  You can plot any or all of these parameters.  By
specifying the hidden parameter curves{\_}per{\_}plot, you can change the
number of curves shown on each plot.  8 is the maximum, but is pretty
hard to read.  5 is quite legible.


\subsection{plot spectrum}

Plots a spectrum.  

\section{ quit  } 
\smallskip
{\bf \hskip 5em Quit Xselect session   }
\medskip

End the current XSELECT run and return to the UNIX operating system.  

Note that exiting will cause all the temporary files and filter
information to be lost if they haven't been explicitly SAVE-d.


\section{ (x)read  } 
\smallskip
{\bf \hskip 5em Enter datafiles by name   }
\medskip

Read in up to 999 datafiles. In xseltcl and ixselect
the command name is xread to avoid conflict with a native Tcl command.


\begin{verbatim}
xsel >  read <readmode> <infiles> <hkfiles> <expand>  
\end{verbatim}

\begin{verbatim}
xsel >  read e "file1 file2"
\end{verbatim}

\begin{verbatim}
xsel >  read hk hkfiles="file1hk file2hk" expand=no  
\end{verbatim}

The possible values of readmode are:  
\medskip
\begin{itemize}
\item
e - reads in the Event (science) files.

\item
hk - reads in the HK files.  The variable expand tells whether they
are in expanded form or not.

\item
d - reads in the Event and HK files.

\end{itemize}
\medskip

Two subsequent reads, with no clear in between, adds the new data
files to the list of files already entered.

You do not have to be in the directory which contains the data. You
will be prompted for the directories containing the Event and HK data.

Subsequent read commands add to the file list, unlike choose, where
the list is automatically cleared before each choose.

Read will attempt to get the mission, instrument and datamode from
the entered files.  It is an error to enter files with different
instruments, missions or datamodes.

It is often easier to respond to the prompts; see the example.  

Examples:

a)

\medskip
\begin{verbatim}
xsel >  read e 
> Enter the Event file dir >[.] 
> Enter Event file list >[] ft930317_1753.1614G30470M.fits  
\end{verbatim}
\medskip

b)

\medskip
\begin{verbatim}
xsel >  read hk  

> Give name[s] of FITS HK files >[] file1hk.fits file2hk.fits  
> Are the HK files in expanded form? >[] yes  
\end{verbatim}
\medskip

This reads in the hk files file1hk.fits and file2hk.fits, and informs
the program that they are in expanded form.

\section{ saoimage  } 
\smallskip
{\bf \hskip 5em Old name for plot image   }
\medskip

Start up SAOIMAGE, which will automatically read in the last image
file accumulated using the image command. Control returns to the
XSELECT program after saoimage is spawned.

\begin{verbatim}
xsel >  saoimage  
\end{verbatim}


\section{ save  } 
\smallskip
{\bf \hskip 5em Save product files\ldots    }
\medskip

Save a light curve, a spectrum, or a filtered list of the original
type.  Save session saves the current state of the session, and exits
Xselect.

\begin{verbatim}
xsel >  save <save_what> <outfile>  
\end{verbatim}

\subsection{save all}

Saves the cleaned events list ( or the filtered events list if none ),
and any of the IMAGE, CURVE, or SPECTRUM which have been made.  One
base name is given, say xsel{\_}save, then you get

\medskip
\begin{itemize}
\item
xsel{\_}save.evt -- the events list

\item
xsel{\_}save.lc  -- the light curve

\item
xsel{\_}save.pha -- the spectrum

\item
xsel{\_}save.img -- the image

\end{itemize}
\medskip

\subsection{save clean}

Saves the events list, and region file or hot pixel list from sisclean 
(q.v.).  


\subsection{save curve}

saves the lightcurve  

\subsection{save dfe}

Saves the Dark Frame Error history file made with FAINT.

\subsection{save events}

Saves the event list output by bin event.  You will also be prompted
whether you want to re-enter the event list.  If you answer yes, the
data and selections will be cleared, and the new output event list
entered into the filename list.  It is assumed for now that the output
event list has been placed in the current working directory.

\subsection{save expanded}

Saves an expanded HK file.  


\subsection{save faint}

saves the workspace files created by running faint.  

\subsection{save fast}

saves the workspace files created by running fast

\subsection{save goodtime}

Save the goodtime intervals produced by the most recent run of extract.  

\subsection{save hksel}

Saves the output GTI from running select hk.  


\subsection{save image}

Saves the image file.  You can also save the smoothed image, if one is
made, with the command

\begin{verbatim}
xsel > save image save_smooth=yes  
\end{verbatim}

\subsection{save intensity}

Saves the intensity selection GTI's from FILTER INTENSITY

\subsection{save mkf{\_}sel}

Saves the output GTI from running select mkf.  

\subsection{save obscat}

saves the current obscat with a user specified name

\subsection{save phase}

save the current phase information in a Xronos window format file

\subsection{save region}

saves the accumulated region file.  

\subsection{save selection}

saves the workspace files created by a select events, select chip,
or select expref commands.  

\subsection{save session}

Saves all the workspace files, and the current state of the program,
and exits xselect.  When you restart, you will be prompted as to
whether you want to restore the session.


\subsection{save spectrum}

Saves the spectrum file.  In addition, the output spectrum can be
grouped or rebinned on output.  The default is to rebin the spectrum.
This can be turned off by saying

\begin{verbatim}
xsel > save spec group=no
\end{verbatim}

Otherwise, the following will be done:
\medskip
\begin{verbatim}
MISSION  INSTRUMENT DATAMODE  ACTION
=======  ========== ========  ========================================
ASCA        GIS      PH       GRPPHA: GROUP channels 0-1023 by 4
            SIS      BRIGHT   RBNPHA: BRIGHT2LINEAR to 512
                              GRPPHA: Channels < EVTR flagged bad
            SIS      BRIGHT2  RBNPHA: LINEAR to 1024
                              GRPPHA: Channels < EVTR flagged bad
ROSAT      PSPC      NONE     GRPPHA: Bad 1-11, 212-256
                              GRPPHA: GROUP 12-211 by 10
\end{verbatim}

For some missions the response for the spectrum can also be calculated as 
part of the save process

\begin{verbatim}
xsel > save spec resp=yes
\end{verbatim}

will create rmfs and arfs as appropriate. If the mission calculates arfs
differently for point and extended sources then the latter option can be
performed by

\begin{verbatim}
xsel > save spec resp=extend
\end{verbatim}

Note that if the mission is Chandra or XMM-Newton then this feature will
run CIAO or SAS tasks, respectively.
\medskip

\subsection{save time}

SAVE TIME CURSOR will save the cursor timing file mades with FILTER
TIME CURSOR, and SAVE TIME KEYBOARD will save the GTI files made with
FILTER TIME UT, SCC, or MJD.

\subsection{save workspace}

Saves the workspace files, whatever their origin.  

\section{ select  } 
\smallskip
{\bf \hskip 5em Select data using event, hk or filter files   }
\medskip

Select the event lists, the HK files, the MKF files or the obscat on
the basis of any available criteria based on the columns in the FITS
file that can be encoded into a Boolean expression.

\begin{verbatim}
xsel >  select <select_what> <expression> [mkf_name]   
\end{verbatim}

The following guidelines on how to construct the $<$expression$>$ are
taken directly from the help file for the FSELECT FTOOL:

This task creates a new table from a subset of rows in an input table.
The rows are selected on the basis of a boolean expression whose
variables are table column names.  The column names are not case
sensitive, but the values are.  If, after substituting the values
associated with a particular row into the column name variables, the
expression evaluates to true, that row is included in the output
table.  

For more details on the syntax for the Boolean expressions, see the
help page for fselect, (i.e. from within Xselect type

\begin{verbatim}
xsel > $fhelp fselect
\end{verbatim}

\subsection{select chip}

Selects events based on chip ID (Chandra and XMM specific).

Syntax:
\begin{verbatim}
xsel> select chip <chipspec>
\end{verbatim}

where chipspec is a string of chip specifiers either as single
digit numbers (0--9) or as two character names (I0,I1,...). This
command extracts events for the relevant chip(s) into a new file
and appends the appropriate GTI. If only one chip is selected the
GTI for the chip is copied, if not the relevant GTIs are merged.
Chip specifiers should be separated by a space or a comma. This
command also finds the minimum and maximum sky coordinates for
the chip and sets the XYCENTER/XYSIZE appropriately.

Examples:
\begin{verbatim}
xsel> select chip "s0 s1 s2 s3"
\end{verbatim}

\subsection{select event}

Select data from the event lists. 

Syntax:

\begin{verbatim}
xsel > select event <event_sel>
\end{verbatim}

Examples:

To select data from within a circular region centered on
(X,Y)=(125,125) with a radius of 10.0..

\begin{verbatim}
xsel >  select event "Sqrt((X-125)\^2 + (Y-125)\^2) < 10.0"  
\end{verbatim}

Note that for region selection and timing selection, it is quicker to
pass the criteria as filters to the extract command.

\subsection{select expref}

Selects events based on exposure ID (Swift UVOT specific).

Syntax:
\begin{verbatim}
xsel> select expref <exprefsel>
\end{verbatim}

where exprefsel is a string of exposure specifiers given as
numbers (1-99). This command extracts events for the exposure(s) 
into a new file and appends the appropriate GTI. If only one 
exposure is selected the GTI for the exposure is copied, if not 
the relevant GTIs are merged. Exposure specifiers should be 
separated by a space or a comma. This command also finds the 
minimum and maximum sky coordinates for the window used in the
exposure sets the XYCENTER/XYSIZE appropriately.

Examples:
\begin{verbatim}
xsel> select expref 4
\end{verbatim}

\subsection{select fast}

Selects either the region INSIDE or OUTSIDE the mask region in ASCA
SIS fast mode data.  This is only available for fast mode data that
has had the area mask disabled, i.e., Sn{\_}ARENA=0.

Syntax:

\begin{verbatim}
xsel > select fast <in_or_out>
\end{verbatim}

\subsection{select HK}

Create a GTI file from criteria applied to data in the HK files.  This
file is automatically applied to the next running of extract.  It can
be saved with save hksel.

Syntax:

\begin{verbatim}
xsel > select hk  <hk_sel> 
\end{verbatim}

\subsection{select MKF}

Create a GTI file from criteria applied to data in the MKF file.  The
MKF file is found by searching the filter file directory using the
mission default filename expression. Alternately, you can specify the 
mkf file name, and directory in the parameters mkf{\_}name and
mkf{\_}dir. mkf{\_}name must be a literal file name, not a regular 
expression.

The GTI file created is automatically applied to the next running of 
extract. It can be saved with save mkf{\_}sel.

More than one file is allowed.  

Syntax:

\begin{verbatim}
xsel > select mkf  <mkf_sel> [mkf_dir] [mkf_name]
\end{verbatim}

Example: 

\begin{verbatim}
xsel > select mkf "SAA.eq.0"
\end{verbatim}

This makes a GTI for all times when the SAA parameter is set to zero.

\begin{verbatim}
xsel >  select mkf "ELV_MIN.gt.10." mkf_name=mkffile.mine  mkf_dir=./
\end{verbatim}

This makes a GTI from the mkf file mkffile.mine in the current directory.


\subsection{select obscat}

Syntax:

This creates a reduced catalogue, based on a selection expression.
The original catalogue is moved to a new name. If the original
catalogue was xsel{\_}s1.cat, then it will be moved to xsel{\_}s1{\_}v.cat.
The new obscat will have the name xsel{\_}s1.cat, and will be
automatically loaded for you.  So choose and show obscat will now act
on this catalogue.  N.B. this command does not read in any data, it
only produces a reduced catalogue. You will now have to choose data
from it.

\begin{verbatim}
xsel > select obscat <cat_sel>
\end{verbatim}

Example:

\begin{verbatim}
xsel > select obscat "datamode=='BRIGHT'"
\end{verbatim}

This makes a reduced obscat containing only files for which the datamode 
is BRIGHT.

\section{ set  } 
\smallskip
{\bf \hskip 5em Set Xselect parameters   }
\medskip

Sets various default parameters. In xseltcl and ixselect
the command name is xset to avoid conflict with a native Tcl command.


Syntax:

\begin{verbatim}
xsel >  set <set_what>
\end{verbatim}


\subsection{set binsize}

Sets the time binsize.

Syntax:

\begin{verbatim}
xsel >  set binsize <binsize>
\end{verbatim}


\subsection{set datadir}

Sets the data directory.  

Syntax:

\begin{verbatim}
xsel >  set datadir <datadir>
\end{verbatim}

Examples:

\begin{verbatim}
xsel > set datadir ../../data/20019000
\end{verbatim}

Sets the datadirectory to ../../data/20019000

If you put a '?' at the end of the directory path, Xselect will do an
ls on the directory, and prompt you for the directory again:

\medskip
\begin{verbatim}
xsel > set datadir ../../data?
20019000  40001000 
which data directory [../../data?] ../../data/20019000
xsel >
\end{verbatim}
\medskip

\subsection{set datamode}

This sets the datamode.  This has several effects.  Some datamodes
need special settings, (e.g. ASCA SIS fast, or ASCA GIS MPC mode),
which are not set by set instrument.  If a datamode is set, make
obscat will filter on datamode.  The datamode controls the grouping of
spectra in the save spectrum command.  Also, Xselect can do the
appropriate preliminary analysis if the datamode is correctly set.
For instance, if you read in FAINT mode data, the EXTRACT command will
now run FAINT first, if you have not done so already\ldots 

This being said, except for filtering the obscat, it is not necessary
to set the datamode yourself, since Xselect will set it when you READ
or CHOOSE data files.

\subsection{set device}

Sets the plotting device from among the PGPLOT devices available.
(set device ? produces a list).

Syntax:

\begin{verbatim}
xsel >  set device <plotdev>
\end{verbatim}


\subsection{set dumpcat}

Toggles on and off the display of the catalogue in the show obscat
command. This is useful in scripts.


\subsection{set image}

Sets the image coordinates to SKY, DETECTOR, or RAW coordinates.  
This is a mission-independent version of the set xyname command.

Example:

\begin{verbatim}
xsel> set image sky  
\end{verbatim}

is equivalent to 

\begin{verbatim}
xsel > set xyname X Y
\end{verbatim}

if the sky coordinates are called X and Y. Definitions of SKY,
DETECTOR, and RAW coordinates are stored in the mission database file
for each supported mission.

\subsection{set instrument}

Sets the instrument used in constructing and accessing the observation 
catalogue  

Syntax:

\begin{verbatim}
xsel >  set instrument <set_instru>  
\end{verbatim}

Example:

\begin{verbatim}
xsel > set inst sis0
\end{verbatim}

This sets the instrument to sis0.  If you have forgotten the names of
the available instruments, just say set instruments without an
argument:

\medskip
\begin{verbatim}
xsel > set instru
The available instruments are:
     SIS0
     SIS1
     GIS2
     GIS3

which instru? []
\end{verbatim}
\medskip

\subsection{set mission}

To change between missions. Currently supported missions are ASCA 
(the default), ASTRO-E, Chandra, BBXRT, EINSTEIN, EXOSAT, ROSAT, SAX, 
XMM, and SPECTRUM-RG. Xselect will automatically set the appropriate
mission when reading in an event file.

\subsection{set mkfdir}

This sets the directory in which Xselect will look for the MKF files.

There is one convenience that Xselect offers that may be confusing if
you are not aware of it\ldots   When the data directory is set, if no MKF
directory has been set, Xselect will look in the data directory for
files matching the mkf default expression, and if it finds them, it
will set the mkfdir to the data directory.  If there are no MKF files
in that directory, then Xselect will look in the directory
datadir/../aux (this is the shipped value of the parameter
mkf{\_}reldir).  If it finds mkf files in that directory, it will set
mkfdir to that.  Otherwise mkfdir will not be set.

However, this only happens if mkfdir has not previously been set.
This search will not override a value set either with the SET MKFDIR
command, or through a previous application of this search.

\subsection{set pagewidth}

Sets the pagewidth for show obs.  

\subsection{set pharebin}

Sets the pharebinning factor.  

\subsection{set phaname}

Sets the column name for the energy values.  

\subsection{set wmapname}

Sets the coordinate used for the weighted map in the primary extension
of the spectral file. If the column names are not in the mission
database file then the user will be prompted for the size keywords for 
both axes. If the TLMAX keyword is included for the specified column 
then the user should enter the string TLMAX. If this keyword is not 
available then another should be given. This keyword will be used to 
set the size of the output image.

\subsection{set xybinsize}

Sets the rebinning factor for the image. The boolean parameter rebinregion
determines whether xselect will attempt to adjust any region files to the
new binning. ds9 region files in sky coordinates do not need to be rebinned
but saoimage or saotng files do.

\subsection{set xycenter}

Sets the center of the image. Takes as argument two numbers in image 
coordinates. Requires 'set xysize' be used to define the size of the
image to be extracted.

\subsection{set xyname}

Sets the column names used for accumulating the image in the extract 
command. If the column names are not in the mission database file then
the user will be prompted for the size keywords for both axes. If the
TLMAX keyword is included for the specified column then the user
should enter the string TLMAX. If this keyword is not available then
another should be given. This keyword will be used to set the size of
the output image.

\subsection{set xysize}

Sets the size of the image in image coordinates. If xybinsize has been
set then the output image dimensions will be xysize divided by xybinsize.

\section{ show  } 
\smallskip
{\bf \hskip 5em Display Xselect settings   }
\medskip

Show current settings or values for data, parameters, selections or 
general status.  

\begin{verbatim}
xsel >  show <show_what>  
\end{verbatim}


\subsection{show data}

Which data files are we currently working on?  If chosen from the
catalogue, the place in the catalogue is listed in the INDEX column.


\subsection{show diff}

Syntax:

\begin{verbatim}
xsel show diff <compare> [copyover]
\end{verbatim}

Displays the obscat in diff form (see fhelp fcatdiff).  The parameter
compare gives the columns in the obscat to compare, and the copyover
parameter gives the columns to copy over to the diff display.

Example:

\begin{verbatim}
xsel > show diff compare="RAWXBINS TIMEBINS RISE{\_}BINS"
\end{verbatim}

\subsection{show event}

Displays the event extension of a data file.  This can be referenced
either by its number in the observation catalogue (show{\_}from = o), or
by its place in the list of read-in data files (show{\_}from = d).  Use
show data to determine the latter. The number is given in the
parameter show{\_}which.  This parameter currently accepts only one
entry, and not a range of values.

The show{\_}rows parameter controls which of the rows you wish to see.
The show{\_}method determines whether the data is displayed by column
(show{\_}method =dump), or by record (show{\_}method=list).

Syntax:

\begin{verbatim}
xsel > show event <show_from> <show_which> [show_rows] [show_method]
\end{verbatim}

Example:

So to show rows 1-50 of the 5th file from the current obscat, say

\begin{verbatim}
xsel > show event obscat 5 show{\_}rows=1-50
\end{verbatim}

\subsection{show filters}

Displays a list of the filters and selections currently loaded.  


\subsection{show goodtime}

Prints to the screen the resultant timing selections from the previous
running of extract.

\subsection{show GTI}

Displays the GTI extension from the data files.  Same parameters as
show events.

\subsection{show MKF}

Displays the first extension of the current MKF file.  The row and
method options are the same as for show event.

Syntax:

\begin{verbatim}
xsel > show MKF <show_from> <show_which> [show_rows] [show_method]
\end{verbatim}

\subsection{show obscat}

Display the observation catalogue. The columns displayed are given in
the parameter displist, and can be listed, one to a line, in the file
filename if displist = @filename.  If displist is blank, the display
list defaults to:

\medskip
\begin{verbatim}
INSTRUME
OBJECT 
DATAMODE 
BIT_RATE 
DATE-OBS 
TIME-OBS 
NEVENTS 
EXPOSURE   
\end{verbatim}
\medskip

The show{\_}rows and show{\_}method parameters work as for show event.

\subsection{show parameters}

Lists the columns in the current event, mkf or obscat FITS file.  Useful for
determining the arguments to use for the SELECT command.  

Syntax:

\begin{verbatim}
xsel > show obscat [show_rows] [show_method]
\end{verbatim}

\subsection{show primary}

Displays the primary header of the events files.  Files can be chosen
either from the obscat or from the currently entered data.

Syntax:

\begin{verbatim}
xsel > show primary <show_from> <show_which>
\end{verbatim}


\subsection{show select}

Show Boolean statement describing most recent selections.  


\subsection{show status}

A thumbnail sketch of the status of Xselect, includes the information
from show filter, as well as data information and default settings.


\section{ sisclean  } 
\smallskip
{\bf \hskip 5em Remove hot pixels from ASCA SIS data   }
\medskip

Runs one of two methods to clean the image of hot and flickering
pixels.  Specify the method with the clean{\_}method parameter.

Method 1) This removes pixels by a straight cutoff, all pixels with
more than n photons per pixel will be eliminated.  First, an image is
accumulated.  Then, to aid the eye, a Gendreau plot is displayed. If
saoimage is yes, then the uncleaned image is displayed as well. Then a
filtered events list is produced.  This will be used in further
processing, and can be saved by the save clean command.

Method 2) This method uses a Poissonian distribution to reject hot
and flickering pixels.  For more details, see the help file for
cleansis (e.g. give the command fhelp cleansis).  First a filtered
event list is produced, then this is fed to cleansis, a final event
list is produced, which has had all the hot pixels removed.  Also a
list of the hot pixels is written out.  The cleaned file and the hot
pixel list can be saved with the save clean command.  The uncleaned
events file can be saved with the save event command.  

\section{ sispi } 
\smallskip
{\bf \hskip 5em Fill PI column for ASCA SIS data }
\medskip

This uses the FTool sispi to fill the PI column for ASCA SIS data.  See the
fhelp page for more details.

Syntax:

\begin{verbatim}
xsel > sispi [pha2pi]
\end{verbatim}

The parameter pha2pi gives the calibration file.  The value AUTO (the
default) will find the appropriate file in the calibration database
and if that is not set up then it will look in the refdata area.

\section{ smooth } 
\smallskip
{\bf \hskip 5em Smooth the images }
\medskip

Currently, GAUSSIAN, BOXCAR and LORENTZIAN smoothings are permitted.
The original image is preserved, and a new, smoothed image is written.
Future calls to PLOT IMAGE will view the smoothed image (unless you
CLEAR SMOOTH).  Future calls to smooth, however, will smooth the
original image again, and overwrite the previous smoothed image.

The output image will preserve the data type of the original image,
unless you set the parameter smooth{\_}outtype.

Syntax:

\begin{verbatim}
xsel > smooth <smooth_method> [smooth_outtype]
\end{verbatim}

\subsection{smooth gaussian}

You give the sigma, and optionally the nsigma for the gaussian.  For
more details, see the fgauss ftools help page.

\begin{verbatim}
xsel > smooth gauss 1.5 nsigma = 2
\end{verbatim}

\subsection{smooth lorentzian}

You give the sigma, and optionally the nsigma for the lorentzian.  For
more information, see the florentz ftools help page.

\begin{verbatim}
xsel > smooth lorentz 1.5 nsigma = 2
\end{verbatim}

\subsection{smooth boxcar}

Give the x and y sizes for the boxcar.  For more information, see the
fboxcar ftools help page.

\begin{verbatim}
xsel > smooth boxcar 3 3
\end{verbatim}


\section{ stop  } 
\smallskip
{\bf \hskip 5em Exit Xselect   }
\medskip

End the current XSELECT run and return to the UNIX operating system.  

Syntax:

\begin{verbatim}
xsel > stop <save_session> 
\end{verbatim}

Examples:   

\begin{verbatim}
xsel >  stop  save_session=no  
\end{verbatim}

exits the program, without saving the session. quit and exit do the same 
thing.  

Note that exiting will cause all the temporary files and filter
information to be lost if they haven't been explicitly SAVE-d.

\appendix

\chapter { The Mission Database File }

Starting with \Xselect\ v2.0 much of the mission-dependence has been
incorporated into a simple ascii file called \verb+xselect.mdb+. The
default location for this file as distributed with the \verb+HEASOFT+
software is \verb+$HEADAS/../ftools/xselect/common/xselect.mdb+, i.e.
%
\begin{verbatim}
>ls $HEADAS/../ftools/xselect/common/xselect.mdb
/software/heasoft/headas/setup/../ftools/xselect/common/xselect.mdb
\end{verbatim}
%
where \verb+$HEADAS+ is the environment variable which points to your HEASOFT software installation (as described in \href{http://heasarc.gsfc.nasa.gov/docs/software/lheasoft/install.html}{the HEASOFT installation instructions}).

%The keyword dictionary is given below. 

\clearpage

\subsubsection{Required MDB Keywords}

The following keywords must be present for each mission entry in the \verb+xselect.mdb+ file.  However these keywords may not be relevant for certain missions.  In such cases  the value of these keywords should be \verb+NONE+.
\begin{center}
\begin{longtable}{l|p{3in}|l|l}

%\hline 
%\multicolumn{1}{l}{\textbf{Entry}} & 
%\multicolumn{1}{l}{\textbf{Description}} & 
%\multicolumn{1}{l}{\textbf{Type}} & 
%\multicolumn{1}{l}{\textbf{Sample Values}}\\ 
%\hline 
%\endfirsthead

\hline 
\multicolumn{1}{l}{\textbf{Entry}} & 
\multicolumn{1}{l}{\textbf{Description}} & 
\multicolumn{1}{l}{\textbf{Type}} & 
\multicolumn{1}{l}{\textbf{Sample Values}}\\ 
\hline 
\endhead

\hline \hline
\verb+submkey+        &    The keyword read from the file to get the SubMission & String     &  \verb+GRATING+; \verb+NONE+\\ \hline
\verb+instkey+         &     The keyword read from the file to get the Instrument & String      & \verb+INSTRUME+; \verb+NONE+   \\ \hline 
\verb+dmodekey+        &     The keyword read from the file to get the Datamode & String        &  \verb+DATAMODE+; \verb+NONE+   \\ \hline 
\verb+ccol+            &      The column for CCD number (if needed - NONE if not)&  String       &   \verb+PIXEL+; \verb+NONE+   \\ \hline
\end{longtable}
\end{center}

\clearpage

\subsubsection{Optional MDB Keywords}

The following keywords are optional, and should only be used if they are relevant for a given mission. 

\begin{center}
\begin{longtable}{l|p{2.5in}|l|l}

%\hline 
%\multicolumn{1}{l}{\textbf{Entry}} & 
%\multicolumn{1}{l}{\textbf{Description}} & 
%\multicolumn{1}{l}{\textbf{Type}} & 
%\multicolumn{1}{l}{\textbf{Sample Values}}\\ 
%\hline 
%\endfirsthead

\hline 
\multicolumn{1}{l}{\textbf{Entry}} & 
\multicolumn{1}{l}{\textbf{Description}} & 
\multicolumn{1}{l}{\textbf{Type}} & 
\multicolumn{1}{l}{\textbf{Sample Values}}\\ 
\hline 
\endhead

\hline \hline
\verb+modes+           &        A list of the datamodes                            &  String    &   \verb+PHOTON+   \\ \hline
\verb+mkf_def_expr+    &      The global expression for filenames of MKF files     &  String    &   \verb+ae*mkf*+   \\ \hline
\verb+time+            &  The column in the events extension used for time         &  String    &   \verb+TIME+   \\ \hline
\verb+tunits+         &  The units for the time column                             &  String  &   \verb+s+   \\ \hline
\verb+binsize+        &  The default time bin size for light curves                &  Numeric  &   \verb+1.157e-5+; \verb+16+   \\ \hline
\verb+x+              &      The column for sky X-axis                             &  String      &   \verb+X+   \\ \hline
\verb+y+              &      The column for sky Y-axis                             &  String      &   \verb+Y+   \\ \hline
\verb+xsiz+           &      The keyword giving the max. value of X                &  String      &   \verb+TLMAX+   \\ \hline
\verb+ysiz+            &      The keyword giving the max. value of Y               &  String       &   \verb+TLMAX+   \\ \hline
\verb+detx+            &      The column for detector X-axis                       &  String       &   \verb+DETX+   \\ \hline
\verb+dety+            &      The column for detector Y-axis                       &  String       &   \verb+DETY+   \\ \hline
\verb+detxsiz+         &      The keyword giving the max. value of DETX            &  String       &   \verb+TLMAX+   \\ \hline
\verb+detysiz+         &      The keyword giving the max. value of DETY            &  String       &   \verb+TLMAX+   \\ \hline
\verb+rawx+            &      The column for raw X-axis                            &  String       &   \verb+RAWX+   \\ \hline
\verb+rawy+            &      The column for raw Y-axis                            &  String       &   \verb+RAWY+   \\ \hline
\verb+rawxsiz+         &      The keyword giving the max. value of RAWX            &  String       &   \verb+TLMAX+   \\ \hline
\verb+rawysiz+         &      The keyword giving the max. value of RAWY            &  String       &   \verb+TLMAX+   \\ \hline
\verb+phamax+         &      The keyword giving the max. value of ECOL             &  String      &   \verb+TLMAX+   \\ \hline
\verb+gti+            &      The name of the extension (\verb+EXTNAME+) with GTI table              &  String      &   \verb+STDGTI+   \\ \hline
\verb+events+         &      The name of the extension (\verb+EXTNAME+) with event data  &  String  &   \verb+EVENTS+   \\ \hline
\verb+timeorde+       &      Yes if the events are in time order                   &  String      &   \verb+yes+   \\ \hline
\verb+instruments+    &      A space-delimited list of the instruments             &  String   &   \verb+EMOS1 EMOS2 EPN RGS1 RGS2+   \\ \hline
\verb+spbn+            &      The binning factor for spectra                       &  Numeric       &   \verb+1+   \\ \hline
\verb+ecol+            &      The column for spectral information                  &  String       &   \verb+PI+   \\ \hline
\verb+gcol+            &      The column for event grade/pattern                   &  String       &   \verb++   \\ \hline
\verb+imagecoord+     &      The default coordinate system for images              &  String      &   \verb+SKY+   \\ \hline
\verb+wmapcoord+      &      The default coordinate system for WMAPs               &  String      &   \verb+DETECTOR+   \\ \hline
\verb+catnum+         &      The extension number for catalog keywords             &  String      &   \verb+1+   \\ \hline
\verb+wtmapb +        &      Yes if a WMAP is to be produced                       &  String      &   \verb+no+   \\ \hline
\verb+wtmapfix+       &      Yes if WMAP pixels outside selected region set to -1  &  String      &   \verb+yes+   \\ \hline
\verb+swmapx+          &      True if WMAP X axis is inverted from sky             &  String       &   \verb+yes+   \\ \hline
\verb+swmapy+          &      True if WMAP Y axis is inverted from sky             &  String       &   \verb+no+   \\ \hline
\verb+lststr+          &      The global expression for event files                &  String       &   \verb+ad*s0*[hml].*+   \\ \hline
\verb+ofilt+           &      The default MKF filtering for valid files            &  String       &   \verb+ONTIME>100&&NEVENTS>0+   \\ \hline
\verb+fbin+           &      The default binning for images                        &  String      &   \verb+4+   \\ \hline
\verb+hbin+           &      The default binning for WMAPs                         &  String      &   \verb+8+   \\ \hline
\verb+modes+          &      A list of the datamodes                               &  String      &   \verb+FAINT BRIGHT+   \\ \hline
\verb+rbnval+         &      Number of channels to which spectra are binned        &  String      &   \verb+512+   \\ \hline
\verb+rbnmod+         &      Compression mode for spectral rebinning               &  String      &   \verb+LINEAR+   \\ \hline
\verb+catcol+         &      A space-delimited list of keywords used to catalog events file &  String  &   \verb+OBJECT DATAMODE DATE-OBS+   \\ \hline
\verb+dispcol+        &      A space-delimited list of keywords used to display the catalog &  String      &   \verb+OBJECT DATAMODE BIT_RATE+   \\ \hline
\verb+extract+        &      The ftool used to extract images, spectra, and light curves. Supported options are extractor and saextrct.      & String &  \verb+extractor+; \verb+saextrct+   \\ \hline
\verb+respscript+      &      The name of the script run to generate the spectral responses. & String &\verb+xsl_asca_sis_makeresp+   \\ \hline                                                \verb+extendresp+      &      If set to yes the spectral response generation has an  extended source option. & String  & \verb+yes+   \\ \hline
\end{longtable}
\end{center}

\subsection{Adding New Missions}
New missions can be added to the mission database file; probably the
best approach when adding a new mission is to copy the entries for the
most similar one currently supported and edit as appropriate.  If a
new mission requires particular \ftools\ which are different from the
standard used by \Xselect, then some changes in the \Xselect\ source
code will be necessary. Users are encouraged to copy the standard
\verb+xselect.mdb+ and to make any changes to the copy.  To use the
modified version of the \verb+xselect.mdb+ users should define an
environment variable \verb+XSELECT_MDB+ and set its value to the new
mission database filename.  For example for C-shell (\verb+csh+)
users:
\begin{verbatim}
setenv XSELECT_MDB /path/to/your/personal/xselect.mdb
\end{verbatim}

\chapter { XPI } 

This is the command line interface used in Xselect.  It has some
useful features for listing the available commands, their parameters,
and the current defaults.  It also has scripting and alias facilities.
It is not case sensitive, and does command completion for both command
names and parameter names, so you need enter only the shortest unique
string for any command.

The UNIX version also inherits the nice command line editing features
of the READLINE library, which has an EMACS like syntax for command
line searches, and supports up and down arrow history recall, and
filename completion using the tab key.

It has some magic characters, which are captured in the parser, and so
they must be surrounded by double quotes to get past XPI.

In most cases, XPI is fairly forgiving, so you do not need too
detailed a knowledge of it.  For all practical purposes, you only need
to know what the magic characters are (see magic), and the general
syntax of the command line.  

\section{ Syntax } 

The commands in Xselect consist of a command name, and a group of
parameters.  The parameters have two seperate qualifiers, they can be
queried or hidden, and learned or fixed.  

The queried parameters will be prompted for if not entered on the
command line, and can be entered (provided the correct order is
maintained) without their command name.  The hidden parameters must be
entered in the form name=value and will not be prompted for.  Rather a
default is provided in the Xselect par file.

The learned parameters will have their defaults set by the last
entered value, whereas the fixed parameters will revert to their
original defaults when no value is specified for them.

The nature of any given parameter can be determined by the LPARM command.

The par file contains all the Xselect parameters, and their defaults.
It will maintain the state of Xselect between invocations.  There is a
master copy of it that is kept with the Xselect executable, and this
is copied into the users home directory the first time Xselect is
used.  This local copy is the one that will be used afterwards.  If
you want to reset the parameters in Xselect to the shipped state, just
remove the par file from your home directory, and you will recieve a
fresh copy the next time you start Xselect.

The convention for giving the syntax of commands that is used in
this document is as follows:

\begin{verbatim}
xsel >  comm <par1name> <par2name> [par3name] [par4name]  
\end{verbatim}

Here, comm is the command, and parXname is the name of the parameter.
The parameters in arrow-brackets $<$$>$ will be prompted for if not given
on the command line. The parameters in [] are hidden.  Thus, in the
above example, entering comm to the XSELECT prompt will result in the
following:

\medskip
\begin{verbatim}
xsel >  comm         
> Value of par1name? >[default1]       
> Value of par2name? >[default2] 
xsel >
\end{verbatim}
\medskip

where the prompting messages are, of course, tailored to the situation
and the user has to either enter the parameters when asked or type
$<$CR$>$ to get the defaults.  To change the hidden parameters, the user
must type

\begin{verbatim}
xsel > comm par3name=value3 par4name=value4
\end{verbatim}

Order does not matter for hidden parameters.

All commands and parameter names can be abbreviated to the shortest
unique string, and are not case sensitive.  The same is true for the
values of the verb{\_}what parameters.  I.e. the following all produce
the same result:

\begin{verbatim}
xsel >  show obscat  
\end{verbatim}

\begin{verbatim}
xsel >  show obs  
\end{verbatim}

\begin{verbatim}
xsel >  sh OBS ...  
\end{verbatim}

\section{ Special Characters } 

XPI recognizes the following special characters:  

\medskip
\begin{verbatim}
! - indicates the rest of the line is a comment
@ - starts reading commands from a command file
$ - spawn to the system
" - protects other special characters
= - seperate parameter-value pairs
\end{verbatim}
\medskip

As a result, you should observe the following rules when entering
expressions on the command line.

\medskip
\begin{itemize}

\item
An argument with imbedded spaces must be delimited by double quotes.  

\item
An argument containing an @ or a ! must be surrounded by double quotes.  

\item
= signs are trapped by XPI, so use .eq. in selection expressions, or
surround your expressions with double quotes.  In fact, to be safe it
is always best to do this anyway.

\end{itemize}
\medskip


\section{ comments } 


All text between a ! character and the end of line is treated as a
comment.  Comments are most useful when entered into a script.  Since
there is no difference between reading from the terminal or reading
from a script, comments can also be entered interactively.

There are two types of comments.  If the first character in the line
is !  then the entire line is ignored and the next line is read. If !
is in the input line, but is not the first character, the ! and all
following characters are removed.  Thus if the software requires that
you enter a blank line (i.e., default) and you wish to include a
comment, then you must include one or more spaces before the !.

Examples:  

\medskip
\begin{verbatim}
xsel >  show       ! This is a comment  
xsel >  ! this line is completely ignored  
xsel >   ! this causes the program to read a blank line  
\end{verbatim}
\medskip

\section{ XPI commands } 

Some of the commands in Xselect are really a function of the command
line interpreter, XPI, and so are common with other HEASARC software
like XSPEC and XIMAGE.  These are generally commands that give
information about the parameters used by Xselect, or do logging of
sessions, history recall, etc.

Perhaps the most useful command of the lot is the LPARM command.
LPARM Lists the PARameters that a given Xselect command will take,
gives a short description of the parameter, and shows its current
value.

XPI on UNIX systems uses the GNU READLINE library.  This supports full
command line editing (including EMACS style commands, e.g. \^ A for
beginning of line \^ E for end of line, and \^ S for incremental search).
The up and down arrow keys function for command recall.  It does not
support the full history mechanism in the READLINE library however, so
!! will not recall the previous command, for example.  However, XPI
also has a built in command recall that supports a similar syntax.

The following are the XPI commands:  

\medskip
\begin{itemize}

\item
recall  - Recall and replay previous commands
\item
alias   - Alias complex commands to one word abbreviations
\item
script  - Open and close script files
\item
log     - Open and close log files
\item
lparm   - lists the parameters for a given command
\item
?       - lists command groupings
\item
??      - lists the commands available
\item
debug   - enter debug mode, watch how the command line is parsed
\item
dumpkey - dumps the current copy of the key table
\item
dumppar - dumps the current (in memory) copy of the par file

\end{itemize}
\medskip

The last three of these are really only for debugging  

Along similar lines, but actually a part of Xselect, is that for most
commands with known range of choices (set device, set instrument, and
all the commands of the verb verb{\_}what form), if you wait to be
prompted (by hitting a return after the command name), you will be
given a list of possible responses, and then prompted for your choice, e.g.:

\medskip
\begin{verbatim}
xsel >  extract<ret>  

ALL             -->	extract a spectrum, image and light curve
CURVE           --> 	extract a light curve
EVENTS          --> 	output the filtered event list
IMAGE           --> 	extract an image
SPECTRUM        --> 	extract a spectrum
QUIT            --> 	quit extract

> Give parameter to be binned >[all]   
\end{verbatim}
\medskip

In the rest of the section we describe the XPI commands one by one.

\subsection{ alias } 

Alias a complicated command with a short one.  For example:  

\medskip
\begin{verbatim}
xsel >  alias cleansis "sisclean clean_method=2"
cleansis == sisclean clean_method=2
\end{verbatim}
\medskip

Note that the double quotes are necessary, otherwise XPI will think that
clean{\_}method is a parameter for alias, rather than part of the alias.


\subsection{ log } 

This command opens or closes a log file.  

\begin{verbatim}
xsel >  log <log file>  
\end{verbatim}

where $<$log file$>$ is the name of the file to be opened (default
extension is .log).  If no arguments are on the line, then the default
file name is xselect.log.  If $<$log file$>$ matches the string ``none''
then the current log file is closed.  The log contains a complete dump
of the session -- to just get the commands (for a macro, for example)
use the scripts command.

Examples: 

\begin{verbatim}
xsel >  log andy  
\end{verbatim}

will start logging commands in andy.log  

Example 2:  

\begin{verbatim}
xsel >  log none
\end{verbatim}

will turn off the logging.  

Xselect will log all the output it generates, as well as the output
that is generated by the spawned Ftools.  This feature is not yet
available on the VMS version.


\subsection{ lparm   } 

The lparm command{\_}name command will give a list of the parameters for
the given command, their default values, and a short description. This
is very useful for reminding yourself of the command options.


\subsection{ recall   } 

With no arguments, recall prints the last 20 commands given.  With a
numerical argument, it reruns that command from the command list.  The
only tricky part of this is that when you add a new commands the
command numbers get shifted down by 1 for all the previous commands,
so the same number will refer to different commands as you add more
commands.

On Unix systems, this is no longer necessary, since the up and down
cursor keys serve the same function.

Example:  

\medskip
\begin{verbatim}
xsel:ASCA-sis1 > recall

        ...
     1 HELP
     2 SET inst sis1
     3 CHOOSE 1-2
     4 FAINT
     5 BIN image
     6 SAVE image -image.fits
     7 SHOW status
     8 HELP

xsel:ASCA-sis1 > recall 3
xsel:ASCA-sis1 > CHOOSE 1-2
\end{verbatim}
\medskip

\subsection{ scripts  } 

This will cause XPI to open, close or use a script file.  

At any prompt, it is possible to cause XPI to start reading from a
script (indirect command file).  For example,

Do you wish to continue? @YES.XCO  

would cause XPI to search for the file YES.XCO.  If the file is found
the XPI would open the file, and read the answer from it.  Thus the
first line in YES.XCO should contain either yes or no.

To open a script file for keystroke recording, give the command  

\begin{verbatim}
xsel >  script <script file>  
\end{verbatim}

where $<$script file$>$ is the name of the file to be opened (default
extension is .xco).  If $<$script file$>$ matches the string``none'' then
the current script file is closed.  The script contains a list of the
commands executed -- to get a complete dump of the session use the log
command.

Examples: 

\begin{verbatim}
xsel >  script michelle  
\end{verbatim}

will start putting commands into michelle.xco  


\begin{verbatim}
xsel >  script none  
\end{verbatim}

stops recording commands and closes the script file.    


\paragraph*{scripts search path }

If you use @filename to cause XPI to read from a script and it cannot
find the script file in the current directory, XPI searches two other
directories for the file.  First, it checks to see if you have defined
the environment variable MY{\_}XCOMS. If MY{\_}XCOMS is defined then XPI
translates it and prepends the translation to the file name.  Thus

setenv  MY{\_}XCOMS  /users/my{\_}name/my{\_}xcoms

would cause XPI to search the directory /users/my{\_}name/my{\_}xcoms for the 
specified
file.  


\paragraph*{scripts parameters}

It is possible to use parameters with scripts.  To do this you enter
the parameters on the line where you started the script. Thus,

\begin{verbatim}
xsel >  @test one two three  
\end{verbatim}

would cause XPI to open and read the test script using three
parameters one, two, and three.  When XPI is reading the script it
will replace \%n\% with parameter n.  Thus, \%1\% will be replaced with
one, \%2\% with two, etc.  The following illustrates a script that
expects to be run with parameters:

make obs  \%1\% choose \%2\% \ldots  bin  \%3\%  

If you forget to enter the three parameters, then XPI will replace \%n\%
with a null string.

It is possible for a script to call another script and pass in 
parameters.  Thus,  

@deeper first \%2\% \%3\%  

is a valid line in a script.  In this example, the first parameter is
first, whereas the next two parameters will be set equal to parameters 2 
and 3 of the current script.  Also quotes can be used to denotes a
single parameter with embedded spaces, or other magic characters.
Thus,

@file ÒThis is all one" two three  

would pass three parameters, and the first parameter would be the
string This is all one.

\paragraph*{scripts terminal prompt}

Sometimes it would be nice to write a script that in which most of the
responses are read from the script, but one or more lines are read
from the terminal.  This can done by using the @ symbol with no
filename.  When XPI is reading an script, and comes to that line it
will proceed to write the prompt on the terminal, and read the user's
response.  After this one line is read, XPI returns to reading the
script.  Of course, @ could again be used on the following line.

For example, consider the file:  

\medskip
\begin{verbatim}
 1,23! Normal input  
 ! Default input 
 @test! Read from the file test, until the end of the file 
 10 ! More input 
 @! Read this line from the terminal 
 999! Another normal line
\end{verbatim}
\medskip


\subsection{ ?   } 

The ? command will give a list of the command groups available
(command and admin for Xselect).  Then typing command or admin will
list the commands available in each group.


\subsection{ ??   } 

The ?? command will list all available commands.  


\subsection{ \$  - spawn or exit to shell   } 

Execute an operating system command.  

\begin{verbatim}
xsel >  $ <command_line>  
\end{verbatim}

where command{\_}line contains a UNIX command.  No parsing of
$<$command{\_}line$>$ is done by the XPI parser, therefore all the \$'s,
skipped fields, double quotes etc have the meaning they would in an
operating system command. Also $<$command{\_}line$>$ must be 80 characters or
less.

If the dollar sign is entered with no $<$command{\_}line$>$ the program opens
a new shell, and a series of commands can be entered -- type exit to
get back into XSELECT.  Spawning can be disabled by setting the
environment variable DIASBLE{\_}SPAWN.

Examples: 

\begin{verbatim}
xsel > $
\end{verbatim}

Spawns a shell.

\begin{verbatim}
xsel >  $ls  
\end{verbatim}

Lists the contents of the current directory.

\begin{verbatim}
xsel >  $cp triala0.pha x1822a0.pha;   ls *.pha;   exit 
\end{verbatim}


starts up a shell, copies a file and returns to XSELECT.  The \$ can
even be given in reply to a prompt:

\medskip
\begin{verbatim}
xsel >  set datadir
> Enter the event file directory > [] $
%ls
...
%exit
> Enter the event file directory > []  
\end{verbatim}
\medskip


\chapter{Known{\_}Bugs/Features}

\medskip
\begin{itemize}
\item
The code explicitely assumes that there is one events extension per
file.  Future decisions to pack lots of extensions into a single FITS
file are not yet supported!

\item
For the obscat to work, the relevant parameters must be stored as
keywords in the primary extensions of the events files.

\item
The method of storing HK parameters for ASCA has changed, so that
now all the HK data for the whole sequence is stored in one file.
Xselect does not support this format automatically, so to view the HK
data, you must read it in by hand using the read hk command.
\end{itemize}
\medskip

\chapter{ List of Files } 

This is a list of the temporary files that Xselect produces as it runs.

\medskip
\begin{itemize}
\item
xsel{\_}hist.xsl         -- temporary file for spectral data
\item
xsel{\_}qdp{\_}curve.xsl    -- temporary file for the QDP light curve data 
\item
xsel{\_}fits{\_}curve.xsl   -- temporary file for the FITS light curve 
\item
xsel{\_}image.xsl        -- temporary file for the image
\item
xsel{\_}region.xsl       -- input region file for EXTRACT
\item
xsel{\_}fits{\_}in.xsl      -- list of input FITS GTI files for EXTRACT
\item
xsel{\_}mkf{\_}out.xsl      -- fits timing file from the SELECT MKF
\item
xsel{\_}ascii{\_}in.xsl     -- input ascii timing file for EXTRACT
\item
xsel{\_}ascii{\_}out.xsl    -- cumulative timing file, computed by EXTRACT
\item
xsel{\_}xronos{\_}in.xsl    -- input Xronos window file for EXTRACT
\item
xsel{\_}xronos{\_}phase.xsl -- xronos window file containing phase selections
\item
xsel{\_}xronos{\_}out.xsl   -- output Xronos window file compputed by EXTRACT
\item
xsel{\_}hksel{\_}out.xsl    -- is the FITS timing file from SELECT HK
\item
xsel{\_}in{\_}event.xsl     -- output events file from SISCLEAN, overrides
other input to EXTRACT if present
\item
xsel{\_}out{\_}event.xsl    -- output events file from EXTRACT
\item
xsel{\_}merged.xsl       -- temporary file for a merged event dataset.
\item
xsel{\_}mergti.xsl       -- temporary file for the GTI associated with
xsel{\_}merged.xsl
\item
xsel{\_}merghk.xsl       -- temporary file for the merged HK files 
\item
xsel{\_}work1            -- root name for events workspace 1
\item
xsel{\_}work2            -- root name for events workspace 2
\item
xsel{\_}workgti1         -- root name for GTI workspace 1
\item
xsel{\_}workgti2         -- root name for GTI workspace 2
\item
xsel{\_}workhk1          -- root name for HK workspace 1
\item
xsel{\_}workhk2          -- root name for HK workspace 2
\item
xsel{\_}ffcurve.fits     -- MKF curve file from MKFBIN
\item
xsel{\_}mermkf.xsl       -- the temporary merged MKF file
\item
xsel{\_}hkcurve.fits     -- the HK curve file from HKBIN
\item
xsel{\_}cursor{\_}time      -- root name for the cursor timing files
\item
xsel{\_}temp.xsl         -- general purpose temp file
\item
xsel{\_}session.xsl      -- stores the saved session data
\item
xsel{\_}xsel.run         -- script file for the spawned Ftools
\item
xsel{\_}files.tmp        -- temp file for file lists
\item
xsel{\_}obscat.tmp       -- temporary file used for creating the obscat
\item
xsel{\_}read{\_}cat.xsl     -- temporary obscat made by READ
\end{itemize}
\medskip
\end{document}
