============================
Guide to SPEX commands
============================

This document covers the following areas:

A) Starting SPEX

B) Reading data

C) Setting up a spectral model

   1) Overview
   2) Setting the source distance
   3) Defining model components
   4) Defining the relationship between model components
   5) Showing the model
   6) Changing the model parameters
      6.1) Coupling parameters between model components
      6.2) Setting the range for a parameter
   7) Showing the model parameters
   8) Calculating the model
   9) Adding model components
   10) Deleting model components
   11) Taking account of the RGS instrumental oxygen feature

D) Plotting

   1) Setting plot device
   2) Setting plot type
   3) Setting plot units
      3.1) Fluxed spectra
      3.2) Logarithmic/linear axes
   4) The plot command
   5) Adding titles to a plot
   6) Changing the plot range
   7) Plotting the graph 'filled' or 'unfilled'
   8) Closing the plot
   9) Plotting in an X-window
   10) Plotting to a Postscript file
   11) Dumping the plot to an ascii file

E) Fitting data
   
   1) Ignoring a region of data
   2) Using a previously ignored region of data
   3) Freezing and thawing fit parameters
   4) Fitting

F) Using a log file

G) Quitting SPEX

-----------------------------
A) STARTING SPEX
-----------------------------

On msslhd, type

	>spex

There is also a very old version on the Alphas which operates differently to
the version described here. The models and atomic data in the new version
are much more up-to-date.

-----------------------------
B) READING DATA
-----------------------------

If you have a spectral data file spectrum.spo and a response file 
response.res, to read in the data you type:

        SPEX> data response spectrum
	
Note that you leave the .spo and .res off the filenames when you use this
command.

------------------------------
C) SETTING UP A SPECTRAL MODEL
------------------------------

This section covers:

1) Overview
2) Setting the source distance
3) Defining model components
4) Defining the relationship between model components
5) Showing the model
6) Changing the model parameters
   6.1) Coupling parameters between model components
   6.2) Setting the range for a parameter
7) Showing the model parameters
8) Calculating the model
9) Adding model components
10) Deleting model components
11) Taking account of the RGS instrumental oxygen feature

---

1) Overview

In SPEX, a spectral model is assembled by: firstly, defining the various
model components; and secondly, defining the relationship of these
components to each other. Before a model can be assembled though, since SPEX
works using source luminosities rather than fluxes, one must set the
distance to the source.

---

2) Setting the source distance

To set the source distance to (say) 50 megaparsecs:

	SPEX> distance 50 mpc
	
The other allowed distance units are:

   spex - internal SPEX units of 1E22 m (this is the default)
   m    - metre
   au   - astronomical unit
   ly   - lightyear
   pc   - parsec
   kpc  - kpc
   mpc  - Mpc
   z    - redshift units for the given H0 and q0
   cz   - recession velocity in km/s for the given H0 and q0
			   
The default value of H0 is 50 km/s/Mpc. To set it a value n km/s/Mpc:

	SPEX> distance H0 n
	
The default value of q0 is 0.5. This can be changed to a value m using:

	SPEX> distance q0 m

See J. Kaastra's document 5_spex_help.txt for more details.

---

3) Defining model components

To define a model component xxx:

	SPEX> comp xxx
	
For example, for a power law:

	SPEX> comp pow
	
or for galactic absorption:

	SPEX> comp absm

'comp' is interchangeable with 'com'. 

---

4) Defining the relationship between model components

Some model components are additive and others are multiplicative. For each
additive component, you have to define which components it is multiplied by.
For example, if you wanted a galactic absorbed power law continuum, you
would define the two components:

	SPEX> com pow
	SPEX> com absm

The power law (here, component 1, as it was the first to be defined) is
additive and absm (equivalent to wabs in xspec - component 2) is
multiplicative. So, to set pow to be multiplied by absm:

	SPEX> com relation 1 2
	
