Creates a contour plot of confidence regions using the
UNCERTAINTY algorithm.
The commands REG-UNC and REGUNC
are abbreviated equivalents.
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.
The two command-line arguments may be:
REGION-UNCERTAINTY Command Arguments
| <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
| 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.
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
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
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
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
...
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.
- sherpa
-
berrors,
bsyserrors,
compute_errors,
compute_statistic,
covariance,
errors,
ftest,
get_paramest,
get_paramestint,
get_paramestlim,
get_paramestreg,
goodness,
interval-projection,
interval-uncertainty,
list_paramest,
mlr,
projection,
region-projection,
restore_paramest,
run_paramest,
run_paramestint,
run_paramestlim,
run_paramestreg,
set_errors,
set_syserrors,
staterrors,
syserrors,
uncertainty
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}