5. Sherpa Models

5.1 Introduction

The primary task of Sherpa is to fit a model $M({\vec x},{\vec p},O)$ to a set of observed data. ${\vec x}$ denotes the set of model arguments, ${\vec p}$ denotes the model parameters, and $O$ denotes model options.

1. Arguments are generic to the model, and describe the axis along which the model fit occurs. For example, when fitting energy spectra, ${\vec x}$ could be a set of photon-energy bin boundaries defined in units of keV.
2. Parameters control the model's shape as a function of the model arguments. For example, $a$ and $b$ are parameters that control the amplitude and slope of the power-law model $ax^{-b}$. Parameters can be varied during the fitting process until their best-fit values are found, or held fixed to specified values.
3. Options place special constraints on the model. For example, in an absorption model the opacity can be input from different tables, so while the mathematical form of the model function remains the same, the computed values of $M$ can vary. Options remain constant during the fitting process.

The modeling aspect of Sherpa is designed with complete generality in mind. Sherpa provides the user with a set of commonly used 1- and 2-D models, some of which are unique to Sherpa , and some of which come directly from Version 11 of XSPEC (Arnaud 1996). The user is free to combine these models to build arbitrarily complex composite models.^5.1The user can also rename models, and apply them along any data axis. Thus the user can provide three names for the 1-D power-law model POWLAW1D and build a 3-D composite power-law model with different photon indices along each axis. (The photon index values could also be linked between different axes.) Finally, Sherpa also provides the user with the capability of inputting his or her own model (see USERMODEL below).

There are three model categories in Sherpa : source, background, and instrument. Each is discussed in turn below. Models from different categories can be combined during the fitting process. The user can combine background and source models when fitting background-subtracted data, or convolve source and instrument models when fitting PSF-broadened spatial data. Sherpa does not require the user to specify models in all three categories; only the source model is required.

5.2 Source Models

Sherpa uses the concept of `source models' in order to highlight their specific physical meaning. They describe parent distributions from which the observed source data may have been sampled. While many of the Sherpa source models have physical interpretation, many are phenomenological, serving only as a mathematical parameterization of the observed data.

Source models may be compared to the observed data in two different ways:

• The user can elect to directly compare source models with the observed data, if for instance they are dominated by the source signal, and the effect of instrument characteristics is negligible. For example, the user may elect to model optical emission lines directly with simple 1-D Gaussian functions.

• The user can also elect to convolve source models with an instrumental response function, then compare the result with the observed data, if for instance they are dominated by instrumental features. For example, the standard analysis of X-ray energy spectra requires source models to be convolved with the response matrix of the instrument. The model predicted counts, $M(i_{\rm PHA})$, are then given by

  $$M(i_{\rm PHA})~=~\int_{E_{\rm lo}}^{E_{\rm hi}} R(i_{\rm PHA}, E) f(E) dE \,$$ (5.1)

  
  
  where $R(i_{\rm PHA},E)$ is the instrument response,^5.2which describes the probability that a photon with energy $E_{\rm lo} \leq E \leq E_{\rm hi}$ will be detected as a count in the PHA channel $i_{\rm PHA}$, and where $f(E)$ is the specified source model function. Another example would be the convolution of a 2-D spatial source model with an instrumental Point-Spread Function (PSF).

5.2.1 1-D Source Models

Sherpa provides a number of 1-D source models that the user may apply to any kind of 1-D data, or may combine together to create arbitrarily complex source models. For instance, one could use POWLAW1D to model energy spectra, SIN to model a binned time series (e.g. a light curve), and GAUSS to arbitrary non-astrophysical data provided in an ASCII file.

5.2.2 2-D Source Models

Sherpa also provides a number of 2-D source models that the user may apply to any kind of 2-D data, or may combine together to create arbitrarily complex source models. For instance, one could use BETA2D or GAUSS2D to fit image data. These 2-D models are sometimes referred to as spatial models in this manual, since it is envisioned that their use will be primarily to fit 2-D image data.

5.2.3 Multi-dimensional Source Models

Chandra is capable of making simultaneous high resolution measurements of a photon's spatial location, energy, and time-of-arrival. Thus the user may wish to combine 1-D and/or 2-D models to create arbitrarily complex 2-D, 3-D, or 4-D models to fit these data. Examples of analyses which require such multi-dimensional models include:

• Supernova Remnants: the user may wish to fit a spectrum in each bin on a 10 arcsec grid, make arrays of Fe-K and Si-K equivalent widths, plot the ratio on a map, and plot ratio versus temperature.

• Cooling flow: the user may wish to create a 3-D flow model and project it to 2-D, and fit to surface brightness, while also modeling the energy spectrum.

• Energy spectrum versus time: the user may wish to make a 2-D image of the energy spectrum versus time, describing temporal variations in the spectrum.

• Aspect quality: the user may wish to divide the data into images binned by, e.g. guide star separation, angle to Earth's B-field, optical bench temperature, etc. , and measure image FWHM in each bin and plot FWHM versus B-field.

As stated above, Sherpa allows the user to combine 1-D models so as to model a 2-D dataset (with, say, energy and time axes). Note however that in the current version of Sherpa it is not yet possible to combine 1-D and/or 2-D instrument models, i.e. the user cannot yet convolve an arbitrary multi-dimensional model with a multi-dimensional instrument model. Such functionality will be provided in a future version of the software.

5.2.4 Source Model Integration

In the analysis of binned data, source model functions can be split into two classes. The first class contains the ``additive" models, which are integrated over bins in energy-space (before being folded through an instrument), or over bins in counts-space (if no instrument model is specified). The second class contains the ``multiplicative" models, which are not integrated when evaluated. Additive models can describe photon generation (e.g. BBODY), while multiplicative models can describe photon attenuation (e.g. ATTEN) or filtering (e.g. BOX1D). Note that in Sherpa , multiplicative model amplitudes for binned data are currently evaluated at the lower boundary of each bin.

In Sherpa , some models are integrated by default, including all XSPEC additive models (see Table 5.9 and the XSPEC Version 11 User's Guide). Sherpa lets the user control the integration of non-XSPEC source models (i.e. those models unique to Sherpa ) when fitting binned data, by using the INTEGRATE $<$ON|OFF$>$ command. An example of a situation in which the user may wish to change the integration status of a source model is when it is used in nested model expressions.

5.3 Background Models

Background models are in every way like source models, except that they are used to describe parent distributions from which observed background data may have been sampled. These data are input using the BACK command. Depending on the type of statistical analysis, these data can be subtracted from the observed raw counts data or can be simultaneously modeled with the source data. Background models are specified using the BACKGROUND | BG command. note that any model component in the Sherpa library may be used to compose a background model.

5.4 Instrument Models

Instrument models describe instrument characteristics, such as an effective area, a detector's energy response, or a mirror's point-spread function. They are convolved with the source, background, or combined source and background model to compute the number of predicted counts in each detector bin.

Instrument models may also be defined with analytic functions. The current version of Sherpa allows the user to define instrument models using functions defined in the TCD library (the Transformation, Convolution and Deconvolution tools). These include 1-D and 2-D Gaussian, box, and top-hat functions. The relevant command is TPSF.

The INSTRUMENT command has more details on modeling the instrument in source or background data analysis.

The following instrument models are available in Sherpa 3.2:

Table 5.1: Summary of Instrument Models

Model	Description
FARF1D | FARF	A 1-D file-based ancillary response model
FARF2D | FEXPMAP | FEXPMAP2D	A 2-D file-based ancillary response model
FPSF1D	A 1-D file-based PSF instrument model
FPSF2D | FPSF | PSFFROMFILE	A 2-D file-based PSF instrument model
FRMF1D | FRMF	A 1-D file-based response matrix model
KERNEL	A 1-D convolution model.
PTSRC1D	A 1-D file-based point-source fitting model
PTSRC2D | PTSRC	A 2-D file-based point-source fitting model
RSP1D | RSP	A 1-D instrument model.
RSP2D	A 2-D instrument model.
TPSF1D	A 1-D TCD-model-based PSF instrument model
TPSF2D | TPSF |PSFFROMTCD | PSF	A 2-D TCD-model-based PSF instrument model

More information on each model is available at the end of this chapter.

5.4.1 Establishing Model Components

The following syntax establishes a model component for usage in the current Sherpa session:

sherpa> $[$CREATE$]$ $<$sherpa_modelname$>$

(The brackets around CREATE indicate that its use is optional; see examples below.) In addition, Sherpa provides the user with the ability to both establish a model component, and to assign to it an arbitrary name:

sherpa> $[$CREATE$]$ $<$sherpa_modelname$>$[$<$modelname$>$]

where $<$sherpa_modelname$>$ is the Sherpa default model name (or an XSPEC model name, with the prefix `xs' attached), and $<$modelname$>$ is the name being given to the model component by the user. Note that $<$modelname$>$ must be enclosed in brackets, $[$ $]$.

Sherpa 's ability to assign arbitrary names to model components allows the user to establish multiple independent models of the same type during a single session, and is a valuable feature of the software. (See Example 7.) Note that an assigned model name can be any arbitrary string, except a string that is already a Sherpa command.

By default, Sherpa will prompt the user for the initial model component parameter values.^5.3At the model parameter prompt, the user may either:

• Enter the $<$RETURN$>$ key to accept the given initial parameter value. Note that if a dataset has not been input, then the initial parameter values are arbitrary default values. However, if a dataset has been input, then the initial parameter values are estimates based on the filtered data and the defined instrument model (see Section 5.4.2 for more information).

• Enter the $<$RETURN$>$ key to accept the given initial parameter value, and subsequently set the parameter value and range using one of the syntax options described in Sections 5.4.3, 5.4.4, and 5.4.5.

• Enter the $<$RETURN$>$ key to accept the given initial parameter value, and subsequently set the parameter value using the GETX or GETY command (see Sections 1.39 and 1.40), which allows the user to assign the value interactively from a plot.

• Enter ,-1 to accept the given initial parameter value, and to set the parameter to be frozen. Note that there cannot be a space between the , and the -1.

• Enter $<$value$>$:$<$min$>$:$<$max$>$$[$:$<$delta$>$$]$$[$,-1$]$, where:

  Argument:	Description:
  $<$value$>$	Model parameter initial value.
  $<$min$>$	Minimum value for that parameter range.
  $<$max$>$	Maximum value for that parameter range.
  $<$delta$>$	Specifies initial parameter step size.
  ,-1	Sets the parameter to be frozen.

  Note that the default setting for delta is 1% of the parameter value. Otherwise, specifying delta will set the initial parameter step size to an absolute value. The parameter step size is used by the optimization method to determine where to sample parameter space. As such, if the value of a parameter is known well, then specifying a small delta may lead to a substantially faster and better fit.

  Note that this colon separated list need not include all of the elements, but it does need to maintain the proper sequential order, and also include the colons around skipped elements (up to three elements only). Also, there cannot be a space between the , and the -1.

The model components that have been established in the current Sherpa session, and their parameter information, may be listed with the command SHOW MODELS. Note however that information about model parameter delta settings is currently not returned by SHOW. Information about model parameter delta settings is included when using SAVE.

Examples:

1. Establish a model component:

   sherpa> CREATE POLY
   POLY.c0 parameter value [1] 
   POLY.c1 parameter value [0] 
   POLY.c2 parameter value [0] 
   POLY.c3 parameter value [0] 
   POLY.c4 parameter value [0] 
   POLY.c5 parameter value [0] 
   POLY.c6 parameter value [0] 
   POLY.c7 parameter value [0] 
   POLY.c8 parameter value [0] 
   POLY.offset parameter value [0]
   

   The command CREATE POLY establishes the Sherpa model POLYNOM1D as a model component available for usage in the current Sherpa session. Note that after issuing this command, the user is prompted for the initial model parameter values. In this example, the user accepted the given initial values for all of the parameters, using the $<$RETURN$>$ key. The following command is equivalent:

   sherpa> POLY
   

2. Establish a model component, and assign it a name:

   sherpa> CREATE POLY[modela]
   modela.c0 parameter value [1]
   modela.c1 parameter value [0]
   modela.c2 parameter value [0]
   modela.c3 parameter value [0]
   modela.c4 parameter value [0]
   modela.c5 parameter value [0]
   modela.c6 parameter value [0]
   modela.c7 parameter value [0]
   modela.c8 parameter value [0]
   modela.offset parameter value [0]
   

   The command CREATE POLY$[$modela$]$ establishes the Sherpa model component POLYNOM1D, and assigns to it the name modela. Note that after issuing this command, the user is prompted for the initial model parameter values. In this example, the user accepted the given initial values for all of the parameters, using the $<$RETURN$>$ key. The following command is equivalent:

   sherpa> POLY[modela]
   

3. Establish a model component, assign it a name, set parameter values and ranges including initial parameter step size, and freeze a parameter:

   sherpa> GAUSS[modelb]
   modelb.fwhm parameter value [10] 2.0:1:10:0.5
   modelb.pos parameter value [0] 1:0.1:
   modelb.ampl parameter value [1] 3::100:2,-1
   

   This example establishes and assigns the name modelb to the Sherpa model component GAUSS1D. Note that in this example the user entered an initial value of 2.0, a minimum range value of 1, a maximum range value of 10, and an initial parameter step size delta of 0.5 for parameter fwhm; entered a value of 1, and a minimum range value of 0.1 for parameter pos; and entered a value of 3, a maximum range value of 100, and an initial parameter step size of 2 for parameter ampl, and froze this parameter.

4. Establish a model component, assign it a name, set parameter values and ranges, and freeze a parameter:

   sherpa> GAUSS[modelbb]
   modelbb.fwhm parameter value [10] 2.0:1:10
   modelbb.pos parameter value [0] 1:0.1:
   modelbb.ampl parameter value [1] 3::100,-1
   

   This example establishes and assigns the name modelbb to the Sherpa model component GAUSS1D. Note that in this example the user entered an initial value of 2.0, a minimum range value of 1, and a maximum range value of 10 for parameter fwhm; entered a value of 1, and a minimum range value of 0.1 for parameter pos; and entered a value of 3, and a maximum range value of 100 for parameter ampl, and froze this parameter (note that after the maximum range value, specification of initial parameter step size delta is optional and may be omitted).

5. Establish an XSPEC model component, assign it a name, and freeze a parameter:

   sherpa> XSBBODY[modeld]
   modeld.kT parameter value [3]
   modeld.norm parameter value [1] ,-1
   

   This command establishes and assigns the name modeld to the XSPEC model component bbody. In this example, the user accepted the given initial values for all of the parameters, using the $<$RETURN$>$ key, and set parameter norm to be frozen (see Section 5.4.11 for further information about freezing and thawing parameters).

6. Turn off model parameter prompting; establish a model component and assign it a name:

   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> POW[modelc]
   

   The first command turns off prompting for model parameter values. The second command establishes the Sherpa model component POWLAW1D, and assigns to it the name modelc. Since parameter prompting was turned off, the model is automatically established using the given initial values for all of the parameters.