Each additive component can be multiplied by several multiplicative
components. One might want to model a power law continuum with intrinsic warm
absorption as well as galactic absorption. Here, you would want components
for the power law, the warm absorber, the cosmological redshift of the
source, and the cold absorption due to our galaxy:

	SPEX> com pow
	SPEX> com absm
	SPEX> com reds
	SPEX> com slab
	SPEX> com relation 1 4,3,2

---

5) Showing the model

To display the model setup:

	SPEX> model show

---

6) Changing the model parameters

If a model component n has a parameter x, to change the parameter value to y:

	SPEX> par 1 n x value y
	
For example, if component 3 was a power law and you wanted to change the
power law index gamma to 1.8, you would type:

	SPEX> par 1 3 gam value 1.8
	
'value' can be abbreviated to 'val'

---

6.1) Coupling parameters between model components

To couple parameters between two model components, e.g. coupling the
normalisations of two cie models (assuming they are model components one and
two respectively):

	SPEX> par 1 1 norm couple 1 2 norm

or to couple the abundances:

	SPEX> par 1 2 02:30 couple 1 1 02:30

---

6.2) Setting the range for a parameter

To set the range for a parameter, e.g. fixing the electron temperature t 
of a cie model within the range 0 to 2 keV:

	SPEX> par 1 1 t range 0 2

---

7) Showing the model parameters

To display the model parameters:

	SPEX> par show

---

8) Calculating the model

After the model has been set up and some parameters defined, the model must
be calculated:

	SPEX> calculate
	
which can be shortened to 'c'. The model must be re-calculated every time a
change is made, and re-plotted.

---

9) Adding model components

Model components can be added simply by using the com command as in 3)
above. Their relation to the other components is set using com rel as
before. For example, if we set up that galactic absorbed power law:

	SPEX> com pow
	SPEX> com absm
        SPEX> com relation 1 2

and then decide that we want to add a gaussian to the power law, we define 
a gaussian component:

	SPEX> com gauss
	
which is additive, and becomes component 3. The gaussian is automatically
added to the power law, but we still need to apply the galactic cold
absorption to it, using:

	SPEX> com relation 3 2
	
If one then wanted to apply cosmologically redshifted warm absorption to
this, one defines the components:

	SPEX> com reds
	SPEX> com slab
	
which become components 4 and 5 respectively, and then sets their
relationship to the other components:

	SPEX> com rel 1 5,4,2
	SPEX> com rel 3 5,4,2
      
This implies the model:

(power law + gaussian)*(warm absorption)*(redshift)*(galactic absorption)
			
---

10) Deleting model components

To delete, say, component 3 from the model:

	SPEX> com delete 3

---

11) Taking account of the RGS instrumental oxygen feature

To take account of this, add a slab component 'over the top of' all the
other multiplicative components and set the neutral oxygen log column 
density to 21.53. Using the example of section 9), the instrumental feature
would be component 6:

	SPEX> com slab
	SPEX> com rel 1 5,4,2,6
	SPEX> com rel 3 5,4,2,6
	SPEX> par 1 6 o1 value 21.53
	
------------------------------
D) PLOTTING
------------------------------

This section covers:

1) Setting plot device
2) Setting plot type
3) Setting plot units
3.1) Fluxed spectra
3.2) Logarithmic/linear axes
4) The plot command
5) Adding titles to a plot
6) Changing the plot range
7) Plotting the graph 'filled' or 'unfilled'
8) Closing the plot
9) Plotting in an X-window
10) Plotting to a Postscript file
11) Dumping the plot to an ascii file

---

1) Setting plot device

To plot in an x-window:

	SPEX> plot device xw
	
To plot to a postscript file:

        SPEX> plot device ps filename.ps

To plot to a colour postscript file:

	SPEX> plot device cps filename.ps

---

2) Setting plot type

To plot the data (with the model if it exists):

	SPEX> plot type data

To plot the spectral model only:

	SPEX> plot type model

---

3) Setting plot units

To set the x-axis to angstroms:

	SPEX> p ux a

