load_user_model

Context: modeling

Synopsis

Create a user-defined model.

Syntax

load_user_model(func, modelname, filename=None, *args, **kwargs)

Description

Assign a name to a function; this name can then be used as any other name of a model component, either in a source expression - such as with `set_model` - or to change a parameter value. The `add_user_pars` function should be called after `load_user_model` to set up the parameter names and defaults.

Example

Create a two-parameter model of the form "y = mx + c", where the intercept is the first parameter and the slope the second, set the parameter names and default values, then use it in a source expression:

>>> def func1d(pars, x, xhi=None):
...     if xhi is not None:
...         x = (x + xhi)/2
...     return x * pars[1] + pars[0]
...
>>> load_user_model(func1d, "myfunc")
>>> add_user_pars(myfunc, ["c", "m"], [0, 1])
>>> set_source(myfunc + gauss1d.gline)

PARAMETERS

The parameters for this function are:

Parameter	Type information	Definition
func	func	The function that evaluates the model.
modelname	str	The name to use to refer to the model component.
filename	str, optional	Set this to include data from this file in the model. The file should contain two columns, and the second column is stored in the _y attribute of the model.
args		Arguments for reading in the data from `filename` , if set. See `load_table` and `load_image` for more information.
kwargs		Keyword arguments for reading in the data from `filename` , if set. See `load_table` and `load_image` for more information.

Notes

The `load_user_model` function is designed to make it easy to add a model, but the interface is not the same as the existing models (such as having to call both `load_user_model` and `add_user_pars` for each new instance). The `add_model` function is used to add a model as a Python class, which is more work to set up, but then acts the same way as the existing models.

The function used for the model depends on the dimensions of the data. For a 1D model, the signature is:

def func1d(pars, x, xhi=None):

where, if xhi is not None, then the dataset is binned and the x argument is the low edge of each bin. The pars argument is the parameter array - the names, defaults, and limits can be set with `add_user_pars` - and should not be changed. The return value is an array the same size as x.

For 2D models, the signature is:

def func2d(pars, x0, x1, x0hi=None, x1hi=None):

There is no way using this interface to indicate that the model is for 1D or 2D data.

Bugs

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