\chapter{Getting Started}
The best way to learn an analysis system is to use it.
In this chapter\footnote{
You can skip this chapter
if you have an experiment to analyze data with ASCA\_ANL.
}
we describe the way to analyze ASCA data using the ASCA\_ANL system
with a sample program {\tt gisspec} (see below) as an example.
We recommend you to read this chapter in front of your computer
following our directions below.

To clarify the directions, let us assume:
\begin{enumerate}
  \item the ASCA\_ANL has already installed in your computer
  \item the ASCA\_ANL is installed in a directory {\tt /asca\_anl/}
  \item You run the ASCA\_ANL on a directory \verb|~/work/|
  \item {\em Display45} has already installed in your computer
\end{enumerate}

\section{Compile Sample Program}
Some examples of a user program
are attached to the distribution kit of the ASCA\_ANL.
Each module in the samples is written both in FORTRAN and in C.
We hope they help you to understand the ASCA\_ANL system\footnote{
the samples are written carefully from ``ASCA\_ANL'' point of view.
Each sample is full of recommendations by the ASCA\_ANL working group.
We hope you master how to write your module by referring the samples.
}.

You can compile the samples easily as follows:
\begin{enumerate}
  \item Copy source files of a sample you want to compile.
  \item Modify include files for your computer system (if needed).
  \item Make the sample.
\end{enumerate}

\subsection{Copy a Sample}
Each directory below a directory {\tt sample}
corresponds to a sample program.
The name of each directory is self-explanatory.
Find a program you want to compile among them
and copy the directory to your local directory.

In our case, type
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% cd ~/work
% cp -r /asca_anl/sample/gisspec .
\end{verbatim}\end{quote}

\subsection{Arrange Makefile}
Before compiling the sample,
you have to modify\footnote{
In most cases you can skip this proceedure
because {\tt Includes.make} is modified so
by a person who installed the ASCA\_ANL.
}
a file {\tt Includes.make} to fit you computer sysytem.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% cd gisspec
% emacs Includes.make
\end{verbatim}\end{quote}

In the file Includes.make
several macros are defined
to specify the directory structure of your computer system.
Edit the file
and change definitions of macros appropriately.

Each macro specifies the directory
which contains a library or header files for the library
and how to compile and link them to the ASCA\_ANL system.
Table\ref{tab:includes_make} shows
required contents in the directory specified by the macros.
Also,
option flags for a compiler and a linker
are also listed in Table\ref{tab:includes_make}.

\begin{table}[htb]
\begin{center}
\begin{tabular}{ll}
\hline
   {\tt MACRO} & Directory Contents etc.\\
\hline
   {\tt ASCA\_ANL\_DIR}	& the ASCA\_ANL directory \\
   {\tt ASCA\_ANL\_INC}	& header files of the ASCA\_ANL \\
   {\tt ASCA\_ANL\_LIB}	& libraries of the ASCA\_ANL \\
   {\tt ASCA\_ANL\_BIN}	& executables for the ASCA\_ANL \\
   {\tt ASCA\_ANL\_LNK} & link option for the ASCA\_ANL \\
   {\tt ASCATOOL\_DIR}	& ascatool directory \\
   {\tt ASCATOOL\_INC}	& header files for ascatool \\
	& {\tt ascatool.h}, etc. \\
   {\tt ASCATOOL\_LNK}  & link option for ascatool\\
	& {\tt libascatool.a} \\
   {\tt COM\_CLI\_LNK}  & link option for CLI/COM \\
	& {\tt libCOM.a}, {\tt libCLI.a}, {\tt libreadline.a} \\
   {\tt ATFUNCTIONS\_INC}& header files for atFunctions \\
	& {\tt atFunctions.h} and {\tt atError.h} \\
   {\tt ATFUNCTIONS\_LNK} & link option for the atFunctions \\
	& {\tt libatFunctions.a} \\
   {\tt CERN\_DIR}	& CERN directory \\
   {\tt CERN\_INC}	& header files for CERN library \\
	& {\tt cfortran.h} and {\tt hbook.h} \\
   {\tt CERN\_LNK}      & link option for CERN library \\
	& {\tt libgraflib.a}, {\tt libgrafX11.a}, {\tt libpacklib.a}, \\
	& {\tt libkernlib.a}, {\tt libmathlib.a}, {\tt libX11.a} \\
   {\tt FITSIO\_LNK}    & link option for FITSIO \\
	& {\tt libfitsio.a} \\
   {\tt CC}             & default C compiler \\
   {\tt FC}             & default FORTRAN compiler \\
   {\tt DEFAULT\_F77\_LNK} & default FORTRAN library \\
