About Chandra Archive Proposer Instruments & Calibration Newsletters Data Analysis HelpDesk Calibration Database NASA Archives & Centers Chandra Science Links

Skip the navigation links
Last modified: December 2006

URL: http://cxc.harvard.edu/ciao3.4/region-uncertainty.html
Hardcopy (PDF): A4 | Letter
AHELP for CIAO 3.4 region-uncertainty Context: sherpa

Synopsis

Creates a contour plot of confidence regions using the UNCERTAINTY algorithm. The commands REG-UNC and REGUNC are abbreviated equivalents.

Syntax

sherpa> REGION-UNCERTAINTY [<dataset range> | ALLSETS] <arg_1> <arg_2>

where <dataset range> = #, or more generally #:#,#:#,..., such that #
specifies a dataset number, and #:# represents an inclusive range of
datasets; one may specify multiple inclusive ranges by separating them
with commas. The default is to compute contours using data from all
appropriate datasets.

Description

The two command-line arguments may be:

REGION-UNCERTAINTY Command Arguments

Argument Description
<sherpa_modelname>.{<paramname> | <#>} A specified model component parameter (e.g., GAUSS.pos).
<modelname>.{<paramname> | <#>} A specified model component parameter (e.g., g.pos).

The user may configure REGION-UNCERTAINTY via the Sherpa state object structure regunc. The current values of the fields of this structure may be displayed using the command print(sherpa.regunc), or using the more verbose Sherpa/S-Lang module function list_regunc().

The structure fields are:

regproj Structure Fields

Field Description
expfac A multiplicative factor that expands the grid limits estimated by the UNCERTAINTY algorithm, if the grid limits are determined automatically (see arange, and below).
arange If 1, the grid limits are to be determined automatically. If 0, the grid limits are specified (see min and max).
min An array of length two giving the grid minima for each plot axis. These are always linear quantities, regardless of the setting of log (see below). The array is ignored if arange = 1.
max An array of length two giving the grid maxima for each plot axis. These are always linear quantities, regardless of the setting of log (see below). The array is ignored if arange = 1.
log An array of length two specifying whether to use linear (0) or logarithmic (1) spacing of grid points along each plot axis.
nloop An array of length two specifying the number of grid points along each plot axis.
sigma An array of arbitrary length specifying the number of sigma for each contour. The length of the array specifies the number of contours.

Field values may be set using directly. If the field does not contain an array, e.g.,

sherpa> sherpa.regunc.arange = 0

and if it does contain an array, e.g.,

sherpa> sherpa.regunc.nloop = [25,20]

NOTE: strict checking of value inputs is not done, i.e., the user can errantly change arrays to scalars, etc. To restore the default settings of the structure at any time, use the Sherpa/S-Lang module function restore_regunc().

The confidence regions are determined by varying each selected parameter's value along an automatically determined grid, computing the best-fit statistic at each grid point and interpolating. REGION-UNCERTAINTY differs from REGION-PROJECTION in that all other thawed parameters are fixed to their best-fit values, rather than being allowed to float to new best-fit values. This makes REGION-UNCERTAINTY contours less accurate, but causes them to be computed much more quickly. For a fuller theoretical description of error estimation, see PROJECTION, UNCERTAINTY, and COVARIANCE.

The grid limits for the plot are determined automatically using the UNCERTAINTY algorithm. Each parameter's value is varied until the fit statistic is increased by delta_S, which is a function of the largest value of sigma (e.g., delta_S = 11.8 if the statistic is chi-square and 3 is the largest element of the array sigma. The uncertainty errors are then multiplied by expfac and are subtracted from and added to the best-fit parameter values to determine the lower and upper grid limits.

The grid-point values and best-fit statistics at each grid point may be retrieved using the Sherpa/S-Lang module function get_regproj. See the examples below.

Example 1

List the current and default values of the regunc structure, and restore the default values:

sherpa> sherpa.regunc.arange = 0
sherpa> sherpa.regunc.log = [1,1]
sherpa> sherpa.regunc.sigma = [1,3,5]
sherpa> list_regunc()
Parameter   Current         Default                        Description
----------------------------------------------------------------------
expfac            3               3          Expansion factor for grid
arange            0               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           [1,1]           [0,0]  Log-spacing: 0(n)/1(y), each axis
nloop       [40,40]         [40,40]   Number of grid points, each axis
sigma       [1,3,5]         [1,2,3]      Number of sigma, each contour
sherpa> restore_regunc()
sherpa> list_regunc()
Parameter   Current         Default                        Description
----------------------------------------------------------------------
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       [40,40]         [40,40]   Number of grid points, each axis
sigma       [1,2,3]         [1,2,3]      Number of sigma, each contour

Example 2

Determine 1-, 2-, 3-, and 4-sigma confidence regions for a fit:

sherpa> READ DATA example1.dat
sherpa> PARAMPROMPT OFF
sherpa> SOURCE = POLYNOM1D[my]
sherpa> THAW my.c1 my.c2
sherpa> my.c0.min = -15
sherpa> FIT
...
sherpa> sherpa.regunc.sigma = [1,2,3,4]
sherpa> REGION-UNCERTAINTY my.c0 my.c2
Region-Uncertainty: computing grid size...done.
                    outer grid loop 20% done...
                    outer grid loop 40% done...
                    outer grid loop 60% done...
                    outer grid loop 80% done...
Minimum: 0.255419
Levels are: 2.55142 6.43642 12.0854 19.5904

Example 3

Determine 1- and 3-sigma confidence regions for the same data:

sherpa> sherpa.regunc.sigma = [1,3]
sherpa> REGION-UNCERTAINTY my.c0 my.c2
Region-Uncertainty: computing grid size...done.
                    outer grid loop 20% done...
                    outer grid loop 40% done...
                    outer grid loop 60% done...
                    outer grid loop 80% done...
Minimum: 0.255419
Levels are: 2.55142 12.0854

Example 4

Save the results of REGION-UNCERTAINTY to an ASCII file:

[...run REGION-UNCERTAINTY...]
sherpa> my_var = get_regunc()
sherpa> writeascii("my_output.dat",my_var.x0,my_var.x1,my_var.y)
sherpa> quit
Goodbye.
unix> more my_output.dat
-12.7129        -0.154565       418.014
-12.7129        -0.0945145      390.736
-12.7129        -0.0344636      364.511
...

CHANGES IN CIAO 3.2

Prior to CIAO 3.2 the REGION-UNCERTAINTY command could not be used until the dataset had been fit. This was done to ensure that the parameter values were at their best-fit location, but caused problems when fitting multiple datasets or loading previously-saved analysis sessions. This restriction has now been removed. Please note that the results of REGION-UNCERTAINTY may not be valid unless the parameters are at their best-fit values.

Bugs

See the Sherpa bug pages online for an up-to-date listing of known bugs.

Hardcopy (PDF): A4 | Letter
Last modified: December 2006



The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory.
60 Garden Street, Cambridge, MA 02138 USA.    Email: cxcweb@head.cfa.harvard.edu
Smithsonian Institution, Copyright © 1998-2004. All rights reserved.