7. Establish two independent model components of the same type:

   sherpa> ERASE ALL
   sherpa> PARAMPROMPT ON
   Model parameter prompting is on
   sherpa> POW[modelc]
   modelc.gamma parameter value [0] 1.0
   modelc.ref parameter value [1] 
   modelc.ampl parameter value [1] 
   sherpa> POW[modelc2]
   modelc2.gamma parameter value [0] 2.0
   modelc2.ref parameter value [1] 
   modelc2.ampl parameter value [1]
   

   The third command establishes the Sherpa model component POWLAW1D, and assigns to it the name modelc. In this example, the user set parameter gamma of model component modelc to the value of 1.0. The last command establishes another Sherpa model component POWLAW1D, and assigns to it the name modelc2. In this example, the user set parameter gamma of model component modelc2 to the value of 2.0. Note that model components modelc and modelc2 are independent of one another:

   sherpa> SHOW MODELS
   Current Composite Models are:
   
   Current Model Components are:
   powlaw1d[modelc]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          1        -10         10                      
    2    ref frozen          1-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1     0.0000 3.4028e+38                      
   
   powlaw1d[modelc2]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          2        -10         10                      
    2    ref frozen          1-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1     0.0000 3.4028e+38
   

5.4.2 Automatic Estimates of Initial Parameter Values

It is important to note that when a model component is established, if a dataset has been input, then estimates based on the (filtered) data are automatically made for the initial parameter values and their minimum and maximum ranges. However, if no dataset has been input, then the initial parameter values and ranges are assigned arbitrary default values.

If multiple datasets have been input, and if no dataset is indicated in the model expression, then automatic parameter estimates are based on the lowest numbered dataset; for instance, if the user inputs

sherpa> DATA 1 example1.dat
sherpa> DATA 2 example2.dat
sherpa> POLY[modela]

then the estimates of modela's parameter values are based on the first dataset. Otherwise, if multiple datasets have been input, and a dataset is indicated in the model expression, then the automatic parameter estimates are made based on the indicated dataset; for instance, if the user inputs

sherpa> DATA 1 example1.dat
sherpa> DATA 2 example2.dat
sherpa> SOURCE 2 = POLY[modela]

then the estimates of modela's parameter values are based on the second dataset.

The user may always obtain updated estimates using the command GUESS (see Example 3 of Section 1.43). Updated estimates may be needed if:

• a dataset is input,
• or an instrument model is specified,
• or a dataset filter is changed,
• or a dataset WCS analysis setting is changed,

after a model expression is input.

The user may of course wish to directly set initial parameter values and ranges; see Sections 5.4.1, 5.4.3, 5.4.4, and 5.4.5.

Examples:

1. Establish a model component prior to data input:

   sherpa> ERASE ALL
   sherpa> POW[modelc]
   modelc.gamma parameter value [0] 
   modelc.ref parameter value [1] 
   modelc.ampl parameter value [1] 
   sherpa> SHOW modelc
   powlaw1d[modelc]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          0        -10         10                      
    2    ref frozen          1-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1     0.0000 3.4028e+38
   

   Here, a model component is established prior to input of data, so the given initial model parameter values are pre-set arbitrary defaults. In this example, the user accepts these values using the $<$RETURN$>$ key.

2. Establish a model component after data input:

   sherpa> ERASE ALL
   sherpa> DATA example.pha
   sherpa> POW[modelc]
   modelc.gamma parameter value [0] 
   modelc.ref parameter value [1] 
   modelc.ampl parameter value [0.0010453]
   sherpa> SHOW modelc
   powlaw1d[modelc]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          0        -10         10                      
    2    ref frozen          1          0         94                      
    3   ampl thawed     0.0010     0.0000     0.0021
   

   In this example, the ERASE ALL command is used to remove the previous model setup. Next, data are input, with the command DATA example.pha. This is then followed by the establishment of the model component, with the command POW[modelc]. Notice that the given initial model parameter values and ranges are estimates based on the filtered data. Compare this example to example 1.

3. Establish a model component prior to data input; obtain parameter estimates using GUESS:

   sherpa> ERASE ALL
   sherpa> POW[modelc]
   modelc.gamma parameter value [0] 
   modelc.ref parameter value [1] 
   modelc.ampl parameter value [1] 
   sherpa> DATA example.pha
   sherpa> SHOW modelc
   powlaw1d[modelc]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          0        -10         10                      
    2    ref frozen          1-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1     0.0000 3.4028e+38   
   sherpa> GUESS modelc
   sherpa> SHOW modelc
   powlaw1d[modelc]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          0        -10         10                      
    2    ref frozen          1          0         94                      
    3   ampl thawed     0.0010     0.0000     0.0021
   

   In this example, the ERASE ALL command is used to remove the previous input data and model component setups. Next, a model component is established prior to input of data (with the command POW[modelc]), and so the given initial parameter values are default values. The GUESS command is then used to obtain parameter value and range estimates, based on the input dataset.

5.4.3 Setting Model Parameters and Ranges

The model components that have been established in the current Sherpa session, and their parameter information, may be listed with the command SHOW MODELS. Values for these established model component parameters may be set individually using one of the following command syntax options:

sherpa> $[$CREATE$]$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$} {= $<$value$>$ | =$>$ $<$paramExpr$>$}
sherpa> $[$CREATE$]$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$}.VALUE = $<$value$>$

where:

Argument:	Description:
$<$modelname$>$	A name given to a model component by the user.
{$<$paramname$>$ | $<$#$>$}	Specifies the parameter whose value is to be set.
$<$value$>$	A number value to which the parameter should be set.
=$>$ $<$paramExpr$>$	A syntax for linking parameters.

Note that either $<$paramname$>$ or $<$#$>$ may specify the parameter whose value is to be set.

Note also that parameter values may be set interactively from a plot: Please see command GETX for information on interactively assigning an x-axis value to a model parameter, from a plot; see command GETY for information on interactively assigning a y-axis value.

In addition, the minimum, maximum, and initial delta for parameters may also be individually set, using one of the following applicable command syntax options:

sherpa> $[$CREATE$]$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$}.MIN = $<$value$>$
sherpa> $[$CREATE$]$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$}.MAX = $<$value$>$
sherpa> $[$CREATE$]$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$}.DELTA = $<$value$>$

Examples:

1. Establish a model component, and assign it a name; set a model parameter value:

   sherpa> ERASE ALL
   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> POLY[modela]
   sherpa> modela.c0 = 3.0
   

   The command (modela.c0 = 3.0) gives the value of 3.0 to parameter c0, of modela. Note that modela is the name given by the user to the Sherpa model component POLYNOM1D. The following commands are each equivalent to the final command:

   sherpa> modela.c0.VALUE = 3.0
   sherpa> modela.1 = 3.0
   sherpa> modela.1.VALUE = 3.0
   

2. Establish a model component, and assign it a name; set a model parameter value, and the parameter range limits:

   sherpa> POW[modelc] 
   sherpa> modelc.3 = 10.0 
   sherpa> modelc.3.MIN = 1.0 
   sherpa> modelc.3.MAX = 100.0
   

   The second command, modelc.3 = 10.0, gives the value of 10.0 to parameter number 3, of modelc. The third and fourth commands set the minimum and maximum values for parameter number 3 of this model component.

3. Set initial model parameter step size delta:

   sherpa> modelc.3.DELTA = 0.05
   

   This command sets the parameter's initial step size, delta, to a value of 0.05.

4. Establish two different model components, and assign them names; link one model parameter to another:

   sherpa> ERASE ALL
   sherpa> POLY[modela]
   sherpa> GAUSS[modelb]
   sherpa> modelb.ampl => 0.5*modela.c0
   

   The last command in this series uses a model parameter expression, to link the ampl parameter of modelb to 0.5 multiplied by the c0 parameter of modela.

5.4.4 Setting Model Parameters and Ranges Simultaneously

Alternatively, model parameters and ranges may all be set at one time, using a single command:

sherpa> $[$CREATE$]$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$} = $<$param$>$

where again $<$modelname$>$ is the name that has been given to a model component by the user. Note that either $<$paramname$>$ or $<$#$>$ may specify the parameter whose value is to be set. The command argument $<$param$>$ contains the parameter assignments

$<$value$>$:$<$min$>$:$<$max$>$:$<$delta$>$, where:

Argument:	Description:
$<$value$>$	The value for the model parameter.
$<$min$>$	The minimum for that parameter range.
$<$max$>$	The maximum for that parameter range.
$<$delta$>$	Specifies initial parameter step size.

Examples:

1. Establish a model component, and assign it a name; set a model parameter value, and the parameter range limits:

   sherpa> POW[modelc] 
   sherpa> modelc.3 = 10.0:1.0:100.0
   

   The command modelc.3 = 10.0:1.0:100.0, gives the value of 10.0 to parameter number 3, sets the minimum to 1.0 for this parameter, and sets the maximum to 100.0 for this parameter, of modelc (where modelc is the name given by the user to the Sherpa model component POWLAW1D, with the second command). The following command is equivalent to the third command:

   sherpa> modelc.ampl = 10.0:1.0:100.0
   

   Compare the syntax of this example to Section 5.4.3, Example 2.

2. Set a model parameter value, the parameter range limits, and set the initial parameter step size delta:

   sherpa> modelc.3 = 10.0:1.0:100.0:0.05
   

   This command gives the value of 10.0 to modelc parameter number 3, sets the minimum to 1.0 for this parameter, sets the maximum to 100.0 for this parameter, and sets the parameter's initial step size, delta, to a value of 0.05. Compare the syntax of this example to Section 5.4.3, Example 3.

5.4.5 Establishing Model Components and Setting Parameters Simultaneously

To be especially efficient, one may establish and assign a name to a model component, as well as set model parameters and their ranges, all at one time using a single command:

sherpa> $[$CREATE$]$ $<$sherpa_modelname$>$[$<$modelname$>$]($<$param$>$ $[$,$<$param$>$,$<$param$>$, ...$]$)

where again $<$sherpa_modelname$>$ is the Sherpa default model name and $<$modelname$>$ is the name being given to the model component by the user. Note that $<$modelname$>$ must be enclosed in brackets, $[$ $]$. The sequential order of the comma-separated $<$param$>$ arguments indicates to which model parameter the values will be applied. That is, the first $<$param$>$ argument will apply to the model's first parameter, the second $<$param$>$ to the model's second parameter, etc.

As in the above Subsection, the command argument $<$param$>$ contains the parameter assignments $<$value$>$:$<$min$>$:$<$max$>$:$<$delta$>$, where:

Argument:	Description:
$<$value$>$	The value for the model parameter.
$<$min$>$	The minimum for that parameter range.
$<$max$>$	The maximum for that parameter range.
$<$delta$>$	Specifies initial parameter step size.

The colon separated list for $<$param$>$ need not include all of the elements, but it does need to maintain the proper sequential parameter order.

Examples:

1. Establish a model component, assign it a name, and set parameter values and ranges:

   sherpa> ERASE ALL
   sherpa> POLY[modela](3.0:1.0:4.0)
   

   Assigns the name modela to the Sherpa model component POLYNOM1D. Also gives the value of 3.0 to the model's first parameter (in this case parameter c0), sets the minimum to 1.0 for this parameter, and sets the maximum to 4.0 for this parameter.

2. Establish a model component, assign it a name, and set parameter values:

   sherpa> POW[modelc](1, 5, 10)
   

   Assigns the name modelc to the Sherpa model component POWLAW1D. Also gives the value of 1.0 to the model's first parameter (in this case parameter gamma), gives the value of 5.0 to the model's second parameter (ref), and gives the value of 10.0 to the model's third parameter (ampl).

3. Establish a model component, assign it a name, and set parameter values:

   sherpa> POW[modelc2](,,10.0:1.0:100.0:0.05)
   

   Assigns the name modelc2 to the Sherpa model component POWLAW1D. Also gives the value of 10.0 to the model's third parameter (in this case parameter ampl), sets the minimum to 1.0 for this parameter, sets the maximum to 100.0 for this parameter, and set the initial step size to 0.05 for this parameter.

5.4.6 Establishing Model Components, Setting Parameters, & Defining a Source Model Simultaneously

Model component names may be assigned, model parameters and ranges may be set, and a source or background model may be defined, using a single command:

