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:

1. 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:

1. Instantiate a polynomial model, and name it p:

   sherpa> () = create_model("POLY","p")
   

2. Instantiate an rsp instrument model, and name it a:

   sherpa> () = create_inst_model("RSP","a")
   

3. 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:

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

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

2. 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
   

3. 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
   

4. 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
   

5. 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 $q$-value
get_ftest	Returns the statistical significance computed with the $F$ 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:

1. 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 $N$-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)

In Sherpa parlance, a "dataspace'' is an $N$-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_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:

1. 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
   

2. 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
   

3. 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:

1. 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 $y$-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:

1. 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

See the related Sherpa command DCOUNTS for more information.

Examples:

1. 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:

1. 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

See the related Sherpa command EFLUX for more information.

Examples:

1. 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
   

2. 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)

In Sherpa parlance, a "dataspace'' is an $N$-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_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:

1. 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:

1. 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)

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 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:

1. 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:

1. 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:

1. 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
   

2. 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:

1. 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 $N + 1$ if information for $N$ 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 $q$ value (see get_qvalue()); this field is NULL for the statistics CASH and BAYES.

See the related Sherpa command GOODNESS for more information.

Examples:

1. [...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)

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:

1. 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
   

2. 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:

1. 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:

1. 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 $F$ test

Double_Type get_ftest(Integer_Type, Double_Type, Integer_Type, Double_Type)

Error Return Value: NULL

Arguments:

(1) number of degrees of freedom $d_1$

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

(3) number of degrees of freedom $d_2$

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

This function returns the tail integral of the $F$ 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:

1. 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.

2. 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:

1. 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

See the related Sherpa command MCOUNTS for more information.

Examples:

1. 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:

1. 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:

1. 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.

Examples:

1. 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
   

2. 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
   

3. 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:

1. 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:

1. 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

See the Sherpa command CREATE for more information.

Examples:

1. 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
   

2. 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().

3. 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:

1. 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...
                        outer grid loop 60% done...
                        outer grid loop 80% done...
   [...plot displayed...]
   sherpa> intproj = get_intproj()
   sherpa> print(intproj)
   x0               =  Float_Type[20]
   y                =  Float_Type[20]
   name             =  p.ampl
   bfit             =  0.000191983
   config           =  sherpa_VisParEst_State
   sherpa> printarr(intproj.x0,3)
   0.000158651
   0.000162159
   0.000165668
   sherpa> printarr(intproj.y,3)
   197.622
   195.83
   194.238
   

   The second-to-last call displays the first three values of the p.ampl grid, while the last call displays the best-fit statistic given those p.ampl values.

8.36.1 CHANGES IN CIAO 3.1

The structures returned by these functions contain additional fields - name, bfit, and config - which are described above.

8.37 get_paramestlim

Module functions to determine confidence intervals, and retrieve the parameter bounds.

Array_Type get_unc()
Array_Type get_proj()
Array_Type get_cov()

Error Return Value: NULL

These functions retrieve information from the most recent run of the UNCERTAINTY or run_unc, PROJECTION or run_proj, and COVARIANCE or run_cov parameter estimation methods, respectively.

Each function returns an array of structures. The length of the array is determined by the number of thawed parameters examined in the most recent run of the parameter estimation method. Each structure has five fields:

$\bullet$

name: the name of the parameter;

$\bullet$

val: its best-fit value;

$\bullet$

vlo: the lower bound for its confidence interval;

$\bullet$

vhi: the upper bound for its confidence interval;

$\bullet$

sigma: the value of the sigma parameter used to calculate vlo and vhi.

Examples:

1. Fit a dataset; run covariance and retrieve the results:

   sherpa> DATA example.pha
   sherpa> SUBTRACT
   sherpa> PARAMPROMPT OFF
   sherpa> SOURCE = POW[p]
   sherpa> FIT
   ...
   sherpa> COVARIANCE
   
   Computed for covariance.sigma = 1
           --------------------------------------------------------
           Parameter Name      Best-Fit Lower Bound     Upper Bound
           --------------------------------------------------------
                p.gamma         1.79469  -0.0811155      +0.0811155    
                p.ampl      0.000191983  -1.11109e-05    +1.11109e-05  
   
   sherpa> cov = get_cov
   sherpa> print(length(cov))
   2
   sherpa> print(cov[0])
   name             =  p.gamma
   val              =  1.79469
   vlo              =  1.71358
   vhi              =  1.87581
   sigma            =  1
   

2. Repeat the last example, but retrieve the uncertainty for one parameter:

   sherpa> UNCERTAINTY p.ampl
   
   Computed for uncertainty.sigma = 1
           --------------------------------------------------------
           Parameter Name      Best-Fit Lower Bound     Upper Bound
           --------------------------------------------------------
                p.ampl      0.000191983  -9.38415e-06    +9.4647e-06   
   
   sherpa> unc = get_unc()
   sherpa> print(unc[0])
   name             =  p.ampl
   val              =  0.000191983
   vlo              =  0.000182599
   vhi              =  0.000201448
   sigma            =  1
   

8.37.1 CHANGES IN CIAO 3.1

The structures returned by these functions contain an additional field, sigma, which is described above.

8.38 get_paramestreg

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

Struct_Type get_regunc()
Struct_Type get_regproj()

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 seven fields:

$\bullet$

x0: the grid of values for one parameter;

$\bullet$

x1: the grid of values for the second parameter;

$\bullet$

y: the statistics as a function of parameter values;

$\bullet$

levels: an array containing the statistic valuecorresponding to each contour;

$\bullet$

name: a two-element array listing the parameter names;

$\bullet$

bfit: a two-element array listing the best-fit values of the parameters; and

$\bullet$

config: a Struct_Type variable containing the parameters used to calculate x0, x1, and y.

Examples:

1. Fit a dataset; get information about $\chi ^2$ as a function of power-law amplitude p.ampl and slope p.gamma

   sherpa> DATA spec.dat
   sherpa> PARAMPROMPT OFF
   sherpa> POLY[p]
   sherpa> THAW p.c1 p.c2 p.c3
   sherpa> SOURCE = p
   sherpa> FIT
    LVMQT: V2.0
    LVMQT: initial statistic value = 82.2297
    LVMQT: final statistic value = 62.2247 at iteration 3
                p.c0  61.4774     
                p.c1  -0.380228     
                p.c2  0.00993229     
                p.c3  -7.01741e-05     
   
   sherpa> REGPROJ p.c0 p.c1
   Region-Projection: computing grid size with covariance...done.
                      outer grid loop 20% done...
                      outer grid loop 40% done...
                      outer grid loop 60% done...
                      outer grid loop 80% done...
   Minimum: 62.2247
   Levels are: 64.5207 68.4057 74.0547
   [...plot displayed...]
   sherpa> regproj = get_regproj()
   sherpa> print(regproj)
   x0               =  Float_Type[100]
   x1               =  Float_Type[100]
   y                =  Float_Type[100]
   levels           =  Float_Type[3]
   name             =  String_Type[2]
   bfit             =  Double_Type[2]
   config           =  sherpa_VisParEst_State
   

8.38.1 CHANGES IN CIAO 3.1

The structures returned by these functions contain additional fields - levels, name, bfit, and config - which are described above.

8.39 get_pflux

get_flux(), get_pflux(), and get_bpflux() calculate the photon flux (unconvolved) for source and background datasets using the module functions in Sherpa.

