normal_sample

sherpa.ui.normal_sample(num: int = 1, scale: float = 1, correlate: bool = True, id: IdType | None = None, otherids: IdTypes = (), numcores: int | None = None, clip: ClipValue = 'none') → np.ndarray

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

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.

Changed in version 4.18.0: 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.

Parameters:

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.

Returns:

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.

Return type:

samples

See also

fit: Fit a model to one or more data sets.
set_model: Set the source model expression for a data set.
set_stat: Set the statistical method.
t_sample: Sample from the Student’s t-distribution.
uniform_sample: Sample from a uniform distribution.

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.

Examples

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

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

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

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")

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)

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

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