Subsections

8. S-lang in Sherpa

The S-Lang programming language can be used to manipulate or create data for plotting; see ``ahelp slang'' for more information on S-Lang. This chapter describes the S-lang functions that duplicate and extend the Sherpa commands.

All of the information provided here is available within CIAO and Sherpa from the ahelp system; ``ahelp -c sherpa'' returns a list of all the help files relating to Sherpa .

S-lang commands are case sensitive and must be written in lowercase.

8.1 compute_errors

Module function to estimate errors for an array of data

Array_Type compute_errors(Array_Type)

Error Return Value: NULL

Argument:

(1) Array of values of type Float_Type or Double_Type

This function estimates the errors for each element of the input array given Sherpa's current STATISTIC setting. (Note that these data need not have been input into Sherpa!) Thus there is an implicit assumption that the input array elements are counts. If the input array elements are not counts, then one could, e.g., create a new S-Lang function to compute the errors properly.

This function is only appropriate for use with data-based variances: chi gehrels, chi dvar, and chi parent.

Note that currently, the input array cannot be of type Integer_Type. This will be fixed in a future version of the module. To check the type of the array, use the S-Lang function _typeof:

sherpa> a = [5,3,9]
sherpa> _typeof(a)
Integer_Type
sherpa> compute_errors(a)
NULL

One can get around this error by explicitly typecasting the array:

sherpa> a = typecast(a,Double_Type)
sherpa> foo = compute_errors(a)
sherpa> print(foo)
3.39792
2.93649
4.1225

See the related function compute_statistic.

8.2 compute_statistic

Module function to estimate a statistic given arrays of data, model amplitudes, and errors, etc.

Double_Type compute_statistic(Struct_Type)
Double_Type compute_statistic(Array_Type,Array_Type \
[,Array_Type[,Array_Type[,Array_Type]]]))

Error Return Value: NULL

Arguments:

(1) Structure containing data, model amplitude, etc., arrays; or

(1) Array of observed data

(2) Array of predicted model amplitudes

(3) Array of estimated errors

(4) Array of systematic errors

(5) Array of statistical weights

This function computes the summed statistic value given Sherpa's current STATISTIC setting. (Note that the data et al. need not have been input into Sherpa!)

If an error array is input, then note that the actual setting of $\chi ^2$ (e.g., CHI GEHRELS or CHI DVAR) does not matter (since the input errors are used instead of error estimates) if the $\chi ^2$ statistic is used. Also note that the error array is ignored for likelihood-based statistics (e.g., CASH).

On the other hand, if an errors array is not provided, and a data-based variance is used (chi gehrels, chi dvar, and chi parent), then errors are estimated via a call to the function compute_errors; there is thus an implicit assumption that the input data array elements are counts. If chi mvar is used, then the errors are set equal to the input predicted model amplitudes.

Examples:

Compute the statistic given a data and model array (with errors estimated):
```
sherpa> get_stat_expr
chi gehrels
sherpa> d = [55,53,59]
sherpa> m = [55.5,55.6,55.7]
sherpa> compute_statistic(d,m)
0.243771
```
Because an error array was not provided, errors were estimated using the CHI GEHRELS variance formula; then the total statistic was computed. Below, we explicit create and use an array of errors:
```
sherpa> e = [5.5,5.3,5.9]
sherpa> compute_statistic(d,m,e)
0.561761
sherpa> STATISTIC CHI DVAR
sherpa> compute_statistic(d,m,e)
0.561761
```
The version of $\chi ^2$ does not matter since the error estimates $\sigma$ are provided.

8.3 create_model

Module functions to instantiate new source or instrument models.

