Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2013

URL: http://cxc.harvard.edu/sherpa/ahelp/load_template_model.html
Jump to: Description · Examples · Bugs · See Also


AHELP for CIAO 4.6 Sherpa v2

load_template_model

Context: modeling

Synopsis

Load a set of template models

Syntax

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

load_template_interpolator(name, interpolator method, [arguments])

Description

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 returns 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 separators in 'templatefile'
  • comment - string value which represents comments in 'templatefile', default = '#'
  • method - interpolation method for independent axis (e.g. energy, wavelength) in sherpa.utils: linear_interp, nearest_interp, neville, neville2d; default=linear_interp
  • template_interpolator_name - interpolation method for dependent axis (e.g. evaluating a template model for parameters not on the template grid); default=KNNInterpolator. Set to None to turn off the interpolation.

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 the available interpolation methods for the dependent axis. This can be done for a specific function:

       from sherpa.utils import  neville, nearest_interp 

Selecting template interpolator

The default template_interpolator_name is KNN interpolator - K-nearest neighbor algorithm, with k=2 and order=2 setting.

load_template_interpolator() can be used to change the method or arguments of the KNN interpolator.

       from sherpa.models import KNNInterpolator
       load_template_interpolator('mymethod', KNNInterpolator, k=3, order=2) 

Example 1

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

Load Kerr Disk model templates into a 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". The default interpolation method for templates parameters is used.

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
....


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', neville)
sherpa> set_model('tbl+const1d.b1')
sherpa> set_method('moncar')   

Import the 'neville' interpolation method from 'sherpa.utils' to apply to the dependent data axis; load a spectrum with errors from an ASCII file and model templates, then use the default 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.

Example 4

sherpa> load_template_model('tbl', 'table.txt', template_interpolator_name = None)
sherpa> set_model('tbl')
sherpa> set_method('gridsearch')
sherpa> show_model()
Model: 1
templatemodel.tbl
   Param        Type          Value          Min          Max      Units
   -----        ----          -----          ---          ---      -----
   tbl.mass     thawed            6            6           10
   tbl.rate     thawed          0.1         0.01            1
   tbl.angle    thawed          0.1          0.1            1

Here, load_template_model will load templates and turn-off interpolation of template model values for parameters not on the original grid. Use of gridsearch method is required in this case. The fit will give the best template using discrete parameters of the template model.

Bugs

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

See Also

data
dataspace1d, dataspace2d, fake, get_bkg_plot, load_arf, load_arrays, load_ascii, load_bkg, load_bkg_arf, load_bkg_rmf, load_data, load_grouping, load_image, load_multi_arfs, load_multi_rmfs, load_pha, load_quality, load_rmf, load_staterror, load_syserror, load_table, pack_image, pack_pha, pack_table, unpack_arf, unpack_arrays, unpack_ascii, unpack_bkg, unpack_data, unpack_image, unpack_pha, unpack_rmf, unpack_table
filtering
load_filter
info
get_default_id, list_bkg_ids, list_data_ids, list_model_ids, show_bkg_model, show_bkg_source
modeling
add_model, add_user_pars, clean, create_model_component, delete_bkg_model, delete_model, delete_model_component, get_model, get_model_autoassign_func, get_model_component, get_model_component_image, get_model_component_plot, get_model_plot, get_num_par, get_order_plot, get_par, get_pileup_model, get_source, get_source_component_image, get_source_component_plot, image_model, image_model_component, image_source, image_source_component, integrate, integrate1d, link, load_table_model, load_user_model, normal_sample, reset, save_model, save_source, set_bkg_model, set_full_model, set_model_autoassign_func, set_pileup_model, set_source, set_xsabund, set_xscosmo, set_xsxsect, set_xsxset, t_sample, uniform_sample
plotting
get_lrt_plot, get_lrt_results, get_pvalue_plot, get_pvalue_results, plot_cdf, plot_lrt, plot_model, plot_model_component, plot_pdf, plot_pvalue, plot_scatter, plot_source, plot_source_component, plot_trace
psfs
delete_psf, load_conv
saving
save_arrays, save_data, save_delchi, save_error, save_filter, save_grouping, save_image, save_pha, save_quality, save_resid, save_staterror, save_syserror, save_table
statistics
load_user_stat
utilities
calc_chisqr, calc_energy_flux, calc_model_sum, calc_photon_flux, calc_source_sum, calc_stat, eqwidth
visualization
contour_model, contour_ratio, contour_resid, get_ratio, get_resid

Last modified: December 2013
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxcweb@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2014. All rights reserved.