normal_sample

Context: modeling

Synopsis

Sample the fit statistic by taking the parameter values from a normal distribution.

Syntax

normal_sample(num: int = 1, scale: float = 1, correlate: bool = True,
id: int | str | None = None, otherids: Sequence[int | str] = (),
numcores: int | None = None, clip: Literal['none'] | Literal['hard'] |
Literal['soft'] = 'none')

Returns: np.ndarray

Description

For each iteration (sample), change the thawed parameters by drawing values from a uni- or multi-variate normal (Gaussian) distribution, and calculate the fit statistic.

Examples

Example 1

The model fit to the default data set has three free parameters. The median value of the statistic calculated by `normal_sample` is returned:

>>> ans = normal_sample(num=10000)
>>> ans.shape
(1000, 5)
>>> np.median(ans[:,0])
119.82959326927781

Example 2

Sample the thawed parameters using the covariance matrix, to account for correlations between the parameters:

>>> ans = normal_sample(num=1000, correlate=True)

Example 3

Ensure that the sampling is repeatable by fixing the random number generator (RNG), and then plot the statistic value (y axis) against the first thawed parmeter (x axis):

>>> set_rng(np.random.default_rng(2462357))
>>> res = normal_sample(id=1000)
>>> plot_scatter(res[:, 1], res[:, 0], ylabel="scatter")

Example 4

Compare the PDF of the first thawed parameter when using the calculated errors versus twice them:

>>> res1 = normal_sample(id=1000)
>>> res2 = normal_sample(id=1000, scale=2)
>>> plot_pdf(res1[:, 1], bins=20)
>>> plot_pdf(res2[:, 1], bins=20, overplot=True)

Example 5

Sample the model fits for datasets 1, 2, and 3:

>>> res = normal_sample(num=1000, correlate=True, id=1, otherids=(2, 3))

PARAMETERS

The parameters for this function are:

Parameter	Type information	Definition
num	int, optional	The number of samples to use (default is 1).
scale	number, optional	Scale factor applied to the sigma values from the fit before sampling the normal distribution.
correlate	bool, optional	Should a multi-variate normal be used, with parameters set by the covariance matrix ( True ) or should a uni-variate normal be used ( False )?
id	int, str, or None, optional	The data set that provides the data. If not given then all data sets with an associated model are used simultaneously.
otherids	sequence of int or str, optional	Other data sets to use in the calculation.
numcores	optional	The number of CPU cores to use. The default is to use all the cores on the machine.
clip	{'hard', 'soft', 'none'}, optional	What clipping strategy should be applied to the sampled parameters. The default ('none') applies no clipping, 'hard' uses the hard parameter limits, and 'soft' the soft limits.

Return value

The return value from this function is:

A NumPy array table with the first column representing the statistic, the later columns the parameters used, and the last column indicating whether any parameter in the row was clipped. The number of rows is given by the num argument.

Notes

It is expected that the model has already been fit to the data.

All thawed model parameters are sampled from the Gaussian distribution. The mean is set as the current parameter values. The variance is calculated from the covariance matrix of the fit multiplied by scale * scale. When correlate is False the diagonal of the matrix is used, so the parameters are uncorrelated. When correlate is True the full matrix is used, allowing for correlations between the parameters.

Changes in CIAO

Changed in CIAO 4.18

The sigma parameter has been renamed to scale, and the code has been updated so that changing it will change the sampled values. The random state returned by get_rng is now used for the sampling. The clip parameter has been added, and the return array now ends in a column indicating whether any parameter in the row was clipped.

Bugs

See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.