To set the y-axis to counts/second/angstrom:

	SPEX> p uy a

Similarly, for units of keV:

	SPEX> p ux kev
	SPEX> p uy keV

For units of eV:

	SPEX> p ux ev
	SPEX> p uy eV

The x and y axes do not have to have the same unit, e.g. the y-axis could 
be in cts/sec/keV whilst the x-axis was in angstroms, and so forth.

---

3.1) Fluxed spectra

To plot a fluxed spectrum, use:

	SPEX> p uy fa

which plots counts/m^2/s/angstrom, or

	SPEX> p uy fkev

which plots counts/m^2/s/keV, or

	SPEX> p uy fev

which plots counts/m^2/s/eV.

---

3.2) Logarithmic/linear axes

To plot linear scales:

	SPEX> p x lin
	SPEX> p y lin
	
To plot logarithmic scales:

        SPEX> p x log
	SPEX> p y log

---

4) The plot command

To plot, type:

	SPEX> p
	
The command 'p' is of course interchangeable throughout with 'plot'

---

5) Adding titles to a plot

To add a main title, say the word 'RGS', to the graph, type:

	SPEX> plot cap ut text RGS

To add a subtitle, for example 'spectrum', type:

	SPEX> plot cap lt text spectrum

---

6) Changing the plot range

To change the x-range to, say, 4.5 to 22.371 use:

	SPEX> p rx 4.5 22.371
	
To change the y-range to e.g. 0.0001 to 0.06, use:

	SPEX> p ry 0.0001 0.06

---

7) Plotting the graph 'filled' or 'unfilled'

SPEX automatically plots the spectral model 'filled in'. To plot it unfilled:

	SPEX> p fill disp false

To plot it filled in:

	SPEX> p fill disp true
 
---

8) Closing the plot

To close the first plot that was opened:

	SPEX> plot close 1
	
Change the number according to which plot is going to be closed. This
command is useful mostly with closing postscript files after the plot has
been created.

---

9) Plotting in an X-window

The procedure is:

 set plot device => set plot type => set plot units => plot
 
Then one can:

 change plot range
 make axes logarithmic/linear
 add titles
 
and so forth if required. The 'plot' command has to be used whenever the
plot needs to be updated after a change - it isn't automatic like in PLT.

An example would be:

	SPEX> plot device xw
	SPEX> plot type data
	SPEX> p ux a
	SPEX> p uy a
	SPEX> p
	
Then wanting to home in on a particular region:

	SPEX> p rx 15 18
	SPEX> p

..and adding titles:

	SPEX> plot cap ut text RGS_spectrum_of_NGC3783
	SPEX> plot cap lt text UTA_region
	SPEX> p
	
---

10) Plotting to a Postscript file

This is effectively the same as for plotting in an X-window, but you need to
make all the alterations to the plot before actually using the 'plot'
command. Otherwise, every time you re-plot, another page appears in the
postscript file. You also need to close the plot after you have created it,
to prevent further pages being added if you do not want them.

Example: Let's say that you already have the X-window plot described in the 
previous section, and want to produce a postscript version. Since it is not
convenient to play around with the postscript plot until it looks right, it
is best simply to create the plot you want in an X-window and repeat the
exact set of commands for the postscript. In this case:

Open the plot file:

	SPEX> plot dev cps RGS_NGC3783.ps
	
You do not need to set the units and plot type again.

	SPEX> p rx 15 18
        SPEX> plot cap ut text RGS_spectrum_of_NGC3783
	SPEX> plot cap lt text UTA_region
	SPEX> p
	
..and then close the plot, remembering that the postscript file is the second
plot as the X-window is still there:

	SPEX> plot close 2

---

11) Dumping the plot to an ascii file

To produce an ascii file filename.asc of the plot:

	SPEX> plot adum filename.asc

The columns in the resulting file will contain:

 wavelength (or energy) at the centre of the bin
 +/- half wavelength (or energy) bin size
 data value
 +/- error on the data
 model value