Integer_Type create_model(String_Type[,String_Type])
Integer_Type create_inst_model(String_Type[,String_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Name of Sherpa model component (e.g., GAUSS)

(2) ID applied to that component (e.g., g)

See the related Sherpa command CREATE for more information.

NOTE: In CIAO 3.1 the definition of INSTRUMENT BACK is required for fitting PHA data if either background file or background models have been defined. INSTRUMENT BACK is set automatically when the PHA data file is input to Sherpa, however it is deleted if the NEW background file is input for a given data set. Thus the new INSTRUMENT BACK has to be defined on the command line before starting a simultaneous fit with the new background file.

Examples:

Instantiate a polynomial model, and name it p:
```
sherpa> () = create_model("POLY","p")
```
Instantiate an rsp instrument model, and name it a:
```
sherpa> () = create_inst_model("RSP","a")
```

Instantiate a Gaussian model with default ID:

sherpa> () = create_model("GAUSS1D")
sherpa> SHOW
...
gauss1d[GAUSS1D]  (integrate: on)
    Param   Type      Value        Min        Max                 Units
    -----   ----      -----        ---        ---                 -----
 1   fwhm thawed         10 1.1755e-38 3.4028e+38                      
 2    pos thawed          0 -3.403e+38 3.4028e+38                      
 3   ampl thawed          1 -3.403e+38 3.4028e+38

8.4 dcounts

Calculates the sum of observed counts data for source or background datasets.

sherpa> [B]DCOUNTS [# [ID]] [{(<value>) | (<min>:<max>) | (<region descriptor>)} ]

DCOUNTS is used for summing source data counts, while BDCOUNTS is used for summing background data counts.

# specifies the dataset over which the source model is evaluated. The ID modifier is used only for summing background counts, and then if and only if the Sherpa state object variable multiback is set to 1, i.e., if more than one background dataset is to be associated with a single source dataset. The ID modifier may be any unreserved string (e.g., A, foo, etc.), i.e., a string that is not a parsable command.

The default is to do summations for all datasets. The summation may be computed at one energy/wavelength, over a range of energies/wavelengths, or within a 2-D region, with the default being to compute the flux the total available range.

For 1-D data, if

$\bullet$: one energy (or wavelength or bin number) value is given, then the data counts is returned for the bin associated with that value.
$\bullet$: an energy or wavelength range is given with the min and max arguments, then the total summed data counts for the given range is returned.
$\bullet$: no value or range is specified, then the total summed data counts for the full range of the dataset is returned.

For 2-D data, if a region descriptor is given, then the summation of data counts within that region is returned; otherwise, the summation is carried out over the entire input image.

Tip: To perform background subtraction in Sherpa, the command SUBTRACT must be issued; this is in contrast to XSPEC, which performs background subtraction automatically.

The summation of data counts may be done using the Sherpa/S-Lang module functions get_dcounts_sum and get_bdcounts_sum.

Examples:

Calculate the summation of data counts over the full energy range:

sherpa> DCOUNTS
Observed counts for source dataset 1: 1688 counts

Calculate the summation of background data counts over the range 2 to 10 keV. If the areas of the source and background extraction regions are different (as manifested by differences in, e.g., the BACKSCAL keywords in the headers of the source and background data files), then the number of expected background counts in the source region will also be shown.
```
sherpa> BDCOUNTS (2.0:10.0)
Observed counts for background dataset 1: 775 counts
     ...scaled to source region: 238.779 counts
```

Calculate the summation of data counts at a single energy (2.0 keV):

sherpa> DCOUNTS 1 (2.0)
Observed counts for source dataset 1: 23 counts

Calculate the summation of data counts over the energy range 2.0 to 4.0 keV:
```
sherpa> DCOUNTS 1 (2:4)
Observed counts for source dataset 1: 328 counts
```

Calculate the total flux within circles of radius 5 and 10 in a 2-D image (note, the quotes are necessary):

sherpa> DCOUNTS 1 "CIRCLE(247,257,5)"
Observed counts for source dataset 1: 1331 counts
sherpa> DCOUNTS 1 "CIRCLE(247,257,10)"
Observed counts for source dataset 1: 3068 counts

8.5 get

Summary of Sherpa/S-Lang module functions that retrieve settings or data.

The get functions of the Sherpa/S-Lang module:

$\bullet$: Retrieve numerical data from Sherpa so that, e.g., they may be manipulated using S-Lang operators and/or functions. (These data may be put back into Sherpa using analogous set functions.)
$\bullet$: Retrieve Sherpa settings. (Quantities may be set using analogous set functions.)

Note that not all get functions have set function analogues: for instance, while it makes sense to retrieve, change, and set estimated errors, it makes little sense to put new arrays of residuals or predicted model amplitudes into Sherpa.

Table 8.1: Summary of Sherpa/S-Lang Module set Functions
Name Description

get_data $\vert$ get_back Retrieves amplitudes of source and background datasets

get_fluxed_spectrum $\vert$ get_back Retrieve a fluxed spectrum (counts divided by ARF)

get_errors $\vert$ get_berrors Retrieves error estimates of source and background datasets

get_syserrors $\vert$ get_bsyserrors Retrieves systematic errors of source and background datasets

get_weights $\vert$ get_bweights Retrieves statistical weights for source and background datasets

get_mcounts $\vert$ get_bmcounts Retrieves predicted source and background model counts amplitudes

get_residuals $\vert$ get_bresiduals Retrieves the fit residuals for source and background datasets

get_delchi $\vert$ get_bdelchi Retrieves the fit sigma residuals for source and background datasets

get_ratio $\vert$ get_bratio Retrieves the ratio of data to model for source and background datasets

get_statistics $\vert$ get_bstatistics Retrieves the contribution to the current statistic value from each bin, for source and background datasets

get_source $\vert$ get_bg Retrieves predicted source and background model photon amplitudes

get_groups $\vert$ get_bgroups Retrieves grouping arrays associated with source and background dataset

get_quality $\vert$ get_bquality Retrieves quality arrays associated with source and background dataset

get_filter $\vert$ get_bfilter Retrieves filter arrays associated with source and background datasets

get_axes $\vert$ get_baxes Retrieves the energy/wavelength/channel grid of source and background datasets

get_energy_axes $\vert$ get_energy_baxes Retrieves the energy grid of source and background datasets

get_wave_axes $\vert$ get_wave_baxes Retrieves the wavelength grid of source and background datasets

get_raw_axes $\vert$ get_raw_baxes Retrieves the raw channel grid of source and background datasets

get_photon_axes $\vert$ get_bphoton_axes Retrieves photon-space grids over which models are evaluated

get_photon_energy_axes $\vert$ get_photon_energy_baxes Retrieves photon-space energy grids over which models are evaluated

get_photon_wave_axes $\vert$ get_photon_wave_baxes Retrieves photon-space wavelength grids over which models are evaluated

get_arf_axes $\vert$ get_arf_baxes Retrieves the energy/wavelength grid of an ARF associated with source and background datasets

get_analysis Retrieves the current analysis setting.

get_coord Retrieves the current coord setting.

get_fit $\vert$ get_goodness Retrieves information about the quality of a fit

get_statistic $\vert$ get_bstatistic Retrieves the current value of the statistic comparing source and background data and model values

get_record Returns a record of model parameter values at the end of each iteration of the fitting process

get_flux $\vert$ get_bflux Returns the unconvolved photon flux for source or background datasets

get_pflux2d Returns photon fluxes in 2-D images

get_eflux $\vert$ get_beflux Returns the unconvolved energy flux for source or background datasets

get_eflux2d Returns energy fluxes in 2-D images

get_mcounts_sum $\vert$ get_bmcounts_sum Returns the sum of convolved model counts in source and background datasets

get_mcounts_sum2d Returns sums of model counts in 2-D images

get_dcounts_sum $\vert$ get_bdcounts_sum $\vert$ get_net_counts_sum Returns the sum of observed counts in source and background datasets

get_dcounts_sum2d Returns sums of observed counts in 2-D images

get_eqwidth $\vert$ get_beqwidth Returns the equivalent width of a line in source or background data

get_par Retrieve model parameter values, etc.

get_unc Retrieves parameter bounds

get_proj Retrieves parameter bounds

get_cov Retrieves parameter bounds

get_intunc Retrieves parameter value and best-fit statistic arrays

get_intproj Retrieves parameter value and best-fit statistic arrays

get_regunc Retrieves parameter value and best-fit statistic arrays

get_regproj Retrieves parameter value and best-fit statistic arrays

get_dimension Retrieve the dimensionality of source data

get_exptime $\vert$ get_bexptime Retrieve source and background exposure times

get_backscale $\vert$ get_bbackscale Retrieve source and background extraction region areas

get_qvalue Returns the statistical significance computed as a -value

get_ftest Returns the statistical significance computed with the test

get_lfactorial Returns the natural logarithm of the factorial of the input quantity

get_source_expr $\vert$ get_bg_expr Get the source and background model stack expression

get_inst_expr $\vert$ get_sinst_expr $\vert$ get_binst_expr Get the source and background instrument model stack expression

get_filter_expr $\vert$ get_bfilter_expr Retrieves description of filters applied to source and background datasets

get_method_expr Returns the name of the current optimization method

get_stat_expr Returns the name of the current statistic

get_defined_models $\vert$ get_defined_inst_models Retrives lists of defined source and instrument models

get_models $\vert$ get_inst_models Returns lists of available source and instrument models

get_model_params $\vert$ get_inst_model_params Returns lists of parameter names for source and instrument models

get_num_par $\vert$ get_num_par_frozen $\vert$ get_num_par_thawed Reports the total number of parameters for all defined models, including instrument models

get_filename $\vert$ get_bfilename $\vert$ get_arf_filename $\vert$ get_rmf_filename Retrieve filenames associated with a dataset

get_dir Returns the name of the current directory

get_verbose Returns Sherpa's verbosity

**Table 8.1:** Summary of Sherpa/S-Lang Module `set` Functions
Name	Description
`get_data` $\vert$ `get_back`	Retrieves amplitudes of source and background datasets
`get_fluxed_spectrum` $\vert$ `get_back`	Retrieve a fluxed spectrum (counts divided by ARF)
`get_errors` $\vert$ `get_berrors`	Retrieves error estimates of source and background datasets
`get_syserrors` $\vert$ `get_bsyserrors`	Retrieves systematic errors of source and background datasets
`get_weights` $\vert$ `get_bweights`	Retrieves statistical weights for source and background datasets
`get_mcounts` $\vert$ `get_bmcounts`	Retrieves predicted source and background model counts amplitudes
`get_residuals` $\vert$ `get_bresiduals`	Retrieves the fit residuals for source and background datasets
`get_delchi` $\vert$ `get_bdelchi`	Retrieves the fit sigma residuals for source and background datasets
`get_ratio` $\vert$ `get_bratio`	Retrieves the ratio of data to model for source and background datasets
`get_statistics` $\vert$ `get_bstatistics`	Retrieves the contribution to the current statistic value from each bin, for source and background datasets
`get_source` $\vert$ `get_bg`	Retrieves predicted source and background model photon amplitudes
`get_groups` $\vert$ `get_bgroups`	Retrieves grouping arrays associated with source and background dataset
`get_quality` $\vert$ `get_bquality`	Retrieves quality arrays associated with source and background dataset
`get_filter` $\vert$ `get_bfilter`	Retrieves filter arrays associated with source and background datasets
`get_axes` $\vert$ `get_baxes`	Retrieves the energy/wavelength/channel grid of source and background datasets
`get_energy_axes` $\vert$ `get_energy_baxes`	Retrieves the energy grid of source and background datasets
`get_wave_axes` $\vert$ `get_wave_baxes`	Retrieves the wavelength grid of source and background datasets
`get_raw_axes` $\vert$ `get_raw_baxes`	Retrieves the raw channel grid of source and background datasets
`get_photon_axes` $\vert$ `get_bphoton_axes`	Retrieves photon-space grids over which models are evaluated
`get_photon_energy_axes` $\vert$ `get_photon_energy_baxes`	Retrieves photon-space energy grids over which models are evaluated
`get_photon_wave_axes` $\vert$ `get_photon_wave_baxes`	Retrieves photon-space wavelength grids over which models are evaluated
`get_arf_axes` $\vert$ `get_arf_baxes`	Retrieves the energy/wavelength grid of an ARF associated with source and background datasets
`get_analysis`	Retrieves the current analysis setting.
`get_coord`	Retrieves the current coord setting.
`get_fit` $\vert$ `get_goodness`	Retrieves information about the quality of a fit
`get_statistic` $\vert$ `get_bstatistic`	Retrieves the current value of the statistic comparing source and background data and model values
`get_record`	Returns a record of model parameter values at the end of each iteration of the fitting process
`get_flux` $\vert$ `get_bflux`	Returns the unconvolved photon flux for source or background datasets
`get_pflux2d`	Returns photon fluxes in 2-D images
`get_eflux` $\vert$ `get_beflux`	Returns the unconvolved energy flux for source or background datasets
`get_eflux2d`	Returns energy fluxes in 2-D images
`get_mcounts_sum` $\vert$ `get_bmcounts_sum`	Returns the sum of convolved model counts in source and background datasets
`get_mcounts_sum2d`	Returns sums of model counts in 2-D images
`get_dcounts_sum` $\vert$ `get_bdcounts_sum` $\vert$ `get_net_counts_sum`	Returns the sum of observed counts in source and background datasets
`get_dcounts_sum2d`	Returns sums of observed counts in 2-D images
`get_eqwidth` $\vert$ `get_beqwidth`	Returns the equivalent width of a line in source or background data
`get_par`	Retrieve model parameter values, etc.
`get_unc`	Retrieves parameter bounds
`get_proj`	Retrieves parameter bounds
`get_cov`	Retrieves parameter bounds
`get_intunc`	Retrieves parameter value and best-fit statistic arrays
`get_intproj`	Retrieves parameter value and best-fit statistic arrays
`get_regunc`	Retrieves parameter value and best-fit statistic arrays
`get_regproj`	Retrieves parameter value and best-fit statistic arrays
`get_dimension`	Retrieve the dimensionality of source data
`get_exptime` $\vert$ `get_bexptime`	Retrieve source and background exposure times
`get_backscale` $\vert$ `get_bbackscale`	Retrieve source and background extraction region areas
`get_qvalue`	Returns the statistical significance computed as a -value
`get_ftest`	Returns the statistical significance computed with the test
`get_lfactorial`	Returns the natural logarithm of the factorial of the input quantity
`get_source_expr` $\vert$ `get_bg_expr`	Get the source and background model stack expression
`get_inst_expr` $\vert$ `get_sinst_expr` $\vert$ `get_binst_expr`	Get the source and background instrument model stack expression
`get_filter_expr` $\vert$ `get_bfilter_expr`	Retrieves description of filters applied to source and background datasets
`get_method_expr`	Returns the name of the current optimization method
`get_stat_expr`	Returns the name of the current statistic
`get_defined_models` $\vert$ `get_defined_inst_models`	Retrives lists of defined source and instrument models
`get_models` $\vert$ `get_inst_models`	Returns lists of available source and instrument models
`get_model_params` $\vert$ `get_inst_model_params`	Returns lists of parameter names for source and instrument models
`get_num_par` $\vert$ `get_num_par_frozen` $\vert$ `get_num_par_thawed`	Reports the total number of parameters for all defined models, including instrument models
`get_filename` $\vert$ `get_bfilename` $\vert$ `get_arf_filename` $\vert$ `get_rmf_filename`	Retrieve filenames associated with a dataset
`get_dir`	Returns the name of the current directory
`get_verbose`	Returns Sherpa's verbosity

8.6 get_analysis

Module function to retrieve the current analysis setting.

String_Type get_analysis([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The get_analysis() function retrieves a string indicating the analysis setting for the specified dataset. The possible return values are "bin" (equivalent to ANALYSIS CHANNELS), "keV" (equivalent to ANALYSIS ENERGY), "Ang" (equivalent to ANALYSIS WAVE), "eV", "MeV", "nm", and "Hz".

Examples:

sherpa> data example.pha
sherpa> instrument = rsp[a](example.rmf,example.arf)
sherpa> get_analysis()
keV
sherpa>

8.7 get_arf_axes

Module functions to retrieve the energy/wavelength grid of an ARF associated with source and background data

Struct_Type get_arf_axes([Integer_Type])
Struct_Type get_arf_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

In Sherpa parlance, a "dataspace'' is an -dimensional grid defined by the independent variables of the dataset (i.e., ${\vec x}_i$ in the expression ${\vec y} = f({\vec x}_0,{\vec x}_1,...,{\vec x}_{N-1})$ ). Simple examples include the CHANNELS array in PHA datasets and the pixel numbers along each axis of FITS images.

The get_arf_axes() function returns a variable of Struct_Type, which is equivalent to that returned by get_axes(). The only difference is that the fields lo and hi contain data from the ENERG_LO and ENERG_HI columns from the input ARF file.

One may display the ARF on the same grid using the Sherpa plotting command LPLOT ARF.

8.8 get_axes

Module functions to get the energy/wavelength/channel grid of source and background datasets.

Struct_Type | Array_Type get_axes([Integer_Type])
Struct_Type | Array_Type get_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The get_axes() function retrieves the dataspace, or filtered data set axes of the appropriate data set (if no argument is given, the axes for data set 1 are retrieved). The units of the axes are those appropriate for the current Sherpa ANALYSIS setting. For instance, if one is working with filtered PHA data in energy-space, what is returned are the low and high bin boundaries in keV (quantities assigned by the EBOUNDS extension of the RMF). (The get_baxes() function retrieves the filtered axes for the background associated with the appropriate data set.)

What is returned is an array of structures of length equal to the number of dimensions (e.g., 2 for image data). If the data are one-dimensional, a single Struct_Type variable is returned. There are five structure fields:

$\bullet$: axistype: either Channels, Energy, or Wavelength.
$\bullet$: axisunits: either unknown, keV, or Å.
$\bullet$: lo: the array of lower bin boundaries; is NULL if there is no bin-width information available.
$\bullet$: hi: the array of upper bin boundaries; is NULL if there is no bin-width information available.
$\bullet$: mid: NULL if bin-width information is available; otherwise it contains the unbinned axis gridpoints.

One may display data et al. on the same grid output by get_axes using the Sherpa plotting commands LPLOT DATA et al.

Examples:

sherpa> data example.fits
sherpa> foo = get_axes()
sherpa> print(foo[0])	# image pixels, x-axis
   axistype         =  Channels
   axisunits        =  unknown
   lo               =  Float_Type[512]
   hi               =  Float_Type[512]
   mid              =  NULL

sherpa> data example.pha
sherpa> instrument = rsp[a](example.rmf,example.arf)
sherpa> foo = get_axes()
sherpa> print(foo[0])	# energy grid for PHA data
axistype         =  Energy
axisunits        =  keV
lo               =  Float_Type[1024]
hi               =  Float_Type[1024]
mid              =  NULL

sherpa> data example.dat
sherpa> foo = get_axes()
sherpa> print(foo[0]) 	# channel grid for unbinned ASCII data
axistype         =  Channels
axisunits        =  unknown
lo               =  NULL
hi               =  NULL
mid              =  Float_Type[100]

8.9 get_coord

Module function to retrieve the current coordinate setting for 2-D image data.

String_Type get_coord([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The get_coord() function retrieves a string indicating the coordinate setting for the specified dataset. For Sherpa version 3.0.2, the possible return values are "logical" (equivalent to image), "physical", or "world" (equivalent to wcs).

Examples:

sherpa> data example.fits
sherpa> coord 1 physical
sherpa> get_coord()
physical
sherpa>

8.10 get_data

Module functions to get the amplitudes of source and background datasets.

Array_Type get_data([Integer_Type])
Array_Type get_back([Integer_Type])
Array_Type get_full_data([Integer_Type])
Array_Type get_full_back([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

In a typical analysis involving module functions, a user will not seek to manipulate the axes (which are useful primarily for plotting), but to manipulate amplitudes (i.e., ${\vec y}$ in the expression ${\vec y} = f({\vec x}_0,{\vec x}_1,...,{\vec x}_{N-1})$ .) A very simple example would be smoothing of data; a more complex example would be the setting of error estimates iteratively in a manner not supported by Sherpa. First the user would "get'' the error array, then process it, then "set'' it back into Sherpa.

These functions return arrays containing the -values of the input datasets. The ones without full in the name return arrays comprised of data within the applied filter; those with full in the name retrieve the unfiltered datasets.

(If the goal is to use these functions to manipulate data, and to set these data back into Sherpa, it is important not to change the filter in Sherpa between calling the get and set functions!)

Source and background data may be displayed, e.g., via the Sherpa plotting commands LPLOT DATA and LPLOT BACK.

Examples:

sherpa> data example.dat
sherpa> d = get_data(1)
sherpa> printarr(d,2)
59      
46      
sherpa> d[0] = 80
sherpa> () = set_data(1,d)
sherpa> write data
Write X-Axis: Bin  Y-Axis: Flux (Counts)
          1         80
          2         46

8.11 get_dcounts_sum

Calculates the sum of observed counts in source and background datasets using module functions in Sherpa.

Struct_Type get_dcounts_sum(Struct_Type)
Struct_Type get_bdcounts_sum(Struct_Type)
Struct_Type get_net_counts_sum(Struct_Type)
Struct_Type get_dcounts_sum([Integer_Type[,{Float_Type | Array_Type}]])
Struct_Type get_bdcounts_sum([Integer_Type[,{Float_Type | Array_Type}]])
Struct_Type get_net_counts_sum([Integer_Type[,{Float_Type | Array_Type}]])

Error Return Values: NULL

Arguments:

(1) Structure of form returned by get_flux_str; or

(1) Dataset number (default 1)

(2) Evaluation point, or lower-upper bounds (default use all data)

(3) Model component or stack name (default use all appropriate models)

These functions retrieve the summation of observed data counts. get_net_counts_sum retrieves the summation of observed source, i.e., background-subtracted counts. Note that this function does not require the data to be background-subtracted.

The output of get_flux_str(), a structure, can be used as input to get_dcounts_sum() and get_bdcounts_sum(). One would retrieve this default structure, modify its field values, and pass it to get_dcounts_sum() et al. See the example below.

Note that numerical arguments are interpreted using Sherpa's current ANALYSIS setting.

The structure output by these functions contains the following fields:

Table 8.2: get_dcounts_sum Structure Fields
Field Description

dataset the dataset for which the counts summation is evaluated

range the single point at which the counts is determined, or the range over which the counts are summed; if NULL, the summation is done over the entire dataset range

comp NULL for these functions

value the summation of counts

units NULL for these functions

**Table 8.2:** `get_dcounts_sum` Structure Fields
Field	Description
`dataset`	the dataset for which the counts summation is evaluated
`range`	the single point at which the counts is determined, or the range over which the counts are summed; if NULL, the summation is done over the entire dataset range
`comp`	`NULL` for these functions
`value`	the summation of counts
`units`	`NULL` for these functions

See the related Sherpa command DCOUNTS for more information.

Examples:

Determine the number of counts in a dataset between 2 and 10 keV:

sherpa> foo = get_flux_str()
sherpa> print(foo)
dataset          =  1
range            =  NULL
comp             =  NULL
sherpa> foo.range = [2,10]
sherpa> print(get_dcounts_sum(foo).value)
518
sherpa> print(get_net_counts_sum(foo).value)
279.221

8.12 get_defined_models

Module functions that return lists of defined Sherpa source and instrument models

Array_Type get_defined_models()
Array_Type get_defined_inst_models()

Error Return Value: NULL

Returns a string array containing the names given by the user to all instantiated Sherpa source or instrument models, for use in record-keeping, GUIs, etc. (This includes XSPEC models and user-defined models.)

See the related Sherpa command SHOW for more information.

Examples:

Define two models; list their names:

sherpa> SOURCE = GAUSS[g] + POW[p]
sherpa> mnames = get_defined_models()
sherpa> printarr(mnames)
g
p

8.13 get_dir

Module function to retrieve the current path.

String_Type get_dir()

Error Return Values: NULL

Note that the returned string does not include the trailing `/'.

See the related Sherpa command CD for more information.

8.14 get_eflux

Calculate the energy flux (unconvolved) for source or background datasets using module functions in Sherpa.

Struct_Type get_eflux(Struct_Type)
Struct_Type get_beflux(Struct_Type)
Struct_Type get_eflux([Integer_Type[,{Float_Type | Array_Type}[,String_Type]]])
Struct_Type get_beflux([Integer_Type[,{Float_Type | Array_Type}[,String_Type]]])

Error Return Values: NULL

Arguments:

(1) Structure of form returned by get_flux_str; or

(1) Dataset number (default 1)

(2) Evaluation point, or lower-upper bounds (default use all data)

(3) Model component or stack name (default use all appropriate models)

The get_eflux and get_ebflux functions retrieve the energy flux, nominally in units of ${\rm erg/cm^2/s}$ (if the flux is computed over a range), or ${\rm erg/cm^2/s/keV}$ (or Å) (if the flux is computed at a single point). The actual units depend upon the units of the input data and whether or not instrument models have been specified, etc.

The output of get_flux_str(), a structure, can be used as input to get_eflux() and get_beflux(). One would retrieve this default structure, modify its field values, and pass it to get_eflux() et al. See the example below.

Note that numerical arguments are interpreted using Sherpa's current ANALYSIS setting.

The structure output by these functions contains the following fields:

Table 8.3: get_eflux Structure Fields
Field Description

dataset the dataset for which the flux is evaluated

range the single point at which the flux is computed, or the range over which the flux is integrated; if NULL, the integral is done over the entire dataset range

comp the model stack or component for which the flux is computed; if NULL, the whole source/bg stack is used

value the computed flux value

units the flux units

**Table 8.3:** `get_eflux` Structure Fields
Field	Description
`dataset`	the dataset for which the flux is evaluated
`range`	the single point at which the flux is computed, or the range over which the flux is integrated; if NULL, the integral is done over the entire dataset range
`comp`	the model stack or component for which the flux is computed; if NULL, the whole source/bg stack is used
`value`	the computed flux value
`units`	the flux units

See the related Sherpa command EFLUX for more information.

Examples:

Fit an absorbed power law function to the data set and compute the flux between 2 and 10 keV:

sherpa> source= xsphabs[abs]*pow[p1]
sherpa> ignore energy :0.3,10:
sherpa> subtract
sherpa> fit
 LVMQT: V2.0
 LVMQT: initial statistic value = 1401.63
 LVMQT: final statistic value = 235.824 at iteration 5
           abs.nH  0.0626393  10**22 atoms/cm**2  
            p1.gamma  1.70739     
            p1.ampl  6.81852e-05     

sherpa> foo=get_eflux(1,[2,10])
sherpa> print(foo)
dataset          =  1
range            =  Float_Type[2]
comp             =  NULL
value            =  7.72792e-14
units            =  ergs/cm**2/s
sherpa> print(foo.value)        
7.72792e-14

Define a structure foo and use it to compute the flux between 2 and 10 keV:

sherpa> foo = get_flux_str()
sherpa> print(foo)
dataset          =  1
range            =  NULL
comp             =  NULL
sherpa> foo.range = [2,10]
sherpa> print(get_eflux(foo).value)
6.76339e-13
sherpa> print(get_eflux(foo).units)
ergs/cm**2/s
sherpa> print(get_eflux(,2.0,"p").value)
1.76965e-13

8.15 get_energy_axes

Module functions to retrieve the energy grids of source and background datasets.

{Struct_Type | Array_Type} get_energy_axes([Integer_Type])
{Struct_Type | Array_Type} get_energy_baxes([Integer_Type])
{Struct_Type | Array_Type} get_full_energy_axes([Integer_Type])
{Struct_Type | Array_Type} get_full_energy_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The get_energy_axes() function retrieves the dataspace, or filtered data set axes of the appropriate data set (if no argument is given, the axes for data set 1 are retrieved). Regardless of the current Sherpa ANALYSIS setting, this function returns the dataspace in units of energy (keV). Otherwise, the function is similar to get_axes().

The function get_full_energy_axes() is similar to get_energy_axes(), except that get_full_energy_axes() returns the original, unfiltered dataspace in units of energy. (And get_energy_baxes() and get_full_energy_baxes() return filtered and unfiltered dataspaces for the background associated with the source data set, in units of energy.)

One may display data et al. on the same grid output by get_energy_axes using the Sherpa plotting commands LPLOT DATA et al.

Examples:

Read the PHA file with the ARF/RMF defined in the header (qso.pha). Obtain the energy axes information into "foo" and print content of "foo". Print the value of the third energy in "foo". The mid is NULL, so the final print command gives an error information.

sherpa> data qso.pha
sherpa> foo=get_energy_axes()
sherpa> print(foo)
axistype         =  Energy
axisunits        =  keV
lo               =  Float_Type[1024]
hi               =  Float_Type[1024]
mid              =  NULL
sherpa> print(foo.lo[2])
0.0292
sherpa> print(foo.mid[2])
Type Mismatch: Context requires an array.  Scalar not converted
Type Mismatch: print(foo.mid[2]);

8.16 get_eqwidth

Module functions that compute the equivalent width of an emission or absorption line in source or background data.

Float_Type get_eqwidth([Integer_Type],String_Type,String_Type)
Float_Type get_beqwidth([Integer_Type],String_Type,String_Type)

Error Return Values: NULL

Arguments:

(1) Dataset number (default 1)

(2) Expression defining the continuum model

(3) Expression defining the continuum-plus-line model

See the related Sherpa command EQWIDTH for definitions and more information.

Examples:

Model a continuum and emission line complex using a power-law and normalized Gaussian, then compute the equivalent width:

sherpa> SOURCE = POW[cont]+NGAUSS[eline]
...
sherpa> FIT
...
sherpa> EQWIDTH 1 (cont,cont+eline)
EW = 0.535073 keV
sherpa> foo = get_eqwidth(1,"cont","cont+eline")
sherpa> print(foo)
0.535073

8.17 get_errors

Module functions to get the error estimates of source and background datasets.

Array_Type get_errors([Integer_Type])
Array_Type get_berrors([Integer_Type])
Array_Type get_full_errors([Integer_Type])
Array_Type get_full_berrors([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

These functions return arrays containing the current error estimates associated with input datasets. The ones without full in the name return arrays comprised of error estimates within the applied filter; those with full in the name retrieve the unfiltered error estimates.

(If the goal is to use these functions to manipulate data, and to set these data back into Sherpa, it is important not to change the filter in Sherpa between calling the get and set functions!)

Source and background error estimates may be displayed, e.g., via the Sherpa plotting commands LPLOT ERRORS and LPLOT BERRORS.

Examples:

sherpa> DATA spec.dat
sherpa> e = get_errors(1)
sherpa> printarr(e,2)
8.72981
7.8374
sherpa> e[0] = 5
sherpa> () = set_errors(1,e)
sherpa> write errors
Write X-Axis: Bin  Y-Axis: Errors
          1          5
          2     7.8374

8.18 get_filename

Module functions to retrieve filenames associated with a dataset.

String_Type get_filename([Integer_Type])
String_Type get_bfilename([Integer_Type])
String_Type get_arf_filename([Integer_Type])
String_Type get_rmf_filename([Integer_Type])

Error Return Value: NULL

These functions retrieve the source dataset file name, the background dataset file name, the ARF instrument file name, and the RMF instrument file name respectively, for use in record-keeping, GUIs, etc.

Note: depending upon how the files are read in, the displayed file name may show the entire directory path. See example below.

See the related Sherpa command SHOW.

Examples:

Input data from files; display file names:

sherpa> DATA example.pha
...
sherpa> get_filename
example.pha
sherpa> get_bfilename
/data/simteste/Testing/sherpaTest/data/example2_bkg.pha
sherpa> get_arf_filename
/data/simteste/Testing/sherpaTest/data/example2.arf
sherpa> get_rmf_filename
/data/simteste/Testing/sherpaTest/data/example2.rmf

8.19 get_filter

Module functions to get the filter arrays associated with source and background datasets.

Array_Type get_filter([Integer_Type])
Array_Type get_bfilter([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The function get_filter() returns an array of type Short_Type that is the same size as the input data set (i.e., the unfiltered data set). The array features two values: 0 for bins outside the currently defined filter, and 1 for bins within the filter. This function may be used in combination with set_filter to define new methods of data filtering that go beyond those currently coded in Sherpa; e.g., filtering based on data amplitude. (The function get_bfilter() returns the filter associated with the background data set.)

Source and background data filters may be displayed, e.g., via the Sherpa plotting commands LPLOT FILTER and LPLOT BFILTER.

Examples:

sherpa> data example.dat          # 100 bins, mean amplitude 60
sherpa> foo = get_data()
sherpa> bar = get_filter()
sherpa> bar[where(foo>60)] = 0    # filter out all bins with data > 60
sherpa> () = set_filter(1,bar)
sherpa> write data
Write X-Axis: Bin  Y-Axis: Flux (Counts)
          1         59
          2         46
          3         49
	  5         60
          6         60
          8         58

sherpa> data foo.pha
sherpa> ignore bad
sherpa> notice energy 4:9
sherpa> bar = get_filter_expr()
sherpa> printarr(bar)
ignore source 1 bad
notice source 1 energy 4 : 9

8.20 get_filter_expr

Module function to retrieve the strings describing filters applied to source and background datasets.

Array_Type get_filter_expr([Integer_Type])
Array_Type get_bfilter_expr([Integer_Type])

Error Return Value: NULL

These functions returns an array of filter expressions, for use in record-keeping, GUIs, etc. Each string in this array is a command that contributed to the calculation of the filter; the commands were applied to the filter in the order in which they are stored in the array.

See the related Sherpa command SHOW ALL.

Examples:

Retrieve a set of filter expressions applied to dataset 1:

sherpa> fltexpr = get_filter_expr()
sherpa> print(fltexpr) 
notice source 1 energy 2 : 4 
notice source 1 wavelength 12 : 24

8.21 get_fit

Module functions to get information about the quality of a fit.

Array_Type get_fit([Integer_Type | Array_Type])
Array_Type get_goodness([Integer_Type | Array_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default all data sets), or an array of data set numbers.

The functions get_fit() and get_goodness() return information about the quality of fit. Currently, the function returns an array of S-Lang variables of Struct_Type. The array is of length 1 if information for only one data set is requested, or if information for data sets is requested. In the latter case, the total statistic, etc., is given by the first element of the returned array.

The output Struct_Type variable contains the following fields:

$\bullet$: dataset: the number of the fit dataset; if NULL, then the Struct_Type variable contains information about all fits.
$\bullet$: datatype: one of source, bkgd, or total.
$\bullet$: stat: the observed statistic value, or the sum of the statistic values if datatype is set to total.
$\bullet$: numbins: the number of bins involved in the fit.
$\bullet$: dof: the number of degrees of freedom: numbins minus the number of model free parameters.
$\bullet$: rstat: the reduced statistic, stat divided by dof; this field is NULL for the statistics CASH and BAYES.
$\bullet$: qval: the value (see get_qvalue()); this field is NULL for the statistics CASH and BAYES.

See the related Sherpa command GOODNESS for more information.

Examples:

[...fit two datasets...]
sherpa> res = get_fit()
sherpa> print(res[0])
dataset          =  NULL    # the total stat, etc., are shown
datatype         =  total   #
stat             =  127.821
numbins          =  200
dof              =  197
rstat            =  0.64884
qval             =  0.999964
sherpa> res = get_res(2)
sherpa> print(res[0])
dataset          =  2       # only the fit info for dataset 2 shown
datatype         =  source
stat             =  63.9103
numbins          =  100
dof              =  98
rstat            =  0.652146
qval             =  0.996969

8.21.1 CHANGES IN CIAO 3.2

The get_fit() function now works correctly when given an argument. Prior to CIAO 3.2 it would ignore the supplied argument.

8.22 get_flux2d

Module functions for computing fluxes/summing counts in 2-D images.

Struct_Type get_pflux2d([Integer_Type[,String_Type[,String_Type]]])
Struct_Type get_eflux2d([Integer_Type[,String_Type[,String_Type]]])
Struct_Type get_mcounts_sum2d([Integer_Type[,String_Type[,String_Type]]])
Struct_Type get_dcounts_sum2d([Integer_Type[,String_Type]])

Error Return Values: NULL

Arguments:

(1) Dataset number (default 1)

(2) Evaluation point, or 2-D region descriptor (default use all data)

(3) Model component or stack name (default use all appropriate models)

These functions retrieve the photon flux, energy flux, summation of convolved predicted model counts, and summation of observed counts respectively. The flux units depend upon the units of the exposure map but may not be correct in the current version of Sherpa, so use caution.

The structure output by these functions contains the following fields:

Table 8.4: 2-D Flux Structure Fields
Field Description

dataset the dataset for which the flux is evaluated/counts summed

range the single point at which the flux is computed/counts summed, or the range over which the flux is integrated/counts summed; if NULL, the integral is done over the entire dataset range

comp the model stack or component for which the flux is computed/counts summed; if NULL, the whole source/bg stack is used

value the computed flux value/sum of counts

units the flux units (NULL for counts)

**Table 8.4:** 2-D Flux Structure Fields
Field	Description
`dataset`	the dataset for which the flux is evaluated/counts summed
`range`	the single point at which the flux is computed/counts summed, or the range over which the flux is integrated/counts summed; if NULL, the integral is done over the entire dataset range
`comp`	the model stack or component for which the flux is computed/counts summed; if NULL, the whole source/bg stack is used
`value`	the computed flux value/sum of counts
`units`	the flux units (`NULL` for counts)

In the current version of the Sherpa/S-Lang module, there are no functions for computing fluxes/summations of counts for 2-D background datasets.

Also, in the current version of the Sherpa/S-Lang module, there is no way to specify a coordinate system when specifying a 2-D region descriptor; logical coordinates are assumed.

See the related Sherpa commands FLUX, EFLUX, MCOUNTS, and DCOUNTS for more information.

Examples:

Fit a 2-D Gaussian to data without an exposure map; compute photon fluxes and summed model counts (which will be equal in this simplistic example):

sherpa> DATA example_img.fits
sherpa> NOTICE FILTER circle(247,257,20)"
sherpa> PARAMPR OFF
sherpa> SOURCE = GAUSS2D[g]
sherpa> FIT
...
sherpa> print(get_pflux2d().value)
3523.46
sherpa> print(get_mcounts_sum2d().value)
3523.46

Include the exposure map in fitting the data, filter the data, define the source model and fit; obtain the photon flux.

sherpa> data img_bin.fits 
sherpa> farf2d[em1]
em1.file parameter value ["none"] expmap.fits
em1.norm parameter value [1] 

sherpa> instrument=em1
               # include the exposure map in the instrument stack

sherpa> notice filter "rotbox(4022.825,4119.3,15.2,14.95,0)"

sherpa> foo=get_eflux2d
sherpa> print(foo)
NULL                 # source model has not been defined

sherpa> source=gauss2d[g2] 
g2.fwhm parameter value [10.8243] 
g2.xpos parameter value [294.5] 
g2.ypos parameter value [306.5] 
g2.ellip parameter value [0] 
g2.theta parameter value [0] 
g2.ampl parameter value [30] 

sherpa> freeze g2.xpos g2.ypos
sherpa> fit
 LVMQT: V2.0
 LVMQT: initial statistic value = 4.14528e+12
 LVMQT: final statistic value = 2625.34 at iteration 5
            g2.fwhm  1.03876     
            g2.ampl  8.5054e-07     

sherpa> foo1=get_flux2d

sherpa> print(foo1)
dataset          =  1
range            =  NULL
comp             =  NULL
value            =  1.03989e-06
units            =  photons/cm**2/s

8.23 get_flux_str

Retrieves a default structure for use with get_pflux(), etc.

Struct_Type get_flux_str()

The output of get_flux_str(), a structure, can be used as input to get_pflux() and get_bpflux(). One would retrieve this default structure, modify its field values, and pass it to get_pflux() et al. See the example below.

Examples:

Define a structure foo and use it to compute the flux between 2 and 10 keV:

sherpa> foo = get_flux_str()
sherpa> print(foo)
dataset          =  1
range            =  NULL
comp             =  NULL
sherpa> foo.range = [2,10]
sherpa> print(get_flux(foo).value)
0.000166532
sherpa> print(get_flux(foo).units)
photons/cm**2/s
sherpa> print(get_pflux(,[2,10],"p").value)
0.000166532

8.24 get_fluxed_spectrum

Retrieve a fluxed spectrum (counts divided by ARF) using module functions in Sherpa.

Struct_Type get_fluxed_spectrum([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

This function takes the appropriate data set and divides it by the ARF, if the data are counts (PHA) data and information from an ARF file has also been read in. The function returns a S-Lang variable of Struct_Type containing the counts data divided by the ARF (data), the Poisson errors divided by the ARF (errors), and (in a future version) the ARF itself, estimated on the counts space energy/wavelength grid (arf).

The data and errors arrays can then be used directly in analyses (after using set_data() and set_errors()), or can be modified further by the user (e.g., converted from $cts\ cm^{-2}$ to $cts\ cm^{-2}\ s^{-1}$ using get_exptime()).

Examples:

Obtain the fluxed spectrum and make a plot of the spectrum, include errorbars. Finally write fluxed spectrum to the ascii file.

sherpa> foo = get_fluxed_spectrum
sherpa> print(spec1)
data             =  Float_Type[663]
errors           =  Float_Type[663]
arf              =  Float_Type[663]
sherpa> xax=get_energy_axes             
                                # obtain the energy scale
sherpa> print(xax)
axistype         =  Energy
axisunits        =  keV
lo               =  Float_Type[663]
hi               =  Float_Type[663]
mid              =  NULL

sherpa> plot x xax.lo y spec1.data e spec1.errors   
                               # this is CHIPS plot command

sherpa> writeascii("fluxed_spec.dat",x.lo, x.hi, spec1.data, 
spec1.errors, spec1.arf)

sherpa> $more fluxed_spec.dat
0.3066  0.3212  0.638139        0.172438        32.8455
0.3212  0.3358  0.249041        0.0901943       52.2003
0.3358  0.3504  0.163455        0.0657966       67.2967
0.3504  0.365   0.206631        0.0633644       82.2723
0.365   0.3796  0.213993        0.0594795       93.3986

8.25 get_ftest

Module function that returns the statistical significance computed with the test

Double_Type get_ftest(Integer_Type, Double_Type, Integer_Type, Double_Type)

Error Return Value: NULL

Arguments:

(1) number of degrees of freedom

(2) observed statistic value $\chi_1^2$

(3) number of degrees of freedom

(4) observed statistic value $\chi_2^2$

This function returns the tail integral of the distribution, $\alpha_F$ .

See the related Sherpa command FTEST for more information.

8.26 get_groups

Module functions for retrieving a grouping or quality array from source and background files.

Integer_Type get_groups([Integer_Type])
Integer_Type get_bgroups([Integer_Type])
Integer_Type get_quality([Integer_Type])
Integer_Type get_bquality([Integer_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1).

The get_(b)groups and get_(b)quality functions allow the user to retrieve grouping and quality information for source and background datasets.

If the file is not grouped or quality is not set, NULL is returned. If the files is grouped or quality defined, an array is returned.

The retrieved array is a Integer_Type array of the same length as the input (grouped) dataset. A grouping array element set to -1 marks the beginning of a group, while array element set to 1 marks members of that group, so the corresponding bins are treated as one during fitting.

A quality array contains the quality flags for each group: 0 for good (grouped) data; 5 for data labeled as bad by the user (within a tab), and 2 for data labeled as questionable by dmgroup (incomplete groups, etc.).

The grouping and quality definitions are based on OGIP standard.

See the related Sherpa commands GROUP and QUALITY for more information.

Examples:

Retrive and apply a grouping scheme from the other data set to an ungrouped data set.

sherpa> DATA spec.pha
sherpa> show
....
-----------------
Input data files:
-----------------
 
Data 1: spec.pha pha.
Total Size: 1024 bins (or pixels)
Dimensions: 1
Total counts (or values): 2231

.......
sherpa> DATA 2 spec_grp.pha
sherpa> show
....
-----------------
Input data files:
-----------------
 
Data 1: spec.pha pha.
Total Size: 1024 bins (or pixels)
Dimensions: 1
Total counts (or values): 2231


......

Data 2: spec_grp.pha pha.
Total Size: 131 bins (or pixels)
Dimensions: 1
Total counts (or values): 2231
......
sherpa> g=get_groups(2)
sherpa> print(g)
1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
1
-1
.....
sherpa> set_groups(1,g)
WARNING: any applied filters are being deleted!
1
sherpa> show

Data 1: spec.pi pha.
Total Size: 131 bins (or pixels)
Dimensions: 1
Total counts (or values): 2231
.....

In this example, ungrouped and group data are read into Sherpa, and then group information is retrieved using get_groups from the grouped dataset. A new array g is defined whose elements are defined by the grouping of the dataset 2. This grouping scheme is then apply to the ungrouped data set with set_groups.

Retrieve and apply a grouping scheme from the source data set to ungrouped background data.

sherpa> DATA spec.pha
sherpa> show
....
-----------------
Input data files:
-----------------
 
Data 1: spec.pha pha.
Total Size: 1024 bins (or pixels)
Dimensions: 1
Total counts (or values): 2231

 Background 1: bg.pha pha.
  Total Size: 1024 bins (or pixels)
  Dimensions: 1
  Total counts (or values): 662

.......

sherpa> g=get_groups(1)
sherpa> print(g)
1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
-1
1
-1
.....
sherpa> set_bgroups(1,g)
WARNING: any applied filters are being deleted!
1
sherpa> show

Data 1: spec.pi pha.
Total Size: 131 bins (or pixels)
Dimensions: 1
Total counts (or values): 2231

 Background 1: bg.pha pha.
 Total Size: 131 bins (or pixels)
  Dimensions: 1
  Total counts (or values): 662
......

In this example, group data and ungrouped background data are read into Sherpa, and then group information is retrieved using get_groups from the grouped dataset. A new array g is defined whose elements are defined by the grouping of the source data set. This grouping scheme is then apply to the ungrouped background data set with set_bgroups.

8.27 get_lfactorial

Module function to compute the natural logarithm of the factorial of the input quantity

Double_Type get_lfactorial(Double_Type)

This function may be used, e.g., to convert the Cash statistic to the true Poisson log-likelihood in simulation scripts. The input number must be non-negative.

Examples:

Compute the natural log of 6 factorial:
```
sherpa> get_lfactorial(6)
6.57925
```

8.28 get_mcounts_sum

Module functions for computing the sum of convolved model counts in source and background datasets.

Struct_Type get_mcounts_sum(Struct_Type)
Struct_Type get_bmcounts_sum(Struct_Type)
Struct_Type get_mcounts_sum([Integer_Type[,{Float_Type | Array_Type}[,String_Type]]])
Struct_Type get_bmcounts_sum([Integer_Type[,{Float_Type | Array_Type}[,String_Type]]])

Error Return Values: NULL

Arguments:

(1) Structure of form returned by get_flux_str; or

(1) Dataset number (default 1)

(2) Evaluation point, or lower-upper bounds (default use all data)

(3) Model component or stack name (default use all appropriate models)

These functions retrieve the summation of convolved predicted model amplitudes.

The output of get_flux_str(), a structure, can be used as input to get_mcounts_sum() and get_bmcounts_sum(). One would retrieve this default structure, modify its field values, and pass it to get_mcounts_sum() et al. See the example below.

Note that numerical arguments are interpreted using Sherpa's current ANALYSIS setting.

The structure output by these functions contains the following fields:

Table 8.5: get_mcounts_sum Structure Fields
Field Description

dataset the dataset for which the counts summation is evaluated

range the single point at which the counts is determined, or the range over which the counts are summed; if NULL, the summation is done over the entire dataset range

comp the model stack or component for which the counts are summed; if NULL, the whole source/bg stack is used

value the summation of counts

units NULL for these functions

**Table 8.5:** `get_mcounts_sum` Structure Fields
Field	Description
`dataset`	the dataset for which the counts summation is evaluated
`range`	the single point at which the counts is determined, or the range over which the counts are summed; if NULL, the summation is done over the entire dataset range
`comp`	the model stack or component for which the counts are summed; if NULL, the whole source/bg stack is used
`value`	the summation of counts
`units`	`NULL` for these functions

See the related Sherpa command MCOUNTS for more information.

Examples:

Fit a power-law to a dataset; compute the sum of model amplitudes between 2 and 10 keV:

sherpa> foo = get_flux_str()
sherpa> print(foo)
dataset          =  1
range            =  NULL
comp             =  NULL
sherpa> foo.range = [2,10]
sherpa> print(get_mcounts_sum(foo).value)
291.483
sherpa> print(get_mcounts_sum(,2.0,"p").value)
12.6129

8.29 get_metadata

Module functions to retrieve metadata associated with source and background datasets.

Integer_Type get_dimension([Integer])
Float_Type get_exptime([Integer])
Float_Type get_bexptime([Integer])
Float_Type get_backscale([Integer])
Float_Type get_bbackscale([Integer])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The function get_dimension() retrieves the dimensionality of the appropriate data set (e.g., 1 for PHA data, 2 for images). (If no argument is given, the dimensionality of data set 1 is retrieved.)

The function get_exptime() retrieves the exposure time of the appropriate data set, in seconds. (The function get_bexptime() retrieves the exposure time of the background data set.)

The function get_backscale() retrieves the value of the BACKSCAL keyword associated with the appropriate data set (assuming the file from which that data was read was a PHA file). (The function get_bbackscale() retrieves the value of the BACKSCAL associated with the appropriate background data set.)

See the related Sherpa command SHOW ALL for more information.

Examples:

sherpa> data example.pha
sherpa> get_exptime()
28678

8.30 get_method_expr

Module function to retrieve the name of the current optimization method.

String_Type get_method_expr()

Error Return Value: NULL

This function retrieves the name of the optimization method currently set in Sherpa, for use in record-keeping, GUIs, etc.

See the related Sherpa command SHOW METHOD.

Examples:

Display the Sherpa optimization method:

sherpa> meth1 = get_method_expr 
sherpa> print(meth1)
levenberg-marquardt
sherpa> METHOD SIMPLEX
sherpa> meth2 = get_method_expr 
sherpa> print(meth2)
simplex

8.31 get_model_params

Access to the default model and instrument parameters of Sherpa from S-Lang.

Array_Type get_model_params([String_Type])
Array_Type get_inst_model_params([String_Type])

Error Return Value: NULL

Argument:

(1) matching string (default none: list all models)

The two functions allow you to get the default parameter values for all the models in Sherpa: get_model_params() works on "source" models - such as xsraymond and gauss2d - whilst get_inst_model_params() works on "instrument" models such as rsp1d. Each model is described by a structure and the functions return an array of structures, one for each model whose name contains the function argument (if no argument is given all models are returned).

These functions return information about the default parameter values of each model (i.e. what the initial values for the models are set to when an instance of the model is created). The get_par() function should be used to get the current parameter values of a particular instance of a model.

Table 8.6: Structure returned by get_model_params() and get_inst_model_params().
Field name Description

name The name of the model.

type The type of the model: "sherpa", "xspec", or "usermodel".

numpars The number of parameters in the model.

integrated What is the default integration mode for this model: 1 for on, 0 for off.

params An array of structures containing the parameter values. This structure is a subset of that returned by the get_par() function and is described below.

Table 8.7: Contents of the params field.
Field name Description

name The parameter name.

value The default parameter value.

min The default minimum value for the parameter.

max The default maximum value for the parameter.

units The units of the parameter. The field will be set to NULL if no units are defined.

frozen Set to 1 if the parameter is frozen by default, 0 otherwise.

**Table 8.6:** Structure returned by `get_model_params()` and `get_inst_model_params()`.
Field name	Description
`name`	The name of the model.
`type`	The type of the model: "`sherpa`", "`xspec`", or "`usermodel`".
`numpars`	The number of parameters in the model.
`integrated`	What is the default integration mode for this model: 1 for on, 0 for off.
`params`	An array of structures containing the parameter values. This structure is a subset of that returned by the `get_par()` function and is described below.

**Table 8.7:** Contents of the `params` field.
Field name	Description
`name`	The parameter name.
`value`	The default parameter value.
`min`	The default minimum value for the parameter.
`max`	The default maximum value for the parameter.
`units`	The units of the parameter. The field will be set to NULL if no units are defined.
`frozen`	Set to 1 if the parameter is frozen by default, 0 otherwise.

Examples:

List the parameters of the GAUSS1D model:

sherpa> gpars = get_model_params("gauss1d")
sherpa> gpars
Struct_Type[1]
sherpa> print(gpars[0])
name             =  gauss1d
type             =  sherpa
numpars          =  3
integrated       =  1
params           =  Struct_Type[3]

This shows that the model contains three parameters. The default values for these parameters can be found by examining the array of structures stored in the params field:

sherpa> print(gpars[0].params[0])
name             =  fwhm
value            =  10
min              =  2.22507e-308
max              =  1.79769e+308
units            =  NULL
frozen           =  0
sherpa> print(gpars[0].params[1])
name             =  pos
value            =  0
min              =  -1.79769e+308
max              =  1.79769e+308
units            =  NULL
frozen           =  0
sherpa> print(gpars[0].params[2])
name             =  ampl
value            =  1
min              =  -1.79769e+308
max              =  1.79769e+308
units            =  NULL
frozen           =  0

Find the parameters of all the models whose name contain the word "raymond":

sherpa> ray = get_model_params("raymond")
sherpa> print(length(ray))
2
sherpa> print(ray[0])
name             =  xsraymond
type             =  xspec
numpars          =  4
integrated       =  1
params           =  Struct_Type[4]
sherpa> print(ray[1])
name             =  xsvraymond
type             =  xspec
numpars          =  15
integrated       =  1
params           =  Struct_Type[15]

The function has returned the default parameter settings for the XSRAYMOND and XSVRAYMOND models. The type of both models is set to "xspec" since they are taken from the XSPEC spectral library. As we know the temperature (kT) is the first parameter in the list for both models, we can see its default value for the two models by using:

sherpa> print(ray[0].params[0])
name             =  kT
value            =  1
min              =  0.008
max              =  64
units            =  keV
frozen           =  0
sherpa> print(ray[1].params[0])
name             =  kT
value            =  6.5
min              =  0.0808
max              =  80
units            =  keV
frozen           =  0

Find all the instrument models:
```
sherpa> im = get_inst_model_params()
sherpa> print(length(im))
9
sherpa> foreach(im) { s=(); vmessage("%-10s  [%d]",s.name,s.numpars); }
farf        [2]
fexpmap     [2]
fpsf1d      [5]
fpsf2d      [6]
frmf        [1]
rsp         [2]
rsp2d       [7]
tpsf1d      [5]
tpsf2d      [5]
```
We called get_inst_model_params() with no argument so all the instrument models are returned and stored in the variable im. The foreach command is used to loop through each element of the im array, which gets stored into the variable s; this is then used in the vmessage() function to write out the model name and number of parameters (s.name and s.numpars respectively).

8.32 get_models

Module functions that return lists of available source and instrument models

Array_Type get_models([String_Type])
Array_Type get_inst_models([String_Type])

Error Return Value: NULL

Argument:

(1) matching string (default none: get all model names)

Returns a string array containing the names of all appropriate Sherpa source or instrument models. (This includes XSPEC models and user-defined models.) If a string argument is provided (e.g., "xs"), only those models whose names contain matching substrings will be returned. Beware of case-sensitivity: upper-case matching strings will yield a NULL return.

Examples:

List all models with psf in their names.

sherpa> psfmods = get_inst_models("psf")
sherpa> printarr(psfmods)
fpsf1d
fpsf2d
tpsf1d
tpsf2d

8.33 get_num_par

Module functions that report the total number of parameters for all defined models, including instrument models

Integer_Type get_num_par()
Integer_Type get_num_par_frozen()
Integer_Type get_num_par_thawed()

Error Return Values: NULL

See the related Sherpa command SHOW.

Examples:

Set up two models; determine the number of parameters:

sherpa> SOURCE = POW[p] + GAUSS[g]
sherpa> get_num_par
6
sherpa> get_num_par_thawed
5
sherpa> get_num_par_frozen
1

8.34 get_par

Module function for getting model parameter values, etc.

Array_Type get_par([String_Type])

Error Return Values: NULL

Argument:

(1) Model name, or model parameter name (default all model parameters)

This function retrieves an array of structures, each of which contains information about a defined model parameter. A typical structure looks as follows:

sherpa> GAUSS[g]
sherpa> foo = get_par("g")
sherpa> print(foo[0])
name             =  g.fwhm
model            =  gauss1d
type             =  src
value            =  10
min              =  2.22507e-308
max              =  1.79769e+308
delta            =  -1
units            =  NULL
frozen           =  0
linked           =  0
linkexpr         =  NULL

The fields of the structure are:

Table 8.8: get_par Structure Fields
Argument Description

name the name of the parameter

model the model that the parameter belongs to

type source/background-type (src) or instrument-type (inst) model

value the parameter value (either a number, or a string filename)

min the current (soft) lower bound on allowed parameter values

max the current (soft) upper bound on allowed parameter values

delta the initial step size for the parameter in fits (or -1 to use the default step size)

units parameter units, if known/appropriate

frozen if 1, the parameter value is frozen; if 0, it is thawed

link if 1, the parameter's value is linked to that of other parameter(s); if 0, it is not linked

linkexpr if the parameter is linked to other parameters, the expression showing how it is linked

**Table 8.8:** `get_par` Structure Fields
Argument	Description
`name`	the name of the parameter
`model`	the model that the parameter belongs to
`type`	source/background-type (`src`) or instrument-type (`inst`) model
`value`	the parameter value (either a number, or a string filename)
`min`	the current (soft) lower bound on allowed parameter values
`max`	the current (soft) upper bound on allowed parameter values
`delta`	the initial step size for the parameter in fits (or -1 to use the default step size)
`units`	parameter units, if known/appropriate
`frozen`	if 1, the parameter value is frozen; if 0, it is thawed
`link`	if 1, the parameter's value is linked to that of other parameter(s); if 0, it is not linked
`linkexpr`	if the parameter is linked to other parameters, the expression showing how it is linked

See the Sherpa command CREATE for more information.

Examples:

Get a parameter structure; change two fields; set back into Sherpa:

sherpa> GAUSS[g]
sherpa> foo = get_par("g.pos")
sherpa> print(foo)
name             =  g.pos
model            =  gauss1d
type             =  src
value            =  0
min              =  -3.40282e+38
max              =  3.40282e+38
delta            =  -1
units            =  NULL
frozen           =  0
linked           =  0
linkexpr         =  NULL
sherpa> foo.value = 15.5
sherpa> foo.min = 0.0
sherpa> () = set_par(foo)
sherpa> SHOW g
gauss1d[g]  (integrate: on)
    Param   Type      Value        Min        Max                 Units
    -----   ----      -----        ---        ---                 -----
 1   fwhm thawed         10 1.1755e-38 3.4028e+38                      
 2    pos thawed       15.5          0 3.4028e+38                      
 3   ampl thawed          1 -3.403e+38 3.4028e+38

Here we loop through all the defined parameters and display their name and current value:
```
sherpa> erase all
sherpa> paramprompt off
sherpa> xsmekal[gal]
sherpa> xsphabs[abs]
sherpa> ps = get_par()
sherpa> ps
Struct_Type[7]
sherpa> foreach(ps){p=();vmessage("Par %-14s = %g",p.name,p.value);} 
Par gal.kT         = 1
Par gal.nH         = 1
Par gal.Abund      = 1
Par gal.Redshift   = 0
Par gal.Switch     = 1
Par gal.norm       = 1
Par abs.nH         = 0.1
```
The initial set of lines are to set up two models ("gal", which is an XSMEKAL model, and "abs", which is an XSPHABS model) with default parameter values. The ps variable is set here to an array of 7 structures, which we loop through using the S-Lang foreach function. Each member of the array is looped through, and stored in the variable p. This variable is then used to get the parameters name and value (p.name and p.value respectively). The whole 'foreach' statement must be on one line since Sherpa does not allow multi-line S-Lang statements. This restriction does not apply to code in a file executed via evalfile().

Here we use a small S-Lang function we have written to display parameter values. If the file print_pars.sl contains:

define print_pars() {
  variable pars = get_par();
  if ( NULL == pars ) {
    print( "No parameter values found!" );
    return;
  }

  vmessage( "# Name                model  frozen  value" );
  foreach ( pars ) {
    variable par = ();
    vmessage( "%-20s  %-10s  %d  %g",
      par.name, par.model, par.frozen, par.value
    );
  }
}

then you can say:

sherpa> () = evalfile("print_pars.sl")
sherpa> erase all
sherpa> paramprompt off
sherpa> xsmekal[gal]
sherpa> xsphabs[abs]
sherpa> print_pars
# Name                model  frozen  value
gal.kT                xsmekal     0  1
gal.nH                xsmekal     1  1
gal.Abund             xsmekal     1  1
gal.Redshift          xsmekal     1  0
gal.Switch            xsmekal     1  1
gal.norm              xsmekal     0  1
abs.nH                xsphabs     0  0.1

although you may find either list_par() or SHOW more useful.

8.35 get_paramest

Module functions to retrieve the output of parameter estimation methods.

Array_Type get_unc()
Array_Type get_proj()
Array_Type get_cov()
Struct_Type get_intunc()
Struct_Type get_intproj()
Struct_Type get_regunc()
Struct_Type get_regproj()

See get_unc, get_proj, get_cov, get_intunc, get_intproj, get_regunc, and get_regproj for more information.

8.35.1 CHANGES IN CIAO 3.1

The structures returned by these functions contain additional fields which are described in the documentation for each function.

8.36 get_paramestint

Module functions to retrieve the value and statistic arrays from the most recent run of a parameter estimation method

Struct_Type get_intunc()
Struct_Type get_intproj()

Error Return Value: NULL

These functions retrieve information from the most recent run of the INTERVAL-UNCERTAINTY or run_intunc, and INTERVAL-PROJECTION or run_intproj parameter estimation methods, respectively.

Each returns a structure with five fields:

$\bullet$: x0: the grid of parameter values;
$\bullet$: y: the statistics as a function of parameter value;
$\bullet$: name: the name of the parameter;
$\bullet$: bfit: the best-fit value of the parameter; and
$\bullet$: config: a Struct_Type variable containing the parameters used to calculate x0 and y.

These functions can be used to retrieve information similar to that provided by the XSPEC command steppar.

Examples:

Fit a dataset; get information about $\chi ^2$ as a function of power-law amplitude p.ampl after running INTERVAL-PROJECTION:

sherpa> DATA example.pha
sherpa> SUBTRACT
sherpa> PARAMPROMPT OFF
sherpa> SOURCE = POW[p]
sherpa> FIT
...
sherpa> INTERVAL-PROJECTION p.ampl
Interval-Projection: computing grid size with covariance...done.
                     outer grid loop 20% done...
                     outer grid loop 40% done...