\hline
\end{tabular}
\caption{Macros in {\tt Includes.make}}
\label{tab:includes_make}
\end{center}
\end{table}

\subsection{Make}
In order to "make" it,
just type
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% make
\end{verbatim}\end{quote}
in the current directory.
When all compilations are done,
executables {\tt gisspec\_f} and {\tt gisspec\_c}
are created in the current directory.
{\tt gisspec\_f} corresponds to {\tt gisspec\_f.f} and {\tt circreg\_f.f},
source files of modules {\tt GISSPEC} and {\tt CIRCREG} written in FORTRAN
and {\tt gisspec\_c} is created from {\tt gisspec\_c.c} and {\tt circreg\_c.c},
source files of modules {\tt GISSPEC} and {\tt CIRCREG} written in C.
A module {\tt FITSREAD} and A main program of the ASCA\_ANL
were also linked to the resultant executables.

To run {\tt gisspec\_f},
type
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% gisspec_f
\end{verbatim}\end{quote}
and to run {\tt gisspec\_c},
type
\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% gisspec_c.
\end{verbatim}\end{quote}
Very few differences\footnote{
Possible differences are the number of spaces or blank lines in output
or something minor.
} are resulted from two executables.

\section{Walk Through the ASCA\_ANL}
\label{sec:walk-through}
Now let us see an example of analysis with the ASCA\_ANL.
Since the usage of any user program are similar in its user interface,
you can analyze data with this program
by following the instructions in this section.

We compiled a program {\tt gisspec\_f} and {\tt gisspec\_c}
both of which includes
``FITSREAD'',
``CIRCREG'',
and ``GISSPEC'' as linked modules.
By typing {\tt gisspec\_f} or {\tt gisspec\_c} in a command line
you can see a command menu of the ASCA\_ANL and the prompt "ANL$>$".

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
%gisspec_f

 ANL:  Program ASCA_ANL *** ASCA Analysis ***

 DEFINE_ANALYSIS SHOW_ANALYSIS   MODIFY_PARAM
 BOOK_HISTOGRAM  ANALYZE_DATA    QUIT

 ANL: Select  1 Option
ANL> 
\end{verbatim}\end{quote}

The first thing you have to do is to define an analysis chain.
To define the analysis chain,
type "DEFINE\_ANALYSIS" or its abbreviation.
The command name can always be abbreviated
and the ASCA\_ANL does not distinguish between upper case and lower case.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> define

 ANL:  Program ASCA_ANL *** Define Analysis ***

 NONE     FITSREAD CIRCREG  GISSPEC  FULL

 ANL: Select  1 or More, Then OK
ANL> 
\end{verbatim}\end{quote}

In this menu you can see all the modules you linked in {\tt gisspec\_f}.
Also, names {\tt NONE} and {\tt FULL} are displayed.
These two are reserved in ASCA\_ANL and explained below.