Struct_Type get_flux(Struct_Type)
Struct_Type get_bflux(Struct_Type)
Struct_Type get_flux([Integer_Type[,{Float_Type | Array_Type}[,String_Type]]])
Struct_Type get_bflux([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_pflux and get_bpflux functions retrieve the photon flux, nominally in units of ${\rm photons/cm^2/s}$ (if the flux is computed over a range), or ${\rm photons/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 (e.g. RMF, RSP etc.) have been specified, etc.

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.

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

The structure output by these functions contains the following fields:

Table 8.9: get_flux 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 FLUX for more information.

Also see these related Sherpa/S-Lang module functions:

Table 8.10: Related Sherpa/S-Lang Module Functions

Name	Description
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

Examples:

1. 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> 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_pflux(1,[2,10])
   sherpa> print(foo)              
   dataset          =  1
   range            =  Float_Type[2]
   comp             =  NULL
   value            =  7.88051e-05
   units            =  photons/cm**2/s
   sherpa> print(foo.value)
   7.88051e-05
   

2. 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.40 get_photon_axes

Module functions to retrieve photon-space grids over which models are evaluated.

{Struct_Type | Array_Type} get_photon_axes([Integer_Type])
{Struct_Type | Array_Type} get_photon_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

In Sherpa parlance, a "dataspace'' is an $N$-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_photon_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. However, the dataspace is also translated into "photon space''. The get_axes() function returns the dataspace in "channel space''. In essence, "photon space'' is what one would see if one could undo the redistribution of energies by the detector. (One can't really "deconcolve'' the data in this manner with any confidence, but for the purposes of visualization only, the data from the appropriate RMF and ARF files are used to estimate what the data would look like after a "deconvolution''.)

Thus, for example, 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, e.g., by the ENERG_LO and ENERG_HI columns of the ARF). These boundaries generally do not match the boundaries that would be returned by get_$[$b$]$axes().

(The function get_photon_baxes() acts as get_photon_axes(), save that it retrieves the dataspace for the background associated with the appropriate data set.)

One may display photon-space model amplitudes et al. on the same grid output by get_photon_axes using the Sherpa plotting commands LPLOT SOURCE et al.

8.41 get_photon_energy_axes

Module functions to retrieve photon-space energy grids over which models are evaluated.

{Struct_Type | Array_Type} get_photon_energy_axes([Integer_Type])
{Struct_Type | Array_Type} get_photon_energy_baxes([Integer_Type])
{Struct_Type | Array_Type} get_full_photon_energy_axes([Integer_Type])
{Struct_Type | Array_Type} get_full_photon_energy_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

In Sherpa parlance, a "dataspace'' is an $N$-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_photon_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). However, the dataspace is also translated into "photon space''. The get_energy_axes() function returns the dataspace in "energy space''. In essence, "photon space'' is what one would see if one could undo the redistribution of energies by the detector. (One can't really "deconvolve'' the data in this manner with any confidence, but for the purposes of visualization only, the data from the appropriate RMF and ARF files are used to estimate what the data would look like after a "deconvolution''.)

Thus, for example, 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, e.g., by the ENERG_LO and ENERG_HI columns of the ARF). But if one is working in wavelength-space or channel-space, the bin boundaries returned are still in keV. These boundaries generally do not match the boundaries that would be returned by get_energy_$[$b$]$axes().

(The function get_photon_energy_baxes() acts as get_photon_energy_axes(), save that it retrieves the dataspace for the background associated with the appropriate data set.)

One may display photon-space model amplitudes et al. on the same grid output by get_photon_axes using the Sherpa plotting commands LPLOT SOURCE et al.

Examples:

1. Read the PHA file with the ARF/RMF defined in the header (qso.pha). Define the model, filter the data and fit.

   sherpa> data qso.pha
   sherpa> foo0=get_photon_energy_axes()
   sherpa> print(foo0)                  
   NULL
   sherpa> source = xsphabs[abs]*pow[p1]
   abs.nH parameter value [0.1] 
   p1.gamma parameter value [1] 
   p1.ref parameter value [1] 
   p1.ampl parameter value [0.00059008] 
   sherpa> 
   sherpa> ignore energy :0.2,10:
   sherpa> fit
    LVMQT: V2.0
    LVMQT: initial statistic value = 297162
    LVMQT: final statistic value = 275.333 at iteration 7
              abs.nH  0.0245136  10**22 atoms/cm**2  
               p1.gamma  1.53707     
               p1.ampl  5.91298e-05
   

   Obtain the photon energy axes information into "fooO" and print content of "foo0". Print the value of the 11th low energy in "foo0". The mid is NULL, so the final print command gives an error information.

   sherpa> foo0=get_photon_energy_axes()
   sherpa> print(foo0)                  
   axistype         =  Energy
   axisunits        =  keV
   lo               =  Float_Type[1077]
   hi               =  Float_Type[1077]
   mid              =  NULL
   sherpa> print(foo0.lo[10])
   0.33
   sherpa> print(foo0.mid[10])
   Type Mismatch: Context requires an array.  Scalar not converted
   Type Mismatch: print(foo0.mid[10]);
   

8.42 get_photon_wave_axes

Module functions to retrieve photon-space wavelength grids over which models are evaluated.

{Struct_Type | Array_Type} get_photon_wave_axes([Integer_Type])
{Struct_Type | Array_Type} get_photon_wave_baxes([Integer_Type])
{Struct_Type | Array_Type} get_full_photon_wave_axes([Integer_Type])
{Struct_Type | Array_Type} get_full_photon_wave_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

In Sherpa parlance, a "dataspace'' is an $N$-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_photon_wave_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 wavelength ( Å). However, the dataspace is also translated into "photon space''. The get_wave_axes() function returns the dataspace in "wavelength space''. In essence, "photon space'' is what one would see if one could undo the redistribution of energies by the detector. (One can't really "deconvolve'' the data in this manner with any confidence, but for the purposes of visualization only, the data from the appropriate RMF and ARF files are used to estimate what the data would look like after a "deconvolution''.)

Thus, for example, if one is working with filtered PHA data in energy-space, what is returned are the low and high bin boundaries in Å (quantities assigned, e.g., by the ENERG_LO and ENERG_HI columns of the ARF). But if one is working in energy-space or channel-space, the bin boundaries returned are still in Å. These boundaries generally do not match the boundaries that would be returned by get_wave_$[$b$]$axes().

(The function get_photon_wave_baxes() acts as get_photon_wave_axes(), save that it retrieves the dataspace for the background associated with the appropriate data set.)

One may display photon-space model amplitudes et al. on the same grid output by get_photon_axes using the Sherpa plotting commands LPLOT SOURCE et al.

8.43 get_qvalue

Module function that returns the statistical significance computed as a $q$-value.

Double_Type get_qvalue(Integer_Type, Double_Type)

Error Return Value: NULL

Arguments:

(1) number of degrees of freedom $d$

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

This function returns the tail integral of the $\chi ^2$ distribution for the given number of degrees of freedom.

See the related Sherpa command MLR for more information.

8.44 get_raw_axes

Module functions to retrieve the raw channel number grids of source and background datasets.

{Struct_Type | Array_Type} get_raw_axes([Integer_Type])
{Struct_Type | Array_Type} get_raw_baxes([Integer_Type])
{Struct_Type | Array_Type} get_full_raw_axes([Integer_Type])
{Struct_Type | Array_Type} get_full_raw_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

In Sherpa parlance, a "dataspace'' is an $N$-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_raw_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 channels. Otherwise, the function is similar to get_axes().

The function get_full_raw_axes() is similar to get_raw_axes(), except that get_full_raw_axes() returns the original, unfiltered dataspace in channels. (And get_raw_baxes() and get_full_raw_baxes() return filtered and unfiltered dataspaces for the background associated with the source data set, in units of channels.)

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

8.45 get_record

Module function to return a record of model parameter values at the end of each iteration of the fitting process.

Struct_Type get_record()

Error Return Value: NULL

The RECORD command saves the best-fit model values at the end of each iteration during fits. For instance, if a particular fit with the POWELL optimization method took 14 iterations, then 14 values are recorded for each free parameter. Also saved is the statistic value at the end of each iteration. The output of get_record is a S-Lang variable of Struct_Type, containing this information.

There are three fields in the output structure:

$\bullet$

name: a String_Type array of length $M$, where $M$ is the number of free model parameters. This array contains the parameter names.

$\bullet$

val: a Double_Type array of length $M \times N$, where $N$ is the number of iterations through parameter space during the fitting process. This array records the value of each free model parameter at the end of each step through parameter space.

$\bullet$

stat: a Double_Type array of statistic values of length $N$. This array records the value of the fit statistic at the end of each step through parameter space.

See the related Sherpa command RECORD for more information.

Examples:

1. sherpa> record
   sherpa> fit
   ...
   sherpa> foo = get_record()
   sherpa> print(foo)
   name             =  String_Type[4]
   val              =  Double_Type[4,14]
   stat             =  Double_Type[14]
   sherpa> variable a = foo.val[0,*]
   sherpa> () = curve(a,foo.stat)
   

8.46 get_source

Module functions to retrieve predicted source and background model photon amplitudes.

Array_Type get_source([Integer])
Array_Type get_bg([Integer])
Array_Type get_full_source([Integer])
Array_Type get_full_bg([Integer])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

These functions evaluate the source or bg model in photon space, and are thus analogous to get_mcounts(), etc., which work in counts space. What is returned is an array of amplitudes for those photon-space bins which map to the filtered data set. (Adding full causes unfiltered amplitudes to be returned.) One retrieves the dataspace for these amplitudes using the functions get_photon_axes() et al.

Filtered source and background model amplitudes in photon-space may be displayed, e.g., via the Sherpa plotting commands LPLOT SOURCE and LPLOT BG.

Examples:

1. sherpa> data example.pha
   sherpa> instrument = rsp[rr]("example.rmf", "example.arf")
   sherpa> source = xspowlaw[pp]
   sherpa> foo = get_source()
   

8.47 get_stackexpr

Module functions to retrieve a model stack expression.

String_Type get_source_expr([Integer_Type])
String_Type get_bg_expr([Integer_Type])
String_Type get_inst_expr([Integer_Type])
String_Type get_sinst_expr([Integer_Type])
String_Type get_binst_expr([Integer_Type])

Error Return Value: NULL

Arguments:

(1) Dataset number (default 1)

These functions get model stack expressions; get_sinst_expr and get_binst_expr get instrument model stack expressions for the source dataset only, and the background dataset only, respectively.

See the related Sherpa commands SOURCE, BACKGROUND, and INSTRUMENT for more information.

Examples:

1. Specify the source model stack expression for dataset 3, then retrieve it:

   sherpa> PARAMPROMPT OFF
   sherpa> GAUSS[g]
   sherpa> POW[p]
   sherpa> () = set_source_expr(3,"p+g")
   sherpa> get_source_expr(3)
   (p + g)
   

2. Specify and retrieve a source model stack expression for dataset 1:

   sherpa> () = set_source_expr("xswabs[xs1]*(pow[p]+gauss[g])")
   sherpa> get_source_expr()
   (xs1 * (p + g))
   

8.48 get_stat_expr

Module function to retrieve the name of the current statistic.

String_Type get_stat_expr()

Error Return Value: NULL

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

See the related Sherpa command SHOW STATISTIC.

Examples:

1. Display the Sherpa statistic setting:

   sherpa> stat1 = get_stat_expr 
   sherpa> print(stat1)
   chi gehrels
   sherpa> STATISTIC CSTAT
   sherpa> stat2 = get_stat_expr 
   sherpa> print(stat2)
   cstat
   

8.49 get_statistic

Module functions to get the current value of the statistic comparing source and background data and model values.

Double_Type get_statistic([Integer_Type])
Double_Type get_bstatistic([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The function get_statistic() returns the latest evaluated statistic value for the given data set. (The function get_bstatistic() does so for the appropriate background data set and background model.)

(Note that this function is not the same as get_statistics(), which returns an array showing the value of the fit statistic in each bin. This function returns the sum of the values in the array returned by get_statistics().)

See the related Sherpa command GOODNESS for more information.

Examples:

1. sherpa> get_statistic()
   638.148
   

8.50 get_stats

Module functions to retrieve predicted model counts, statistics, residuals, sigma residuals, and ratios from source and background datasets.

Array_Type get[_full]_[b]mcounts([Integer_Type])
Array_Type get[_full]_[b]statistics([Integer_Type])
Array_Type get[_full]_[b]residuals([Integer_Type])
Array_Type get[_full]_[b]delchi([Integer_Type])
Array_Type get[_full]_[b]ratio([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

The function get_mcounts() calls the model associated with the appropriate data set and returns an array containing the predicted model counts amplitudes (i.e., the y-values of the predicted data). The array contains only those y-values which fall within the filter. The other functions all return the result of a comparison of the predicted model counts amplitudes to the data set. Thus, get_statistics() returns an array of statistics ($\chi ^2$ only), get_residuals() returns residuals ($D_i - M_i$), get_delchi() returns residuals divided by sigma ( $(D_i - M_i) / \sigma_i$, where $\sigma_i$ is the estimated error), and get_ratio() returns ratios ($D_i / M_i$).

Arrays containing the whole, unfiltered sets of y-values are returned by using the related functions that have "full'' added to their names. Thus, e.g., get_mcounts() returns the filtered array of predicted model counts, and get_full_mcounts() returns the unfiltered array of predicted model counts.

These functions all use the source model associated with the appropriate data set. (If no argument is given, the default is data set 1.) To instead use the background model and background data set associated with the data set number, append "b'' to the function names, i.e., get_bmcounts() returns the filtered array of predicted model counts, for the background model, and get_full_bmcounts() returns the unfiltered array of predicted model counts, for the background model.

These quantities may be displayed, e.g., via the Sherpa plotting commands LPLOT $[$B$]$MCOUNTS, LPLOT $[$B$]$STATISTICS, LPLOT $[$B$]$RESIDUALS, LPLOT $[$B$]$DELCHI, and LPLOT $[$B$]$RATION.

Examples:

1. sherpa> data example.dat
   sherpa> source = gauss
   sherpa> foo = get_mcounts(1)
   sherpa> printarr(foo,2)
   0.162616
   0.211218
   sherpa> write models
   Write X-Axis: Bin  Y-Axis: Flux (Counts)
           758     0.1626
           759     0.2112
   

8.51 get_syserrors

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

Array_Type get_syserrors([Integer_Type])
Array_Type get_bsyserrors([Integer_Type])
Array_Type get_full_syserrors([Integer_Type])
Array_Type get_full_bsyserrors([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 current systematic error estimates associated with input datasets. (The quantities are the systematic errors multiplied by the data in each bin, thus one may want to also retrieve the data and divide by them to yield quantities that may be input into set_syserrors.) The ones without full in the name return arrays comprised of systematic error estimates within the applied filter; those with full in the name retrieve the unfiltered systematic 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 systematic errors may be displayed, e.g., via the Sherpa plotting commands LPLOT SYSERRORS and LPLOT BSYSERRORS.

Examples:

1. Retrieve and display systematic errors:

   sherpa> data example.pha
   The inferred file type is PHA.  If this is not what you want, please 
   specify the type explicitly in the data command.
   WARNING: using systematic errors specified in the PHA file.
   RMF is being input from:
     /data/simteste/Testing/sherpaTest/data/example2.rmf
   ARF is being input from:
     /data/simteste/Testing/sherpaTest/data/example2.arf
   Background data are being input from:
     /data/simteste/Testing/sherpaTest/data/example2_bkg.pha
   sherpa> syserr = get_full_syserrors()
   sherpa> printarr(syserr,3)
   0
   0
   0
   

8.52 get_verbose

Module function to display Sherpa's current verbosity setting.

Void_Type get_verbose()
get_verbose

This function retrieve's Sherpa's verbosity setting.

The current verbosity settings are:

Table 8.11: Verbosity Settings for get_verbose

Setting	Displays:
0	(almost) no output (useful for scripts/batch jobs)
1	normal output; many warnings are suppressed and the results of each fit iteration are not shown (the default)
2	full output

8.53 get_wave_axes

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

{Struct_Type | Array_Type} get_wave_axes([Integer_Type])
{Struct_Type | Array_Type} get_wave_baxes([Integer_Type])
{Struct_Type | Array_Type} get_full_wave_axes([Integer_Type])
{Struct_Type | Array_Type} get_full_wave_baxes([Integer_Type])

Error Return Value: NULL

Arguments:

(1) data set number (default 1)

In Sherpa parlance, a "dataspace'' is an $N$-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_wave_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 wavelength. Otherwise, the function is similar to get_axes().

The function get_full_wave_axes() is similar to get_wave_axes(), except that get_full_wave_axes() returns the original, unfiltered dataspace in units of wavelength. (And get_wave_baxes() and get_full_wave_baxes() return filtered and unfiltered dataspaces for the background associated with the source data set, in units of wavelength.)

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

8.54 get_weights

Module functions to get the statistical weights of source and background datasets.

Array_Type get_weights([Integer_Type])
Array_Type get_bweights([Integer_Type])
Array_Type get_full_weights([Integer_Type])
Array_Type get_full_bweights([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 current statistical weights associated with input datasets. The ones without full in the name return arrays comprised of statistical weights within the applied filter; those with full in the name retrieve the unfiltered statistical weights.

(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 statistical weights may be displayed, e.g., via the Sherpa plotting commands LPLOT WEIGHTS and LPLOT BWEIGHTS.

Examples:

1. sherpa> DATA spec.dat
   sherpa> w = get_weights(1)
   sherpa> printarr(w,2)
   1
   1
   sherpa> e[0] = 0.5
   sherpa> () = set_weights(1,e)
   sherpa> write weights
   Write X-Axis: Bin  Y-Axis: Errors
             1        0.5
             2          1
   

8.55 is

Summary of Sherpa/S-Lang module query functions.

The is functions of the Sherpa/S-Lang module answer questions, returning 1 for yes/true and 0 for no/false, and, if appropriate, NULL for inappropriate queries (such as querying about background subtraction for a non-existant dataset).

Table 8.12: Summary of Sherpa/S-Lang Module is Functions

Name	Description
is_thawed	Determines if the specified parameter(s) are thawed
is_frozen	Determines if the specified parameter(s) are frozen
is_subtracted	Determines if a specified dataset is background-subtracted

8.56 is_paramset

Module functions to determine if whether the specified parameter(s) are thawed or frozen.

Integer_Type is_thawed([String_Type])
Integer_Type is_frozen([String_Type])

Arguments:

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

If:

$\bullet$

no argument is provided, these functions will return 1 if all model parameters are thawed, or frozen;

$\bullet$

a model component name is provided, these functions return 1 if all parameters of that model are thawed, or frozen; and

$\bullet$

if a model parameter name is provided, these functions return 1 if that parameter is thawed, or frozen.

See the related Sherpa commands THAW and FREEZE for more information.

Examples:

1. Determine if all parameters of a specified Gaussian model are thawed, then determine if the ampl parameter is frozen:

   sherpa> PARAMPROMPT OFF
   sherpa> GAUSS[g]
   sherpa> is_thawed("g")
   1
   sherpa> is_frozen("g.ampl")
   0
   

   The 1 returned from the first call indicates that yes, all parameters of the Gaussian model named g are thawed. The 0 returned from the second call indicates that no, the parameter g.ampl is not frozen.

8.57 is_subtracted

Module function to determine if whether the specified dataset is background-subtracted.

Integer_Type is_subtracted([Integer_Type])

Arguments:

(1) Dataset number (default 1)

This function returns 1 if the background has been subtracted in the specified source dataset.

See the related Sherpa commands SUBTRACT and UNSUBTRACT for more information.

Examples:

1. Determine if dataset 1 is background subtracted:

   sherpa> DATA example.pha
   The inferred file type is PHA.  If this is not what you want, please 
   specify the type explicitly in the data command.
   WARNING: using systematic errors specified in the PHA file.
   RMF is being input from:
     <directory_path>/example2.rmf
   ARF is being input from:
     <directory_path>/example2.arf
   Background data are being input from:
     <directory_path>/example2_bkg.pha
   sherpa> is_subtracted
   0
   sherpa> SUBTRACT
   sherpa> is_subtracted(1)
   1
   

   The 0 returned from the first call indicates that no, dataset 1 is not background subtracted. (Unlike XSPEC, Sherpa does not automatically subtract background data upon input.) The 1 returned from the second call, issued after the SUBTRACT command, indicates that yes, dataset 1 is now background-subtracted.

8.58 list_par

Module function that lists information about all defined model parameters.

Void_Type list_par()
list_par

This function causes a table to be displayed with the following columns:

Table 8.13: Columns in list_par Output

Label	Displays:
Name	The parameter name in the form $<$modelname$>$.$<$paramname$>$
Type	Source/background model (src) or instrument model (inst)
Value	The current value of the parameter, or the filename if appropriate
Lnk	If 1, indicates that the listed parameter's value is linked to other parameter(s) (which are listed)
Frz	If 1, indicates that the parameter's value is frozen
{Min $\vert$ Max}	The current (soft, i.e., changable) parameter lower and upper bounds
Delta	The initial step size for the parameter in fits, with a negative value indicating that a default (usually 0.01 times Value) will be used

See the related Sherpa command SHOW for more information.

Examples:

1. Set up a Sherpa session; use list_par to show parameters:

   sherpa> SOURCE = GAUSS[g]
   sherpa> GAUSS[g2]
   sherpa> g2.pos => g.pos
   sherpa> RSP[a](example.rmf,example.arf)
   sherpa> list_par
     #    Name Type       Value Lnk Frz         Min         Max       Delta
     1  g.fwhm  src      2.6593   0   0    0.026593      265.93          -1
     2   g.pos  src     0.94418   0   0    0.027614      14.549          -1
     3  g.ampl  src  0.00010564   0   0  1.0564e-06    0.010564          -1
     4 g2.fwhm  src      3.5711   0   0    0.035711      357.11          -1
     5  g2.pos  src     0.94418   1 => g.pos
     6 g2.ampl  src   0.0010453   0   0  1.0453e-05     0.10453          -1
     7   a.rmf inst  "example.rmf"
     8   a.arf inst  "example.arf"
   

8.59 list_paramest

Module functions listing the current and default values of the parameters used to configure each Sherpa parameter estimation method.

list_unc
list_proj
list_cov
list_intunc
list_intproj
list_regunc
list_regproj

These functions cause tables to be displayed that show the names, current values, default values, and descriptions of the Sherpa configuration variables (also called "state objects") sherpa.unc et al. The variable values may be modified at the command line (see the example below).

To reset the current values to default values, use the functions restore_unc et al.

These functions replace the Sherpa commands SHOW UNCERTAINTY et al. See the related Sherpa commands UNCERTAINTY, PROJECTION, COVARIANCE, INTERVAL-UNCERTAINTY, INTERVAL-PROJECTION, REGION-UNCERTAINTY, and REGION-PROJECTION for more information.

Examples:

1. Modify the Sherpa state variable sherpa.regproj; display current values with list_regproj:

   sherpa> sherpa.regproj.nloop = [30,20]
   sherpa> sherpa.regproj.sigma = [1.6,2.6]  # 90 and 95 percent contours
   sherpa> list_regproj
   Parameter   Current         Default                        Description
   ----------------------------------------------------------------------
   fast              1               1    Switch to LM/simplex: 0(n)/1(y)
   expfac            3               3          Expansion factor for grid
   arange            1               1              Auto-range: 0(n)/1(y)
   min           [0,0]           [0,0]          Minimum values, each axis
   max           [0,0]           [0,0]          Maximum values, each axis
   log           [0,0]           [0,0]  Log-spacing: 0(n)/1(y), each axis
   nloop       [30,20]         [10,10]   Number of grid points, each axis
   sigma     [1.6,2.6]         [1,2,3]      Number of sigma, each contour
   

8.60 load

Summary of Sherpa/S-Lang module functions that load data into Sherpa

The load functions of the Sherpa/S-Lang module are functional analogues to the Sherpa command READ, with a key difference: READ simply inputs file-based data into Sherpa, while the load functions may be invoked after data are manipulated at the command-line. A simple intuitive example is the processing of read-in time-series data before analysis, by shifting the photon arrival times by some constant (e.g., to make the arrival time of the first photon $t_{\rm new}$ $=$ 0).

Table 8.14: Summary of Sherpa/S-Lang Module load Functions

Name	Description
load_dataset	Loads a source dataset from a file or a S-Lang structure
load_backset	Loads a background dataset from a file or a S-Lang structure
{load_ascii $\vert$ load_bascii}	Loads a source or background dataset from an ASCII file
{load_fitsbin $\vert$ load_bfitsbin}	Loads a source or background dataset from a FITS binary table file
{load_pha $\vert$ load_bpha}	Loads a source or background dataset from a PHA-format file
load_pha2	Loads source datasets from a PHA Type II-format file
{load_image $\vert$ load_bimage}	Loads a source or background dataset from a FITS image file
load_back_from	Loads the contents of a background file named in the header of a PHA data file
load_arf	Loads the contents of an ARF file/structure, placing them in an RSP instrument model
load_rmf	Loads the contents of an RMF file/structure, placing them in an RSP instrument model
load_inst	Loads the contents of an ARF and RMF file/structure, placing them in an RSP instrument model
{load_inst_from $\vert$ load_binst_from}	Loads the contents of ARF and RMF files named in the header of a PHA data file, placing them in an RSP instrument model

8.61 load_arf

Module function to load data from an ARF file into Sherpa

Integer_Type load_arf(String_Type, {String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) Name of instrument (RSP) model instance

(2) ARF filename, or

(2) S-Lang variable output by readarf()

This function loads data from an ARF file into Sherpa, assigning the data to the RSP model instance identified by the first argument. If no such model exists before the call, a new RSP model is created.

See the related Sherpa models RSP and FARF for more information.

Examples:

1. sherpa> () = load_arf("rr","example.arf")
   

   In this example, the data from the ARF file example.arf is assigned to the RSP model "rr''.

2. sherpa> arfst = readarf("example.arf")
   sherpa> () = load_arf("rr","arfst")
   sherpa> () = sherpa_eval("instrument 1 = rr")
   

   Here the ARF data are read into the S-Lang variable "arfst''. The load_arf() function then reads the data from arrays which are part of the variable "arfst''.

8.62 load_ascii

Module function to load ASCII data into Sherpa

Integer_Type load_ascii([Integer_Type], {String_Type | Struct_Type})
Integer_Type load_bascii([Integer_Type], {String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) ASCII filename, or

(2) S-Lang variable of Struct_Type (e.g., type of variable returned by VARMM readascii())

The function load_ascii() loads data from an ASCII file into a Sherpa data set. The function load_bascii() loads data from an ASCII file into the background associated with a Sherpa source data set. (The brackets indicate an optional letter in the function name, with "$[$b$]$'' representing functions to use with background data. Note that background functions currently assume that the setting of multiback in the Sherpa state object is 0, i.e., that only one background dataset is allowed per source dataset.)

Currently, users may only input 1D data (i.e., two columns, with the first assumed to contain values of the independent variable $x$ and the second to contain values of the dependent variable $y = f(x)$). Field names in the struct do not matter, although in the current implementation an _nrows field is needed to establish the length of the arrays.

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_ascii(,"example.dat")
   sherpa> () = load_ascii(1,"example.dat")
   sherpa> () = load_bascii(,"example.dat")
   sherpa> () = load_bascii(1,"example.dat")
   

   The first two commands will load data from the ASCII file into Sherpa source data set 1. The last two commands will load data from the ASCII file into the background associated with Sherpa source data set 1.

2. sherpa> foo = readascii("example.dat")
   sherpa> () = load_ascii(1,foo)
   

   Here the data are read into the S-Lang variable "foo''. The load_ascii() function then reads the data from arrays which are part of the variable "foo''.

8.63 load_back_from

Module function to load background from a PHA file into Sherpa

Integer_Type load_back_from([Integer_Type], {String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) PHA filename, or

(2) S-Lang variable output by readpha()

The function load_back_from() loads the contents of a background PHA file into Sherpa. The file name of the background file is determined from the header keywords of the input (source) PHA file or S-Lang variable.

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_back_from(,"example.pha")
   sherpa> () = load_back_from(1,"example.pha")
   

   These two commands will load the background data from the file background file listed in the header of example.pha.

2. sherpa> foo = readpha("example.pha")
   sherpa> () = load_back_from(1,foo)
   

   The name of the background file is one of the fields of the "foo'' variable. The background data, and only the background data, is then loaded with the load_back_from function.

8.64 load_backset

Module function to load background data into Sherpa

Integer_Type load_backset([Integer_Type], {String_Type | Struct_Type | Array_Type}, [,Array_Type, ...])

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) File name, or

(2) S-Lang variable of Struct_Type (e.g., type of variable returned by VARMM readfile()), or

(2) S-Lang variable of Array_Type

(3) More S-Lang variables of Array_Type

This function acts as a wrapper around the filetype-specific load functions (e.g., load_bascii, load_bpha, etc.). If a file name is provided, then the data are read in via the VARMM library readfile() function. If a S-Lang variable of Struct_Type is provided, then the data are loaded from the fields of that variable. If one or more S-Lang variables of Array_Type are provided, then the data are passed to the functions set_axes() and set_data(). A maximum of 8 arrays, for for data of up to 7 dimensions, can be passed as arguments of Array_Type.

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_backset(,"example.dat")
   sherpa> () = load_backset(1,"example.pha")
   

   These two commands are equivalent; both load data from file into the background associated with the first source data set. In the first case, data are loaded from an ASCII file, and in the second, data are loaded from a PHA file; load_backset() calls the appropriate function to read from ASCII and FITS files respectively.

2. sherpa> foo = readfile("example.pha")
   sherpa> () = load_backset(1,foo)
   sherpa> () = load_backset(1,foo.channels, foo.counts)
   

   Here the data are loaded into a S-Lang variable of Struct_Type. In the first call to load_backset(), this S-Lang variable is passed to the function. In the second call, two arrays are passed to load_backset(). The data in "foo.channels'' and "foo.counts'' are used as the $x$ and $y$ arrays respectively; but the other fields of the variable "foo'' are not used. This means the second call to load_backset() is not quite the equivalent of the first.

8.65 load_dataset

Module function to load data into Sherpa

Integer_Type load_dataset([Integer_Type], {String_Type | Struct_Type | Array_Type}, [,Array_Type, ...])

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) File name, or

(2) S-Lang variable of Struct_Type (e.g., type of variable returned by VARMM readfile()), or

(2) S-Lang variable of Array_Type

(3) More S-Lang variables of Array_Type

This function acts as a wrapper around the filetype-specific load functions (e.g., load_ascii, load_pha, etc.). If a file name is provided, then the data are read in via the VARMM library readfile() function. If a S-Lang variable of Struct_Type is provided, then the data are loaded from the fields of that variable. If one or more S-Lang variables of Array_Type are provided, then the data are passed to the functions set_axes() and set_data(). A maximum of 8 arrays, for for data of up to 7 dimensions, can be passed as arguments of Array_Type.

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_dataset(,"example.dat")
   sherpa> () = load_dataset(1,"example.pha")
   

   These two commands are equivalent; both load data from file into data set 1. In the first case, data are loaded from an ASCII file, and in the second, data are loaded from a PHA file; load_dataset() calls the appropriate function to read from ASCII and FITS files respectively.

2. sherpa> foo = readfile("example.pha")
   sherpa> () = load_dataset(1,foo)
   sherpa> () = load_dataset(1,foo.channels, foo.counts)
   

   Here the data are loaded into a S-Lang variable of Struct_Type. In the first call to load_dataset(), this S-Lang variable is passed to the function. In the second call, two arrays are passed to load_dataset(). The data in "foo.channels'' and "foo.counts'' are used as the $x$ and $y$ arrays respectively; but the other fields of the variable "foo'' are not used. This means the second call to load_dataset() is not quite the equivalent of the first.

8.66 load_fitsbin

Module functions to load source and background data from a FITS binary table into Sherpa

Integer_Type load_fitsbin([Integer_Type], {String_Type | Struct_Type})
Integer_Type load_bfitsbin([Integer_Type], {String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) FITS binary table filename, or

(2) S-Lang variable output by readbintab()

The function load_fitsbin() loads data from a FITS binary table into a Sherpa data set. The function load_bfitsbin() loads data from a FITS binary table into the background associated with a Sherpa source data set. (The brackets indicate an optional letter in the function name, with "$[$b$]$'' representing functions to use with background data. Note that background functions currently assume that the setting of multiback in the Sherpa state object is 0, i.e., that only one background dataset is allowed per source dataset.)

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_fitsbin(,"example.fits")
   sherpa> () = load_fitsbin(1,"example.fits")
   sherpa> () = load_bfitsbin(,"example.fits")
   sherpa> () = load_bfitsbin(1,"example.fits")
   

   The first two commands will load data from the FITS binary table into Sherpa source data set 1. The last two commands will load data from the FITS binary table into the background associated with Sherpa source data set 1.

2. sherpa> foo = readbintab("example.dat")
   sherpa> () = load_fitsbin(1,foo)
   

   Here the data are read into the S-Lang variable "foo''. The load_fitsbin() function then reads the data from arrays which are part of the variable "foo''.

3. sherpa gt; () = load_fitsbin(1,"example.pha[cols CHANNEL,COUNTS]")
   

   Here is an example using Data Model syntax. With this function, the file name can include virtual file syntax to specify the FITS file extension from which data are read (the default is the first FITS binary table extension), and the columns from which data are read.

8.67 load_image

Module functions to load source and background data from a FITS image into Sherpa

Integer_Type load_image([Integer_Type], {String_Type | Struct_Type})
Integer_Type load_bimage([Integer_Type], {String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) FITS image filename, or

(2) S-Lang variable output by readimage()

The function load_image() loads data from a FITS image file into a Sherpa data set. The function load_bimage() loads data from a FITS image file into the background associated with a Sherpa source data set. (The brackets indicate an optional letter in the function name, with "$[$b$]$'' representing functions to use with background data. Note that background functions currently assume that the setting of multiback in the Sherpa state object is 0, i.e., that only one background dataset is allowed per source dataset.) WCS information is automatically loaded from the header into Sherpa, if it exists.

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_image(,"example.fits")
   sherpa> () = load_image(1,"example.fits")
   sherpa> () = load_bpha(,"example.fits")
   sherpa> () = load_bpha(1,"example.fits")
   

   The first two commands will load data from the FITS image file into Sherpa source data set 1. The last two commands will load data from the FITS image file into the background associated with Sherpa source data set 1.

2. sherpa> foo = readimage("example.pha")
   sherpa> () = load_image(1,foo)
   

   Here the data are read into the S-Lang variable "foo''. The load_image() function then reads the data from arrays which are part of the variable "foo''.

8.68 load_inst

Module function to load data from ARF and RMF files into Sherpa. load_instrument is an alternate name.

Integer_Type load_inst({String_Type | Struct_Type},{String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) ARF filename, or

(1) S-Lang variable output by readarf()

(2) RMF filename, or

(2) S-Lang variable output by readrmf()

This function loads data from an ARF file and an RMF file into Sherpa, assigning them to an automatically named RSP model instance.

Note that the order (ARF,RMF; RMF,ARF) does not actually matter, except that currently an unsuppressible library error message appears when the RMF is listed first. This error message may be safely ignored.

See the related Sherpa models RSP, FRMF, and FARF for more information.

Examples:

1. sherpa> rmfst = readrmf("example.rmf")
   sherpa> () = load_inst("example.arf",rmfst)
   

   In this example, RMF data are read from example.rmf and put into the S-Lang variable "rmfst''; this variable is then passed as an argument to load_inst(). The ARF data are read directly from the example.arf file.

8.69 load_inst_from

Module function to load data from ARF and RMF files into Sherpa source or background instrument models.

Integer_Type load_inst_from({String_Type | Struct_Type})
Integer_Type load_binst_from({String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) PHA filename, or

(1) S-Lang variable output by readpha()

This function loads data from an ARF file and an RMF file into Sherpa, assigning them to an automatically named RSP model instance. The file names are determined from the header keywords of the input PHA file or S-Lang variable.

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_inst_from("example.pha")
   sherpa> phast = readpha("example.pha")
   sherpa> () = load_inst_from(phast)
   

   In the first example, the first call causes ARF and RMF files to be read from the files named in the header of the PHA file. In the second example, the data from the PHA file is first read into a S-lang variable; that S-Lang variable is then passed as an argument to the load_inst_from() function.

8.70 load_pha

Module function to load source and background data from PHA Type I files into Sherpa

Integer_Type load_pha([Integer_Type], {String_Type | Struct_Type})
Integer_Type load_bpha([Integer_Type], {String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) PHA Type I filename, or

(2) S-Lang variable output by readpha()

The function load_pha() loads data from a PHA Type I file into a Sherpa data set. The function load_bpha() loads data from a PHA Type I file into the background associated with a Sherpa source data set. (The brackets indicate an optional letter in the function name, with "$[$b$]$'' representing functions to use with background data. Note that background functions currently assume that the setting of multiback in the Sherpa state object is 0, i.e., that only one background dataset is allowed per source dataset.)

If the file contains the header keywords BACKFILE, RESPFILE, and/or ANCRFILE, the background, RMF, and/or ARF file contents are automatically read in as well. (BACKFILE is ignored for load_bpha.)

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_pha(,"example.pha")
   sherpa> () = load_pha(1,"example.pha")
   sherpa> () = load_bpha(,"example.pha")
   sherpa> () = load_bpha(1,"example.pha")
   

   The first two commands will load data from the PHA Type I file into Sherpa source data set 1. The last two commands will load data from the PHA Type I file into the background associated with Sherpa source data set 1.

2. sherpa> foo = readpha("example.pha")
   sherpa> () = load_pha(1,foo)
   

   Here the data are read into the S-Lang variable "foo''. The load_pha() function then reads the data from arrays which are part of the variable "foo''.

8.71 load_pha2

Module function to load source data from PHA Type II files into Sherpa

Integer_Type load_pha2([Integer_Type], {String_Type | Struct_Type})

Success/Error Return Values: 1/0

Arguments:

(1) Data set number (default 1)

(2) PHA Type II filename, or

(2) S-Lang variable output by readpha()

The function load_pha2() loads data from a PHA Type II file into a Sherpa data set. If the file contains the header keywords BACKFILE, RESPFILE, and/or ANCRFILE, the background, RMF, and/or ARF file contents are automatically read in as well. If the file contains the columns BACKGROUND_UP and BACKGROUND_DOWN, their contents are combined into a single background dataset, which is then read in.

Note that there is no equivalent function currently for inputting background data from a PHA Type II file.

See the related Sherpa command READ for more information.

Examples:

1. sherpa> () = load_pha2(,"example.pha")
   sherpa> () = load_pha2(1,"example.pha")
   

   These two commands will load data from the PHA Type II file into Sherpa source data sets, starting with data set 1.

2. sherpa> foo = readpha("example.pha")
   sherpa> () = load_pha2(1,foo)
   

   Here the data are read into the S-Lang variable "foo''. The load_pha2() function then reads the data from arrays which are part of the variable "foo''.

8.72 load_rmf

Module function to load data from an RMF file into Sherpa

Integer_Type load_rmf(String_Type, String_Type | Struct_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Name of instrument (RSP) model instance

(2) RMF filename, or

(2) S-Lang variable output by readrmf()

This function loads data from an RMF file into Sherpa, assigning the data to the RSP model instance identified by the first argument. If no such model exists before the call, a new RSP model is created.

See the related Sherpa models RSP and FRMF for more information.

Examples:

1. sherpa> () = load_rmf("rr","example.rmf")
   

   In this example, the data from the RMF file example.rmf is assigned to the RSP model "rr''.

2. sherpa> rmfst = readrmf("example.arf")
   sherpa> () = load_rmf("rr","rmfst")
   sherpa> () = sherpa_eval("instrument 1 = rr")
   

   Here the RMF data are read into the S-Lang variable "rmfst''. The load_rmf() function then reads the data from arrays which are part of the variable "rmfst''.

8.73 restore_paramest

Module functions to restore the default values of the parameters used to configure each Sherpa parameter estimation method.

restore_unc
restore_proj
restore_cov
restore_intunc
restore_intproj
restore_regunc
restore_regproj

These functions restore the default values of the Sherpa configuration variables (also called "state objects") sherpa.unc et al.

To display the current values, use the functions list_unc et al.

See the related Sherpa commands UNCERTAINTY, PROJECTION, COVARIANCE, INTERVAL-UNCERTAINTY, INTERVAL-PROJECTION, REGION-UNCERTAINTY, and REGION-PROJECTION for more information.

Examples:

1. Modify the Sherpa state variable sherpa.regproj; display current values with list_regproj; restore the default values:

   sherpa> sherpa.regproj.nloop = [30,20]
   sherpa> sherpa.regproj.sigma = [1.6,2.6]  # 90 and 95 percent contours
   sherpa> list_regproj
   Parameter   Current         Default                        Description
   ----------------------------------------------------------------------
   fast              1               1    Switch to LM/simplex: 0(n)/1(y)
   expfac            3               3          Expansion factor for grid
   arange            1               1              Auto-range: 0(n)/1(y)
   min           [0,0]           [0,0]          Minimum values, each axis
   max           [0,0]           [0,0]          Maximum values, each axis
   log           [0,0]           [0,0]  Log-spacing: 0(n)/1(y), each axis
   nloop       [30,20]         [10,10]   Number of grid points, each axis
   sigma     [1.6,2.6]         [1,2,3]      Number of sigma, each contour
   sherpa> restore_regproj
   sherpa> list_regproj
   Parameter   Current         Default                        Description
   ----------------------------------------------------------------------
   fast              1               1    Switch to LM/simplex: 0(n)/1(y)
   expfac            3               3          Expansion factor for grid
   arange            1               1              Auto-range: 0(n)/1(y)
   min           [0,0]           [0,0]          Minimum values, each axis
   max           [0,0]           [0,0]          Maximum values, each axis
   log           [0,0]           [0,0]  Log-spacing: 0(n)/1(y), each axis
   nloop       [10,10]         [10,10]   Number of grid points, each axis
   sigma       [1,2,3]         [1,2,3]      Number of sigma, each contour
   

8.74 run

Summary of Sherpa/S-Lang module run functions.

Most commands issued in Sherpa cause it to do tasks that are accomplished quickly. However, several cause Sherpa to begin potentially time-consuming tasks, like FIT, PROJECTION, etc. This time consumption could make life difficult for the novice user if he or she was to do something like this:

sherpa> projection
[...done 20 minutes later...]
["Hmm, I'd like to save those results in S-Lang scope..."]
sherpa> p = do_projection()   # (does not actually exist)
[...done 20 minutes later...and the user is somewhat disturbed...]

To avoid this, the Sherpa/S-Lang module utilizes two different kinds of functions: run functions that actually perform time-consuming tasks and return the results, and get analogues to the run functions which simply return the most recent relevant results. Applied to the situation above, the second 20-minute run would be avoided: the results would be carried into S-Lang scope instantly. Or the user could have just typed run_projection in the beginning to achieve the same result.

Table 8.15: Summary of Sherpa/S-Lang Module run Functions

Name	Description
run_fit	Fits datasets, and retrieves information about the fits
run_unc	Determines confidence intervals, retrieves the parameter bounds
run_proj	Determines confidence intervals, retrieves the parameter bounds
run_cov	Determines confidence intervals, retrieves the parameter bounds
run_intunc	Displays statistics as a function of parameter value, and retrieves the value and statistic arrays
run_intproj	Displays statistics as a function of parameter value, and retrieves the value and statistic arrays
run_regunc	Displays contours of statistics as a function of parameter values, and retrieves arrays of values and statistics
run_regproj	Displays contours of statistics as a function of parameter values, and retrieves arrays of values and statistics

8.75 run_fit

Module function to fit datasets, and retrieve information about the final fit.

Struct_Type run_fit([{Integer_Type | Array_Type}])

Arguments:

(1) Dataset number or array of dataset numbers (default all datasets)

This function initiates a Sherpa fit. When complete, it calls get_goodness, and a structure or an array of structures is returned. A single structure is returned if only one data set is fit, and an array of N$+$1 structures is returned if N data sets are fit simultaneously. For the latter case, the summed statistics for the combined fit are returned in the 0th element of the structure array.

See the related Sherpa commands FIT and GOODNESS for more information.

Examples:

1. Load two datasets; fit the second and examine the results:

   sherpa> DATA 1 example.pha
   The inferred file type is PHA.  If this is not what you want, please 
   specify the type explicitly in the data command.
   WARNING: using systematic errors specified in the PHA file.
   RMF is being input from:
     <directory_path>/example2.rmf
   ARF is being input from:
     <directory_path>/example2.arf
   Background data are being input from:
     <directory_path>/example2_bkg.pha
   sherpa> DATA 2 spec.dat
   sherpa> () = set_source_expr(2,"CONST[cs]")
   sherpa> result = run_fit(2)
    LVMQT: V2.0
    LVMQT: initial statistic value = 82.2297
    LVMQT: final statistic value = 63.9111 at iteration 3
               cs.c0  57.7977     
   
   sherpa> print(result)
   dataset          =  2
   datatype         =  source
   stat             =  63.9111
   numbins          =  100
   dof              =  99
   rstat            =  0.645567
   qval             =  0.997605
   

8.76 run_paramest

Module functions to run parameter estimation routines and retrieve information.

Array_Type run_unc([Array_Type])
Array_Type run_proj([Array_Type])
Array_Type run_cov([Array_Type])
Struct_Type run_intunc(String_Type)
Struct_Type run_intproj(String_Type)
Struct_Type run_regunc(Array_Type)
Struct_Type run_regproj(Array_Type)

See run_unc, run_proj, run_cov, run_intunc, run_intproj, run_regunc, and run_regproj for more information.

8.76.1 CHANGES IN CIAO 3.2

The run_intunc(), run_intptoj(), run_regunc(), and run_regproj() routines have been updated so that they only return one variable. Please see the documentation for the individual functions for further details.

8.76.2 CHANGES IN CIAO 3.1

The structures returned by these functions contain additional fields. Please see the documentation for the corresponding "get" function for further details.

8.77 run_paramestint

Module functions to display statistics as a function of parameter value, and to retrieve the value and statistic arrays

Struct_Type run_intunc(String_Type)
Struct_Type run_intproj(String_Type)

Argument:

(1) A string representing an individual thawed model parameter

These functions initiate the INTERVAL-UNCERTAINTY and INTERVAL-PROJECTION parameter estimation methods respectively. The chosen method is run using the most recently fit datasets, which are automatically determined and hence are not function arguments. When done, each returns a structure, which are the same as those returned by get_intunc and get_intproj.

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

Examples:

1. Fit a dataset; get information about $\chi ^2$ as a function of power-law amplitude p.ampl

   sherpa> () = load_dataset(1,"example.pha")
   sherpa> () = set_subtract
   sherpa> () = set_source_expr(1,"POW[p]")
   sherpa> set_verbose(0)
   sherpa> () = run_fit
   sherpa> list_intproj()
   Parameter   Current         Default                        Description
   ----------------------------------------------------------------------
   fast              1               1    Switch to LM/simplex: 0(n)/1(y)
   expfac            3               3          Expansion factor for grid
   arange            1               1              Auto-range: 0(n)/1(y)
   min               0               0                      Minimum value
   max               0               0                      Maximum value
   log               0               0             Log-spacing: 0(n)/1(y)
   nloop            20              20              Number of grid points
   sigma             1               1                    Number of sigma
   sherpa> sherpa.intproj.sigma = 3
   sherpa> sherpa.intproj.nloop = 100
   sherpa> intproj = run_intproj("p.ampl")
   [...plot displayed...]
   sherpa> print(intproj)
   x0               =  Float_Type[100]
   y                =  Float_Type[100]
   name             =  p.ampl
   bfit             =  0.000191983
   config           =  sherpa_VisParEst_State
   sherpa> printarr(intproj.x0,3)
   9.19654e-05
   9.39859e-05
   9.60065e-05
   sherpa> printarr(intproj.y,3)
   270.566
   267.213
   263.936
   

   The second-to-last call displays the first three values of the p.ampl grid, while the last call displays the best-fit statistic given those p.ampl values.

8.77.1 CHANGES IN CIAO 3.2

The run_intunc() and run_intproj() commands no longer fail with an error message when called. This means that you can use

  retval = run_intproj(parameter_name);

rather than having to use sherpa_eval() to call INTERVAL-PROJECTION (or INTERVAL-UNCERTAINTY) and then get_regproj() to access the results.

8.77.2 CHANGES IN CIAO 3.1

The structures returned by these functions contain additional fields: name, bfit, and config. These fields contain information on the name of the parameter, its best-fit value, and the values used by the "interval" command to calculate the x0 and y values.

8.78 run_paramestlim

Module functions to determine confidence intervals, and retrieve the parameter bounds.

Array_Type run_unc([Array_Type])
Array_Type run_proj([Array_Type])
Array_Type run_cov([Array_Type])

Argument:

(1) An array of strings representing individual thawed model parameters (default all thawed parameters)

These functions initiate runs of the UNCERTAINTY, PROJECTION, and COVARIANCE parameter estimation methods respectively. The chosen method is run using the most recently fit datasets, which are automatically determined and hence are not function arguments. When done, each returns an array of structures, with one structure for each parameter whose bounds were estimated. These structures are the same as those returned by get_unc, get_proj, and get_cov.

Examples:

1. Fit a dataset; run projection and examine the results:

   sherpa> () = load_dataset(1,"example.pha")
   sherpa> () = set_subtract
   sherpa> () = set_source_expr(1,"POW[p]")
   sherpa> set_verbose(0)
   sherpa> () = run_fit
   sherpa> proj = run_proj
   sherpa> print(length(proj))
   2
   sherpa> print(proj[0])
   name             =  p.gamma
   val              =  1.79469
   vlo              =  1.71462
   vhi              =  1.87662
   sigma            =  1
   sherpa> print(proj[1])
   name             =  p.ampl
   val              =  0.000191983
   vlo              =  0.000180884
   vhi              =  0.000203087
   sigma            =  1
   

2. Repeat the last example, but only run covariance for one parameter:

   sherpa> cov = run_cov(["p.ampl"])
   sherpa> print(cov[0])
   name             =  p.ampl
   val              =  0.000191983
   vlo              =  0.000180873
   vhi              =  0.000203094
   sigma            =  1
   

8.78.1 CHANGES IN CIAO 3.1

The structures returned by these functions contain an additional field, sigma, which lists the value of the sigma parameter used in the covariance, uncertainty, or projection run.

8.79 run_paramestreg

Module functions to display contours of statistics as a function of parameter values, and to retrieve arrays of values and statistics

Struct_Type run_regunc(Array_Type)
Struct_Type run_regproj(Array_Type)

Argument:

(1) An array of two strings representing two thawed model parameters.

These functions initiate the REGION-UNCERTAINTY and REGION-PROJECTION parameter estimation methods respectively. The chosen method is run using the most recently fit datasets, which are automatically determined and hence are not function arguments. When done, each returns a structure, which are the same as those returned by get_regunc and get_regproj.

Examples:

1. Fit a dataset; get information about $\chi ^2$ as a function of power-law amplitude p.ampl and slope p.gamma

   sherpa> () = load_ascii(1,"spec.dat")
   sherpa> () = create_model("POLY","p")
   sherpa> set_thawed(["p.c1","p.c2","p.c3"])
   sherpa> () = set_source_expr(1,"p")
   sherpa> () = run_fit
    LVMQT: V2.0
    LVMQT: initial statistic value = 82.2297
    LVMQT: final statistic value = 62.2247 at iteration 3
                p.c0  61.4774     
                p.c1  -0.380228     
                p.c2  0.00993229     
                p.c3  -7.01741e-05     
   
   sherpa> list_regproj()
   Parameter   Current         Default                        Description
   ----------------------------------------------------------------------
   fast              1               1    Switch to LM/simplex: 0(n)/1(y)
   expfac            3               3          Expansion factor for grid
   arange            1               1              Auto-range: 0(n)/1(y)
   min           [0,0]           [0,0]          Minimum values, each axis
   max           [0,0]           [0,0]          Maximum values, each axis
   log           [0,0]           [0,0]  Log-spacing: 0(n)/1(y), each axis
   nloop       [10,10]         [10,10]   Number of grid points, each axis
   sigma       [1,2,3]         [1,2,3]      Number of sigma, each contour
   sherpa> sherpa.regproj.sigma = [1.6,2.6]
   sherpa> regproj = run_regproj(["p.c0","p.c1"])
   [...plot displayed...]
   sherpa> print(regproj)
   x0               =  Float_Type[100]
   x1               =  Float_Type[100]
   y                =  Float_Type[100]
   levels           =  Float_Type[2]
   name             =  String_Type[2]
   bfit             =  Double_Type[2]
   config           =  sherpa_VisParEst_State
   sherpa> printarr(regproj.x0,3)
   61.3661
   61.3661
   61.3661
   sherpa> printarr(regproj.x1,3)
   -1.79518
   -1.48075
   -1.16631
   sherpa> printarr(regproj.y,3)
   154.651
   118.31
   90.9931
   

   The third-to-last and second-to-last function calls cause the first three values of the p.c0 and p.c1 grid axes to be displayed (with p.c0 repeated because a 2-D grid is being computed). The last function call displays the best-fit statistic given the p.c0 and p.c1 values.

8.79.1 CHANGES IN CIAO 3.2

The run_regunc() and run_regproj() commands no longer place two arrays on the stack. This means that you can use

  retval = run_regproj(parameter_names);

rather than having to say something like

  (,,retval) = run_regproj(parameter_names);

8.79.2 CHANGES IN CIAO 3.1

The structures returned by these functions contain additional fields: levels, name, bfit, and config. These fields contain information on the statistic value for each contour, the name of the parameters, their best-fit values, and the values used by the "region" command to calculate the x0, x1, and y values.

8.80 set

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

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

$\bullet$

Move numerical data into Sherpa after, e.g., they were manipulated. (These data may be retrieved from Sherpa using analogous get functions.)

$\bullet$

Change Sherpa settings. (These settings may be determined using analogous get functions.)

(See below to find out how plot configuration once done using Sherpa's no-longer-existent SET is now done with the Sherpa state object.)

Table 8.16: Summary of Sherpa/S-Lang Module set Functions

Name	Description
set_erroff $\vert$ set_xerroff $\vert$ set_yerroff	Turn off the drawing of errorbars in Sherpa plots
set_erron $\vert$ set_xerron $\vert$ set_yerron	Turn on the drawing of errorbars in Sherpa plots
set_lin $\vert$ set_xlin $\vert$ set_ylin	Switch plotting axis to linear scale in Sherpa plots
set_log $\vert$ set_xlog $\vert$ set_ylog	Switch plotting axis to logarithmic scale in Sherpa plots
set_data $\vert$ set_back	Assign source and background data
set_errors $\vert$ set_berrors	Assign source and background error estimates
set_syserrors $\vert$ set_bsyserrors	Assign source and background systematic errors
set_weights $\vert$ set_bweights	Assign source and background statistical weights
set_filter $\vert$ set_bfilter	Assign source and background filters from an array
set_groups $\vert$ set_bgroups	Assign grouping to source and background from an array
set_quality $\vert$ set_bquality	Assign quality to source and background from an array
set_axes $\vert$ set_baxes	Create new source and background dataspaces
set_analysis	Set units for 1-D spectral analysis
set_coord	Set the coordinate system for 2-D image analysis
set_par	Set model parameter values, etc.
set_thawed $\vert$ set_frozen	Thaw or freeze model parameter values
set_ignore $\vert$ set_signore $\vert$ set_bignore	Set source and background ignore ranges in 1-D datasets
set_ignore2d $\vert$ set_signore2d $\vert$ set_bignore2d	Set source and background exclude regions in 2-D datasets
set_ignore_all $\vert$ set_signore_all $\vert$ set_bignore_all	Ignore all source and background data
set_ignore_bad $\vert$ set_signore_bad $\vert$ set_bignore_bad	Ignore all bad quality source and background data
set_notice $\vert$ set_snotice $\vert$ set_bnotice	Set source and background notice ranges in 1-D datasets
set_notice2d $\vert$ set_snotice2d $\vert$ set_bnotice2d	Set source and background include regions in 2-D datasets
set_notice_all $\vert$ set_snotice_all $\vert$ set_bnotice_all	Notice all source and background data
set_subtract $\vert$ set_unsubtract	Do or undo background subtraction
set_exptime $\vert$ set_bexptime	Set source and background exposure times
set_backscale $\vert$ set_bbackscale	Set source and background extraction region areas
set_source_expr $\vert$ set_bg_expr	Set source and background model stack expression
set_inst_expr $\vert$ set_sinst_expr $\vert$ set_binst_expr	Set source and background instrument model stack expression
set_dir	Set into directory
set_verbose	Reset Sherpa's verbosity

The following table shows how settings once made using the SET are now made with the Sherpa state object:

Table 8.17: Configuring Plots in CIAO 3.x

Old Command:	New Functions/Settings:
SET PLOT NOERRORBARS	set_erroff, or change x_errorbars and y_errorbars to 0 in the plotting state objects
SET PLOT XERRORBARS	set_xerron and set_yerroff, or change x_errorbars to 1 and y_errorbars to 0 in the plotting state objects
SET PLOT YERRORBARS	set_xerroff and set_yerron, or change x_errorbars to 0 and y_errorbars to 1 in the plotting state objects
SET PLOT ERRORBARS	set_erron, or change x_errorbars and y_errorbars to 1 in the plotting state objects
SET PLOT LIN LIN	set_lin, or change x_log and y_log to 0 in the plotting state objects
SET PLOT LIN LOG	set_xlin and set_ylog, or change x_log to 0 and y_log to 1 in the plotting state objects
SET PLOT LOG LIN	set_xlog and set_ylin, or change x_log to 1 and y_log to 0 in the plotting state objects
SET PLOT LOG LOG	set_log, or change x_log and y_log to 1 in the plotting state objects
SET PLOT AUTORANGE	Leave sherpa.multiplot.xfilter_lo and xfilter_hi set to NULL
SET PLOT RANGE MIN:MAX	Set sherpa.multiplot.xfilter_lo to MIN and sherpa.multiplot.xfilter_hi to MAX

See the documentation on the Sherpa state objects for more information.

8.81 set_analysis

Module function to set the units for 1-D spectral analysis.

Integer_Type set_analysis([Integer_Type],String_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) Units string

The set_analysis() function tells Sherpa the units in which to do subsequent analyses, for the specified dataset. For Sherpa version 3.0.2, supported (case-insensitive) string inputs are "bin" (equivalent to ANALYSIS CHANNELS), "kev" (equivalent to ANALYSIS ENERGY), "ang" (equivalent to ANALYSIS WAVE), "ev", "mev", "nm", and "hz".

Examples:

1. sherpa> data example.pha
   sherpa> instrument = rsp[a](example.rmf,example.arf)
   sherpa> () = set_analysis(1,"hz")
   sherpa> get_analysis()
   Hz
   sherpa>
   

8.82 set_axes

Module functions for creating new source or background dataspaces.

Integer_Type set_axes([Integer_Type,]Struct_Type|Array_Type)
Integer_Type set_baxes([Integer_Type,]Struct_Type|Array_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) A structure containing fields that define a 1-D dataspace, or

(2) An array that defines a 1-D dataspace, or

(2) An array of N structures containing fields that define an $N$-D dataspace, or

(2) An array of N arrays that define an $N$-D dataspace.

Note that if only one argument is provided, it is assumed to be one of the quantities listed for argument 2, and the dataset is assumed to be dataset 1.

The set_axes function is the equivalent of Sherpa's DATASPACE command. (The function set_baxes, used to set up dataspaces for background datasets, has no Sherpa command analogue.) A "dataspace'' is an $N$-dimensional grid representing the independent variables of a dataset (e.g., the $x$ values in $y = f(x)$).

A given axis may be defined using an array, or a structure; the former are appropriate for unbinned data entry, while structures are appropriate for either unbinned or binned data entry (the equivalent of DATASPACE HISTOGRAM). The structures must contain fields named lo and hi (for binned dataspaces), or mid (for unbinned dataspaces). These fields point to numeric arrays. (set_axes can thus process the structures output by get_axes. Note that the array lengths of the lo and hi fields of each input structure must be equal (though they may vary from axis to axis; e.g., to define a $512{\times}1024$ binned dataspace).

The set_axes functions should be used with care, as it instructs Sherpa to replace any dataset previously input with the same dataset number, with the new dataspace.

See the related Sherpa command DATASPACE for more information.

Examples:

1. Create a new 1-D dataspace:

   sherpa> DATA spec.dat
   sherpa> str = get_axes(1)
   sherpa> print(str)
   axistype         =  Channels
   axisunits        =  unknown
   lo               =  NULL
   hi               =  NULL
   mid              =  Float_Type[100]
   sherpa> theaxis = @(foo[0].mid)
   sherpa> () = set_axes(1,theaxis)
   

   In this example, the user takes a dataset and ends up replacing the read-in counts with zeroes. In the first step, unbinned ASCII data are read in. Because they are unbinned, get_axes returns a structure for which only the mid field is non-NULL. (There are no lower and upper bin boundaries.) The array pointed to by str.mid is then copied (the `@' sign denotes a total copy of array contents), and used to define a new dataspace via set_axes.

2. Create a new binned 2-D dataspace:

   sherpa> variable a0 = struct{lo,hi}
   sherpa> a0.lo = [1:1024]
   sherpa> a0.hi = [2:1025]
   sherpa> variable a1 = struct{lo,hi}
   sherpa> a1.lo = [1:1024]
   sherpa> a1.hi = [2:1025]
   sherpa> a = Struct_Type[2]
   sherpa> a[0] = a0
   sherpa> a[1] = a1
   sherpa> set_axes(1,a)
   1
   

   In this example, the user creates two structures which are minimally sufficient for setting up a binned dataspace (such a structure must have fields lo and hi, and it could have more fields, but these are ignored). Arrays are defined for each of the structure fields, such that the first bin has lower and upper bin boundaries 1 and 2, the second bin 2 and 3, etc. An array of structures a is then defined, and sent to Sherpa via set_axes. The call returns 1, indicating that Sherpa successfully set up a $1024{\times}1024$ dataspace.

8.83 set_backscale

Module functions for setting source and background extraction region areas.

Integer_Type set_backscale([Integer_Type],Float_Type)
Integer_Type set_bbackscale([Integer_Type],Float_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) Extraction region area

These functions take their names from the PHA header keyword BACKSCAL. BACKSCAL can be defined as the ratio of the area of the source (or background) extraction region in image pixels to the total number of image pixels. The fact that there is no ironclad definition for this quantity does not matter so long as the BACKSCAL for a source dataset and its associated background dataset are defined in the similar manner, because only the ratio of source and background BACKSCAL is used in analyses.

The specified backscale replaces the current value of the backscale within Sherpa, which as mentioned above may have been set when the dataset was loaded from the value of the BACKSCAL header keyword of a PHA file.

See the related Sherpa commands SETDATA and SETBACK for more information.

Examples:

1. Change the backscale value of dataset 1 from 0.0441895 to 0.07:

   sherpa> get_backscale()
   0.0441895
   sherpa> set_backscale(1,0.07)
   1
   sherpa> get_backscale()
   0.07
   

8.84 set_coord

Module function to set the coordinate system for 2-D image analysis.

Integer_Type set_coord([Integer_Type],String_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) Coordinate system string

The set_coord() function indicates to Sherpa the coordinate system within which to do 2-D image analysis. For Sherpa version 3.0.2, supported string inputs are "logical" (equivalent to "image"), "physical", and "world" (equivalent to "wcs").

Examples:

1. sherpa> data example.fits
   sherpa> () = set_coord(1,"physical")
   sherpa> get_coord()
   physical
   sherpa>
   

8.85 set_data

Set source and background data using the S-lang module function in Sherpa.

Integer_Type set_data([Integer_Type,]Array_Type)
Integer_Type set_back([Integer_Type,]Array_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) An array of source/background data amplitudes

Note that if only one argument is provided, it is assumed to be an array, and the dataset is assumed to be dataset 1.

The set_data and set_back functions allow the user to assign new source and background data amplitudes (for example number of counts) (i.e., the $y$ values in $y = f(x)$) to Sherpa datasets.

Note that:

$\bullet$

The input array length must match the number of bins in the filtered dataset; consequently, if one's goal is to use these functions in data manipulation, it is important not to change the filter in Sherpa between any call to, e.g., get_data and set_data!

$\bullet$

The input array is typecast to match the type of its associated dataspace (see, e.g., set_axes for a definition of dataspaces). For instance, if dataset 3 is of Double_Type, then when set_data(3,$<$array$>$) is run, the array is typecast to Double_Type if necessary.

Examples:

1. Retrieve data from Sherpa, process it, and replace:

   sherpa> DATA spec.dat
   sherpa> d = get_data(1)
   sherpa> print(d)
   2
   8
   12
   20
   18
   27
   ....
   sherpa> d -= 10
   sherpa> print(d)
   -8
   -2
   2
   10
   8
   17
   ....
   sherpa> () = set_data(,d)
   

   In this example, data are read into Sherpa in the first command and the counts values are retrived using get_data. Then, 10 counts are subtracted off every element of the array d; the new array is then sent to Sherpa, where it overwrites the old array. print command shows the first numbers of the array values.

8.86 set_dir

Module function to change directories.

Integer_Type set_dir(String_Type)

Success/Error Return Values: 1/0

Arguments:

(1) The directory to set into.

See the related Sherpa command CD for more information.

8.87 set_erroff

Switch off the drawing of error bars in Sherpa plots

set_erroff
set_xerroff
set_yerroff

These commands allow a user to turn off the drawing of error bars in all Sherpa plots. A plotting command LPLOT needs to be issued in order for these commands to take effect.

Errors bars can be turned on or off in plots (from LPLOT) by setting the x_errorbars and y_errorbars fields in the corresponding Sherpa configuration variable (also called "state object") sherpa.plot, sherpa.dataplot, sherpa.fitplot, or sherpa.resplot.

The functions set_erroff, set_xerroff, and set_yerroff allow you to change these fields in all the configuration variables (sherpa.plot, sherpa.dataplot, sherpa.fitplot, sherpa.resplot) in one go as shown in the following table:

Function Name	Description
set_erroff	Set x_errorbars $=$ 0 and y_errorbars $=$ 0
set_xerroff	Set x_errorbars $=$ 0
set_yerroff	Set y_errorbars $=$ 0

Examples:

1. sherpa> set_erroff
   

   This turns off the drawing of errorbars (both in x and y directions) in all Sherpa plots.

2. sherpa> set_xerroff
   

   This turns off the drawing of errorbars in only the x direction in all Sherpa plots.

3. sherpa> set_yerroff
   sherpa> print(sherpa.fitplot.y_errorbars)
   0
   sherpa> lplot 2 fit delchi
   

   The first command (set_yerroff) turns off the drawing of errorbars in only the y direction in all Sherpa plots. The second command prints out the value of the y_errorbars field of the sherpa.fitplot variable; it is set to 0 because of the set_yerroff command. The third command plots fit and delchi without y errorbars.

4. sherpa> set_yerroff
   sherpa> sherpa.fitplot.y_errorbars = 1
   sherpa> lplot fit
   

   The first command (set_yerroff) turns off the drawing of errorbars in only the y direction in all Sherpa plots. The second command changes the sherpa.fitplot variable so that its y_errorbars field is set to 1 which means that "LPLOT FIT" will include y error bars. The third command plots fit with y errorbars.

8.88 set_erron

Switch on the drawing of error bars in Sherpa plots

set_erron
set_xerron
set_yerron

These commands allow a user to turn on the drawing of error bars in all Sherpa plots. A plotting command LPLOT needs to be issued in order for these commands to take effect.

Errors bars can be turned on or off in plots (from LPLOT) by setting the x_errorbars and y_errorbars fields in the corresponding Sherpa configuration variable (also called "state object") sherpa.plot, sherpa.dataplot, sherpa.fitplot, or sherpa.resplot.

The functions set_erron, set_xerron, and set_yerron allow you to change these fields in all the configuration variables (sherpa.plot, sherpa.dataplot, sherpa.fitplot, sherpa.resplot) in one go as shown in the following table:

Function Name	Description
set_erron()	Set x_errorbars $=$ 1 and y_errorbars $=$ 1
set_xerron()	Set x_errorbars $=$ 1
set_yerron()	Set y_errorbars $=$ 1

Examples:

1. sherpa> set_erron
   

   This turns on the drawing of errorbars (both in x and y directions) in all Sherpa plots.

2. sherpa> set_xerron
   

   This turns on the drawing of errorbars in only the x direction in all Sherpa plots.

3. sherpa> set_yerron
   sherpa> print(sherpa.fitplot.y_errorbars)
   1
   sherpa> lplot 2 fit delchi
   

   The first command (set_yerron) turns on the drawing of errorbars in only the y direction in all Sherpa plots. The second command prints out the value of the y_errorbars field of the sherpa.fitplot variable; it is set to 1 because of the set_yerron command. The third command displays two plots with the errorbars in only the y direction.

4. sherpa> set_yerron
   sherpa> sherpa.fitplot.y_errorbars = 0
   sherpa> lplot fit
   

   The first command (set_yerron) turns on the drawing of errorbars in only the y direction in all Sherpa plots. The second command changes the sherpa.fitplot variable so that its y_errorbars field is set to 0 which means that "LPLOT FIT" will not include y error bars. The third command displays the fit with no errorbars in y direction.

8.89 set_errors

Module functions for assigning source and background error estimates.

Integer_Type set_errors([Integer_Type,]Array_Type)
Integer_Type set_berrors([Integer_Type,]Array_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) An array of source/background error estimates

Note that if only one argument is provided, it is assumed to be an array, and the dataset is assumed to be dataset 1.

The set_errors and set_berrors functions allow the user to assign new source and background error estimates to Sherpa datasets.

Note that:

$\bullet$

Any errors that are assigned via set_errors replace the error estimates that Sherpa makes automatically using the current STATISTIC setting, and are used until the errors are explicitly redefined.

$\bullet$

The input array length must match the number of bins in the filtered dataset; consequently, if one's goal is to use these functions in data manipulation, it is important not to change the filter in Sherpa between any call to, e.g., get_errors and set_errors!

$\bullet$

The input array is typecast to match the type of its associated dataspace (see, e.g., set_axes for a definition of dataspaces). For instance, if dataset 3 is of Double_Type, then when set_errors(3,$<$array$>$) is run, the array is typecast to Double_Type if necessary.

See the related Sherpa commands ERRORS and BERRORS for more information.

Examples:

1. Cause Sherpa to perform a least-squares fit:

   sherpa> DATA spec.dat
   sherpa> d = get_data()
   sherpa> d[*] = 1
   sherpa> () = set_errors(,d)
   

   In this example, an array of the length of the filtered data is retrieved from Sherpa, and all elements of the array are reset to 1. This new array is then sent to Sherpa, where it overwrites the old array of error estimates.

8.90 set_exptime

Module functions for setting source and background exposure times.

Integer_Type set_exptime([Integer_Type],Float_Type)
Integer_Type set_bexptime([Integer_Type],Float_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) Exposure time

The specified exposure time replaces the current value of the exposure time within Sherpa, which may have been set when the dataset was loaded from the value of the EXPTIME header keyword of a PHA file.

See the related Sherpa commands SETDATA and SETBACK for more information.

Examples:

1. Set the exposure time of the background dataset of dataset 4 to 30 ks:

   sherpa> get_bexptime(4)
   108676
   sherpa> () = set_bexptime(4,30000.0)
   sherpa> get_bexptime(4)
   30000
   

8.91 set_filter

Module functions for assigning source and background filters from an array.

Integer_Type set_filter([Integer_Type,]Array_Type)
Integer_Type set_bfilter([Integer_Type,]Array_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) An array of source/background filter values

Note that if only one argument is provided, it is assumed to be an array, and the dataset is assumed to be dataset 1.

The set_filter and set_bfilter functions allow the user to set new filters for source and background datasets.

The input array is a Short_Type, Long_Type, or Integer_Type array of the same length as the input (unfiltered) dataset for which a new filter is to be defined. If an input array element is zero, then the corresponding data bin is to be ignored; non-zero, and the corresponding bin is to be noticed/used.

One may use these functions in combination with get_filter and get_bfilter to define new methods of data filtering that go beyond those currently coded in Sherpa; e.g., filtering based on data amplitude. See example below.

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in a 100-bin dataset, and filter out bins 10 to 60:

   sherpa> DATA spec.dat
   sherpa> a = [0:99]
   sherpa> a[*] = 1
   sherpa> a[[9:59]] = 0
   sherpa> () = set_filter(1,a)
   

   In this example, data are read into Sherpa, and then the filter array a defined: step 1 defines a 100-bin-length array, step 2 resets all elements to 1, and step 3 resets a subset of the elements to 0 (bins to be ignored). Note that while the bins are numbered 1 to 100 in the data, the analogous array indices are 0 to 99, so array elements 9 to 59 are reset. The array is then sent to Sherpa, where it sets the new filter.

2. Read in a 100-bin dataset, and filter out all bins with counts greater than 65:

   sherpa> DATA spec.dat
   sherpa> WRITE DATA
   Write X-Axis: Bin  Y-Axis: Flux (Counts)
             1         59
             2         46
             3         49
             4         65
             5         60
             6         60
             7         74
   ...
   sherpa> d = get_data()
   sherpa> a = where(d>65)
   sherpa> printarr(a)
   6
   9
   11
   26
   ...
   sherpa> f = get_filter()
   sherpa> f[a] = 0
   sherpa> set_filter(1,f)
   1
   sherpa> WRITE DATA
   Write X-Axis: Bin  Y-Axis: Flux (Counts)
             1         59
             2         46
             3         49
             4         65
             5         60
             6         60
             8         58
   ...
   

   In this example, data are read into Sherpa, and the counts amplitude is retrieved using get_data. A new array a is defined whose elements are the bins for which the data are greater than 65; the length of this array is 13 (13 bins have data greater than 65 and are thus to be ignored). The filter array is then retrieved with get_filter and the appropriate 13 elements of that array are reset to 0. The new filter array is then read back into Sherpa, and we see, e.g., that bin 7 is now ignored.

8.92 set_groups

Module functions for grouping and setting quality to source and background files from an array.

Integer_Type set_groups([Integer_Type,]Array_Type)
Integer_Type set_bgroups([Integer_Type,]Array_Type)
Integer_Type set_quality([Integer_Type,]Array_Type)
Integer_Type set_bquality([Integer_Type,]Array_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1).

(2) An array defining the grouping or quality and it should be of the same length as the input data set. This argument is required.

Note that if only one argument is provided, it is assumed to be an array, and the dataset is assumed to be dataset 1.

The set_(b)groups and set_(b)quality functions allow the user to set new groups or quality for source and background datasets.

The input array is a Integer_Type array of the same length as the input (ungrouped) dataset for which a new grouping or quality scheme is to be defined. An input grouping array element set to -1 marks the beginning of a group, while an input 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:

1. Apply a grouping definition from the other PHA file to the 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> g=readfile("grouped.pha")
   sherpa> print(g)
   _filename        =  grouped.pha
   _path            =  /data
   _filter          =  NULL
   _filetype        =  7
   _header          =  String_Type[361]
   _exptime         =  13804
   _ncols           =  13
   _nrows           =  1024
   channels         =  Float_Type[596]
   counts           =  Float_Type[596]
   grouping         =  Integer_Type[1024]
   qualityflags     =  Integer_Type[596]
   phachans         =  Integer_Type[596]
   areascal         =  1
   backscal         =  4.2132e-07
   errors           =  Float_Type[596]
   background       =  /data/bg.pha
   arf              =  /data/spec.arf
   response         =  /data/spec.rmf
   numgroups        =  596
   numchans         =  1024
   
   sherpa> set_groups(1,g.grouping)
   sherpa> show
   ...
   -----------------
   Input data files:
   -----------------
    
   Data 1: spec.pha pha.
   Total Size: 596 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 from the other file, by reading the file first into a variable g using readfile. A new array g.grouping can be apply to the ungrouped data set. g.grouping is defined by the grouping in the dataset 2. This grouping scheme is then apply to the ungrouped data set with set_groups.

2. Apply a grouping scheme from the other data set to ungrouped 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
   
   .......
   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.

3. 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.93 set_ignore

Module functions for ignoring source and background filter ranges in 1-D datasets.

Integer_Type set_ignore([Integer_Type],Float_Type,Float_Type)
Integer_Type set_signore([Integer_Type],Float_Type,Float_Type)
Integer_Type set_bignore([Integer_Type],Float_Type,Float_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) The lower bound for the ignore range (default no lower bound)

(3) The upper bound for the ignore range (default no upper bound)

The commands set_ignore, set_signore, and set_bignore allow the user to specify data ranges to ignore in both source and background datasets, a source dataset, or a background dataset respectively. These functions may only be applied to 1-D data. Use set_ignore2d to set exclude regions in images.

Note that these functions work in the space given by the current ANALYSIS setting, e.g., if the setting is ENERGY, then the defined bounds are assumed to be in energy units. Note that in CIAO 3.1 set_ignore will work only if instrument models for both source and background are set.

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in a PHA file with instrument; ignore the lowest-energy channels:

   sherpa> () = load_dataset(1,"example.pha")
   sherpa> set_ignore(1,,0.3)
   1
   sherpa> ANALYSIS
   Analysis Space for Dataset 1: Energy
   

   In this example, all data below 0.3 keV are ignored in dataset 1.

2. Continue Example 1, ignoring all data between 6 and 12 Å:

   sherpa> ANALYSIS WAVE
   sherpa> set_ignore(,6,12)
   1
   

3. Continue Example 2, now ignoring all source data above 9 keV:

   sherpa> ANALYSIS ENERGY
   sherpa> set_signore(1,9,)
   1
   

   The corresponding background data above 9 keV are still noticed.

8.94 set_ignore2d

Module functions for ignoring source and background regions in 2-D datasets.

Integer_Type set_ignore2d([Integer_Type],String_Type[,String_Type])
Integer_Type set_signore2d([Integer_Type],String_Type[,String_Type])
Integer_Type set_bignore2d([Integer_Type],String_Type[,String_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) A filter expression: $<$filterExpr$>$

(3) The coordinate system expression

The commands set_ignore2d, set_signore2d, and set_bignore2d allow the user to specify regions to ignore in both source and background datasets, a source dataset, or a background dataset respectively. These functions may only be applied to 2-D data. Use set_ignore to set ranges to ignore in 1-D spectra.

See the Sherpa Filtering Chapter for the full definition of $<$filterExpr$>$. (Also see examples below.)

The default coordinate system expression is "logical" (i.e., image coordinates). Allowed coordinate system expressions include:

$\bullet$

"logical" $\vert$ "image" - image coordinates

$\bullet$

"physical" - physical coordinates

$\bullet$

"wcs" $\vert$ "world" - world coordinates

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in an image; ignore the central source using a circular exclude region:

   sherpa> load_image(2,"example_img.fits") 
   1
   sherpa> set_ignore2d(2,"circle(247,257,20)")
   1
   

   In this example, all data within a radius of 20 pixels of the image coordinate (247,257) are ignored.

2. Apply a box filter to an image in physical coordinates:

   sherpa> load_image(1,"example_img2.fits")
   1
   sherpa> set_ignore2d(,"box(4050,3920,30,30)","physical")
   1
   

8.95 set_ignore_all

Module functions for ignoring all source and background data.

Integer_Type set_ignore_all([Integer_Type])
Integer_Type set_signore_all([Integer_Type])
Integer_Type set_bignore_all([Integer_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

The commands set_ignore_all, set_signore_all, and set_bignore_all allow the user to ignore all data in both source and background datasets, a source dataset, or a background dataset respectively.

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in a PHA file with instrument; ignore all channels as a prelude to defining notice ranges:

   sherpa> () = load_dataset(1,"example.pha")
   sherpa> set_ignore_all(1)
   1
   ...
   

8.96 set_ignore_bad

Module functions for ignoring bad (quality $>$ 0) channels.

Integer_Type set_ignore_bad([Integer_Type])
Integer_Type set_signore_bad([Integer_Type])
Integer_Type set_bignore_bad([Integer_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

The commands set_ignore_bad, set_signore_bad, and set_bignore_bad allow the user to ignore bad quality (quality $>$ 0) channels in both source and background datasets, a source dataset, or a background dataset respectively. These functions have no impact if the data quality has not been defined, either within a column of a PHA dataset or via the READ QUALITY command.

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in a PHA file; ignore the bad channels:

   sherpa> () = load_dataset(1,"example.pha")
   sherpa> f = get_filter()
   sherpa> print(length(where(f>0)))
   95                                        # 95 noticed bins
   sherpa> set_ignore_bad
   1
   sherpa> f = get_filter()
   sherpa> print(length(where(f>0)))    
   80                                        # now only 80 noticed bins
   

8.97 set_lin

Switch plotting axis to linear scale in Sherpa plots

set_lin
set_xlin
set_ylin

These commands allow a user to switch x- and y-axis to linear scale in all Sherpa plots. A plotting command LPLOT needs to be issued in order for these commands to take effect.

A user can control log and linear scale of the x and y-axis created with the LPLOT command by setting the x_log and y_log in the corresponding Sherpa configuration variable (also called "state object") sherpa.plot, sherpa.dataplot, sherpa.fitplot, or sherpa.resplot.

The functions set_lin, set_xlin, and set_ylin allow you to change these fields in all the configuration variables (sherpa.plot, sherpa.dataplot, sherpa.fitplot, sherpa.resplot) at once as shown in the following table:

Function Name	Description
set_lin	Set x_log $=$ 0 and y_log $=$ 0
set_xlin	Set x_log $=$ 0
set_ylin	Set y_log $=$ 0

Examples:

1. sherpa> set_lin
   

   This sets plot axis (both in x and y ) to linear scale in all Sherpa plots.

2. sherpa> set_xlin
   

   This sets plot axis to linear scale for only the x-axis in all Sherpa plots.

3. sherpa> set_ylin
   sherpa> print(sherpa.fitplot.y_log)
   0
   sherpa> lplot fit
   

   The first command (set_ylog) sets y-axis to linear scale in all Sherpa plots. The second command prints out the value of the y_log field of the sherpa.fitplot variable; it is set to 0 (false) because of the set_ylin command. The third command displays fit in linear scale

8.98 set_log

Switch axis to log in Sherpa plots

set_log
set_xlog
set_ylog

These commands allow a user to switch x- and y-axis to log in all Sherpa plots. A plotting command LPLOT needs to be issued in order for these commands to take effect.

A user can control log and linear scale of the x and y-axis created with the LPLOT command by setting the x_log and y_log in the corresponding Sherpa configuration variable (also called "state object") sherpa.plot, sherpa.dataplot, sherpa.fitplot, or sherpa.resplot.

The functions set_log, set_xlog, and set_ylog allow you to change these fields in all the configuration variables (sherpa.plot, sherpa.dataplot, sherpa.fitplot, sherpa.resplot) at once as shown in the following table:

Function Name	Description
set_log	Set x_log $=$ 1 and y_log $=$ 1
set_xlog	Set x_log $=$ 1
set_ylog	Set y_log $=$ 1

Examples:

1. sherpa> set_log
   

   This sets plot axis (both in x and y ) to log scale in all Sherpa plots.

2. sherpa> set_xlog
   

   This sets plot axis to log scale for only the x-axes in all Sherpa plots.

3. sherpa> set_ylog
   sherpa> print(sherpa.fitplot.y_log)
   1
   sherpa> lplot fit
   

   The first command (set_ylog) sets y-axis to log scale in all Sherpa plots. The second command prints out the value of the y_log field of the sherpa.fitplot variable; it is set to 1 because of the set_ylog command. The third command displays fit in log scale

8.99 set_notice

Module functions for noticing source and background filter ranges in 1-D datasets.

Integer_Type set_notice([Integer_Type],Float_Type,Float_Type)
Integer_Type set_snotice([Integer_Type],Float_Type,Float_Type)
Integer_Type set_bnotice([Integer_Type],Float_Type,Float_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) The lower bound for the notice range (default no lower bound)

(3) The upper bound for the notice range (default no upper bound)

The commands set_notice, set_snotice, and set_bnotice allow the user to specify data ranges to notice in both source and background datasets, a source dataset, or a background dataset respectively. These functions may only be applied to 1-D data. Use set_notice2d to set include regions in images.

Note that these functions work in the space given by the current ANALYSIS setting, e.g., if the setting is ENERGY, then the defined bounds are assumed to be in energy units. Note that in CIAO 3.1 set_notice will work only if instrument models for both source and background are set.

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in a PHA file with instrument; notice the data below 1 keV:

   sherpa> () = load_dataset(1,"example.pha")
   sherpa> set_notice(1,,1)
   1
   sherpa> ANALYSIS
   Analysis Space for Dataset 1: Energy
   

2. Continue Example 1, notice all data between 3 and 6 Å:

   sherpa> ANALYSIS WAVE
   sherpa> set_notice(,3.0,6.0)
   1
   

3. Continue Example 2, now noticings all source data above 9 keV:

   sherpa> ANALYSIS ENERGY
   sherpa> set_snotice(1,9.0,)
   1
   

   The corresponding background data above 9 keV are still ignored.

8.100 set_notice2d

Module functions for noticing source and background regions in 2-D datasets.

Integer_Type set_notice2d([Integer_Type],String_Type[,String_Type])
Integer_Type set_snotice2d([Integer_Type],String_Type[,String_Type])
Integer_Type set_bnotice2d([Integer_Type],String_Type[,String_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) A filter expression: $<$filterExpr$>$

(3) The coordinate system expression

The commands set_notice2d, set_snotice2d, and set_bnotice2d allow the user to specify regions to notice in both source and background datasets, a source dataset, or a background dataset respectively. These functions may only be applied to 2-D data. Use set_notice to set ranges to notice in 1-D spectra.

See the Sherpa Filtering Chapter for the full definition of $<$filterExpr$>$. (Also see examples below.)

The default coordinate system expression is "logical" (i.e., image coordinates). Allowed coordinate system expressions include:

$\bullet$

"logical" $\vert$ "image" - image coordinates

$\bullet$

"physical" - physical coordinates

$\bullet$

"wcs" $\vert$ "world" - world coordinates

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in an image; notice the central source using a circular include region:

   sherpa> load_image(2,"example_img.fits") 
   1
   sherpa> set_notice2d(2,"circle(247,257,20)")
   1
   

   In this example, all data within a radius of 20 pixels of the image coordinate (247,257) are noticed.

2. Apply a box filter to an image in physical coordinates:

   sherpa> load_image(1,"example_img2.fits")
   1
   sherpa> set_notice2d(,"box(4050,3920,30,30)","physical")
   1
   

8.101 set_notice_all

Module functions for noticing all source and background data.

Integer_Type set_notice_all([Integer_Type])
Integer_Type set_snotice_all([Integer_Type])
Integer_Type set_bnotice_all([Integer_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

The commands set_notice_all, set_snotice_all, and set_bnotice_all allow the user to notice all data in both source and background datasets, a source dataset, or a background dataset respectively.

See the related Sherpa commands NOTICE and IGNORE for more information.

Examples:

1. Read in a PHA file with instrument; ignore all channels, then notice all channels:

   sherpa> () = load_dataset(1,"example.pha")
   sherpa> set_ignore_all(1)
   1
   sherpa> set_notice_all(1)
   1
   sherpa> SHOW
   ...
   Current filters for dataset 1:
   notice source 1 all
   Noticed filter size: 95 bins 
   ...
   

8.102 set_par

Module function for setting model parameter values, etc.

Integer_Type set_par(Struct_Type)
Integer_Type set_par(String_Type,String_Type,{Float_Type | String_Type})

Success/Error Return Values: 1/0

Arguments:

(1) A parameter information structure

or

(1) The parameter name

(2) The field to set

(3) The new value for that field

The first form of this function assumes as input the parameter information structure output by get_par, e.g.

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

The second form of this function takes the arguments listed above; fields to set include:

Table 8.22: Allowed set_par Arguments

Argument	Description
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)
frozen	if 1, freeze the parameter's value; if 0, thaw it
thawed	if 1, thaw the parameter's value; if 0, freeze it

See the Sherpa command CREATE for more information.

Examples:

1. 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
   

2. Change two parameter attributes directly:

   sherpa> GAUSS[g]
   sherpa> () = set_par("g.pos","value",15.5)
   sherpa> () = set_par("g.pos","min",0.0)
   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
   

8.103 set_paramset

Module functions to thaw or freeze the specified parameter(s).

Integer_Type set_thawed([String_Type])
Integer_Type set_frozen([String_Type])

Success/Error Return Values: 1/0

Arguments:

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

If:

$\bullet$

no argument is provided, these functions will thaw or freeze all model parameters;

$\bullet$

a model component name is provided, these functions will thaw or freeze all parameters of that model; and

$\bullet$

if a model parameter name is provided, these functions will thaw or freeze that parameter.

See the related Sherpa commands THAW and FREEZE for more information.

Examples:

1. Freeze all parameters of a specified Gaussian model, then thaw the position parameter:

   sherpa> PARAMPROMPT OFF
   sherpa> GAUSS[g]
   sherpa> set_frozen("g")
   1
   sherpa> set_thawed("g.pos")
   1
   sherpa> SHOW g
   gauss1d[g]  (integrate: on)
       Param   Type      Value        Min        Max                 Units
       -----   ----      -----        ---        ---                 -----
    1   fwhm frozen         10 1.1755e-38 3.4028e+38
    2    pos thawed          0 -3.403e+38 3.4028e+38
    3   ampl frozen          1 -3.403e+38 3.4028e+38
   

8.104 set_stackexpr

Module functions to set a model stack expression.

Integer_Type set_source_expr([Integer_Type,]String_Type])
Integer_Type set_bg_expr([Integer_Type,]String_Type])
Integer_Type set_inst_expr([Integer_Type,]String_Type])
Integer_Type set_sinst_expr([Integer_Type,]String_Type])
Integer_Type set_binst_expr([Integer_Type,]String_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) A string expression

Note that if only one argument is provided, it is assumed to be a string expression, and the dataset is assumed to be dataset 1.

These functions set model stack expressions; set_sinst_expr and set_binst_expr set instrument model stack expressions for the source dataset only, and the background dataset only, respectively.

See the related Sherpa commands SOURCE, BACKGROUND, and INSTRUMENT for more information.

NOTE: In CIAO 3.1 the instrument model stack expression for the background dataset is required for simultanous filtering in energy/wave or fitting of PHA files.

Examples:

1. Specify the source model stack expression for dataset 3:

   sherpa> PARAMPROMPT OFF
   sherpa> GAUSS[g]
   sherpa> POW[p]
   sherpa> () = set_source_expr(3,"p+g")
   

2. Specify a source model stack expression for dataset 1:

   sherpa> () = set_source_expr("xswabs[xs1]*(pow[p]+gauss[g])")
   sherpa> get_source_expr()
   (xs1 * (p + g))
   

8.105 set_subtract

Module functions to subtract background from a source dataset, or to undo subtraction.

Integer_Type set_subtract([Integer_Type])
Integer_Type set_unsubtract([Integer_Type])

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

These functions return 1 if successful, and 0 if the (un)subtraction cannot be done (because, e.g., background already have been subtracted before a call to set_subtract).

See the related Sherpa commands SUBTRACT and UNSUBTRACT for more information.

Examples:

1. Subtract the background from dataset 1; then add it back in:

   sherpa> DATA example.pha
   The inferred file type is PHA.  If this is not what you want, please 
   specify the type explicitly in the data command.
   WARNING: using systematic errors specified in the PHA file.
   RMF is being input from:
     <directory_path>/example2.rmf
   ARF is being input from:
     <directory_path>/example2.arf
   Background data are being input from:
     <directory_path>/example2_bkg.pha
   sherpa> is_subtracted
   0
   sherpa> set_subtract
   1
   sherpa> is_subtracted(1)
   1
   sherpa> set_unsubtract()
   1
   sherpa> is_subtracted(1)
   0
   

   The 0 returned from the first call indicates that no, dataset 1 is not yet background subtracted. (Unlike XSPEC, Sherpa does not automatically subtract background data upon input.) The 1 returned from the third call, issued after the call to the set_subtract function, indicates that yes, dataset 1 is now background-subtracted. Similarly, the 0 returned from the last call to is_subtracted indicates that the call to set_unsubtract was successful.

8.106 set_syserrors

Module functions for assigning source and background systematic error estimates.

Integer_Type set_syserrors([Integer_Type,]Array_Type)
Integer_Type set_bsyserrors([Integer_Type,]Array_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) An array of source/background systematic error estimates

Note that if only one argument is provided, it is assumed to be an array, and the dataset is assumed to be dataset 1.

The set_syserrors and set_bsyserrors functions allow the user to assign new source and background systematic error estimates to Sherpa datasets.

Note that:

$\bullet$

Systematic errors are added in quadrature to statistical errors (error estimates that Sherpa makes automatically using the current STATISTIC setting) to yield overall error estimates in each bin.

$\bullet$

The input array length must match the number of bins in the filtered dataset; consequently, if one's goal is to use these functions in data manipulation, it is important not to change the filter in Sherpa between any call to, e.g., get_syserrors and set_syserrors!

$\bullet$

The input array is typecast to match the type of its associated dataspace (see, e.g., set_axes for a definition of dataspaces). For instance, if dataset 3 is of Double_Type, then when set_syserrors(3,$<$array$>$) is run, the array is typecast to Double_Type if necessary.

See the related Sherpa commands SYSERRORS and BSYSERRORS for more information.

Examples:

1. Assign systematic errors of one-tenth the data amplitude to each data bin:

   sherpa> DATA spec.dat
   sherpa> d = get_data()
   sherpa> d[*] = 0.1
   sherpa> () = set_syserrors(,d)
   

   In this example, an array of the length of the filtered data is retrieved from Sherpa, and all elements of the array are reset to 0.1 (the systematic error estimate). This new array is then sent to Sherpa, where it overwrites the old array of systematic error estimates.

8.107 set_verbose

Module function to reset Sherpa's verbosity.

Void_Type set_verbose(Integer_Type)

Arguments:

(1) The verbosity level.

This function sets the amount that Sherpa outputs to the screen.

The current verbosity settings are:

Table 8.23: Verbosity Settings for set_verbose

Setting	Displays:
0	(almost) no output (useful for scripts/batch jobs)
1	normal output; many warnings are suppressed and the results of each fit iteration are not shown (the default)
2	full output

8.108 set_weights

Module functions for assigning source and background statistical weights.

Integer_Type set_weights([Integer_Type,]Array_Type)
Integer_Type set_bweights([Integer_Type,]Array_Type)

Success/Error Return Values: 1/0

Arguments:

(1) Dataset number (default 1)

(2) An array of source/background statistical weight settings

Note that if only one argument is provided, it is assumed to be an array, and the dataset is assumed to be dataset 1.

The set_weights and set_bweights functions allow the user to assign new source and background statistical weight values to Sherpa datasets. The default value of a statistical weight is 1, meaning the all data bins have equal influence in the calculation of a statistic. A weight less than 1 decreases a bin's contribution to the total statistic value; a weight greater than 1 increases the contribution.

Note that:

$\bullet$

the input array length must match the number of bins in the filtered dataset; consequently, if one's goal is to use these functions in data manipulation, it is important not to change the filter in Sherpa between any call to, e.g., get_weight and set_weight!

$\bullet$

the input array is typecast to match the type of its associated dataspace (see, e.g., set_axes for a definition of dataspaces). For instance, if dataset 3 is of Double_Type, then when set_weight(3,$<$array$>$) is run, the array is typecast to Double_Type if necessary.

See the related Sherpa command READ WEIGHTS for more information.

Examples:

1. Change the statistical weights of the lowest-value bins in a dataset to reduce the influence of these bins in a statistic calculation:

   sherpa> DATA spec.dat
   sherpa> SOURCE = CONST[cs]
   sherpa> FIT
    LVMQT: V2.0
    LVMQT: initial statistic value = 82.2297
    LVMQT: final statistic value = 63.9111 at iteration 3
               cs.c0  57.7977     
   
   sherpa> d = get_data(1)
   sherpa> d[*] = 1
   sherpa> d[[0:5]] = 0.5
   sherpa> printarr(d,10)
   0.5
   0.5
   0.5
   0.5
   0.5
   0.5
   1
   1
   ...
   sherpa> set_weights(1,d)
   1
   sherpa> FIT
    LVMQT: V2.0
    LVMQT: initial statistic value = 61.7966
    LVMQT: final statistic value = 61.7912 at iteration 2
               cs.c0  57.8627
   

   In this example, data are read into Sherpa and the counts amplitude array is retrived using get_data. Every element of this array is reset to 1, then the first six elements are reset to 0.5. The array is then sent to Sherpa, where it overwrites the old weight array; the subsequent fit shows a slight change.