depending of course on what the original plot contained.

-----------------------------
E) FITTING DATA
-----------------------------

This section contains:

1) Ignoring a region of data
2) Using a previously ignored region of data
3) Freezing and thawing fit parameters
4) Fitting

---

1) Ignoring a region of data

Whilst the plot command allows you to zoom in on a region of interest, for
fitting purposes it is necessary to completely remove from consideration
irrelevant regions of the spectrum which might contribute to an
inappropriate result, or even in some cases cause SPEX to crash. SPEX can
ignore a part of the spectrum specified in channels. For example, the command:

	SPEX> ignore 300:850

will ignore all spectral channels between 300 and 850. RGS spectra, once
they have been converted to SPEX format, might have around 2000 channels in
total. Using the 'plot' command again:

	SPEX> p
	
The ignored region will be seen to disappear from the plot. Alternatively, 
regions can be specified in terms of wavelength (angstroms), e.g.

        SPEX> ignore 15.5:20 unit a

or in keV:

        SPEX> ignore 0.5:0.6 unit kev

or in eV:

        SPEX> ignore 500:600 unit ev

---

2) Using a previously ignored region of data

Data ignored as described in the previous section can be noticed again; the
command:

	SPEX> use 300:850

will notice the region of the spectrum between these channels. Using the
'plot' command:

	SPEX> p
	
this region will reappear in the plot. Again, the region can be specified in 
wavelength or energy, e.g., in angstroms:

        SPEX> use 15.5:20 unit a

or in keV:

        SPEX> use 0.5:0.6 unit kev

or in eV:

        SPEX> use 500:600 unit ev

---

3) Thawing and freezing fit parameters

If you want to thaw a fit parameter 'xxx' of a model component 'n' (see
section C on setting up a spectral model), the command is:

	SPEX> par 1 n xxx status t
	
To re-freeze this parameter:

	SPEX> par 1 n xxx status f
	
The word 'status' can be abbreviated to 'sta' in this command.

For example: Let's say that you have a spectral model, containing a power
law continuum, in which you want to fit the power law spectral index gamma. 
The name of the fit parameter is 'gam'. If the power law continuum is 
component 2 of the model, then to thaw the power law slope:

	SPEX> par 1 2 gam status t
	
To re-freeze gamma,

	SPEX> par 1 2 gam status f

---

4) Fitting

The procedure is:

	SPEX> fit print 1
	
Which ensures that the result of each stage of the fit is printed - in this
case - on plot number 1, usually the X-window. This is useful as it enables
you to watch what the fit is doing in real time.

To perform the fit:

	SPEX> fit

-----------------------------
F) USING A LOG FILE
-----------------------------

Due to the 'text line intensive' nature of SPEX, especially when
manipulating spectral models, it is often more convenient to read in data,
set up a model and open the plot using a log file. The log file, which must
be in the form filename.com, is simply a text file containing all the
commands you would type into SPEX on the command line. To run a log file,
first start up SPEX:

	> spex
	
And then use the command:

	SPEX> log execute filename
	
Note that the .com has to be omitted from the name of the log file.

For example, let's say that you want to read in a RGS spectrum file
spectrum.spo and corresponding response.res, set up a galactic absorbed
power law model, and plot the data and model in an X-window. The
log_file.com for this might contain the following lines:

#read in data and response

 data response spectrum

#set up model

 distance 50 mpc
 comp pow
 comp absm
 comp relation 1 2
 par 1 2 nh value 8.7e-4
 par 1 2 nh status f
 par 1 1 gam value 1.655
 par 1 1 gam status f
 par 1 1 norm value 52872244.72
 par 1 1 norm status f
				
#calculate model

 calculate

#plot model

 plot type data
 plot device xw
 plot ux a
 plot uy a
 plot
				
-----------------------------
G) QUITTING SPEX
-----------------------------

To exit SPEX:

	SPEX> q
	
---