Suppose that we read ASCA data from a science FITS file,
select events in a circular region on GIS images,
and create GIS spectra and GIS images.
To do these we need three modules;
{\tt FITSREAD} to read data from a FITS file,
{\tt CIRCREG} to select events in the specified circle on GIS images,
and {\tt GISSPEC} to obtain GIS spectra and GIS images.
You can choose these modules in this order
by typing {\tt FITSREAD CIRCREG GISSPEC ok}.
The ASCA\_ANL returns to the command menu by accepting ``ok''.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> FITSREAD CIRCREG GISSPEC ok

 ANL:  Program ASCA_ANL *** ASCA Analysis ***

 DEFINE_ANALYSIS SHOW_ANALYSIS   MODIFY_PARAM
 BOOK_HISTOGRAM  ANALYZE_DATA    QUIT

 ANL: Select  1 Option
ANL> 
\end{verbatim}\end{quote}

If you type {\tt FULL ok} instead of {\tt FITSREAD CIRCREG GISSPEC ok},
all the modules displayed in the menu are chosen,
{\em i.e.},
the effect of typing {\tt FULL ok} is,
in this case,
completely the same as you typed.
If you type {\tt NONE ok} instead,
none of the modules is chosen.

Now let us return to our analysis.

After defining the analysis chain,
you can modify parameters you use in our analysis.
To do this,
type {\tt MODIFY\_PARAM} in the command menu.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> modify

 ANL:  *** Modify Parameter ***

 NONE     FITSREAD CIRCREG  GISSPEC  FULL

 ANL: Select  1 or More, Then OK
ANL> 
\end{verbatim}\end{quote}

In this menu
you can see only three modules you selected in {\tt DEFINE\_ANALYSIS}.
By typing {\tt CIRCREG ok}
you are asked to modify parameters for the module {\tt CIRCREG}.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> circreg ok

 *** Circular Region ***

 Sensor to set (-1=end of set): 0 ? 0
 DETX of Center (pixel): 640.5 ? 0.0
 DETY of Center (pixel): 640.5 ? 0.0
 Radius (pixel): 1024.0 ? 150.0

 *** Circular Region ***

 Sensor to set (-1=end of set): 0 ? 
\end{verbatim}\end{quote}

You can specify parameters as you desire
by answering values as is asked.
In above case
we set a image region for SIS--0
centering (0.0, 0.0) with 150.0 pixels as its radius.

The values printed left to a question mark is a default value.
If you can accept the default,
you can omit inputing a value,
{\em i.e.},
all you have to do is to hit a return key.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
 *** Circular Region ***

Sensor to set (-1=end of set): 0 ? 1
DETX of Center (pixel): 640.5 ?
DETY of Center (pixel): 640.5 ?
Radius (pixel): 1024.0 ?

 *** Circular Region ***

 Sensor to set (-1=end of set): 1 ? 
\end{verbatim}\end{quote}

In above case
we set a image region for SIS--1
centering (640.5, 640.5) with 1024.0 pixels as its radius.
Note that
we did NOT type coordinates of the region center
BUT only hit a return key.

There is another way to specify parameters.
Now you know the order of parameters to be asked,
it is a little bit boring to hit the return key after typing a value.
You can put values in one line like this:

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
 *** Circular Region ***

 Sensor to set (-1=end of set): 1 ? 2 0.0 0.0 16.0


 *** Circular Region ***

 Sensor to set (-1=end of set): 2 ? 
\end{verbatim}\end{quote}

In above case
we set a image region for GIS--2
centering (0.0, 0.0) with 16.0 pixels as its radius.

At this point
perhaps you feel uncomfortable by watching the input line
because the input line is difficult to remember which value means what.
Now you know the begining {\tt 2} means GIS-2,
first {\tt 0.0} means {\tt DETX} of the region center, and so on.
But, you may forget its meaning one month after.

For such people
there is yet another way of specifying parameters.
You can put meanings of the values to some extent
in case of setting integer or floating point paramters.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
 *** Circular Region ***

 Sensor to set (-1=end of set): 2 ? g3 x=0.0 y=0.0 r=16.0


 *** Circular Region ***

 Sensor to set (-1=end of set): 0 ? 
