load_template_model

Context: modeling

Syntax

load_template_model(modelname, templatefile, [dstype=Data1D, sep=' ',
comment='#', method=linear_interp])

The Sherpa load_template_model function, an extension of load_table_model (see 'ahelp load_table_model'), can be used to read in a collection of template models from a directory full of template files, in order to compare a data set to all of the templates in that collection. Sherpa finds the template that best matches the data, and reports back the parameter values associated with that template.

In the simplest case, the user will have a directory containing a set of ASCII template model files, along with a single ASCII index file which lists the various templates in that directory. The index file is specified in the "templatefile" parameter of load_template_model, and the various templates are loaded into a Sherpa model instance assigned the ID specified in the "modelname" parameter.

modelname - the name for the template model
templatefile - the name of the index file (with path) which contains the list of template files
dstype (template input) - dataset type: Data1D, Data1DInt; default=Data1D
sep - string value which represents column separator in 'templatefile'
comment - string value which represents comment in 'templatefile'
method - interpolation method in sherpa.utils: linear_interp, nearest_interp, neville, neville2d; default=linear_interp

The Sherpa model library will accommodate templates of the following form:

Template(parameters, x, y) - Model Template file for set of parameters and coordinates

parameters - set of parameters, such as (temperature, density)

x - x-coordinate of templates, e.g. wavelength, energy, or time

y - y-coordinate of templates, e.g. flux, counts or intensity

The index file should contain a table with one line per template data file, with three groups of columns in the following order:

Model parameter columns, an arbitrary number of columns
The MODELFLAG column which separates the parameter list from the filenames/model arrays, and marks lines which are to be used or not: MODELFLAG = 1 - use the file; MODELFLAG = 0 - do not use the file
The FILENAME column which points to the data file for that instance.

Sherpa reads the index file in order to set up the model with the parameters specified in the first line, and the arrays from the columns given by the data file.

The Sherpa template model supports linear, nearest-neighbor, and polynomial interpolation. (Interpolation is used by the template model to match the data grid to the model grid - which must match before the fit statistics can be calculated for fitting.)

Selecting interpolation method

Importing sherpa.utils is required in order to access available interpolation methods. This can be done for a specific function:

       from sherpa.utils import  neville, nearest_interp

or by importing all functions in sherpa.utils:

      import sherpa.utils

Example 1

sherpa> load_template_model("kerr_templ", "templ_index.txt")

Load Kerr Disk model templates into Sherpa model instance "kerr_templ". Template models are loaded from a directory containing one ASCII file per template model, listed in the ASCII index file "templ_index.txt".

sherpa> !more templ_index.txt
      
#MASS MDOT  PHI  MODELFLAG FILENAME
1.E9 0.1   0.25  1         k9_bf_01_025.dat
1.E8 0.8   0.25  0         k8_bf_08_025.dat
....

sherpa> load_template_model("kerr_temp","templ_index.txt")

Example 2

sherpa> load_template_model('tbl', 'table.txt')

Load a collection of template models into the Sherpa model instance 'tbl', and fit to a source data set using the Sherpa grid-searching optimization method (see 'ahelp gridsearch'). The parameters of the template model which best matches the data are returned.

sherpa> load_ascii('source.dat', ncols=3, dstype=Data1D)
sherpa> load_template_model('tbl', 'table.txt')
sherpa> set_model(tbl)
sherpa> set_method('gridsearch')
sherpa> set_method_opt('sequence', tbl.parvals)
sherpa> fit()
Dataset               = 1
Method                = gridsearch
Statistic             = chi2gehrels
Initial fit statistic = 1.53806e+12
Final fit statistic   = 212.321 at function evaluation 106
Data points           = 7
Degrees of freedom    = 4
Probability [Q-value] = 8.41533e-45
Reduced statistic     = 53.0803
Change in statistic   = 1.53806e+12
   tbl.mass       9           
   tbl.rate       0.3         
   tbl.angle      1           
WARNING: parameter value tbl.angle is at its maximum boundary 1.0  

     
sherpa> show_model()
Model: 1
templatemodel.tbl
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   tbl.mass     thawed            9            6           10           
   tbl.rate     thawed          0.3         0.01            1           
   tbl.angle    thawed            1          0.1            1

Example 3

sherpa> from sherpa.utils import neville
sherpa> load_ascii('source.dat', ncols=3, dstype=Data1D)
sherpa> load_template_model('tbl', 'table.txt', method=neville)
sherpa> set_model('tbl+const1d.b1')
sherpa> set_method('moncar')

Import 'neville' interpolation method from 'sherpa.utils'; load a spectrum with errors from an ascii file, and templates and use neville interpolation method when fitting the spectrum with this model. A combination of a template model 'tbl' and an analytical model 'const1d' from Sherpa model library is used to fit the data. Note that in this case we use moncar (see 'ahelp moncar') instead of gridsearch (see 'ahelp gridsearch') to find the best fit.

Bugs

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