Creating model instances¶
namespaces provides a collection of one- and
two-dimensional models as a convenience; the actual definition of
each particular model depends on its type.
The following modules are assumed to have been imported for this section:
>>> import numpy as np >>> import matplotlib.pyplot as plt >>> from sherpa import models
Creating a model instance¶
Models must be created before there parameter values can
be set. In this case a one-dimensional gaussian using the
>>> g = models.Gauss1D() >>> print(g) gauss1d Param Type Value Min Max Units ----- ---- ----- --- --- ----- gauss1d.fwhm thawed 10 1.17549e-38 3.40282e+38 gauss1d.pos thawed 0 -3.40282e+38 3.40282e+38 gauss1d.ampl thawed 1 -3.40282e+38 3.40282e+38
A description of the model is provided by
The parameter values have a current value, a valid range
(as given by the the minimum and maximum columns in the table above),
and a units field. The units field is a string, describing the
expected units for the parameter; there is currently no support for
using astropy.units to set a
parameter value. The “Type” column refers to whether the parameter is
frozen) or can be varied during a fit (
as described below, in the Freezing and Thawing parameters section.
Models can be given a name, to help distinguish multiple versions of the same model type. The default value is the lower-case version of the class name.
>>> g.name 'gauss1d' >>> h = models.Gauss1D('other') >>> print(h) other Param Type Value Min Max Units ----- ---- ----- --- --- ----- other.fwhm thawed 10 1.17549e-38 3.40282e+38 other.pos thawed 0 -3.40282e+38 3.40282e+38 other.ampl thawed 1 -3.40282e+38 3.40282e+38 >>> h.name 'other'
The model classes are expected to derive from the
Models can be combined and shared by using the standard Python
numerical operators. For instance, a one-dimensional gaussian
plus a flat background - using the
Const1D class - would be
represented by the following model:
>>> src1 = models.Gauss1D('src1') >>> back = models.Const1D('back') >>> mdl1 = src1 + back >>> print(mdl1) (src1 + back) Param Type Value Min Max Units ----- ---- ----- --- --- ----- src1.fwhm thawed 10 1.17549e-38 3.40282e+38 src1.pos thawed 0 -3.40282e+38 3.40282e+38 src1.ampl thawed 1 -3.40282e+38 3.40282e+38 back.c0 thawed 1 -3.40282e+38 3.40282e+38
Now consider fitting a second dataset where it is known that the background is two times higher than the first:
>>> src2 = models.Gauss1D('src2') >>> mdl2 = src2 + 2 * back >>> print(mdl2) (src2 + (2 * back)) Param Type Value Min Max Units ----- ---- ----- --- --- ----- src2.fwhm thawed 10 1.17549e-38 3.40282e+38 src2.pos thawed 0 -3.40282e+38 3.40282e+38 src2.ampl thawed 1 -3.40282e+38 3.40282e+38 back.c0 thawed 1 -3.40282e+38 3.40282e+38
The two models can then be fit separately or simultaneously. In this
example the two source models (the Gaussian component) were completely
separate, but they could have been identical - in which case
mdl2 = src1 + 2 * back would have been used instead - or
parameter linking could be used to constrain the
models. An example of the use of linking would be to force the two
FWHM (full-width half-maximum)
parameters to be the same but to let the position and amplitude
values vary independently.
More information is available in the combining models documentation.
Changing a parameter¶
The parameters of a model - those numeric variables that control the
shape of the model, and that can be varied during a fit -
can be accesed as attributes, both to read or change
the current settings. The
contains the current value:
>>> print(h.fwhm) val = 10.0 min = 1.17549435082e-38 max = 3.40282346639e+38 units = frozen = False link = None default_val = 10.0 default_min = 1.17549435082e-38 default_max = 3.40282346639e+38 >>> h.fwhm.val 10.0 >>> h.fwhm.min 1.1754943508222875e-38 >>> h.fwhm.val = 15 >>> print(h.fwhm) val = 15.0 min = 1.17549435082e-38 max = 3.40282346639e+38 units = frozen = False link = None default_val = 15.0 default_min = 1.17549435082e-38 default_max = 3.40282346639e+38
Assigning a value to a parameter directly (i.e. without using the
val attribute) also works:
>>> h.fwhm = 12 >>> print(h.fwhm) val = 12.0 min = 1.17549435082e-38 max = 3.40282346639e+38 units = frozen = False link = None default_val = 12.0 default_min = 1.17549435082e-38 default_max = 3.40282346639e+38
The soft and hard limits of a parameter¶
Each parameter has two sets of limits, which are referred to as
“soft” and “hard”. The soft limits are shown when the model
is displayed, and refer to the
attributes for the parameter, whereas the hard limits are
given by the
(which are not displayed, and can not be changed).
>>> print(h) other Param Type Value Min Max Units ----- ---- ----- --- --- ----- other.fwhm thawed 12 1.17549e-38 3.40282e+38 other.pos thawed 0 -3.40282e+38 3.40282e+38 other.ampl thawed 1 -3.40282e+38 3.40282e+38 >>> print(h.fwhm) val = 12.0 min = 1.17549435082e-38 max = 3.40282346639e+38 units = frozen = False link = None default_val = 12.0 default_min = 1.17549435082e-38 default_max = 3.40282346639e+38
These limits act to bound the acceptable parameter range; this is often because certain values are physically impossible, such as having a negative value for the full-width-half-maxium value of a Gaussian, but can also be used to ensure that the fit is restricted to a meaningful part of the search space. The hard limits are set by the model class, and represent the full valid range of the parameter, whereas the soft limits can be changed by the user, although they often default to the same values as the hard limits.
Setting a parameter to a value outside its soft limits will
During a fit the paramater values are bound by the soft limits, and a screen message will be displayed if an attempt to move outside this range was made. During error analysis the parameter values are allowed outside the soft limits, as long as they remain inside the hard limits.
Guessing a parameter’s value from the data¶
Sherpa models have a
method which is used to seed the paramters (or
parameter) with values and
which match the data.
The idea is to move the parameters to values appropriate
for the data, which can avoid un-needed computation by
guess routines are very basic - such as
picking the index of the largest value in the data for
the peak location - and do not always account for the
full complexity of the model expression, so care should
be taken when using this functionality.
The arguments depend on the model type, since both the
independent and dependent axes may be used, but the
to_guess() method of
a data object will return the correct data (assuming the
dimensionality and type match):
Note that the soft limits can be changed, as in this example which ensures the position of the gaussian falls within the grid of points (since this is the common situation; if the source is meant to lie outside the data range then the limits will need to be increased manually):
>>> yg, xg = np.mgrid[4000:4050:10, 3000:3070:10] >>> r2 = (xg - 3024.2)**2 + (yg - 4011.7)**2 >>> zg = 2400 * np.exp(-r2 / 1978.2) >>> d2d = Data2D('example', xg.flatten(), yg.flatten(), zg.flatten(), shape=zg.shape) >>> mdl = Gauss2D('mdl') >>> print(mdl) mdl Param Type Value Min Max Units ----- ---- ----- --- --- ----- mdl.fwhm thawed 10 1.17549e-38 3.40282e+38 mdl.xpos thawed 0 -3.40282e+38 3.40282e+38 mdl.ypos thawed 0 -3.40282e+38 3.40282e+38 mdl.ellip frozen 0 0 0.999 mdl.theta frozen 0 -6.28319 6.28319 radians mdl.ampl thawed 1 -3.40282e+38 3.40282e+38 >>> mdl.guess(*d2d.to_guess()) >>> print(mdl) mdl Param Type Value Min Max Units ----- ---- ----- --- --- ----- mdl.fwhm thawed 10 1.17549e-38 3.40282e+38 mdl.xpos thawed 3020 3000 3060 mdl.ypos thawed 4010 4000 4040 mdl.ellip frozen 0 0 0.999 mdl.theta frozen 0 -6.28319 6.28319 radians mdl.ampl thawed 2375.22 2.37522 2.37522e+06
Freezing and Thawing parameters¶
Not all model parameters should be varied during a fit: perhaps
the data quality is not sufficient to constrain all the parameters,
it is already known, the parameter is highly correlated with
another, or perhaps the parameter value controls a behavior of the
model that should not vary during a fit (such as the interpolation
scheme to use). The
attribute controls whether a fit
should vary that parameter or not; it can be changed directly,
as shown below:
>>> h.fwhm.frozen False >>> h.fwhm.frozen = True
>>> h.fwhm.thaw() >>> h.fwhm.frozen False
There are times when a model parameter should never be varied
during a fit. In this case the
attribute will be set to
True (this particular
parameter is read-only).
Resetting parameter values¶
method of a parameter will change the parameter settings (which
includes the status of the thawed flag and allowed ranges,
as well as the value) to the values they had the last time
the parameter was explicitly set. That is, it does not restore
the initial values used when the model was created, but the
last values the user set.
- explicitly setting parameter values (or using the default values)
- fit the data
- call reset
- change one or more parameters
Inspecting models and parameters¶
Models, whether a single component or composite, contain a
pars attribute which is a tuple of all the parameters
for that model. This can be used to programatically query
or change the parameter values.
There are several attributes that return arrays of values
for the thawed parameters of the model expression: the most
which gives the current values.
Composite models can be queried to find the individual
components using the
parts attribute, which contains
a tuple of the components (these components can themselves
be composite objects).