\end{verbatim}\end{quote}

In above case
we set a image region for GIS--3
centering (0.0, 0.0) with 16.0 pixels as its radius.

How about this!

In case of setting integer values
the system\footnote{
Exactly speaking,
this is a feature of the CLI,
a standard user interface routines used in the ASCA\_ANL.
} ignores
a part of the input line which can not be recognized as an integer
({\tt g} of {\tt g3} in above case).
The same is true in case of floating point values.

Note that
no space is allowed between {\tt g} and {\tt 3}.
Also,
{\tt x=0.0} must not include any space between {\tt x}, {\tt =}, and {\tt 0.0}.
The others follow the same restriction.

After setting parameters
type {\tt -1} to return to the command menu as is prompted.
Then you will be back to the command menu again.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
 *** Circular Region ***

 Sensor to set (-1=end of set): 3 ? -1

 ANL:  Program ASCA_ANL *** ASCA Analysis ***

 DEFINE_ANALYSIS SHOW_ANALYSIS   MODIFY_PARAM
 BOOK_HISTOGRAM  ANALYZE_DATA    QUIT

 ANL: Select  1 Option
ANL>
\end{verbatim}\end{quote}

The next is to book histograms.
Type a command {\tt BOOK\_HISTOGRAM} or its abbreviated form
and Select modules to book histograms for.

In our case
histograms should be booked for the module {\tt GISSPEC}.
So type {\tt GISSPEC ok}.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> book
 
 ANL:  *** Book Histogram ***
 
 NONE     FITSREAD CIRCREG  GISSPEC  FULL    
 
 ANL: Select  1 or More, Then OK
ANL> gisspec ok
 
 ANL:  Program ASCA_ANL *** ASCA Analysis ***
 
 DEFINE_ANALYSIS SHOW_ANALYSIS   MODIFY_PARAM   
 BOOK_HISTOGRAM  ANALYZE_DATA    QUIT           
 
 ANL: Select  1 Option
ANL> 
\end{verbatim}\end{quote}

You can confirm the analysis chain you defined now
by commanding {\tt SHOW\_ANALYSIS}.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> show

                   **************************
                   ***** Analysis chain *****
                   **************************

     [ 1] FITSREAD         ------
     [ 2] CIRCREG          ------
     [ 3] GISSPEC          BOOKED
 
 HBOOK_BUF_SIZE =      2200000
 BNK_BUF_SIZE   =       120000

 ANL:  Program ASCA_ANL *** ASCA Analysis ***
 
 DEFINE_ANALYSIS SHOW_ANALYSIS   MODIFY_PARAM   
 BOOK_HISTOGRAM  ANALYZE_DATA    QUIT           
 
 ANL: Select  1 Option
ANL> 
\end{verbatim}\end{quote}

The number in a bracket shows the order of procedures in our analysis.
{\tt BOOKED} at right most column means
that histograms for the module have already been booked
and {\tt ------} means not.
{\tt HBOOK\_BUF\_SIZE} and {\tt BNK\_BUF\_SIZE} are sizes of buffers
(in unit of four bytes) used for HBOOK and BNK, respectively.

Now you are ready to analyze ASCA data.

By commanding {\tt ANALYZE\_DATA}
you can proceed next stage of ASCA\_ANL.
In this stage
you can read data,
analyze data,
save histogram,
clear histogram,
and so on.
On the way to this stage
the {\tt SHOW\_ANALYSIS} command is executed automatically.
Also,
{\tt PSEUDO\_INTERVAL}\footnote{
See Section\ref{app:BNK-key} in details.
} is printed out by {\tt FITSREAD} in our case.
Now you don't have to worry about {\tt PSEUDO\_INTERVAL}
because it is set to zero as a default.
That means nothing special happening to our analysis.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> ana

                   **************************
                   ***** Analysis chain *****
                   **************************

     [ 1] FITSREAD         ------
     [ 2] CIRCREG          ------
     [ 3] GISSPEC          BOOKED

 HBOOK_BUF_SIZE =      2200000
 BNK_BUF_SIZE   =       120000

 ANL:  *** FITSREAD show parameter ***

     PSEUDO_INTERVAL    0.0000 (sec)
 
 ANL:  Program ASCA_ANL *** ASCA Analysis ***
 
 READ_DATA    SAVE_HIST    CLEAR_HIST   SHOW_STATUS 
 RESET_STATUS EXIT        
 
 ANL: Select  1 Option