sherpa> {SOURCE | BACKGROUND} $[$#$]$ = $<$sherpa_modelname$>$[$<$modelname$>$]($<$param$>$ $[$,$<$param$>$,$<$param$>$, ...$]$)

where again $<$sherpa_modelname$>$ is the Sherpa default model name and $<$modelname$>$ is the name being given to the model component by the user. Note that $<$modelname$>$ must be enclosed in brackets, $[$ $]$. The sequential order of the comma-separated $<$param$>$ arguments indicates to which model parameter the values will be applied. That is, the first $<$param$>$ argument will apply to the model's first parameter, the second $<$param$>$ to the model's second parameter, etc.

The command argument $<$param$>$ contains the parameter assignments $<$value$>$:$<$min$>$:$<$max$>$:$<$delta$>$, where:

Argument:	Description:
$<$value$>$	The value for the model parameter.
$<$min$>$	The minimum for that parameter range.
$<$max$>$	The maximum for that parameter range.
$<$delta$>$	Specifies initial parameter step size.

The colon separated list for $<$param$>$ need not include all of the elements, but it does need to maintain the proper sequential parameter order.

Please also see the SOURCE command and the BACKGROUND command for more information and examples.

Examples:

1. Establish a model component, assign it a name, define the parameters, and define it as the source model to be used for fitting:

   sherpa> ERASE ALL
   sherpa> SOURCE = POLY[modela](3.0:1.0:4.0)
   

   With this single command, the name modela is assigned to the Sherpa model component POLYNOM1D, the value of 3.0 is given to the model's first parameter (in this case parameter c0), the minimum of 1.0 is set for this parameter, the maximum of 4.0 is set for this parameter, and then this model is defined as the source model to be used for fitting dataset number 1.

2. Establish multiple model components, assign them names, and use them in a source model expression definition:

   sherpa> SOURCE 2 = GAUSS[modelb](3:2.5:4.403, 1:-10:10, 1:-3.5:3.5) + POW[modelc]
   

   With this single command, the following is performed: the name modelb is assigned to the Sherpa model component GAUSS1D; various parameter values and ranges are set for the parameters of modelb; the name modelc is assigned to the Sherpa model component POWLAW1D; a model expression, which is the sum of these two models, is defined as the source model to be used for fitting dataset number 2.

5.4.7 Creating Model Expressions

Model components can be used to create model expressions, in conjunction with the SOURCE and BACKGROUND commands (which then are used to fit the data), or with model stacks:

sherpa> {SOURCE | BACKGROUND | $<$model_stackname$>$} = $<$modelExpr$>$

Where the model expression, $<$modelExpr$>$, may be composed of one, or more (combined algebraicly), of the following elements:

Model Expression Element:	Description:
$<$sherpa_modelname$>$	A Sherpa default model name.
$<$sherpa_modelname$>$$[$modelname$]$	A name that is being given to a Sherpa model component ($<$modelname$>$ must be enclosed in brackets, $[$ $]$).
$<$modelname$>$	A name that has been given to a Sherpa model component.
$<$nested_model$>$	A nested model.
$<$jointmode_model$>$	A joint-mode model.

A model expression may be an algebraic combination of these elements that may include numerical values and the following operators: + - * / ( ) $<$ $>$ {}.

Note that by default, if a model expression includes a model component that has not previously been established, Sherpa will prompt the user for the initial model parameter values for that model component. Parameter prompting can be turned off using the PARAMPROMPT OFF command.

Examples:

1. Create a simple source model expression containing one model component:

   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> POLY[modela]
   sherpa> SOURCE 1 = modela
   

   The last command in this series assigns a model expression to the source model for dataset number 1. This model expression contains one model component, modela (which is an arbitrary name that the user has given to the Sherpa model component POLYNOM1D).

2. Create a source model expression containing multiple model components:

   sherpa> ATTEN[modelm]
   sherpa> BBODY[modelh]
   sherpa> SOURCE 1 = modelm * modelh
   

   This example establishes two model components, modelm and modelh (which are arbitrary names that the user has given to the Sherpa model components ATTEN and BBODY, respectively). The last command assigns the model expression modelm * modelh to the source model for dataset number 1. The following commands each assign various other model expressions to source models for other datasets:

   sherpa> SOURCE 2 = 10*(modelm + modelh)
   sherpa> SOURCE 3 = (modelm - modelh)/2
   sherpa> SOURCE 4 = 0.5*modelm + 0.7*modelh
   

3. Create a source model expression and establish model components simultaneously:

   sherpa> ERASE ALL
   sherpa> SOURCE 1 = ATTEN[modelm] * BBODY[modelh]
   

   In this example the user assigns the model expression ATTEN[modelm] * BBODY[modelh] to the source model for dataset number 1. Note that this single command is equivalent to the first series of commands in Example 2, above.

4. Create a background model expression:

   sherpa> ERASE ALL
   sherpa> PARAMPROMPT ON
   Model parameter prompting is on
   sherpa> BACKGROUND = (POW[modelc])/2
   modelc.gamma parameter value [0] 
   modelc.ref parameter value [1] 
   modelc.ampl parameter value [1]
   

   This command assigns the model expression (POW[modelc])/2, to the background model for dataset number 1. In this example, via parameter prompting, the user accepted the given initial values for all of the parameters, using the $<$RETURN$>$ key.

5. Create a source model expression that includes a nested model:

    
   sherpa> PARAMPROMPT OFF  
   Model parameter prompting is off
   sherpa> shape = GAUSS
   sherpa> SIN[modeli]
   sherpa> COS[modelj]
   sherpa> SRC = modeli{shape} + modelj
   

   The second command, shape = GAUSS, creates a model stack. The commands SIN[modeli] and COS[modelj] establish and assign names to the Sherpa model components SIN and COS, respectively. The final command assigns the model expression modeli{shape} + modelj, to the source model for dataset number 1. In this example, the model expression is an algebraic combination of a nested model, modeli{shape}, and a model component, modelj. Note that modeli will be evaluated on the output of the model expression shape (i.e.: SRC = SIN(GAUSS(x)) + COS(x)).

6. Create a source model expression involving joint mode 2-D models:

   sherpa> DATA example_img.fits FITSIMAGE
   sherpa> POLY[modelaForAxis1]
   sherpa> GAUSS[modelbForAxis2]
   sherpa> SRC = modelaForAxis1{x1}*modelbForAxis2{x2}
   

   The command POLY[modelaForAxis1] assigns the name modelaForAxis1 to the Sherpa model component POLYNOM1D; likewise the command GAUSS[modelbForAxis2] assigns the name modelbForAxis2 to the Sherpa model component GAUSS1D. The final command assigns the model expression modelaForAxis1{x1}*modelbForAxis2{x2}, to the source model for dataset number 1. This model expression is an algebraic combination of joint-mode models.

5.4.8 Creating Model Stacks

A model stack assigns an arbitrary name to a model expression, for subsequent use in parameter expressions and/or nested models.

sherpa> $<$model_stackname$>$ = $<$modelExpr$>$

where $<$model_stackname$>$ is the name being assigned to the model expression.

See Section 5.4.7 Example 5, Section 5.4.9, and Section 5.4.12 Example 3 for further examples.

Examples:

1. Create a model stack for use in a parameter expression:

   sherpa> ERASE ALL
   sherpa> GAUSS[modelb]
   sherpa> SRC = modelb 
   sherpa> PositionVariation = POLY
   sherpa> modelb.pos => PositionVariation
   

   The command GAUSS[modelb], assigns the name modelb to the Sherpa model component GAUSS1D. The next command defines this model component as the source model to be used for fitting. The third command, PositionVariation = POLY, assigns a model stack name to the Sherpa default model POLYNOM1D. The final command creates a parameter expression that links the parameter pos of modelb to the model component POLY (via the model stack name PositionVariation). Note that the creation of a model stack is necessary since the following syntax is currently not allowed:
   modelb.pos => POLY.

2. Create multiple model stacks for use in parameter expressions:

   sherpa> ERASE ALL
   sherpa> SRC = GAUSS[modelb]
   sherpa> PositionVariation = POLY[modela]
   sherpa> fwhmVariation = POLY[modelaa]
   sherpa> modelb.pos => PositionVariation
   sherpa> modelb.fwhm => fwhmVariation
   

   This example creates two different model stacks, and assigns the names PositionVariation and fwhmVariation to the model stacks. These model stack names are then used in parameter expressions, to link different parameters of modelb to different model components: the command modelb.fwhm => fwhmVariation, for example, links the parameter fwhm of modelb to the model component modelaa (via the model stack name fwhmVariation).

3. Create a model stack for use in a nested model:

   sherpa> SHLOGE[modelk]
   sherpa> independent = SIN[modeli] + COS[modelj]
   sherpa> SOURCE = modelk{independent}
   

   The command SHLOGE[modelk] assigns the name modelk to the Sherpa model component SHLOGE. Next, the user assigns a model stack name (independent) to the model expression SIN[modeli] + COS[modelj]. With the final command, the user then assigns the model expression modelkindependent, to the source model for dataset number 1. This source model expression is a nested model, which utilizes the model stack. Note that the model stack definition is necessary since the following syntax is not allowed:
   SOURCE = modelk{SIN[modeli] + COS[modelj]}.

5.4.9 Creating Nested Models

Nested models define the function argument, on which a model expression is evaluated, to be another model expression.

A nested model, $<$nested_model$>$, appears as an element of a model expression, $<$modelExpr$>$, and is constructed using one of the following syntax options:

$<$sherpa_modelname$>${$<$model_stackname$>$}
$<$sherpa_modelname$>$[$<$modelname$>$]{$<$model_stackname$>$}
$<$modelname$>${$<$model_stackname$>$}

where $<$model_stackname$>$ must be enclosed in curly braces, { }, and where the model stack defines the model expression for the function argument.

See Section 5.4.7 Example 5, and Section 3, Example 3, for further examples.

Examples:

1. Create a nested model that defines one model component as the argument for another:

   sherpa> ERASE ALL
   sherpa> oscillation = SIN
   sherpa> SRC = SHLOGE{oscillation}
   

   The user first assigns a model stack name to the Sherpa default model SIN. The final command establishes the nested model, SHLOGE{oscillation}, and assigns it to the source model for dataset number 1. This nested model defines the function argument SIN, over which the model component SHLOGE is to be evaluated. Note that the following syntax is not allowed:
   SRC = SHLOGE{SIN}.

2. Create two layers of nested models:

    
   sherpa> stackA = POLY
   sherpa> stackB = GAUSS{stackA}
   sherpa> SIN[modeli]
   sherpa> SOURCE = modeli{stackB}
   

   The command stackA = POLY creates the first model stack. The next command creates a second model stack, using the nested model construction, GAUSS{stackA}, where the function argument on which the model component GAUSS is evaluated is the first model stack. Finally, the source model expression is defined as the nested model modeli{stackB} (i.e. modeli evaluated upon the second model stack).

5.4.10 Creating Joint-Mode Models

Joint-mode models define the function argument, on which a model expression is evaluated, to be a particular data axis.

A joint-mode model, $<$jointmode_model$>$, may appear as an element of a model expression, $<$modelExpr$>$, and is constructed using one of the following syntax options:

$<$sherpa_modelname$>${$<$axis$>$}
$<$sherpa_modelname$>$[$<$modelname$>$]{$<$axis$>$}
$<$modelname$>${$<$axis$>$}

where $<$axis$>$ must be enclosed in curly braces, { }, and where $<$axis$>$ is a data column name. Note that $<$axis$>$ defines the particular data axis on which the model expression is to be evaluated.

See Section 5.4.7 Example 6 for an additional example.

Examples:

1. Create 2-D joint-mode models that define data axes as the arguments for model components:

   sherpa> DATA example_img.fits FITSIMAGE
   sherpa> LORENTZ[SpatialModelAxis0](98:5:200, 70:50:90, 1:1:200)
   sherpa> POWLAW1D[SpecModelAxis1]
   sherpa> SRC 1 = SpatialModelAxis0{x1}*SpecModelAxis1{x2}
   

   The command LORENTZ[SpatialModelAxis0](98:5:200, 70:50:90, 1:1:200) assigns the name SpatialModelAxis0 to the Sherpa model component LORENTZ1D, and assigns various parameters values and ranges. Similarly, a second model component is established and assigned a name. The final command assigns the model expression SpatialModelAxis0{x1}*SpecModelAxis1{x2}, to the source model for dataset number 1. This source model expression is an algebraic combination of joint-mode models, where these joint-mode models each define a specific data axis as the argument for a model component. So with this source model expression, the joint-mode model SpatialModelAxis0{x1} will fit model SpatialModelAxis0 to Axis 0 (x1) of the data, and the joint-mode model SpecModelAxis1{x2} will jointly fit model SpecModelAxis1 to Axis 1 (x2) of the data, etc.

5.4.11 Freezing & Thawing Model Parameters

Model parameters may be frozen or thawed using one of the following equivalent commands:

sherpa> $<$modelname$>$.$<$paramname$>$.TYPE = {FREEZE | THAW}
sherpa> $<$modelname$>$.$<$#$>$.TYPE = {FREEZE | THAW}
sherpa> {FREEZE | THAW} $<$modelname$>$.{$<$paramname$>$ | $<$#$>$} $\backslash$
$[$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$} ...$]$

In addition, all parameters of a model component may be frozen or thawed at once using:

sherpa> {FREEZE | THAW} $<$modelname$>$

And, all parameters of a source model's components may be frozen or thawed at once using:

sherpa> {FREEZE | THAW} SOURCE $[$#$]$

where # may specify the number of the dataset (default dataset number is 1).

With parameter prompting on, a model parameter may be frozen by entering $[$$<$value$>$:$<$min$>$:$<$max$>$$]$,-1 at the model parameter value prompt, where the -1 sets the parameter to be frozen. (see Example 2, below).

See the FREEZE command and the THAW command for more information and further examples.

Examples:

1. Freeze a model parameter:

   sherpa> PARAMPROMPT OFF
   sherpa> GAUSS[modelb]
   sherpa> modelb.ampl.TYPE = FREEZE
   

   This command freezes the parameter ampl of modelb. The following commands are each equivalent:

   sherpa> modelb.3.TYPE = FREEZE
   sherpa> FREEZE modelb.ampl
   sherpa> FREEZE modelb.3
   

2. Freeze model parameters:

   sherpa> ERASE ALL
   sherpa> PARAMPROMPT ON
   Model parameter prompting is on
   sherpa> GAUSS[modelb]
   modelb.fwhm parameter value [10] 2,-1
   modelb.pos parameter value [0] ,-1
   modelb.ampl parameter value [1] 
   sherpa> SHOW modelb
   gauss1d[modelb]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   fwhm frozen          2 1.1755e-38 3.4028e+38                      
    2    pos frozen          0-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1-3.4028e+38 3.4028e+38
   

   In this example, parameters are frozen by entering $<$value$>$, -1 at the model parameter value prompt. Note that , -1 at the model parameter value prompt accepts the given initial parameter value and freezes that parameter.

3. Freeze all model parameters at once; thaw all source parameters at once:

   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> DATA data/example.pha
   sherpa> GAUSS[modelc]
   sherpa> SOURCE = modelb + modelc
   sherpa> FREEZE modelc
   sherpa> SHOW SOURCE
   (modelb + modelc)
   gauss1d[modelb]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   fwhm frozen          2 1.1755e-38 3.4028e+38                      
    2    pos frozen          0-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1-3.4028e+38 3.4028e+38                      
   gauss1d[modelc]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   fwhm frozen     0.7113     0.0071    71.1283                      
    2    pos frozen     0.9442     0.0276    14.5494                      
    3   ampl frozen     0.0001 1.0564e-06     0.0106                      
   sherpa> THAW SOURCE
   sherpa> SHOW SOURCE
   (modelb + modelc)
   gauss1d[modelb]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   fwhm thawed          2 1.1755e-38 3.4028e+38                      
    2    pos thawed          0-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1-3.4028e+38 3.4028e+38                      
   gauss1d[modelc]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   fwhm thawed     0.7113     0.0071    71.1283                      
    2    pos thawed     0.9442     0.0276    14.5494                      
    3   ampl thawed     0.0001 1.0564e-06     0.0106
   

   Note that the command FREEZE modelc freezes all parameters of the source model component modelc, while THAW SOURCE thaws all parameters of both source model components.

5.4.12 Linking Model Parameters

Parameter expressions are used to link model component parameters:

sherpa> $[$CREATE$]$ $<$modelname$>$.{$<$paramname$>$ | $<$#$>$} =$>$ $<$paramExpr$>$

where again $<$modelname$>$ is the name that has been given to a model component by the user. Note that either $<$paramname$>$ or $<$#$>$ may specify a parameter. The parameter expression, $<$paramExpr$>$, to which the parameter is being linked, may be composed of one, or more (combined algebraicly), of the following elements:

Element:	Description:
$<$modelname$>$.{$<$paramname$>$ | $<$#$>$}	A model component parameter.
$<$model_stackname$>$	A model expression, specified via a model stack name.

A parameter expression may be an algebraic combination of these elements that may include numerical values and the following operators: + - * / ( ) $<$ $>$ {}.

The command UNLINK may be used to remove a link between model parameters:

sherpa> UNLINK $<$modelname$>$.{$<$paramname$>$ | $<$#$>$}

Examples:

1. Link one model parameter to another:

   sherpa> ERASE ALL
   sherpa> PARAMPROMPT ON
   Model parameter prompting is on
   sherpa> GAUSS[modelb]
   modelb.fwhm parameter value [10] 
   modelb.pos parameter value [0] 
   modelb.ampl parameter value [1] 
   sherpa> GAUSS[modelf]
   modelf.fwhm parameter value [10] 
   modelf.pos parameter value [0] 
   modelf.ampl parameter value [1] 
   sherpa> modelf.ampl => 0.5*modelb.ampl
   

   The last command in this series uses a model parameter expression, to link the ampl parameter of modelf to 0.5 multiplied by the ampl parameter of modelb. That is, the amplitudes of two Gaussian models are linked, where one is half that of the other. Note that model parameter expressions cannot be created within the model parameter prompting. Note that the link may be removed as follows:

   sherpa> UNLINK modelf.ampl
   

2. Link one model parameter to another:

   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> POW[modelc]
   sherpa> POW[modele]
   sherpa> modelc.1 => modele.1
   sherpa> modelc.3 => 2*modele.3 - modele.3
   

   The next-to last command in this series links the first parameter (gamma) of modelc to the first parameter of modele. The last command in this series links the third parameter (ampl) of modelc to the parameter expression: 2 multiplied by the third parameter of modele, minus the third parameter of modele. Note that the links may be removed as follows:

   sherpa> UNLINK modelc.1
   sherpa> UNLINK modelc.3
   

3. Link a model parameter to a model expression:

   sherpa> ERASE ALL 
   sherpa> SIN[modeli]
   sherpa> SOURCE = modeli
   sherpa> PeriodVariation = POLY[modela]
   sherpa> modeli.period => PeriodVariation
   

   The first command, SIN[modeli], assigns the name modeli to the Sherpa model component SIN. The second command defines this model component as the source model to be used for fitting. The third command, PeriodVariation = POLY[modela], creates a model stack. The final command links the parameter period of modeli to the parameter expression PeriodVariation (which is composed of the model component modela). Note that the following parameter expression syntax is currently not allowed:
   modeli.period => POLY[modela].

5.4.13 Controlling the Integration of Model Components

The user can turn on and off the integration of non-XSPEC, non-instrument model components:

sherpa> $<$modelname$>$ INTEGRATE $<$ON|OFF$>$

Changing the integration status of a model component will only have an affect if binned data are being fit (e.g. PHA or histogram data).

The default integration status for each model is provided in Table 5.9, while the SHOW command can be used to determine whether a model component is currently being integrated.

The user must be careful not to define an unacceptable mixture of additive/integrated and multiplicative/non-integrated model components, such as by adding two model components with different integration statuses. Sherpa will issue a warning when it detects such an unacceptable mixture.

Example:

1. Turn off integration for a power-law model component:

   sherpa> POWLAW1D[p]
   sherpa> SHOW p
   powlaw1d[p]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          0        -10         10                      
    2    ref frozen          1-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1      1e-20 3.4028e+38                      
   sherpa> p INTEGRATE OFF
   sherpa> SHOW p
   powlaw1d[p]  (integrate: off)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  gamma thawed          0        -10         10                      
    2    ref frozen          1-3.4028e+38 3.4028e+38                      
    3   ampl thawed          1      1e-20 3.4028e+38
   

5.5 Summary of Available Models

Table 5.9: Summary of Models

$<$sherpa_modelname$>$	Description	Integration
ATTEN	Attenuation by ISM.	OFF
BBODY | BB	Blackbody as a function of energy.	ON
BBODYFREQ	Blackbody as a function of frequency.	ON
BETA1D	1-D surface brightness beta-model.	OFF
BETA2D | LORPOW2D	2-D Lorentzian with varying power law.	ON
BOX1D	1-D box function.	OFF
BOX2D	2-D box function.	OFF
BPL1D	Broken power law function.	ON
CONST1D | CONST	1-D constant amplitude model.	ON
CONST2D	2-D constant amplitude model.	ON
COS	Cosine function.	OFF
DELTA1D	1-D delta function.	ON
DELTA2D	2-D delta function.	ON
DEVAUCOULEURS	DeVaucouleurs profile.	ON
DERED	Dereddening function.	OFF
EDGE	Photoabsorption edge model.	OFF
ERF	A 1-D error function.	OFF
ERFC	A 1-D complementary error function.	OFF
FARF1D | FARF	A 1-D file-based ancillary response model	N/A
FARF2D | FEXPMAP | FEXPMAP2D	A 2-D file-based ancillary response model	N/A
FPSF1D	A 1-D file-based PSF instrument model	N/A
FPSF2D | FPSF | PSFFROMFILE	A 2-D file-based PSF instrument model	N/A
FRMF1D | FRMF	A 1-D file-based response matrix model	N/A
GAUSS1D | GAUSS	1-D unnormalized Gaussian function.	ON
GAUSS2D	2-D unnormalized Gaussian function.	ON
GRIDMODEL	N-D user-specified amplitude model.	OFF
HIGHPASS | STEPHI1D	1-D step function.	OFF
HUBBLE | REYNOLDS	Hubble-Reynolds profile.	ON
JDPILEUP	John Davis (MIT) pileup model.	OFF
KERNEL	A 1-D convolution model.	N/A
LINEBROAD	Line broadening profile.	ON
LORENTZ1D | LORENTZ	1-D normalized Lorentzian function.	ON
LORENTZ2D	2-D unnormalized Lorentzian function.	ON
LORPOW2D | BETA2D	2-D Lorentzian with varying power law.	ON
LOWPASS | STEPLO1D	1-D step function.	OFF
NBETA	1-D normalized beta function.	ON
NGAUSS1D	1-D normalized Gaussian function.	ON
PILEUP	1-D pileup model function.	N/A
POISSON	Poisson function.	OFF
POLYNOM1D | POLY	1-D polynomial function.	ON
POLYNOM2D	2-D polynomial function.	ON
POWLAW1D	1-D power law.	ON
PTSRC1D	A 1-D file-based point-source fitting model	OFF
PTSRC2D | PTSRC	A 2-D file-based point-source fitting model	OFF
REYNOLDS | HUBBLE	Hubble-Reynolds profiles.	ON
RSP1D | RSP	A 1-D instrument model.	N/A
RSP2D	A 2-D instrument model.	N/A
SCHECHTER	Schechter function.	OFF
SHEXP10	Exponential function, base 10.	OFF
SHEXP	Exponential function.	OFF
SHLOG10	Logarithm function, base 10.	OFF
SHLOGE | SHLOG	Natural logarithm function.	OFF
SIN	Sine function.	OFF
SQRT	Square root function.	OFF
STEPHI1D | HIGHPASS	1-D step function.	OFF
STEPLO1D | LOWPASS	1-D step function.	OFF
TAN	Tangent function.	OFF
TPSF1D	A 1-D TCD-model-based PSF instrument model	N/A
TPSF2D | TPSF |PSFFROMTCD | PSF	A 2-D TCD-model-based PSF instrument model	N/A
USERMODEL	User implemented model.	OFF
XS$<$xspecname$>$	An XSPEC model function.	N/A

The last column in Table 5.9 indicates whether the model is integrated by default when fit to binned data: ON indicates that the model is integrated by default. In section 5.4.13, we describe the INTEGRATE $<$ON|OFF$>$ command, which allows the user to change the integration status of a non-XSPEC, non-instrument model components.

In the remainder of this chapter, we describe each of the models listed above, in alphabetical order. Each model section includes a description of the model, and a table listing of the model parameters. The listing of model parameters includes the Sherpa parameter number, and the corresponding Sherpa parameter name ($<$paramname$>$).

5.6 ATTEN

Attenuation by ISM. Integration OFF.

This model calculates the transmission of the interstellar medium using the description of the ISM absorption of Rumph, Bowyer, & Vennes 1994, AJ 107, 2108. It includes neutral He autoionization features. Between 1.2398 and 43.655 Angstroms (i.e. in the 0.28-10 keV range) the model also accounts for metals as described in Morrison & MacCammon 1983, ApJ 270, 119.

The code uses the best available photoionization cross-sections to date from the atomic data literature and combines them in an arbitrary mixture of the three ionic species: HI, HeI, and HeII.

The model assumes that the data are expressed in Angstroms.

This model provided courtesy of Pat Jelinsky.

Table 5.10: ATTEN Parameters

Number	Name	Description
1	hcol	N(HI) column (atoms ${\rm cm}^{-2}$)
2	heiRatio	N(HeI)/N(HI)
3	heiiRatio	N(HeII)/N(HI)

5.7 BBODY | BB

Blackbody as a function of energy. Integration ON.

Blackbody emission calculated as a function of energy using the expression:

$$f(E) = A \frac{E^2}{\exp(\frac{E}{kT}) - 1}$$ (5.2)

where $E$ is the photon energy, and $kT$ is the blackbody temperature (expressed in the same units as the photon energy). The amplitude $A$ is related to the ratio of source radius to distance:

$$A = \frac{2{\pi}}{c^2h^3}\left(\frac{R}{d}\right)^2~=~9.884{\times}10^{31}\left(\frac{R}{d}\right)^2 ,$$ (5.3)

with Planck's constant $h$ specified in keV-s and the speed of light $c$ specified in cm/s, and with $R$ and $d$ representing the radius of, and distance to, the source respectively. If $E/kT < 10^-4, f(E) = AEkT$, while if $E/kT > 60, f(E) = 0$.

Table 5.11: BBODY Parameters

Number	Name	Description
1	space	0: energy $\vert$ 1: wavelength
2	kT	temperature $kT$ (in energy units)
3	ampl	amplitude $A$

5.8 BBODYFREQ

Blackbody as a function of frequency. Integration ON.

Blackbody emission calculated as a function of ${\rm frequency~} \nu$ using Wien's law ( $h\nu \gg kT$):

$$f(\nu) = A \frac{2h\nu^3}{c{^2}} \exp(-\frac{h\nu}{kT})$$ (5.4)

where $A$ is the amplitude, $T$ is the temperature in Kelvin, and $h, c, {\rm and~} k$ are Planck's constant, the speed of light, and Boltzmann's constant, respectively.

Table 5.12: BBODYFREQ Parameters

Number	Name	Description
1	T	temperature $T$ (K)
2	ampl	amplitude $A$

5.9 BETA1D

1-D surface brightness beta-model. Integration OFF

1-D surface brightness beta-model:

$$f(x) = A\left(1 + \left[\frac{x-x_o}{r_o}\right]^2\right)^{-3{\beta}+\frac{1}{2}}$$ (5.5)

Table 5.13: BETA1D Parameters

Number	Name	Description
1	r_o	core radius $r_{\rm o}$
2	beta	$\beta$ index
3	xpos	offset $x_o$ from $x = 0$
4	ampl	amplitude $A$ at $x = x_o$

5.10 BETA2D | LORPOW2D

2-D Lorentzian with varying power law. Integration OFF. The LORPOW2D model is equivalent.

A 2-D Lorentz model with a varying power law, also known as a Beta model:

$$f(x,y) = f(r)~=~\frac{A}{(1+(\frac{r}{r_0})^2)^{\alpha}}$$ (5.6)

where

$$r(x,y) = \frac{\sqrt{x_{\rm new}^2(1-{\epsilon})^2 + y_{\rm new}^2}}{1-{\epsilon}}$$ (5.7)

$$x_{\rm new} = (x - x_{\rm o})\cos{\theta} + (y - y_{\rm o})\sin{\theta}$$ (5.8)

and

$$y_{\rm new} = (y - y_{\rm o})\cos{\theta} - (x - x_{\rm o})\sin{\theta}$$ (5.9)

Table 5.14: BETA2D Parameters

Number	Name	Description
1	r0	core radius $r_0$
2	xpos	x mean position $x_o$
3	ypos	y mean position $y_o$
4	ellip	ellipticity $\epsilon$
5	theta	angle of ellipticity $\theta$
6	ampl	amplitude $A$ at $(x_o, y_o)$
7	alpha	power law index $\alpha$

5.11 BOX1D

1-D box function. Integration OFF.

A 1-D box model:

$$f(x)~=~A~~~~~~{\rm if}~x_{\rm low} \leq x \leq x_{\rm hi}$$ (5.10)

$$f(x)~=~0~~~~~~~{\rm otherwise}$$ (5.11)

Table 5.15: BOX1D Parameters

Number	Name	Description
1	xlow	low cut-off $x_{\rm low}$
2	xhi	high cut-off $x_{\rm hi}$
3	ampl	amplitude $A$

5.12 BOX2D

2-D box function. Integration OFF.

A 2-D box model:

$$f(x,y) = A$$ (5.12)

if $x_{\rm low} \leq x \leq x_{\rm hi}$ and $y_{\rm low} \leq y \leq y_{\rm hi}$ ,

$$f(x,y)~=~0~~~~~~~{\rm otherwise}$$ (5.13)

Table 5.16: BOX2D Parameters

Number	Name	Description
1	xlow	low x cut-off $x_{\rm low}$
2	xhi	high x cut-off $x_{\rm hi}$
3	ylow	low y cut-off $y_{\rm low}$
4	yhi	high y cut-off $y_{\rm hi}$
5	ampl	amplitude $A$

5.13 BPL1D

Broken power law function. Integration ON.

A broken power-law model:

$$f(x) = A\left(\frac{x}{x_{\rm ref}}\right)^{-\gamma_1}$$ (5.14)

if $x \leq x_b$, and

$$= A'\left(\frac{x}{x_{\rm ref}}\right)^{-\gamma_2}$$ (5.15)

otherwise, where

$$A' = A \left(\frac{x_b}{x_{\rm ref}}\right)^{\gamma_2-\gamma_1}$$ (5.16)

Table 5.17: BPL1D Parameters

Number	Name	Description
1	gamma1	first power law photon index $\gamma_1$
2	gamma2	second power law photon index $\gamma_2$
3	eb	break-point $x_b$
4	ref	normalization reference point $x_{ref}$
5	ampl	amplitude $A$

5.14 CONST1D | CONST

1-D constant amplitude model. Integration ON.

A 1-D constant amplitude model:

$$f(x) = A$$ (5.17)

A is limited to being $>0$. To model negative constant amplitudes, multiple by -1 in Sherpa:

sherpa> source = (-1)*const[cs]

Table 5.18: CONST1D Parameter:

Number	Name	Description
1	c0	amplitude $A$

5.15 CONST2D

2-D constant amplitude model. Integration ON.

A 2-D constant amplitude model:

$$f(x) = A$$ (5.18)

Table 5.19: CONST1D Parameter:

Number	Name	Description
1	c0	amplitude $A$

5.16 COS

Cosine function. Integration OFF.

A 1-D cosine model:

$$f(x) = A {\cos}\left(\frac{2\pi(x-x_{\rm off})}{P}\right)$$ (5.19)

Table 5.20: COS Parameters

Number	Name	Description
1	period	period $P$, in units of x
2	offset	x offset $x_{\rm off}$
3	ampl	amplitude $A$

5.17 DELTA1D

1-D delta function. Integration ON.

A 1-D delta-function model:

$$f(x) = A$$ (5.20)

if $x = x_o$, and

$$= 0$$ (5.21)

otherwise.

with

$$\int_{-\infty}^{+\infty} dx f(x)~=~A \,.$$ (5.22)

Table 5.21: DELTA1D Parameters

Number	Name	Description
1	pos	position $x_o$
2	ampl	amplitude $A$

5.18 DELTA2D

2-D delta function. Integration ON.

A 2-D delta-function model:

$$f(x,y) = A$$ (5.23)

if $x = x_o$ and $y = y_o$,

and,

$$f(x,y) = 0$$ (5.24)

otherwise.

with

$$\int_{-\infty}^{+\infty} \int_{-\infty}^{+\infty} dx dy f(x,y)~=~A$$ (5.25)

Table 5.22: DELTA2D Parameters

Number	Name	Description
1	xpos	x position $x_o$
2	ypos	y position $y_o$
3	ampl	amplitude $A$

5.19 DERED

Dereddening function. Integration OFF.

This dereddening model uses the analytic formula for the mean extension law described in Cardelli, Clayton, & Mathis 1989, ApJ 345, 245:

$$A(\lambda ) = E(B-V) \left( a R_v + b \right) = 1.086 \tau(\lambda)$$ (5.26)

where $\tau(\lambda)$ is the wavelength-dependent optical depth,

$$I(\lambda) = I (0) \exp\left( -\tau(\lambda) \right)$$ (5.27)

and $a$ and $b$ are computed using wavelength-dependent formulae which we will not reproduce here, for the wavelength range 1000 Å - 3.3 microns. The relationship between the color excess and the column density is

$$E(B-V) = \frac{N_{H{\rm gal}} (10^{20} {\rm cm}^{-2})}{58.0}$$ (5.28)

(Bohlin, Savage, & Drake 1978, ApJ 224, 132). The value of the ratio of total to selective extinction, $R_v$, is initially set to 3.1, the standard value for the diffuse ISM. The final model form is:

$$I(\lambda) = I(0) \exp\left [-\frac{N_{H{\rm gal}} \left[a R_v + b\right]}{58.0 \times 1.086}\right]$$ (5.29)

This model should only be used as a multiplicative model:

sherpa> powlaw1d[con1](1.,2588.6,0.1)
sherpa> dered[dr](3.1,0.1)
sherpa> source 1 = con1*dr

This model provided courtesy of Karl Forster.

Table 5.23: DERED Parameters

Number	Name	Description
1	rv	total to selective extinction ratio $R_v$
2	nhgal	absorbing column density $N_{H{\rm gal}}$

5.20 DEVAUCOULEURS

DeVaucouleurs profile. Integration OFF.

A 2-D de Vaucouleurs model:

$$f(x,y) = f(r) = A\exp\left[-7.67\left(\sqrt{\left[\frac{x_{\rm ma... ...ght]^2 + \left[\frac{x_{\rm min}}{r_{\rm min}}\right]^2}\right)^{0.25}-1\right]$$ (5.30)

where

$$r_{\rm maj} = r_0$$ (5.31)

$$r_{\rm min} = (1-\epsilon)r_0$$ (5.32)

$$x_{\rm maj} = (x-x_{\rm o}){\cos}{\theta} + (y-y_{\rm o}){\sin}{\theta}$$ (5.33)

$$x_{\rm min} = -(x-x_{\rm o}){\sin}{\theta} + (y-y_{\rm o}){\cos}{\theta}$$ (5.34)

Table 5.24: DEVAUCOULEURS Parameters

Number	Name	Description
1	r0	core radius $r_0$
2	xpos	x mean position $x_{/rm o}$
3	ypos	y mean position $y_{\rm o}$
4	ellip	ellipticity $\epsilon$
5	theta	angle of ellipticity $\theta$
6	ampl	amplitude $A$ at $(x_o, y_o)$

5.21 EDGE

Photoabsorption edge model. Integration OFF.

A phenomenological photoabsorption edge model as a function of energy:

$$f'(x) = f(x)$$ (5.35)

if $x < E_b$, and

$$f(x) \exp\left[-A\left(\frac{x}{E_b}\right)^{-3}\right]$$ (5.36)

otherwise.

Or, as a function of wavelength:

$$f'(x) = f(x)$$ (5.37)

if $x > {\lambda}_b$, and

$$= f(x) \exp\left[-A\left(\frac{x}{{\lambda}_b}\right)^3\right]$$ (5.38)

otherwise.

Table 5.25: EDGE Parameters

Number	Name	Description
1	space	energy (0) or wavelength (1)
2	thresh	edge position $E_b$ or $\lambda_b$
3	abs	absorption coefficient $A$

5.22 ERF

A 1-D error function. Integration OFF.

$$f(x)~=~A\,\mathrm{erf}\left(\frac{x - x_{\rm off}}{\sigma}\right)$$ (5.39)

where

$$\mathrm{erf}(y)~=~\frac{2}{\sqrt\pi}\,\int_{0}^{y}\exp\left[-t^2\right]dt$$ (5.40)

Table 5.26: ERF Parameters

Number	Name	Description
1	ampl	amplitude $A$
2	offset	offset $x_{\rm off}$
3	sigma	scaling factor $\sigma$

erf is related to erfc, a complementary error function:

	erfc(y) = 1 - erf(y)

See ERFC for information on that function.

5.23 ERFC

A 1-D complementary error function. Integration OFF.

$$f(x)~=~A\,\mathrm{erfc}\left(\frac{x - x_{\rm off}}{\sigma}\right)$$ (5.41)

where

$$\mathrm{erfc}(y)~=~\frac{2}{\sqrt\pi}\,\int_{y}^{\infty}\exp\left[-t^2\right]dt$$ (5.42)

Table 5.27: ERF Parameters

Number	Name	Description
1	ampl	amplitude $A$
2	offset	offset $x_{\rm off}$
3	sigma	scaling factor $\sigma$

erfc is related to erf, a 1-D error function:

	erfc(y) = 1 - erf(y)

See ERF for information on that function.

5.24 FARF1D | FARF

A 1-D file-based ancillary response model.

FARF is a file-based ARF model that represents an ancillary response vector (e.g., the effective area as a function of energy/wavelength).

Note that in Sherpa analyses, the energy-space binning of the ARF (found typically in the ENERG_LO and ENERG_HI columns of the SPECRESP extension of the ARF file) does not have to match the analogous energy-space binning of a matching RMF. (This is also true if instead of energy, the ARF is defined as a function of wavelength.)

See the documentation on the INSTRUMENT command. See also the RSP and FRMF instrument models.

Table 5.28: FARF Parameters

Number	Name	Description
1	arf	ARF file name
2	norm	normalization

5.25 FARF2D | FEXPMAP | FEXPMAP2D

A 2-D file-based ancillary response model. Alternate names include FEXPMAP and FEXPMAP2D.

FARF2D is a file-based model whose primary use is to represent 2-D exposure maps in arbitrary units (seconds, ${\rm cm^2}$, etc.).

Note the following about exposure maps:

$\bullet$

The exposure map image must be of the same size as the data image, and it must have the same plate-scale (i.e., bins in each image must have the same size in arc-seconds, etc.).

$\bullet$

If an exposure map and a point-spread function (PSF) are to be used in the same instrument stack, then the images containing both must have the same plate-scale.

See the documentation on the INSTRUMENT command. See also the RSP2D instrument model.

Table 5.29: FARF2D Parameters

Number	Name	Description
1	file	exposure map file name
2	norm	normalization

Examples:

1. Input an exposure map for use with a dataset:

   sherpa> DATA data/data.fits
   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> FEXPMAP[emap]
   sherpa> emap.file = "data/data_expmap.fits"
   sherpa> INSTRUMENT = emap
   

   In this example, the instrument model component FEXPMAP is established, the exposure map file is input using this model's file parameter, and the instrument model stack is set for dataset number 1.

   The CIAO 2.3 equivalent of this command is:

   sherpa> DATA data/data.fits
   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> GRIDMODEL[gm]
   sherpa> gm.file = "data/data_expmap.fits"
   sherpa> EXPMAP 1 = gm
   

2. Use a point-spread function file in addition to an exposure map:

   sherpa> FEXPMAP[emap]
   sherpa> emap.file = "data/data_expmap.fits"
   sherpa> FPSF[psfunc]
   sherpa> psfunc.file = "data/data_psf.fits"
   sherpa> INSTRUMENT = emap*psfunc
   

   This may also be done with the RSP2D command:

   sherpa> RSP2D[r]
   sherpa> r.empfile = "data/data_expmap.fits"
   sherpa> r.psffile = "data/data_psf.fits"
   sherpa> INSTRUMENT = r
   

5.26 FPSF1D

A 1-D file-based PSF instrument model.

FPSF1D is a file-based PSF model that represents the point-spread function, a redistribution function that maps photon locations to data bins.

This model cannot be used in a source model expression. See PTSRC1D model if you want to fit the data with the PSF model file.

ASCII and FITS formats are allowed for the input model file . The current implementation requires that the bin size of the data and the PSF model file are the same. The number of bins can be different.

Note that the input file is automatically renormalized to 1 upon entry. Renormalization is done by summing over all bins, regardless of the setting of xsize.

The input PSF array is used to convolve (fold) a given source model. This convolution can be performed using either Fast Fourier Transforms (FFTs, the default), or the sliding cell technique (see the parameter fft). If the axis length is $N$ and the length of the kernel axis is $M (= 2 \times {\tt xsize} + 1)$, then the computation time for the sliding cell goes as $N \times M$, i.e., for large kernels the best choice is using the FFT. A rough rule-of-thumb for 1-D fits is to use the FFT if $M > 10$.

"xsize" parameter defines the number of bins extracted from the file to be used in the PSF model.

xoff $=$ 0, the PSF (kernel) sub-array is extracted from the center of the original array contained in the input PSF file.

Note that the kernel centroid must always be at the center of the extracted sub-array! Otherwise, systematic shifts will occur in best-fit positions of point sources.

In Sherpa version 3.0.2, a new parameter is introduced: radial. If set to 1 the kernel array will be extended and its values reflected across the edge boundary. The resultant function will be symmetric. The default value is 0.

See the documentation on the INSTRUMENT command.

Table 5.30: FPSF1D Parameters

Number	Name	Description
1	file	input file name (FITS or ASCII)
2	xsize	x-full-width of the subset region of kernel file to use in convolution
3	xoff	x-direction offset
4	fft	convolution type: 1 $=$ FFT / 0 $=$ sliding cell
5	radial	radial profile: 1 $=$ yes / 0 $=$ no

Examples:

1. The example below shows the initial parameter values for the FPSF1D model. Note that the default xsize value is set to 32 before the PSF data file is read in. After reading the data file the xsize is set to the size of the array in the model file.

   sherpa> fpsf1d[psf0]
   sherpa> show psf0
   fpsf1d[psf0]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   file string: "none"
    2  xsize frozen         32          1       1024
    3   xoff frozen          0       -512        512
    4    fft frozen          1          0          1
    5 radial frozen          0          0          1
   
   sherpa> psf0.file=test_model.dat
   sherpa> show psf0
   fpsf1d[psf0]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   file string: "test_model.dat"
    2  xsize frozen         38          1         38
    3   xoff frozen          0        -19         19
    4    fft frozen          1          0          1
    5 radial frozen          0          0          1
   
   sherpa> instrument = psf0
   

5.27 FPSF2D | FPSF | PSFFROMFILE

A 2-D file-based PSF instrument model.

FPSF is a file-based PSF model that represents the point-spread function, a redistribution function that maps photon spatial locations to image bins.

The input PSF FITS image is used to convolve (fold) a given source model. This convolution can be performed using either Fast Fourier Transforms (FFTs, the default), or the sliding cell technique (see the parameter fft). If the length of one axis is $N$ and the length of the kernel axis is $M (= 2 \times {\tt xsize} + 1)$, then the computation time for the sliding cell goes as $N \times M$, i.e., for large kernels the best choice is using the FFT. A rough rule-of-thumb for 2-D fits is to use the FFT if $M_1 \times M_2 > 100$.

Note that the PSF is automatically renormalized upon entry. Renormalization is done by summing over all image pixels, regardless of the setting of xsize and ysize.

The following example will serve to clarify the meanings of the remaining parameters.

Assume that the PSF is provided in a FITS image (file) of size $N_x \times N_y$. $N_x$ and $N_y$ may be much larger than the PSF size in bins. An optimally sized sub-image of size ( $) xsize \times ysize$ can be extracted and used in the PSF convolution process.

If xoff $=$ yoff $=$ 0, the kernel sub-image is extracted from the center of the original image contained in file. The user may find that changing xoff and/or yoff can result in his or her being able to extract a smaller optimally sized sub-image if, say, the PSF is too asymmetric to be fit easily into a centered rectangle. Note that actual PSF image may be outside the default extracted PSF image.

Note that the kernel centroid must always be at the center of the extracted sub-image! Otherwise, systematic shifts will occur in best-fit positions of point sources, etc.

See the documentation on the INSTRUMENT command.

Table 5.31: FPSF Parameters

Number	Name	Description
1	file	input FITS file name
2	xsize	x-width of the subset region of kernel PSF file to use in convolution
3	ysize	y-width of the subset region of kernel PSF file to use in convolution
4	xoff	x-direction offset
5	yoff	y-direction offset
6	fft	convolution type: 1 $=$ FFT / 0 $=$ sliding cell

5.28 FRMF1D | FRMF

A 1-D file-based response matrix model.

FRMF is a file-based RMF model that represents the redistribution matrix which maps photon energy to, e.g., PHA bin.

Note that in Sherpa analyses, the energy-space binning of the RMF (found typically in the ENERG_LO and ENERG_HI columns of the MATRIX extension of the RMF file) does not have to match the analogous energy-space binning of a matching ARF. (This is also true if instead of energy, the RMF is defined as a function of wavelength.)

See the documentation on the INSTRUMENT command. See also the RSP and FARF1D instrument models.

Table 5.32: FRMF Parameters

Number	Name	Description
1	rmf	RMF file name

5.29 GAUSS1D | GAUSS

1-D unnormalized Gaussian function. Integration ON.

An unnormalized 1-D Gaussian model:

$$f(x) = A\exp\left[-f\left(\frac{x-x_{\rm o}}{F}\right)^{2}\right]$$ (5.43)

The constant $f$ $=$ 2.7725887 $=$ 4log2 relates the full-width at half-maximum $F$ to the Gaussian $\sigma$ so that F$=$sqrt(8log2)*sigma.

See also the 1-D normalized Gaussian function, NGAUSS1D.

Table 5.33: GAUSS1D Parameters

Number	Name	Description
1	fwhm	full-width at half-maximum $F$
2	pos	mean position $x_{\rm o}$
3	ampl	amplitude $A$

5.30 GAUSS2D

2-D unnormalized Gaussian function. Integration OFF.

A 2-D Gaussian model:

$$f(x,y) = f(r) = A\exp\left[-f\left(\frac{r}{F}\right)^2\right]$$ (5.44)

where

$$r(x,y) = \frac{\sqrt{x_{\rm new}^2(1-\epsilon)^2 + y_{\rm new}^2}}{1-\epsilon}$$ (5.45)

$$x_{\rm new} = (x - x_{\rm o})\cos{\theta} + (y - y_{\rm o})\sin{\theta}$$ (5.46)

and

$$y_{\rm new} = (y - y_{\rm o})\cos{\theta} - (x - x_{\rm o})\sin{\theta}$$ (5.47)

The constant $f$ $=$ 2.7725887 $=$ 4log2 relates the full-width at half-maximum $F$ to the Gaussian $\sigma$.

Table 5.34: GAUSS2D Parameters

Number	Name	Description
1	fwhm	full-width at half-maximum $F$
2	xpos	x mean position $x_{\rm o}$
3	ypos	y mean position $y_{\rm o}$
4	ellip	ellipticity $\epsilon$
5	theta	angle of ellipticity $\theta$
6	ampl	amplitude $A$ at $(x_o, y_o)$

5.31 GRIDMODEL

N-D user-specified amplitude model. Integration OFF.

Table 5.35: GRIDMODEL Parameters

Number	Name	Description
1	file	input filename
2	norm	normalization

With GRIDMODEL, an N-dimensional data array may be input and used directly as a model. The data array must be of the same size as the source data and have the same binning.

Prior to CIAO 3.0, it was necessary to use GRIDMODEL when inputting an exposure map for use in spatial fitting; this is no longer true. Example 2 compares the CIAO 3.0 and 2.3 syntax; see the FEXPMAP command for further information.

Examples:

1. Input a data array as a model:

   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> GRIDMODEL[gm]
   sherpa> gm.file = "data/example1.dat"
   sherpa> THAW gm.norm
   sherpa> SOURCE = gm
   

   In this example, the model component GRIDMODEL is established and assigned the name gm. Then, the input data array file is input using this model's file parameter. This model component, thus defined using an input data array, can then be used just as any other model component may be used. For example, here the model's normalization is thawed and then the model is used to define a source model expression for fitting.

2. Input an exposure map for use with a dataset (this no longer uses the GRIDMODEL command):

   sherpa> DATA data/data.fits
   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> FEXPMAP[emap]
   sherpa> emap.file = "data/data_expmap.fits"
   sherpa> INSTRUMENT = emap
   

   In this example, the instrument model component FEXPMAP is established, the exposure map file is input using this model's file parameter, and the instrument model stack is set for dataset number 1.

   The CIAO 2.3 equivalent of this command is:

   sherpa> DATA data/data.fits
   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> GRIDMODEL[gm]
   sherpa> gm.file = "data/data_expmap.fits"
   sherpa> EXPMAP 1 = gm
   

5.32 HIGHPASS | STEPHI1D

1-D step function. Integration OFF. The command HIGHPASS is equivalent.

A 1-D step model:

$$f(x)~=~A~~~~~~{\rm if}~x > x_{\rm cut}$$

and

$$f(x)~=~0~~~~~~~{\rm otherwise}$$ (5.48)

Table 5.36: STEPHI1D Parameters

Number	Name	Description
1	xcut	cut-off x_cut
2	ampl	amplitude A

5.33 HUBBLE | REYNOLDS

Hubble-Reynolds profile. Integration OFF. The REYNOLDS model is equivalent.

A 2-D Hubble-Reynolds model:

$$f(x,y)~=~f(r)~=~\frac{A}{\left[\sqrt{\left(\frac{x_{\rm maj}}{r_{\rm maj}}\right)^2+\left(\frac{x_{\rm min}}{r_{\rm min}}\right)^2} + 1\right]^2 }$$ (5.49)

where

$$r_{\rm maj} = r_0$$ (5.50)

$$r_{\rm min}~=~(1-\epsilon)r_0$$ (5.51)

$$x_{\rm maj}~=~(x-x_{\rm o}){\cos}{\theta} + (y-y_{\rm o}){\sin}{\theta}$$ (5.52)

and

$$x_{\rm min} = -(x-x_{\rm o}){\sin}{\theta} + (y-y_{\rm o}){\cos}{\theta}$$ (5.53)

Table 5.37: HUBBLE Parameters

Number	Name	Description
1	r0	core radius $r_0$
2	xpos	x mean position $x_{\rm o}$
3	ypos	y mean position $y_{\rm o}$
4	ellip	ellipticity $\epsilon$
5	theta	angle of ellipticity $\theta$
6	ampl	amplitude $A$

5.34 JDPILEUP

A CCD pileup model developed by John Davis of MIT.

The 1D pileup model can be applied to model the 1D Chandra spectrum obtained in the imaging mode. It should not be used for Chandra grating or 2D image data. This model is used for fitting energy spectra only.

Subsequent use of Powell and Simplex optimization methods is desirable when fitting data with pileup model.

Several model parameters describe pileup:

n, f and g0: The values of n, f and g0 should remain frozen; The full discussion of these parameters is presented in Davis (2001).

alpha:

The value of the parameter alpha should be allowed to vary. alpha parameterizes "grade migration" in the detector, and represents the probability, per photon count greater than one, that the piled event is not rejected by the spacecraft software as a "bad event". Specifically, if n photons are piled together in a single frame, the probability of them being retained (as a single photon event with their summed energy) is given by alpha(n-1). In reality, the alpha parameter should be a photon-energy-dependent and detector-chip-dependent matrix; for simplicity, the jdpileup model assumes a constant value.

ftime:

The ftime and parameter should be set to the value given in the header keyword EXPTIME of the event file. (Note that EXPTIME is used instead of TIMEDEL because the latter includes the transfer time, which ftime should not.)

fracexp:

The fracexp parameter should be set to the value given in the header keyword FRACEXPO of the ARF file:

Table 5.38: JDPILEUP Parameters

Number	Name	Description
1	alpha	grade migration; probability of a good grade when two photons pile together
2	g0	probability of grade 0 assignment
3	f	fraction of flux falling into the pileup region
4	n	number of detection cells
5	ftime	frame time $[$seconds$]$ (keyword EXPTIME in the event file)
6	fracexp	fractional exposure that the point source experienced while dithering on the chip (keyword FRACPROB in the ARF file)

The pileup model does not work for pileup in dispersed grating spectra. The model was designed for imaging pileup, including pileup by the gratings in zeroth order.

For more information, see the Sherpa thread on Using a Pileup Model and the Event Pileup in Charge Coupled Devices page by John E. Davis.

Examples:

1. This example illustrate the setting of the pileup model.

   sherpa> DATA spectrum.pi
   sherpa> INSTRUMENT = RSP[myinst]("source.rmf", "source.arf")
   sherpa> POW[p]
   sherpa> SOURCE = p
   sherpa> JDPILEUP[jdp]
   sherpa> PILEUP = jdp
   sherpa> show jdp
   jdpileup[jdp]  (integrate: off)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  alpha thawed        0.5          0          1
    2     g0 frozen          1     1e-120          1
    3      f thawed       0.95        0.9          1
    4      n frozen          1     1e-120        100
    5  ftime frozen      3.241     1e-120          5                   sec
    6fracexp frozen      0.987          0          1
   sherpa> fit
   

   In this example, data is input and a power-law model component is established and then defined as the source model for fitting. The command JDPILEUP$[$jdp$]$ establishes the JDPILEUP model component and assigns it the name jdp. The command PILEUP $=$ jdp then defines this pileup model for use in fitting.

2. After fitting, display the pileup fractions with SHOW PILEUP:

   sherpa> SHOW PILEUP
      1: 0.224696  0.541445
      2: 0.263513  0.304025
      3: 0.206024  0.113808
      4: 0.120808  0.031952
      5: 0.0566711  0.00717652
      6: 0.0221538  0.00134322
      7: 0.00742312  0.000215494
      8: 0.00217637  3.02503e-05
      9: 0.000567189  3.77462e-06
      10: 0.000133035  4.23895e-07
      *** pileup fraction: 0.458555
   

   Each row represents the number of photons per CCD frame. The maximum number of rows is 20; here, there were no more than 10 photons piled together per frame. The left column represents the percentage of frames with the stated number of photons: here, 22.47% of frames contained a single photon, 26.35% contained two photons piled together, etc. The right column indicates the percentage of observed counts with the stated number of photons: here, 54.14% of recorded counts were comprised of one photon, etc.. The total pileup fraction is the sum of the right column, excluding the first row: here, 45.85% of observed counts actually contain two or more photons piled together.

5.35 KERNEL

Defines an expression to be used as a kernel in 1D source model convolution.

sherpa> KERNEL [<dataset range> | ALLSETS [ID]] = <modelExpr>

$<$dataset range$>$ $=$ # (or more generally #:#,#:#, etc.) such that # specifies a dataset number and #:# represents an inclusive range of datasets; one may specify multiple inclusive ranges by separating them with commas. The default dataset is dataset 1.

The model expression, $<$modelExpr$>$, is an algebraic combination of one or more of the following elements:

{<sherpa_modelname> | <sherpa_modelname>[modelname] | 
 <modelname> | <model_stack> | <nested_model>}

along with numerical values. The following operators are recognized: $+$ - * / ( ) { }. See the CREATE command for further information.

Note that:

$\bullet$

The documentation on Sherpa Models contains a summary list, and descriptions, of the models that are available within Sherpa, which include models from XSPEC, v. 11.3.

$\bullet$

By default, if the model expression includes a model component that has not previously been established, Sherpa will prompt for the initial parameter values for that model component. This prompting can be turned off using the PARAMPROMPT OFF command.

To reset the kernel model stack, issue the command:

sherpa> KERNEL [<dataset range> | ALLSETS] =

The KERNEL model stack is used to convolve source model expressions. As such, it has many uses, of which two are the following:

$\bullet$

It can be used instead of an INSTRUMENT model stack if the instrumental response is representable by analytic functions (e.g., by a Gaussian).

$\bullet$

It can be used to model circumstellar smearing of photon spectra; these spectra may then be further smeared by the observing instrument.

Note that the parameter values of a KERNEL model stack are frozen in fits; the kernel shape cannot be optimized.

The KERNEL model stack is evaluated on the same data grid as the SOURCE model stack. In general, the data grid will not be the correct grid for convolution; in the case of Gaussian smoothing, the convolved spectrum may exhibit, e.g., spectral lines that are both dilated and translated. To prevent translation, the user must set an origin for the convolution kernel using the command:

sherpa> KERNEL.ORIGIN [<dataset range> | ALLSETS] = <coordinate>

The example below will help illustrate this point.

Examples:

1. Define SOURCE and KERNEL model stacks; define the origin of the convolution kernel; and fit:

   sherpa> SOURCE = GAUSS[modela]
   modela.fwhm parameter value [19.3451] 
   modela.pos parameter value [804] 
   modela.ampl parameter value [126] 
   sherpa> KERNEL = NGAUSS[modelb]
   modelb.fwhm parameter value [19.3451] 20
   modelb.pos parameter value [804] 
   modelb.ampl parameter value [2594.62] 1:1:1
   sherpa> KERNEL.ORIGIN = 804
   sherpa> FIT
    LVMQT: V2.0
    LVMQT: initial statistic value = 578.346
    LVMQT: final statistic value = 64.8424 at iteration 6
           modela.fwhm  25.3426     
           modela.pos  807.882     
           modela.ampl  150.302     
   sherpa> KERNEL =
   sherpa> FIT
    LVMQT: V2.0
    LVMQT: initial statistic value = 294.76
    LVMQT: final statistic value = 64.3803 at iteration 7
           modela.fwhm  32.3536     
           modela.pos  807.863     
           modela.ampl  117.826
   

   The convolution kernel is a normalized Gaussian, with integrated area set to 1 and full-width half-max of 20. (For a normalized Gaussian, the integrated area equals the amplitude.) The kernel origin is set to be the centroid of the normalized Gaussian (modelb.pos). Note the differences in the values of modela.fwhm and modela.ampl between each fit.

5.36 LINEBROAD

Line broadening profile. Integration ON.

A line-broadening profile:

$$f(\lambda)~=~\frac{2 A c}{{\pi}{\lambda}v{\sin}i} \left[ 1 - \left( \frac{{\Delta}\lambda}{\lambda_{\rm rest}} \frac{c}{v{\sin}i} \right)^2 \right]$$ (5.54)

where

$${\Delta}\lambda = \lambda - \lambda_{\rm rest}.$$ (5.55)

Table 5.39: LINEBROAD Parameters

Number	Name	Description
1	rest	rest wavelength $\lambda_{\rm rest}$ (A)
2	vsini	rotation velocity $v{\sin}i$ (km/s)
3	ampl	amplitude $A$

5.37 LORENTZ1D | LORENTZ

1-D normalized Lorentzian function. Integration ON.

A normalized 1-D Lorentz model:

$$f(x)~=~\frac{A}{\pi} \frac{\frac{F}{2}}{\left(\frac{F}{2}\right)^2 + (x - x_{\rm o})^2}$$ (5.56)

with

$$\int_{-\infty}^{+\infty} dx f(x)~=~A$$ (5.57)

Table 5.40: LORENTZ1D Parameters

Number	Name	Description
1	fwhm	full-width at half-maximum $F$
2	pos	mean position $x_{\rm o}$
3	ampl	amplitude $A$

5.38 LORENTZ2D

2-D unnormalized Lorentzian function. Integration OFF.

An unnormalized 2-D Lorentz model:

$$f(x,y)~=~f(r)~=~A \frac{\left(\frac{F}{2}\right)^2}{\left(\frac{F}{2}\right)^2 + r^2}$$ (5.58)

where

$$r(x,y)~=~\frac{\sqrt{x_{\rm new}^2(1-\epsilon)^2 + y_{\rm new}^2}}{1-\epsilon}$$ (5.59)

$$x_{\rm new} = (x - x_{\rm o})\cos{\theta} + (y - y_{\rm o})\sin{\theta}$$ (5.60)

and

$$y_{\rm new} = (y - y_{\rm o})\cos{\theta} - (x - x_{\rm o})\sin{\theta}$$ (5.61)

Table 5.41: LORENTZ2D Parameters

Number	Name	Description
1	fwhm	full-width at half-maximum $F$
2	xpos	x mean position $x_{\rm o}$
3	ypos	y mean position $y_{\rm o}$
4	ellip	ellipticity $\epsilon$
5	theta	angle of ellipticity $\theta$
6	ampl	amplitude $A$ at $(x_o, y_o)$

5.39 LORPOW2D | BETA2D

Another name for the BETA2D model. See Section 5.10.

5.40 LOWPASS | STEPLO1D

1-D step function. Integration OFF. The command LOWPASS is equivalent.

A 1-D step model:

$$f(x)~=~A~~~~~~{\rm if}~x < x_{\rm cut}$$ (5.62)

$$f(x)~=~0~~~~~~~{\rm otherwise}$$ (5.63)

Table 5.42: STEPLO1D Parameters

Number	Name	Description
1	xcut	cut-off x_cut
2	ampl	amplitude A

5.41 NBETA

1-D normalized beta function. Integration ON.

A normalized 1-D beta function appropriate for use fitting line profiles:

$$f(x)~=~\frac{A}{\left[1 + \frac{(x-x_0)^2}{w^2}\right]^{-\alpha}}$$ (5.64)

Table 5.43: NGAUSS1D Parameters

Number	Name	Description
1	pos	line centroid $x_0$
2	width	line width $w$
3	index	index $\alpha$
4	ampl	line amplitude $A$

5.42 NGAUSS1D

1-D normalized Gaussian function. Integration ON.

A normalized 1-D Gaussian model:

$$f(x)~=~\frac{A}{\sqrt{\frac{\pi}{f}}F} \exp\left[-f\left(\frac{x-x_{\rm o}}{F}\right)^{2}\right]$$ (5.65)

with

$$\int_{-\infty}^{+\infty} dx f(x)~=~A$$ (5.66)

The constant $f$ $=$ 2.7725887 $=$ 4log2 relates the full-width at half-maximum $F$ to the Gaussian $\sigma$ so that F$=$sqrt(8log2)*sigma.

See also the 1-D unnormalized Gaussian function, GAUSS1D.

Table 5.44: NGAUSS1D Parameters

Number	Name	Description
1	fwhm	full-width at half-maximum $F$
2	pos	mean position $x_{\rm o}$
3	ampl	amplitude $A$

5.43 PILEUP

Defines the pileup model expression to be used for fitting a 1D dataset.

sherpa> PILEUP [<dataset range> | ALLSETS] = <pileupModelExpr>

$<$dataset range$>$ $=$ # (or more generally #:#,#:#, etc.) such that # specifies a dataset number and #:# represents an inclusive range of datasets; one may specify multiple inclusive ranges by separating them with commas. The default dataset is dataset 1.

In CIAO 3.0 Sherpa, there is one pileup model available: JDPILEUP, developed by John Davis at MIT. The pileup model does not work for pileup in dispersed spectra. Rather, the model was designed for imaging pileup, including pileup by the gratings in zeroth order. This model is used for fitting energy spectra only.

Note that:

$\bullet$

To apply the JDPILEUP model, an instrument model with ARF must be defined, and the ARF must have a uniform grid.

$\bullet$

The parameters of the JDPILEUP model (in particular, $\alpha$) themselves do not indicate how much pileup occurred during the observation. To retrieve this information, use the command SHOW PILEUP, based on the PRINT_KERNEL function of the fitting application ISIS. See the example below for an explanation of the output of SHOW PILEUP.

$\bullet$

By default, if the model instance of JDPILEUP has not previously been established, Sherpa will prompt for its initial parameter values. This prompting can be turned off using the PARAMPROMPT OFF command.

To reset the pileup model stack, issue the command:

sherpa> PILEUP [<dataset range> | ALLSETS] =

Examples:

1. Define a pileup model for use:

   sherpa> DATA data/source.pi
   The inferred file type is PHA.  If this is not what you want, please
   specify the type explicitly in the data command.
   WARNING: statistical errors specified in the PHA file.
            These are currently IGNORED.  To use them, type:
            READ ERRORS "<filename>[cols CHANNEL,STAT_ERR]" fitsbin
   sherpa> PARAMPROMPT OFF
   Model parameter prompting is off
   sherpa> INSTRUMENT = RSP[myinst]("data/source.rmf", "data/source.arf")
   The inferred file type is ARF.  If this is not what you want, please 
   specify the type explicitly in the data command.
   sherpa> POW[p]
   sherpa> SOURCE = p
   sherpa> JDPILEUP[jdp]
   sherpa> PILEUP = jdp
   sherpa> FIT
   

   In this example, data is input and a power-law model component is established and then defined as the source model for fitting. The command JDPILEUP$[$jdp$]$ establishes the JDPILEUP model component and assigns it the name jdp. The command PILEUP $=$ jdp then defines this pileup model for use in fitting.

2. After fitting, display the pileup fractions with SHOW PILEUP:

   sherpa> SHOW PILEUP
      1: 0.224696  0.541445
      2: 0.263513  0.304025
      3: 0.206024  0.113808
      4: 0.120808  0.031952
      5: 0.0566711  0.00717652
      6: 0.0221538  0.00134322
      7: 0.00742312  0.000215494
      8: 0.00217637  3.02503e-05
      9: 0.000567189  3.77462e-06
      10: 0.000133035  4.23895e-07
      *** pileup fraction: 0.458555
   

   Each row represents the number of photons per CCD frame. The maximum number of rows is 20; here, there were no more than 10 photons piled together per frame. The left column represents the percentage of frames with the stated number of photons: here, 22.47% of frames contained a single photon, 26.35% contained two photons piled together, etc. The right column indicates the percentage of observed counts with the stated number of photons: here, 54.14% of recorded counts were comprised of one photon, etc.. The total pileup fraction is the sum of the right column, excluding the first row: here, 45.85% of observed counts actually contain two or more photons piled together.

5.44 POISSON

Poisson function. Integration OFF.

A model expressing the ratio of two Poisson distributions of mean mu, one for which the random variable is x, and the other for which the random variable is equal to mu itself:

$$f(x)~=~A\frac{\frac{{\mu}^x}{x!}\exp(-\mu)}{\frac{{\mu}^{\mu}}{{\mu}!}\exp(-\mu)}~=~A\frac{{\mu}!}{x!}\mu^{x-\mu}$$ (5.67)

Table 5.45: POISSON Parameters

Number	Name	Description
1	mean	mean $\mu$
2	ampl	amplitude $A$

5.45 POLYNOM1D | POLY

1-D polynomial function. Integration ON.

A 1-D polynomial of order $\leq$ 8:

$$f(x)~=~\sum_{i=0}^{8} c_i (x - x_{\rm off})^i$$ (5.68)

where the coefficients $c_i$ are the parameters numbered $i+1$, and $x_{\rm off}$ is parameter number 10.

Note that there is a degeneracy in the parameters, so it is recommended to set at least one of $c_0$ or $x_{\rm off}$ to zero and freeze it; thawing both may lead to unpredicted results.

Note also that all coefficients except $c_0$ are default frozen, so that the default polynomial model is a constant.

Table 5.46: POLYNOM1D Parameters

Number	Name	Description
1	c0	coefficient $c_0$
2	c1	coefficient $c_1$
3	c2	coefficient $c_2$
4	c3	coefficient $c_3$
5	c4	coefficient $c_4$
6	c5	coefficient $c_5$
7	c6	coefficient $c_6$
8	c7	coefficient $c_7$
9	c8	coefficient $c_8$
10	offset	offset for x $x_{\rm off}$

5.46 POLYNOM2D

2-D polynomial function. Integration ON.

A 2-D polynomial model of order $\leq 2:$

$$f(x,y) = c_0 + c_{\rm x1}x + c_{\rm x2}x^2 + c_{\rm y1}y + c_{\rm... ...+ c_{\rm x1,y1}xy + c_{\rm x1,y2}xy^2 + c_{\rm x2,y1}x^2y + c_{\rm x2,y2}x^2y^2$$ (5.69)

Table 5.47: POLYNOM2D Parameters

Number	Name	Description
1	constant	constant coefficient
2	cx1	coefficient $c_{\rm x1}$
3	cx2	coefficient $c_{\rm x2}$
4	cy1	coefficient $c_{\rm y1}$
5	cy2	coefficient $c_{\rm y2}$
6	cx1y1	coefficient $c_{\rm x1,y1}$
7	cx1y2	coefficient $c_{\rm x1,y2}$
8	cx2y1	coefficient $c_{\rm x2,y1}$
9	cx2y2	coefficient $c_{\rm x2,y2}$

5.47 POWLAW1D

1-D power law. Integration ON.

A 1-D power-law model:

$$f(x)~=~A \left(\frac{x}{x_{\rm ref}}\right)^{-\gamma}$$ (5.70)

The variable $x$ is assumed to be $>0$.

Table 5.48: POWLAW1D Parameters

Number	Name	Description
1	gamma	power law photon index $\gamma$
2	ref	normalization reference point $x_{\rm ref}$
3	ampl	amplitude $A$

5.48 PTSRC1D

A 1-D file-based point-source fitting model.

PTSRC1D is a file-based model that may be used in fitting sources, to determine, e.g., if they are point-like or extended.

This model cannot be used as an instrument model.

ASCII and FITS formats are allowed for the input model file . The current implementation requires that the bin size of the data and the PTSRC1D model file are the same. The number of bins can be different.

The model has several parameters, which can be used to adjust the model array to be used in fitting.

"xsize" parameter defines the number of bins extracted from the file to be used in the model.

xoff $=$ 0 parameters defines the center of the array and it should be left at 0 in CIAO 3.2 version of the model.

"norm" parameter is thawed by definition and it is defined as a total number of counts (values) in the model. The best-fit value for a point-like source will be approximately equal to the number of detected counts from the source.

"xpos" parameter indicates where the center of the sub-array is located in the extracted model array, for example it should be set to the location of the source centroid if the input file is a gaussian function. Note that the initial value of the xpos is estimated using the input dataset.

Table 5.49: PTSRC1D Parameters

Number	Name	Description
1	file	input file name (FITS or ASCII)
2	xsize	x-full-width of the subset region of the model file
3	xoff	x-direction offset
4	xpos	x-position of the centroid in the data coordinates
5	norm	normalization

Examples:

1. The example below shows the initial parameter values for the PTSRC1D model. Note that the default xsize value is set to 32 before the data file is read in. After reading the data file the xsize is set to the size of the array in the model file.

   sherpa> ptsrc1d[p1]
   sherpa> show p1
   ptsrc1d[p1]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   file string: "none"
    2  xsize frozen         32          1       1024
    3   xoff frozen          0       -512        512
    4   xpos thawed       12.5       12.5      197.5
    5   norm thawed          1          0       1000
   
   shrpa> p1.file="model.dat"
   sherpa> show p1
   ptsrc1d[p1]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   file string: "model.dat"
    2  xsize frozen         38          1         38
    3   xoff frozen          0        -19         19
    4   xpos thawed       12.5       12.5      197.5
    5   norm thawed          1          0       1000
   
   sherpa> source 1 = p1 
   sherpa> fit
   

5.49 PTSRC2D |PTSRC

A 2-D file-based point-source fitting model.

PTSRC is a file-based model that may be used in fitting image data, to determine, e.g., if they are point-like or extended.

This model cannot be used as an instrument model.

FITS formats are allowed for the input model file. The current implementation requires that the image bins of the data and the PTSRC2D model file are the same.

Assume that the PSF is provided in a FITS image (file) of size $N_x \times N_y$. $N_x$ and $N_y$ may be much larger than the PSF size in pixels. An optimally sized sub-image of size $xsize \times ysize$ can speed up the computation of model amplitudes.

If xoff $=$ yoff $=$ 0, the sub-image is extracted from the center of the original image contained in file. The user may find that changing xoff and/or yoff can result in his or her being able to extract a smaller optimally sized sub-image if, say, the PSF is too asymmetric to be fit easily into a centered rectangle.

If norm is thawed its best-fit value for a point-like source will be approximately equal to the number of detected counts from the source.

The parameters xpos and ypos indicate where the center of the sub-image is to be placed in the data image that is to be analyzed, i.e., they should be set to the location of the source centroid. Note that the initial values of the xpos and ypos are estimated using the input dataset.

Table 5.50: PTSRC Parameters

Number	Name	Description
1	file	input FITS file name
2	xsize	x-width of the subset region of kernel file to use in convolution
3	ysize	y-width of the subset region of kernel file to use in convolution
4	xoff	x-direction offset
5	yoff	y-direction offset
6	xpos	x-position of the centroid in data image coordinates
7	ypos	y-position of the centroid in data image coordinates
8	norm	normalization defined as a sum over the model image

Examples:

1. The example below shows the initial parameter values for the PTSRC2D model. Note that the default xsize and ysize values are set to 32. After reading the data file these parameter can be adjusted to expand the image and include most of the PSF fraction. Notice after image command indicates the fraction of PSF included in the sub-image.

   sherpa> ptsrc2d[p2]
   sherpa> show p2
   ptsrc2d[p2]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   file string: "none"
    2  xsize frozen         32          1       1024
    3  ysize frozen         32          1       1024
    4   xoff frozen          0       -512        512
    5   yoff frozen          0       -512        512
    6   xpos thawed      128.5        0.5      256.5
    7   ypos thawed      128.5        0.5      256.5
    8   norm thawed          1          0       1000
   
   sherpa> p2.file=psf2.fits
   sherpa> show p2
   ptsrc2d[p2]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   file string: "psf2.fits"
    2  xsize frozen         32          1       1024
    3  ysize frozen         32          1       1024
    4   xoff frozen          0       -512        512
    5   yoff frozen          0       -512        512
    6   xpos thawed      128.5        0.5      256.5
    7   ypos thawed      128.5        0.5      256.5
    8   norm thawed          1          0       1000
   sherpa> image p2
   NOTE: PSF fraction for (xsize,ysize): FRAC = 0.984733
   
   sherpa> p2.xsize=64
   sherpa> p2.ysize=64
   sherpa> image p2
   

5.50 REYNOLDS | HUBBLE

Another name for the HUBBLE model. See Section 5.33.

5.51 RSP1D |RSP

A 1-D instrument model.

RSP is used to model instrument response. It has two parameters (as listed below): ARF and RMF filenames. The ARF file contains an ancillary response vector representing effective area as a function of photon energy, while the RMF file contains the redistribution matrix which maps photon energy to, e.g., PHA bin.

There are several things to be aware of:

$\bullet$

It is not necessary to specify both an ARF and RMF file to do analysis; for instance, the user can analyze data using only an ARF.

$\bullet$

In Sherpa analyses, the energy-space binning of the ARF (found typically in the ENERG_LO and ENERG_HI columns of the SPECRESP extension of the ARF file) does not have to match the analogous energy-space binning of the RMF. (This is also true if instead of energy, the ARF is defined as a function of wavelength.)

$\bullet$

The explicit use of RSP is only necessary if the filenames are not given in the header of the input PHA data file.

See the documentation on the INSTRUMENT command. See also the FARF1D and FRMF1D instrument models.

Table 5.51: RSP Parameters

Number	Name	Description
1	rmf	RMF file name
2	arf	ARF file name

5.52 RSP2D

A 2-D instrument model utilizing an exposure map and point-spread function.

RSP2D is used to model instrument response with an exposure map and point-spread function (PSF).

Note the following:

$\bullet$

The exposure map image must have the same size as the data image, and it must have the same plate-scale (i.e., bins in each image must have the same size in arc-seconds, etc.).

$\bullet$

The exposure map and PSF images need not have the same size, but both must have the same plate-scale.

See the documentation on the INSTRUMENT command. See also the FARF2D and FPSF2D instrument models, for a fuller explanation of the parameters.

Table 5.52: RSP2D Parameters

Number	Name	Description
1	psffile	PSF file name
2	xsize	x-full-width of the subset region of the PSF file to use in convolution
3	ysize	y-full-width of the subset region of the PSF file to use in convolution
4	xoff	x-direction offset
5	yoff	y-direction offset
6	fft	convolution type: 1 $=$ FFT / 0 $=$ sliding cell
7	empfile	exposure map file name

5.53 SCHECHTER

Schechter function. Integration OFF.

An integrated 1-D Schechter model:

$$f(x_i)~=~A\left(\frac{x_i}{x_{\rm ref}}\right)^{\alpha} \exp\left(-\frac{x_i}{x_{\rm ref}}\right) \frac{x_{i+1} - x_i}{x_{\rm ref}}$$ (5.71)

Table 5.53: SCHECHTER Parameters

Number	Name	Description
1	alpha	power coefficient $\alpha$
2	ref	reference value $x{\rm ref}$
3	norm	normalization factor $A$

5.54 SHEXP10

Exponential function, base 10. Integration OFF.

An exponential model, base 10:

$$f(x)~=~A 10^{C (x - x_{\rm off})}$$ (5.72)

Table 5.54: SHEXP10 Parameters

Number	Name	Description
1	offset	offset $x_{\rm off}$
2	coeff	coefficient $C$
3	ampl	amplitude $A$

5.55 SHEXP

Exponential function. Integration OFF.

An exponential model:

$$f(x)~=~A \exp[C (x - x_{\rm off})]$$ (5.73)

Table 5.55: SHEXP Parameters

Number	Name	Description
1	offset	offset x_off
2	coeff	coefficient C
3	ampl	amplitude A

5.56 SHLOG10

Logarithm function, base 10. Integration OFF.

A base-10 logarithm model:

$$f(x)~=~A \log_{\rm 10}[C (x - x_{\rm off})]$$ (5.74)

Table 5.56: SHLOG10 Parameters

Number	Name	Description
1	offset	offset $x_{\rm off}$
2	coeff	coefficient $C$
3	ampl	amplitude $A$

5.57 SHLOGE | SHLOG

Natural logarithm function. Integration OFF.

A natural logarithm model:

$$f(x)~=~A \log[C (x - x_{\rm off})]$$ (5.75)

Table 5.57: SHLOGE Parameters

Number	Name	Description
1	offset	offset $x_{\rm off}$
2	coeff	coefficient $C$
3	ampl	amplitude $A$

5.58 SIN

Sine function. Integration OFF.

A 1-D sine model:

$$f(x)~=~A {\sin}\left(\frac{2\pi(x-x_{\rm off})}{P}\right)$$ (5.76)

Table 5.58: SIN Parameters

Number	Name	Description
1	period	period $P$, in units of x
2	offset	x offset $x_{\rm off}$
3	ampl	amplitude $A$

5.59 SQRT

Square root function. Integration OFF.

A 1-D square-root model:

$$f(x)~=~A\sqrt{x - x_{\rm off}}$$ (5.77)

Table 5.59: SQRT Parameters

Number	Name	Description
1	offset	offset $x_{\rm off}$
2	ampl	amplitude $A$

5.60 STEPHI1D | HIGHPASS

Another name for the HIGHPASS model. See Section 5.32.

5.61 STEPLO1D | LOWPASS

Another name for the LOWPASS model. See Section 5.40.

5.62 TAN

Tangent function. Integration OFF.

A 1-D tangent model:

$$f(x)~=~A {\tan}\left(\frac{2\pi(x-x_{\rm off})}{P}\right)$$ (5.78)

Table 5.60: TAN Parameters

Number	Name	Description
1	period	period $P$, in units of x
2	offset	x offset $x_{\rm off}$
3	ampl	amplitude $A$

5.63 TPSF1D

A 1-D TCD-model-based instrument model.

TPSF1D is a model-based instrument model. It utilizes the predefined Gaussian, box, and top hat functions of the TCD library.

Note that Top Hat function cannot be used in version 3.2

The convolution can be performed using either Fast Fourier Transforms (FFTs, the default), or the sliding cell technique (see the parameter fft). If the axis length is $N$ and the length of the kernel axis is $M (= 2 \times {\tt xsize} + 1)$, then the computation time for the sliding cell goes as $N \times M$, i.e. for large kernels the best choice is using the FFT. A rough rule-of-thumb for 1-D fits is to use the FFT if $M > 10$.

In Sherpa version 3.0.2, a new parameter is introduced: radial. If set to 1 the kernel array will be extended and its values reflected across the edge boundary. The resultant function will be symmetric. The default value (set to 0) should be used in version 3.2.

See the documentation on the INSTRUMENT command.

Table 5.61: TPSF1D Parameters

Number	Name	Description
1	xsize	x-axis kernel width (pixels)
2	nsigma	sigma kernel width (Gaussian only)
3	funcTyp	Gaussian (1) / box (2) / top-hat (3)
4	fft	convolution type: 1 $=$ FFT / 0 $=$ sliding cell
5	radial	radial profile: 1 $=$ yes / 0 $=$ no

Examples:

1. This example illustrate the definition of the TPSF1D model.

   sherpa> tpsf1d[t1]
   sherpa> show t1
   tpsf1d[t1]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  xsize frozen          4          1       1024
    2 nsigma frozen          2      1e-02        100
    3funcTyp frozen          1          0          7
    4    fft frozen          1          0          1
    5 radial frozen          0          0          1
    The Function Type is:  Gaussian.
   

   The parameter funcTyp in t1 model indicate that the Gaussian function will be used. The 1 sigma width of the Gaussian is set to xsize$=$4 bins and the total size of the Gaussian kernel is set to 2 sigma.

5.64 TPSF2D | TPSF | PSFFROMTCD | PSF

A 2-D TCD-model-based instrument model.

TPSF is a model-based 2D instrument model. It utilizes the predefined Gaussian, box, and top hat functions of the TCD library. It can represent the point-spread function (PSF), a redistribution function that maps photon spatial locations to image bins.

Note that the top hat function cannot be used in version 3.2

The convolution can be performed using either Fast Fourier Transforms (FFTs, the default), or the sliding cell technique (see the parameter fft). If the length of one axis is $N$ and the length of the kernel axis is $M (= 2 \times {\tt xsize} + 1)$, then the computation time for the sliding cell goes as $N \times M$, i.e. for large kernels the best choice is using the FFT. A rough rule-of-thumb for 2-D fits is to use the FFT if $M_1 \times M_2 > 100$.

See the documentation on the INSTRUMENT command.

Table 5.62: TPSF Parameters

Number	Name	Description
1	xsize	x-axis 1 sigma width (pixels)
2	ysize	y-axis 1 sigma width (pixels)
3	nsigma	kernel width in sigma (Gaussian only)
4	funcTyp	Gaussian (1) / box (2) / top-hat (3)
5	fft	convolution type: 1 $=$ FFT / 0 $=$ sliding cell

Examples:

1. This example illustrates the definition of the TPSF1D model.

   sherpa> tpsf2d[t2]
   sherpa> show t2
   tpsf2d[t2]
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1  xsize frozen          4          1       1024
    2  ysize frozen          4          1       1024
    3 nsigma frozen          2      1e-02        100
    4funcTyp frozen          1          0          7
    5    fft frozen          1          0          1
    The Function Type is:  Gaussian.
   

   The parameter funcTyp in t2 model indicate that the Gaussian function will be used. The 1 sigma width of the Gaussian is set to xsize$=$ysize$=$4 pixels and the total size of the Gaussian kernel is set to 2 sigma.

5.65 USERMODEL

User implemented model.

It is possible for the user to create and implement his or her own model, own optimization method, and own statistic function within Sherpa. The User Models, Statistics, and Methods Within Sherpa chapter of the Sherpa Reference Manual has more information on this topic.

The tar file sherpa_user.tar.gz contains the files needed to define the usermethod, e.g Makefiles and Implementation files, plus example files, and it is available from the Sherpa threads page: Data for Sherpa Threads

5.66 XS$<$xspecname$>$

XSpec model functions.

Sherpa includes the "additive" and "multiplicative" models of XSpec version 11.3. To use these models, simply prefix the original XSpec name by "xs"; for example, the name xsphabs represents the XSpec phabs model. To define a composite XSpec model such as

$$phabs * apec$$ (5.79)

do the following:

sherpa> xsphabs[abs1]
sherpa> xsapec[gas1]
sherpa> source 1 = abs1 * gas1

(Of course, one can use names other than "abs1" and "gas1" to represent these model components.)

Note that XSPEC models are always integrated over a bin and so require binned data.

5.66.1 Important Note:

XSpec models based on physical processes (e.g. line models such as raymond or absorption models such as wabs) assume that the dataspace is defined in keV. On the other hand Sherpa models are always calculated based on the input data scale. Thus when XSpec models are combined with Sherpa models, the user should be careful to ensure that both components have the same dataspace units; otherwise, calculated model amplitudes may be incorrect.

These models also expect that the x-values will always be energy bins. When the analysis setting is using non-energy bins (e.g., ANALYSIS WAVE) and an XSPEC model is defined, Sherpa converts the bins to energy before sending them to the XSPEC model. After the XSPEC model finishes, Sherpa converts back to the original units. Sherpa also scales the model values appropriately (e.g., if counts/keV came out of the XSPEC model, and Sherpa is working with wavelength bins, then Sherpa scales the output of the XSPEC model to counts/Angstrom).

5.66.2 Unavailable XSPEC Models and Commands

The following XSPEC components are NOT included in CIAO 3.4:

$\bullet$

the bkn2pow (three-segment broken power law) and kerrd (optically thick extreme-Kerr disk) models

$\bullet$

the xset command: this means that users cannot currently modify certain XSPEC internal switches.

$\bullet$

the atable, etable, and mtable models

5.66.3 Available XSPEC Models

The available XSpec models are listed below. Please see either the ahelp page for each model (e.g. "ahelp xsabsori") or the XSpec User's Guide for more information about each of these models. Note that the ahelp files describe the version of the XSpec model included in CIAO, while the XSpec User's Guide may reference a newer version with different options.

$<$xspecname$>$	Description
absori	Ionized absorber
acisabs	Decay in the ACIS quantum efficiency
apec	APEC thermal plasma model
bapec	APEC thermal plasma model with velocity broadening as a free parameter
bbody	Blackbody spectrum
bbodyrad	Blackbody spectrum with norm proportional to surface area
bexrav	E-folded broken power law reflected from neutral matter
bexriv	E-folded broken power law reflected from ionized matter
bknpower	Broken power law
bmc	Comptonization by relativistically moving matter
bremss	Thermal bremsstrahlung
bvapec	APEC thermal plasma model with variable abundances and velocity broadening as a free parameter
c6mekl	6th-order Chebyshev polynomial DEM using mekal
c6pmekl	Exponential of 6th-order Chebyshev polynomial DEM using mekal
c6pvmkl	Variable abundance version of c6pmekl
c6vmekl	Variable abundance version of c6mekl
cabs	Compton scattering (non-relativistic)
cemekl	Multi-temperature mekal
cevmkl	Multi-temperature vmeka
cflow	Cooling flow model
compbb	Comptonized blackbody spectrum after Nishimura et al. (1986)
compls	Comptonization spectrum after Lamb and Sanford (1979)
compst	Comptonization spectrum after Sunyaev and Titarchuk (1980)
comptt	Comptonization spectrum after Titarchuk (1994)
constant	Energy-independent multiplicative factor
cutoffpl	Power law with high energy exponential cutoff
cyclabs	Cyclotron absorption line
disk	Disk model
diskbb	Multiple blackbody disk model
diskline	Line emission from relativistic accretion disk
diskm	Disk model with gas pressure viscosity
disko	Modified blackbody disk model
diskpn	Accretion disk around a black hole
dust	Dust scattering out of the beam
edge	Absorption edge
equil	Equilibrium ionization collisional plasma model from Borkowski
expabs	Low-energy exponential cutoff
expdec	Exponential decay
expfac	Exponential factor
gabs	Multiplicative gaussian absorption line
gaussian	Simple gaussian line profile
gnei	Generalized single ionization NEI plasma model
grad	GR accretion disk around a black hole
grbm	Gamma-ray burst model
highecut	High energy cutoff
hrefl	Simple reflection model good up to 15 keV
laor	Line from accretion disk around a black hole
lorentz	Lorentzian line profile
meka	Mewe-Gronenschild-Kaastra thermal plasma (1992)
mekal	Mewe-Kaastra-Liedahl thermal plasma (1995)
mkcflow	Cooling flow model based on mekal
nei	Simple nonequilibrium ionization plasma model
notch	Notch line absorption
npshock	Plane-parallel shock with ion and electron temperatures
nsa	Spectra in the X-ray range (0.05-10 keV) emitted from a hydrogen atmosphere of a neutron star.
nteea	Pair plasma model
pcfabs	Partial covering fraction absorption
pegpwrlw	Power law with pegged normalization
pexrav	Exponentially cutoff power law reflected from neutral matter
pexriv	Exponentially cutoff power law reflected from ionized matter
phabs	Photo-electric absorption
plabs	Absorption model with power law dependence on energy
plcabs	Cutoff power law observed through dense, cold matter
posm	Positronium continuum
powerlaw	Simple photon power law
pshock	Constant temperature, plane-parallel shock plasma model
pwab	Extension of partial covering fraction absorption into a power-law distribution of covering fraction
raymond	Raymond-Smith thermal plasma
redden	IR/optical/UV extinction from Cardelli et al. (1989)
redge	Recombination edge
refsch	E-folded power law reflected from an ionized relativistic disk
sedov	Sedov model with electron and ion temperatures
smedge	Smoothed absorption edge
spline	Spline multiplicative factor
srcut	Synchrotron radiation from cutoff electron distribution
sresc	Synchrotron radiation from escape-limited electron distribution
SSS_ice	Einstein Observatory SSS ice absorption
step	Step function convolved with gaussian
TBabs	Calculates the absorption of X-rays by the ISM
TBgrain	Calculates the absorption of X-rays by the ISM with variable hydrogen to H2 ratio and grain parameters
TBvarabs	Calculates the absorption of X-rays by the ISM, allowing user to vary all abundances, depletion factors, and grain properties
uvred	UV reddening
vapec	APEC thermal plasma model with variable abundances
varabs	Photoelectric absorption with variable abundances
vbremss	Thermal bremsstrahlung spectrum with variable H/He
vequil	Ionization equilibrium collisional plasma model with variable abundances
vgnei	Non-equilibrium ionization collisional plasma model with variable abundances
vmcflow	Cooling flow model based on vmekal
vmeka	M-G-K thermal plasma with variable abundances
vmekal	M-K-L thermal plasma with variable abundances
vnei	Non-equilibrium ionization collisional plasma model with variable abundances
vnpshock	Plane-parallel shock plasma model with separate ion and electron temperatures and variable abundances
vphabs	Photoelectric absorption with variable abundances
vpshock	Constant temperature, plane-parallel shock plasma model with variable abundances
vraymond	Raymond-Smith thermal plasma with variable abundances
vsedov	Sedov model with separate ion and electron temperatures and variable abundances
wabs	Photoelectric absorption (Morrison and McCammon)
wndabs	Photoelectric absorption with low energy window
xion	Reflected spectra of a photo-ionized accretion disk or ring
zbbody	Redshifted blackbody
zbremss	Redshifted thermal bremsstrahlung
zedge	Redshifted absorption edge
zgauss	Redshifted gaussian
zhighect	Redshifted high energy cutoff
zpcfabs	Redshifted partial covering absorption
zphabs	Redshifted photoelectric absorption
zpowerlw	Redshifted power law
zTBabs	Calculates the absorption of X-rays by the ISM for modeling redshifted absorption. Does not include a dust component.
zvarabs	Redshifted photoelectric absorption with variable abundances
zvfeabs	Redshifted absorption with variable iron abundance
zvphabs	Redshifted photoelectric absorption with variable abundances
zwabs	Redshifted "Wisconsin absorption''
zwndabs	Redshifted photoelectric absorption with low energy window