ANL> 
\end{verbatim}\end{quote}

Command {\tt READ\_DATA} starts the analysis.
You are asked to enter a name of a science FITS file
you want to analyze.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
 ANL> read
 Input fits filename: frf.fits ? ../testdata/dummysis.fits
  successfully opened
 number of rows          128
 Instrument : SIS0
 Data Mode : BRIGHT
 Bit Rate : HIGH
  FTISREAD: Can not get STDGTI (status=         107)
  FTISREAD: use TSTART and TSTOP keywords
\end{verbatim}\end{quote}

After replying the file name
{\tt FITSREAD} opens the data file.
Then you are asked the number of events you want to analyze.
If you want analyze all data in the input FITS file,
reply {\tt -1}.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Number of events (-1=all, 0=exit): -1 ? -1
\end{verbatim}\end{quote}

You are also asked a frequency of displaying the number of data
analyzed until that time.
If you specify 500,
you will see the number of analyzed data
displayed every 500 events.
In our case
total number of events (printed by {\tt FITSREAD}) is only 128,
let us specify {\tt 10} as a printout frequency.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Event number printout frequency: 100 ? 10
\end{verbatim}\end{quote}

Just after answering the printout frequency
the ASCA\_ANL starts processing data.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
 Event...           1
 Event...          11
 Event...          21
 Event...          31
 Event...          41
 Event...          51
 Event...          61
 Event...          71
 Event...          81
 Event...          91
 Event...         101
 Event...         111
 Event...         121
 
 ANL:  Program ASCA_ANL *** ASCA Analysis ***
 
 READ_DATA    SAVE_HIST    CLEAR_HIST   SHOW_STATUS 
 RESET_STATUS EXIT        
 
 ANL: Select  1 Option
ANL> 
\end{verbatim}\end{quote}

After finishing analyzing data in the specified file
If you have another FITS file to be analyzed,
type {\tt READ\_FILE} again
and repeat the procedure after that.

With all the data analyzed,
it is time to exit from this program.
That is simple.
Type {\tt EXIT}.
Then you will see
the version numbers of modules in the analysis chain you defined
and the statistics of the analysis you did
before you exit.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
ANL> exit

                   **************************
                   ***** Analysis chain *****
                   **************************

          ASCA_ANL         version 0.81   
     [ 1] FITSREAD         version 0.73    
     [ 2] CIRCREG          version 1.0     
     [ 3] GISSPEC          version 4.0     

 *** results of Event selection *** < Number of selects :   26 > (EVS vers.2.6) 
          0 : SIS:SIS0 Event                  
          0 : SIS:SIS1 Event                  
        128 : GIS:GIS2 Event                  
          0 : GIS:GIS3 Event                  
          0 : SIS:PSEUDO Event                
        128 : GIS:PSEUDO Event                
          0 : SIS:SIS0 Pseudo                 
          0 : SIS:SIS1 Pseudo                 
        128 : GIS:GIS2 Pseudo                 
          0 : GIS:GIS3 Pseudo                 
          0 : ANL:BIT HIGH                    
          0 : ANL:BIT MEDIUM                  
          0 : ANL:BIT LOW                     
        256 : GIS:PH mode                     
          0 : GIS:MPC mode                    
          0 : SIS:BRIGHT mode                 
          0 : SIS:BRIGHT2 mode                
          0 : SIS:FAINT mode                  
          0 : SIS:FAST mode                   
          1 : FITSREAD:BEGIN                  
        256 : FITSREAD:ENTRY                  
        256 : FITSREAD:OK                     
        128 : FITSREAD:PSEUDO                 
        128 : FITSREAD:OBS                    
          1 : CIRCREG:BEGIN                   
        256 : CIRCREG:ENTRY                   
        134 : CIRCREG:OK                      
          1 : GISSPEC:BEGIN                   
        134 : GISSPEC:ENTRY                   
        134 : GISSPEC:OK                      
\end{verbatim}\end{quote}

The last question is
if you need to save histograms or not.
You can answer {\tt Y} or {\tt N}.
By entering a file name for histograms to be saved
you will exit from this program.
If your specified file already exists,
you are also asked if you want to delete the old one
before you exit.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
Save histogram (Y/N): Y ? Y
File Name: histfile.hbk ? test.hbk
'test.hbk' already exists, delete (Y/N): Y ? Y
\end{verbatim}\end{quote}

Now you get the result of analysis in a file "test.hbk".
You can operate these histograms very easily
with {\em display45}.
Here
we just look at resultant histograms with {\em display45}.

\section{Browse Results with Display45}
We have a results from our own analysis of ASCA data.
Let us look at the results with {\em display45}.
Since {\em display45} displays histograms with opening X-window,
you have to set an environment variable {\tt DISPLAY}.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% setenv DISPLAY <your-terminal>
\end{verbatim}\end{quote}

To invoke {\em display45}, type

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
% dis45 test.hbk
 Version 1.18/08 of HIGZ started
DIS> @%
%output off
%output on
DIS> FETC test.hbk 0 0
DIS> (End of File)
DIS> 
\end{verbatim}\end{quote}

The X-window is opened
and you are prompted to enter a command for {\em display45}.
At first
let us see what kind of histograms are stored in {\tt test.hbk}.
Type {\tt i} to do this.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
DIS> i     
       1   100 1  GIS2 PHA
       2   200 1  GIS3 PHA
       3   300 1  GIS2 PI
       4   400 1  GIS3 PI
       5   500 2  GIS2 RAWX vs RAWY
       6   600 2  GIS3 RAWX vs RAWY
DIS> 
\end{verbatim}\end{quote}

In the left most column sequencial numbers of the histograms are shown.
In the second column
you can see ``histogram ID'' to specify histograms.
The third colunm means its dimension
and the right most column shows its titles.

For example,
the first line means:
\begin{itemize}
  \item histogram ID is 100
  \item one dimensional histogram
  \item title is {\tt GIS2 PHA}
\end{itemize}

To display the histogram with its ID of 100
type {\tt h 100 t} which means
``select \underline{h}istogram with ID \underline{100},
and \underline{t}ype it.''

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
DIS> h 100 t
   100 1  GIS2 PHA
DIS> 
\end{verbatim}\end{quote}

You can see a PHA spectrum of GIS--2,
one of the result from our analysis.
If you want to browse a next histogram (whose ID is 200),
just type {\tt nt} which stands for
``select \underline{n}ext histogram, and \underline{t}ype it''.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
DIS> nt
   200 1  GIS3 PHA
DIS> 
\end{verbatim}\end{quote}

You are watching a PHA spectrum of GIS--3 now.
You can also browse PI spectra and GIS images in the same way.

To exit from {\em display45}
just type {\tt exit}.

\begin{quote}\baselineskip 3.2mm\begin{verbatim}
DIS> exit
Complete Display 45...
%
\end{verbatim}\end{quote}

{\em Display45} features poweful functions to operate histograms
which I hope are helpful for your analysis.
Also,
it includes a fitting package called {\em MINUIT} which is well established.
See a manual of {\em display45} distributed with {\em display45}
for how to use these functions.
