Reference for fitting functions
Doppler_velocity
Synopsis
calculates a Doppler velocity shift from a wavelength and the rest wavelength
Usage
Double_Type v = Doppler_velocity(Double_Type lambda, Double_Type lambda0);
Description
v = (lambda-lambda0)/lambda_0 * c; %
speed of light c = 299792
km/s
See also: get_line_velocity
List_par
Synopsis
list current fit function and parameters
Usage
List_par ([arg])
or
```c
List_par ( String_Type[] pattern )
##### Description
The optional argument is used to redirect the output. If arg
is omitted, the output goes to stdout. If arg is of type
Ref_Type, it the output string is stored in the referenced
variable. If arg is a file name, the output is stored in that
file. If arg is a file pointer (File_Type) the output is
written to the corresponding file.
If the given argument is a String pattern, only parameter matching
this pattern are listed!
The parameter listing looks like this:
gauss(1) + poly(1)
idx param tie-to freeze value min max
1 gauss(1).area 0 0 103.6 0 0
2 gauss(1).center 0 0 12.1 10 13
3 gauss(1).sigma 0 0 0.022 0.001 0.1
4 poly(1).a0 0 0 1.2e4 0 0
5 poly(1).a1 0 1 0 0 0
6 poly(1).a2 0 1 0 0 0
The first line defines the form of the fit-function. The
parameter index idx may be used to refer to individual fit
parameters (see set_par). freeze = 1 (0) indicates that the
corresponding parameter value is frozen (variable). If two
parameter values are tied together, the connection is indicated
in the tie-to column. For example, if parameter 1 has tie-to =
5, that means the value of parameter 1 is tied to the value of
parameter 5; if parameter 5 changes, parameter 1 will follow
the change exactly. If min=max=0, the corresponding parameter
value is unconstrained.
In input parameter files (see load_par), lines beginning with a
'#' are mostly ignored and may be used to include comments.
Exceptions to this rule are "special" comment lines which are
used to support additional functionality such as, e.g. writing
some parameters as functions of other parameters (see
set_par_fun). Note that, aside from these special cases,
comment lines are not loaded by load_par and will not be
preserved if file is later overwritten by save_par.
__See also__: list_free, edit_par, set_par, get_par, save_par, set_par_fun
#### PG_function
##### Synopsis
sets fitting statistic for poisson source counts and already subtracted gaussian background
##### Usage
```c
set_fit_statistic("PG");
Description
This fitting statistic can be used when dealing with low count spectra that have already been subtracted by the instrumental background. Cash statistics are not suited for this task since purely poisson distri- buted counts are assumed in that case. This version of the fitting statistic has been derived from the profile likelihood statistic for zero back- ground counts from:
https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XSappendixStatistics.html
The statistic should be used when fitting low count spectra of the Swift/BAT instrument. IMPORTANT: the statistic can only be used when fitting count rate spectra since the exposure times for each channel have dummy values of 1s.
See also: set_fit_statistic
array_fit_gauss
Synopsis
performs a gaussian fit on given x- or xy-data
Usage
Struct_Type array_fit_gauss(x [,y] [,dy] [,c] [,s] [,a] [,o]);
Qualifiers
- frz: boolean array determining which parameters (c,s,a,o) are frozen
- keep: keeps the data and fit function (be careful, needs to be deleted for the next fit
- plot: plot the given data and oplot the fit
- oplot: only oplot the fit
Description
Tries to fit the given data by a gaussian and an offset. If the y-data is
omitted, the given x-data is interpreted as y-data. The x-values are then
generated as indices of the y-data.
The uncertainties of the y-data can be passed to the fit algorithm by the
dy' parameter. If not given the errors are calculated assuming Poisson statistics. The four remaining parameters are the starting values: c - center position s - sigma a - area o - offset in y-direction They may also be given by an array as parameter
c' in the order shown
above. The same order is used for the freeze status qualifier `frz'.
Performing the fit is done with the actual choosen fit method. The result
is returned as a structure of the form
Struct_Type { center, sigma, area, offset, chisqr }
where chisqr is the reduced chi-square value of the best fit.
backshift
Synopsis
determines the shift of an array to a reference one
Usage
Struct_Type backshift(Double_Type[] in, Double_Type[] ref[, Double_Type[] error]);
or Double_Type[] backshift(Double_Type[] in, Double_Type[] ref[, Double_Type[] error]; retarr);
Qualifiers
retarr - function returns the unshifted array instead of the structure defined below
Description
The function 'shift' rotates an array by a given number of indices. The function described here tries to get this number back: an input array 'in' is assumed to be a shifted version of the reference array 'ref'. The shift is then determined by using the fit-function 'unshift', also taking optional 'error's into acocunt. The returned structure, if the 'retarr'-qualifier is not set, is defined as follows: shift - shift in number of indices shift_conf - its [lower, upper] confidence limits relative - relative shift between 0 and 1 relative_conf - its [lower, upper] confidence limits redChiSqr - reduced chi-square value of the fit
See also: unshift, shift_intpol, shift
bknpowerlaw_xyfit
Synopsis
linear xy fit function to be used with xyfit_fun
Usage
xyfit_fun ("bknpowerlaw");
Description
This function is not meant to be called directly!
Calling xyfit_fun ("bknpowerlaw");
sets up a powerlaw fit
function for xy-data. It has the form y = norm*x^{-index}
See also: xyfit_fun, define_xydata, plot_xyfit, linear_regression
cl_save
Synopsis
computs single-parameter confidence lmits for several parameters, using multiple cores on one machine
Usage
Struct_Type results = cl_save([Integer_Type pars[]]);
Qualifiers
- strict[=1]: restarts the calculation if a new best fit was found
- saveoutput[=1]
- basefilename[=<date_time>]
- level[=1]: specifies the confidence level. Values of 0, 1, or 2 indicate 68%, 90%, or 99% confidence levels respectively. By default, 90% confidence limits are computed.
- tolerance: convergence criterion for the calculation of the confidence limits (see help for the conf command). Default: 1e-3
- cleanup: will remove all temporary files ending in *.[0-9][0-9]* from the basefilename directory
Description
This function is a direct copy of fit_pars, however, using
"conf_loop" to allow multi-core support on one machine. The
number of slaves is determined by the global variable
Isis_Slaves.num_slaves.
The return value results = struct { index, name, value, min, max, conf_min, conf_max, buf_below, buf_above, tex }
is a table with the following information for each parameter:
min
and max
are the minimum/maximum values allowed.
conf_min
and conf_max
are the confidence limits.
buf_below
(buf_above
) is the fraction of the allowed range [min:max]
which separates the lower (upper) confidence limit from min
(max
).
If one of these buffers is 0, your confidence interval has bounced.
See also: fit_pars, pvm_fit_pars, conf
compare_par
Synopsis
compares models saved in parameter files
Usage
compare_par([String_Type pattern]);
or
Struct_Type info = compare_par([String_Type pattern]; get_list);
Qualifiers
- fit_fun: include fit-function
- fit_fun=fitfun: only include models using the fit-function
fitfun
- get_list: the information is not printed, but returned
- load_best: load the best fit parameters
- verbose
Description
It is assumed that the corresponding data sets are already initialized.
See also: load_par, eval_counts
contour_trq
Synopsis
creates and (with qualifier trq) sends bins^2 jobs to torque (at Remeis cluster) and calculates chi_2 values for each point for chosen 2 parameters.
Usage
contour_trq(String_Type inputPar1, inputPar2, Int_Type bins,
Double_Type lowLimPar1, upLimPar1,lowLimPar2, upLimPar2,
String_Type startUpFile [, parFile], outDir, time);
Qualifiers
- trq: Sends the jobs to Remeis torque
Description
-
inputPar1
input parameter 1 written as in .par file -
inputPar2
input parameter 2 written as in .par file -
bins
number of chosen bins -
lowLimPar1
lower parameter 1 value -
upLimPar1
upper parameter 1 value -
lowLimPar2
lower parameter 2 value -
upLimPar2
upper parameter 2 value -
startUpFile
upload file (with data, binning, noticing etc.) -
parFile
best fit parameter file name (optional) -
outDir
output directory for torque files and calculated output files -
time
torque wall time
In case where values for all bins^2 points are not calculated (for example when the torque walltime is shorter than needed), one can run function missing_contour_trq in order to get all bins^2 values.
To plot the result use the function plot_contour_trq.
EXAMPLE
contour_trq(relconv(1).Incl
,reflionx(1).Xi
,32,25,35,1000,4000,"data.sl",
"results/bestFit.par","outputInclXi","02:00:00";trq);
will calculate 32 by 32 values for two parameters and write the output files to "outputInclXi" subdirectory. It will do that by sending the 32x32 jobs to Remeis torque via qualifier "trq", and giving it a walltime of 02:00:00 hours.
See also: missing_contour_trq, plot_contour_trq
define_counts_2d
Synopsis
defines a pseudo-spectrum from two-dimensional data
Usage
Integer_Type define_counts_2d(value[, err][, X, Y])
Description
value
and err
are 2d arrays of Double_Type.
ISIS usually deals with 1d spectra. For fitting 2d data, define_counts_2d
can be used to define a pseudo 1d spectrum by reshaping arrays,
to which ISIS' internal fit routines can be applied.
User defined fit-functions should not use the bin_lo, bin_hi arguments,
but the actual data-grid which can be set / obtained with set
/get_2d_data_grid
,
if the user doesn't prefer to take care of the data grid on his own.
If the optional 1d Double_Type arrays X
and Y
are specified,
set_2d_data_grid
is already called by define_counts_2d
.
See also: gauss_2d
define_xydata
Synopsis
defines an xy-dataset to be modeled with xyfit_fun
Usage
Integer_Type data_id = define_xydata ( x[], y[] [, yerr[]] );
or
```c
Integer_Type data_id = define_xydata ( x[], xerr[], y[], yerr[] );
##### Qualifiers
* N[=1000]: number of curve points, when xerr is considered
* x_mdl [default: array covering <code>x</code> with <code>N</code> steps]:
(initial) x-values of the model, when <code>xerr</code> is considered
* y_mdl [default: array covering <code>y</code> with <code>N</code> steps]:
(initial) y-values of the model, when <code>xerr</code> is considered
##### Description
This function creates a dummy spectral dataset for ISIS and stores
the xy-dataset in its metadata, which are only considered when
fitting with a dedicated xy-fit-function defined by <code>xyfit_fun</code>.
Fitting via <code>fit_counts</code> will minimize the sum of squared residuals,
see <code>xyfit_residuals</code>.
If no <code>xerr</code> is specified, the xy-fit-function will only be evaluated
at the x-values of the data. (yerr defaults to 1, if not specified.)
If <code>xerr</code> is given as well, a curve is constructed in order to compute
the residuals of the data points. The xy-fit-function may produce a
(reasonably smooth!) graph (x, y(x)) or parameterized curve (x(t), y(t)).
It operates on the model points and possibly (constant) parameters
defined by <code>set_xy_qualifier</code>. Model points for an xy-dataset
are initially defined by the <code>N</code> or <code>x_mdl</code> and <code>y_mdl</code> qualifiers.
If xerr, yerr are lists with two array entries, than the first is
interpreted as lower and second as upper uncertainty
##### Example
N = 150; (x, y) = ellipse(8, 5, 0.2\*PI, grand(N)\*1.5);
x += grand(N)+4; y += grand(N)+1;
id = define_xydata (x, ones(N), y, ones(N));
xyfit_fun("ellipse_xy");
set_xyfit_qualifier(id; curve_parameter=[0:2\*PI:#3000]);
()=fit_counts;
set_par("ellipse_xy(1).pos_angle", 30); ()=fit_counts; % help with angles...
plot_xyfit(id);
% fit_interactive(&plot_xyfit);
__See also__: xyfit_fun, set_xyfit_qualifier, xyfit_residuals, plot_xyfit
#### detconst_init
##### Synopsis
initializes the "dectonst" fit-function
##### Usage
```c
detconst_init(String_Type[] detectors);
or detconst_init(List_Type detectors);
Description
Before any detector calibration constants can be fitted by using the 'detconst' fit-function, this function has to be called. It initalizes and defines the fit-function based on the given detector names (and if statements).
In general, the detector names are given as an array of strings. Each entry has to represent the 'instrument' field defined in the FITS-header of any used dataset. Internally, the 'detconst' matches this field against the given names and returns the corresponding parameter.
If the instrument field is not enough to determine the parameter (e.g., if multiple instruments are build within the same detector), a list of strings can be provided instead of an array. If a list item itself is an array with exactly two strings, the first one is the detector name and the second specifies the if statement to be evaluated to determine the corresponding parameter. Within the if statement, information about the dataset can be accessed via the 'info' struct (see get_data_info).
If the 'debug' qualifier is given, the S-Lang code of the fit-function is printed out as well.
Example
% RXTE consisted of two instruments: PCA and HEXTE detconst_init(["PCA", "HEXTE"]);
% SUZAKU consists of six instruments: XIS0-3, PIN, % and GSO. PIN and GSO are, however, within one detector % called HXD (as in the FITS-header). Thus, identify % these two instruments via the PHA-filename detconst_init({"XIS0", "XIS1", "XIS2", "XIS3", ["PIN", "is_substr(info.file, "hxd_pin")"], ["GSO", "is_substr(info.file, "hxd_gso")"] }; debug);
See also: detconst, get_data_info, add_slang_function
dont_use_line
Synopsis
sets the EW / amplitude of a line in the lines-model to zero
Usage
dont_use_line([id,] line);
Description
If id
is not specified, id=1
is used.
line
is the name in the lines-model, appearing as parameters
line_lam
, line_EW
, line_FWHM
and line_A
.
See also: lines
eqwFit_init
Synopsis
initializes the fit function 'eqwFit'
Usage
eqwFit_init(Integer_Type N);
Description
Defines and initializes the equivalent width fit function 'eqwFit' to handle 'N' number of features. Note, that the number has to be set before one can use the fit function and that it can only be set once!
See also: eqwFit, eqw
eval_xyfun
Synopsis
evaluate current xy-function for points x [y]
Usage
(Double_Type[] x, Double_Type[] y) = eval_xyfun(Double_Type[] x [, Double_Type[] y]);
Qualifiers
- id[=Isis_Active_Dataset]: uses parameter and model for dataset #id
Description
Evaluate the current xy-model on the points (x,y)
See also: define_xydata, xyfit_fun
eval_xyfun2
Synopsis
evaluate valid xyfit_fun string with parameters
Usage
(Double_Type[] x, Double_Type[] y) = eval_xyfun2 (handle, x[ , y, par])
Qualifiers
- qualifier: pass qualifier structure to function
Description
Evaluates function handle
(either the name of a xy-function or reference)
on the points x (and y) with parameters par
.
See also: eval_xyfun, define_xydata, xyfit_fun
exponential_xyfit
Synopsis
linear xy fit function to be used with xyfit_fun
Usage
xyfit_fun ("exponential");
Description
This function is not meant to be called directly!
Calling xyfit_fun ("exponential");
sets up a powerlaw fit
function for xy-data. It has the form y = norm*x^{-index}
See also: xyfit_fun, define_xydata, plot_xyfit, linear_regression
fit_brute_force
Synopsis
Performs a fit by stepping the given parameters and does a usual fit for the remaining ones
Usage
Struct_Type fit_brute_force(Integer_Type[] par [, Double_Type[] stepsize])
or Struct_Type fit_brute_force(String_Type[] par [, Double_Type[] stepsize])
Qualifiers
- nofit: instead of fitting the remaining parameters the model is just evaluated
- nomap: the chi-square map will not be created
- chatty: boolean value to show the remaining time (default=1)
Description
For the given parameters the best fit of the actual model
is found by going through the complete parameter range.
The parameters can be passed as an array containing their
indices or names. The stepsize for each parameter can
either be given by the second stepsize' parameter or the intrinsic stepsizes are used, which can be set using a qualifier of the
set_par' function. The latter can also
be used to determine the minimum and maximum value of each
parameter. While the given parameters are stepped the other
parameters of the model are fitted by the actual fitting
method, that means the function fit_counts' is called. If the qualifier
nofit' is given eval_counts' is used instead, evaluating the model without performing a chi- square minimization. This function is very similar to the
get_confmap' function.
But this function steps n given parameters in a very small
grid. In contrast it is possible to perform a fit for all
parameters of the model. However BE CAREFUL as the runtime
rises exponentially with the number of parameters!! For
this reason the function is chatty by default to show the
estimated remaining time during the fit.
The returned structure contains an array bestpar' of the best values found for each given parameter, the corres- ponding reduced chi-square value
bestchi' and a structure
chimap', which holds the chi-square values for each tested parameter combination up to two given parameters. Because this map may be very big its creation can be suppressed by the
nomap' qualifier. In the structure the one or two
dimensional array (depending on the number of parameters)
chisqr' contains the reduced chi-square values. In case of two dimensions the first one specifies the second parameter to directly pass it to image function like
plot_image'. The
corresponding parameter values are stored in the x-field for
the first parameters and y-field for the second one.
See also: get_confmap, fit_counts, eval_counts, set_par, plot_image
fit_interactive
Synopsis
Interactivly change parameters and evaluate the model
Usage
fit_interactive(Ref_Type plotfunction[, Any_Type arg0, arg1, ...]
Description
The Ref_Type 'plotfunction' is a reference to the plot function, which has to be used (see example below). Any additional arguments are passed to this function as well as given qualifiers. The user may changes the parameters interactivly by the following keys: LEFT/RIGHT: increase/decrease value of active parameter by one stepsize UP/DOWN : change active parameter PGUP/PGDN : increase/decrease stepsize by one order t : freeze/thaw active parameter r : change range of active parameter v : set value of active parameter z : set the internal step size used by fit_counts m : modify fit function f : perform a fit by running fit_counts s : show/hide frozen parameter p/P : load/save parameters in 'parfile' q : quit interactive mode Every time the value of a parameter is changed, the model is evaluated automatically and the given plot function is called. Actual parameter values and the reduced chi- square are printed out to the plot window. The active parameter is shown in red, thawed ones in black and frozen ones in gray. If the parameter turns blue, one of the borders of the range is reached.
Qualifiers
parfile - filename, which is used to save or load the fit parameters using 'save_par' or 'load_par', respectively. The user will be asked for if 'parfile' is not set.
plotscript - filename, used to load in a user-defined plotting script. If not set, function reverts to Ref_Type 'plotfunction'.
Example
variable id = load_data("example.pha"); fit_fun("cutoffpl"); fit_interactive(&plot_data, id; res=1);
The appearing plot window then is internaly called by plot_data(id; res=1);
See also: eval_counts, open_plot, keyinput
fit_line
Synopsis
activates a line in the lines model and fits its parameters
Usage
fit_line([id,] line);
See also: lines
fit_pars
Synopsis
computes single-parameter confidence limits for several parameters
Usage
Struct_Type results = fit_pars([Integer_Type pars[]]);
Qualifiers
- strict[=1]: restarts the calculation if a new best fit was found
- saveoutput[=1]
- basefilename[=<date_time>]
- level[=1]: specifies the confidence level. Values of 0, 1, or 2 indicate 68%, 90%, or 99% confidence levels respectively. By default, 90% confidence limits are computed.
- chi2diff: if given, fit_pars invokes fconf instead of conf with the value given to caluculate confidence in chi2 range. Defaults to 1.0.
- tolerance: convergence criterion for the calculation of the confidence limits (see help for the conf command). Default: 1e-3
Description
The return value results = struct { index, name, value, min, max, conf_min, conf_max, buf_below, buf_above, tex }
is a table with the following information for each parameter:
min
and max
are the minimum/maximum values allowed.
conf_min
and conf_max
are the confidence limits.
buf_below
(buf_above
) is the fraction of the allowed range [min:max]
which separates the lower (upper) confidence limit from min
(max
).
If one of these buffers is 0, your confidence interval has bounced.
See also: pvm_fit_pars, conf, fconf
fit_pars_read_stdoutlogfile
Synopsis
reads chi2-improvements from a stdout-logfile created by (pvm_)fit_pars
Usage
(t, chi2) = fit_pars_read_stdoutlogfile(String_Type filename);
Description
t
is the number of seconds since the start of (pvm_
)fit_pars
.
See also: fit_pars, pvm_fit_pars
fit_steppar
Synopsis
tries to obtain better fits for a stepped parameter
Usage
Struct_Type result = fit_steppar(String_Type parname, parfiles[]);
Qualifiers
- method: "optimize", "interpol_guess", or "eval_all"
- extrapol: allows for extrapolation as well
- fit [=1]
- min_improvement
- plot
- verbose [=1]
Description
fitfun_cache_enabled
Synopsis
returns whether the ISISscripts caching extension for fit-functions is enabled (1) or disabled (0).
Usage
Integer_Type fitfun_cache_enabled();
See also: fitfun_cache, fitfun_enable_cache, fitfun_disable_cache
fitfun_disable_cache
Synopsis
disables the ISISscripts caching extension
Usage
fitfun_disable_cache();
See also: fitfun_cache, fitfun_enable_cache, fitfun_cache_enabled
fitfun_enable_cache
Synopsis
enables the ISISscripts caching extension
Usage
fitfun_enable_cache();
See also: fitfun_cache, fitfun_disable_cache, fitfun_cache_enabled
fitfun_get_cache
Synopsis
return the cache for the current dataset and the given fit-function
Usage
Struct_Type fitfun_get_cache([String_Type fit-function_name]);
Description
The cached slang structure for the currently evaluated fit-function and the current dataset (Isis_Active_Dataset) is returned. In case caching is disabled (by 'fitfun_disable_cache') a new structure as defined using 'fitfun_init_cache' is returned.
The optional and only parameter specifies the name of a fit-function, which stack is to be returned. This allows to share and access the cache between different fit-functions. If this particular fit-function has not been evaluated yet (or is not used in the current model) NULL is returned.
Note: if the number of bins of the data grid of the current dataset changes, the cache is initialized again with the structure defined by 'fitfun_init_cache'. This might be necessary as soon as, e.g., the fit-function is 'eval_fun'ed on a user-grid.
Example
% retrieve the cache from another fit-function inside a fit-function define mybetter_fit(lo, hi, pars) { ... variable ocache = fitfun_get_cache("myfun"); if (ocache != NULL) { ocache.tempresult ... ... } ... }
% investigate the temporary results after a fit from the command line isis> Isis_Active_Dataset = 2; % get the cache for this dataset isis> cache = fitfun_get_cache("myfun"); isis> print(cache.tempresult);
See also: fitfun_cache, fitfun_init_cache
fitfun_init_cache
Synopsis
Usage
fitfun_init_cache(String_Type fit-function_name, Ref_Type fit-function_handle, Struct_Type init_struct);
Description
Defines the structure, which is used to initialize the cache of the the given fit-function. This should be called after a user-defined fit-function, which uses caching, has been added to the list of available models.
The first parameter 'fit-function_name' specifies the name of the fit-function, 'fit-function_handle' is the reference to the actual function calculating the model, and 'init_struct' is the structure the cache will be initialized with for each dataset.
Example
% Define a new fit-function, add it to the list of available % models, and initialize its cache with a structure with empty % fields. Inside the fit-function 'myfun' the value of lastpars % can be checked on NULL or changed parameters in order to % trigger an expensive calculation.
define myfun_fit(lo, hi, par) { ... }
add_slang_function("myfun", ["par1", "par2", ...]);
fitfun_init_cache( "myfun", &myfun_fit, struct { tempresult, lastpars = NULL } );
See also: fitfun_cache, fitfun_get_cache
fits_list_fit_pars
Synopsis
Lists parameter values and confidence intervals for a file saved with fits_save_fit.
Usage
fits_list_fit_pars(String_Type fit.fits)
Description
When loading a previously saved fit with fits_load_fit, list_par
does not print the borders of the parameter confidence intervals saved
in appropriate fields of fit.fits.
Instead the parameter limits are printed.
As a work-around use this function to get a similar list as for
list_par
including the confidence intervals if already determined.
Example
isis> fits_list_fit_pars("fit.fits");
See also: fits_save_fit,fits_load_fit
freeParameters
Synopsis
find all free parameters of the current fit-function
Usage
Integer_Type[] freeParameters()
Description
Free parameters are not frozen, tied to another one, or derived as functions of other parameters.
See also: thawedParameters
get_column_density_from_line
Synopsis
Usage
Double_Type N = get_column_density_from_line([Integer_Type i,] String_Type line);
Description
N = mc^2/[pi e^2] * W_lambda / [f_lu * lambda^2];
= 1.13e17/cm^2 * (W_lambda/mA) / [f_lu * (lambda/A)^2]
% f_lu = mc / [8 pi^2 e^2] * lambda^2 * g_u / g_l * A_ul
% = 1.4992e-16 * (lambda/A)^2 * g_u / g_l * (A_ul/s^{-1})
get_confmap
Synopsis
computes a 2d confidence map and possibly stores the fit-parameters in a file
Usage
conf_map = get_confmap(par1, min1, max1[, n1], par2, min2, max2[, n2]);
Qualifiers
- save [=
"confmap"
]: save all parameters tosave
+".fits" - fail [=
NULL
]: failure recovery hook, seeconf_map_counts
- mask [=
NULL
]: region mask out hook, seeconf_map_counts
Description
(All qualifiers are also passed to the conf_map_counts
function.)
par1
is stepped from min1
to max1
in n1
(default=8) steps;
par2
is stepped from min2
to max2
in n2
(default=8) steps.
A save hook is used to write each step's parameter values and chi^2 to files
named sav+"*.dat
, which are finally collected by get_confmap_collect_results
and converted to a table.
Parameters from this table can be set with set_par_from_confmap_table
.
See also: conf_grid, conf_map_counts, load_conf, plot_conf, get_confmap_collect_results, set_par_from_confmap_table
get_confmap_collect_results
Synopsis
collect results produced by get_confmap
Usage
get_confmap_collect_results(String_Type save_basefilename);
Description
get_confmap_collect_results
is used internally by get_confmap
,
but it can also collect the results of an unfinsihed calculation.
Qualifiers
- remove_files: if set,
save_basefilename+"_*.dat"
files will be deleted when read - use_file_from_save_conf: if set, results are appended to
save_basefilename+".fits"
See also: get_confmap
get_lambda_parameters_of_all_lines
get_lambda_parameters_of_lines
get_lambda_parameters_of_lines_from_one_ion
get_line_labels
Qualifiers
- label_Ly_He [=1]
- print_list
See also: lines
get_line_velocity
Synopsis
calculates the velocity shift in a line of the lines-model
Usage
Double_Type v = get_line_velocity([Integer_Type i,] String_Type line);
Description
lambda = get_par("lines(i).line_lam");
lambda0 = mean( get_line_lambdas(line) );
v = (lambda-lambda0)/lambda_0 * c; %
speed of light c = 299792
km/s
See also: Doppler_velocity
get_params_from_file
Synopsis
retrieves fit-parameter information from a file
Usage
Struct_Type params[] = get_params_from_file(String_Type params);
See also: load_par, get_params
get_params_table_from_files
Synopsis
retrieves fit-parameter information from files
Usage
Struct_Type get_params_table_from_files(String_Type filenames[]);
Qualifiers
- free: only include free parameters
- par: array of parameters to be included
- filename: include filenames into the structure
- nominmax: do not include min max values
- eval_counts: evaluates the model and returns the statistic as well. It is assumed that the appropriate data is already loaded.
- verbose: show name of parameter files while being processed
Description
filename
may be a globbing expression.
It is assumed that all parameter files rely on the same model
and that this model can be loaded with the current data set.
get_simple_gpile_info
Synopsis
retrieves pileup information within a simple_gpile2 model
Usage
Struct_Type info = get_simple_gpile_info(Integer_Type id);
get_unpiled_fit_fun
Synopsis
return the currently defined fit function without simple_gpile*
Usage
String_Type get_unpiled_fit_fun()
Description
simple_gpile*(Isis_Active_Dataset,
is replaced by (
.
See also: get_fit_fun
get_xydata
Synopsis
provides the xy-data, which has been defined with define_xydata
Usage
(x[], y[], yerr[]) = get_xydata(Integer_Type data_id);
or
```c
(x[], xerr[], y[], yerr[]) = get_xydata(Integer_Type data_id);
##### Description
This function returns the xy-data of dataset # <code>data_id</code>
previously defined with <code>define_xydata</code>.
If no x-uncertainty was defined, no <code>xerr</code> is returned.
__See also__: define_xydata, get_xymodel
#### get_xymodel
##### Synopsis
provides the xy-model <code>(x_mdl[], y_mdl[])</code> given by an xy-fit
<!--%{{{ -->
##### Usage
```c
(x_mdl[], y_mdl[]) = get_xymodel(Integer_Type data_id);
Description
This function returns the xy-model ((x_mdl[],y_mdl[])
)
provided by the last evaluation (by fit_counts
/ eval_counts
)
of the xy-fit-function specified with xyfit_fun
.
See also: xyfit_fun, get_xydata, define_xydata
ignore_xy
Synopsis
ignore points from xy-dataset
c
Usage
ignore_xy (index [, low, high]);
Description
Wraper function of the ignore function for datasets defined with
define_xydata. Ignores data points of dataset index
(in the range low to high) for fitting.
See also: notice_xy, ignore, ignore_en, define_xydata
linear_fit_xerr_yerr_data
Synopsis
fits a linear function to data points with both x- and y-errors
Usage
(Double_Type a, b) = linear_fit_xerr_yerr_data(Double_Type X[], Xerr[], Y[], Yerr[][, Double_Type b0]);
or
(Double_Type a, aerr, b, berr) = linear_fit_xerr_yerr_data(Double_Type X[], Xerr[], Y[], Yerr[][, Double_Type b0]; with_errors);
Qualifiers
- verbose
- n: number of iterations
- with_errors: The 90% confidence interval (Delta chi^2 = 2.7) is computed as well.
Description
The data points (X[i]+-Xerr[i], Y[i]+-Yerr[i])
are iteratively fitted with the linear function y = a + b*x
.
If no initial value for the slope b is specified,
b0 = s * [max(Y)-min(Y)]/[max(X)-min(X)]
is used.
The best fit is found iteratively after the algorithm
by Fasano & Vio (1988), BICDS 35, p.191.
See also: linear_regression
linear_xyfit
Synopsis
linear xy fit function to be used with xyfit_fun
Usage
xyfit_fun ("linear");
Description
This function is not meant to be called directly!
Calling xyfit_fun ("linear");
sets up a linear fit
function for xy-data. It has the form y = a*x + b
,
where a
and b
are the two fit parameters.
See also: xyfit_fun, define_xydata, plot_xyfit, linear_regression
list_Par
Synopsis
lists parameters of the current fit-function as ISIS-commands
Usage
list_Par([ pars[] ]);
Qualifiers
- fit_fun: lists also the fit-function
- fmt: format statement for min/max/value
list_lines
Synopsis
shows the parameters of a lines-model's used lines in a given wavelength range
Usage
list_lines([ids][, lMin, lMax]);
See also: lines, get_lambda_parameters_of_lines, list_all_lis
list_xypar
Synopsis
list current xy-parameter and xy-function
Usage
list_xypar();
See also: get_xyfit_fun, save_xypar, xyfit_fun
load_grouped_xmm_data
Synopsis
wrapper for load_data, which sets already a few basic options
Usage
Integer_Type Index = load_grouped_xmm_data([String_Type Path], [E_lo, E_hi]);
Qualifiers
- min_sn[=5] [
=5
]: Set the minimal S/N ratio (see help("group");) - min_chan[=2] [
=2
]: Set the minimal number of Channels do be rebinned (see help("group");) - delete_data If set, any data sets loaded previously will be deleted.
Description
This functions loads data (by default "src_sd.pha"), groups it, and notices the energy bins between E_lo[=1keV] and E_hi[=10keV]. When changing all default values, it can be easily used for any other satellite.
load_par_from_FITS_header
Synopsis
loads the fit-function and parameters from a FITS file
Usage
load_par_from_FITS_header(String_Type filename);
Description
This function reads keywords from a FITS header
created with save_par_to_FITS_header_struct
.
See also: save_par_to_FITS_header_struct, save_par, load_par
load_par_tbnew
Synopsis
load a parameter file after decreasing the upper limit for tbnew.PL
Usage
load_par_tbnew(String_Type filename);
Description
Early versions of the TBnew
absorption model allowed
for a too large upper limit of the PL
parameter of 5.
This function reduces the PL
parameter to 3.999,
rewrites the parameter file, and loads it with load_par
.
See also: load_par
load_xypar
Synopsis
load xy-parameter and xy-function from parameter file
Usage
load_xypar(String_Type file);
Description
Load parameter file saved with save_xypar("file.par")
. To display
the load parameters one should use list_xypar
instead of
list_par
.
See also: save_xypar, load_par
missing_contour_trq
Synopsis
calculates remaining contour points from function contour_trq. It is used in such cases where countour_trq does finnished before all point are calculated due to torque issues.
Usage
missing_contour_trq(String_Type inputDir);
Qualifiers
Description
-inputDir
directory where all torque job files are,
created by function contour_trq
It may be required to run the function several times. The output (number of files) needs to be checked manualy.
EXAMPLE
missing_contour_trq("torqueFiles");
See also: contour_trq
mpi_fit_pars
Synopsis
computes confidence intervals using MPI
Usage
Struct_Type results = mpi_fit_pars([Integer_Type pars[]]);
Description
The function mpi_fit_pars
is designed to provide a similar
interface then pvm_fit_pars
, written by M. Hanke for the
isis-scripts. Please pay special attention to the notes marked IMPORTANT
below.
pars
is an array of parameters, for which the confidence levels are to be fitted.
If pars
is not specified, all free parameters of the current model are used.
The best fit which is eventually found is always saved in
<dir
>/<basefilename
>_best.par
; the confidence limits are
written in plain-text to <dir
>/<basefilename
>_conf.txt
and as a
FITS table to <dir
>/<basefilename
>_conf.fits
.
The verbosity of mpi_fit_pars
is controlled by the intrinsic variable Fit_Verbose
.
The return value results = struct { index, name, value, min, max, conf_min, conf_max, buf_below, buf_above, tex }
is a table with the following information for each parameter:
min
and max
are the minimum/maximum values allowed.
conf_min
and conf_max
are the confidence limits.
buf_below
(buf_above
) is the fraction of the allowed range [min:max]
which seperates the lower (upper) confidence limit from min
(max
).
If one of these buffers is 0, your confidence interval has bounced.
Perhaps more usefully, this information is written to the files
<dir
>/<basefilename
>_conf.txt
and
<dir
>/<basefilename
>_conf.fits
. In case of any
error, the return value is NULL
. If run via slurm/torque, these
files will only be written by the host node once all threads have
completed - i.e., there's no danger of the results being written by
several machines at the same time.
NOTE: The function "mpi_new_best_fit_hook()" can be defined by the user. This function will be called whenever a new best fit is found. This can be used to, e.g, store the newly found best fit (although the usual caveats about writing files to disk while running via MPI still apply...).
IMPORTANT: Rember that the whole script containing the call "mpi_fit_pars()" is typically run on N > 1 computers. Therefore only the *minimum* amount of code necessary to run mpi_fit_pars() should be included in the script.
IMPORTANT: This function relies on MPI. This means that it only
works when started externally via, e.g., mpiexec isis-script
my_script.sl
or via a slurm jobfile. Slurm or mpiexec must be able to
start as many processes as you have parameters for which you want to
calculate confidence limits (e.g., if you want error bars on four
parameters, you need four tasks - no more, no less).
IMPORTANT: This code is still in test. It might happen that the function ends unexpectedly.
Qualifiers
- level: specifies the confidence level to be computed. As for conf, 0 means 68%, 1 means 90% [default], and 2 means 99% confidence level.
- tolerance: the tolerance for chi^2 improvements without interrupting the search
for the confidence intervals, see
help("conf");
. The default is1e-3
. - fitmethod: fit-method to be used, see
help("set_fit_method");
Default is the currently used fit-method returned byget_fit_method()
. - dir [="."]: specifies the directory in which the logfiles shall be stored. It may be a relative path to the current working directory.
- basefilename [=startdate]
- verbose Files with the stdout and the inital parameters are kept after program is finished.
- forked [=0] Use a separate (forked) process to calculate the confidence levels. It speeds up the calculation, but might cause troubles for models which write files to disk, as this process is killed immediatelly when asked to restart calculation and not stopped smoothly. This option can also cause your job to be killed if run via slurm, as it requests additional threads beyond those allocated by slurm.
- do_not_finalize if set, "mpi_finalize()" is not called within the routine. In this case the code following the mpi_fit_pars() call will be executed on *all* nodes. Only the master process will return the confidence structure (see above); all other processes will return NULL. This can be used to start more than one mpi_fit_pars() in one script. Only use it for very quick evaluations and if you *know that you're doing*. At the end of such an script, it is important to call "mpi_finalize()" manually.
Example
% EXAMPLE 1 % Simple script for confidence level calcualtion with mpi_fit_pars() variable id = load_data("my_data.pha"); % load the data xnotice_en(id,0.5,16); % initialize data load_par("my_best_fit.par");
variable result = mpi_fit_pars(pars); % do calculation for pars[] fits_save_fit("result.fits",result); % save all information % to disk % Note that mpi_fit_pars() alone will save information to disk, % by default in files named _best.par, _conf.txt, % and _conf.fits
% EXAMPLE 2 - Uses slurm to schedule jobs on the Remeis cluster. % This requires two files - mpi_fit.sl, containing the ISIS code to be % executed, and mpi_fit.slurm, containing the job specification for slurm. % This would be run by calling "sbatch mpi_fit.slurm" at the command line. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % ISIS script (mpi_fit.sl) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% variable id = load_data("my_data.pha"); % load the data xnotice_en(id,0.5,16); % initialize data load_par("my_best_fit.par"); variable pars = [1,2]; % obviously you will pick whatever parameters you need here () = mpi_fit_pars(pars; % Do the confidence limit calculations. Results will be saved to basefilename="my_fit"); % "my_fit_conf.fits","my_fit_conf.txt", and "my_fit_best.par". % Note that unlike the above example, we do not manually save %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % the results to a file - mpi_fit_pars does this on its own. % Jobfile (mpi_fit.slurm) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% #!/bin/bash #SBATCH --job-name my_fit # name of the job to be run by slurm #SBATCH --time 00:10:00 # You might need more (or less) time. #SBATCH --ntasks 2 # we want erors on two parameters (see above), so we need 2 cores #SBATCH --mem-per-cpu 1G # 1 gig of memory per core (tweak to your liking) srun /usr/bin/nice -n +19 isis mpi_fit.sl # run the script with srun (and nice +19 because you don't
want to bog down someone else's machine)
See also: fit_pars; conf, set_fit_method, pvm_fit_pars
mpi_fit_pars_trqscript_gen
Synopsis
Creates torque scripts for derivation of confidence intervals
Usage
mpi_fit_pars_trqscript_gen(String_Type fitfile, String_Type resultfile, String_Type scriptfile)
Description
This function generates 1) an executable S-Lang file
that is loading a previous fit saved with fits_save_fit
,
calling mpi_fit_pars
with the current number of free parameters
and saving the result via fits_save_fit
and save_pars
,
2) writing the .cmd and 3) the .cmd.job file
that can be submitted to Torque via 'qsub *.cmd.job'.
If only two arguments are given (the resultfile and the scriptfile), the function expects that you want to calculate the uncertainties out of isis In that case the function will itself save the fit to a file in the results-directory. When mpi_fit_pars is finished, you have to delete it by your own.
ATTENTION: make sure that the min/max parameter borders are set wide enough in your previous fit but still with a reasonable width to allow mpi to find the best fit and ncertainties in a reasonable amount of time.
NOTE: All given qualifiers are passed to the function fits_load_fit.
Qualifiers
- walltime[="00:30:00"]: String_Type, wallime for the torque
- ROC: Rmf OGIP Compliance (see fits_load_fit
- submit: 1-submit to torque, 0-only create job files%
Example
isis>
isis> mpi_fit_pars_trqscript_gen("input.fits","result.fits","trq_scripts/mpi_script.sl"; walltime="01:00:00") OR isis> mpi_fit_pars_trqscript_gen("result.fits","trq_scripts/mpi_script.sl"; walltime="01:00:00")
THEN
qsub trq_scripts/mpi_script.cmd.job
See also: fits_save_fit, mpi_fit_pars, fits_list_fit_pars
notice_xy
Synopsis
notice points from xy-dataset
Usage
notice_xy (index [, low, high]);
Description
Wraper function of the notice function for datasets defined with
define_xydata. Include data points of dataset index
(in the range low to high) for fitting.
See also: ignore_xy, notice, notice_en, define_xydata
par_list
Synopsis
Print a parameter file listing
Usage
Int_Type par_list([String_Type filename | Ref_Type buffer | File_Type fd]);
Qualifiers
- tex[=0]: Format parameter listing in form of a LATEX tabular environment. This does currently not work for a Ref_Type argument.
- pdf[=0]: Compile a pdf file containing the parameter listing as a table.
- all[=0]: Add all parameters to tex and pdf file. By default parameters with the following name - value combinations are excluded: norm 1
- exclude[=0]: Array or list of parameters to be excluded in tex and pdf listings. These are even excluded if the "all" qualifier above is set.
- include[=0]: Array or list of additional parameters to be included in tex and pdf listings.
Description
Prints all internally stores parameter file lines to screen. This includes out-commented fit functions and parameter lines, which are only loaded if par_load is used instead of load_par. Writes parameter listing to file if a String_Type parameter is given, which will be interpreted as filename. If a File_Type parameter is given the listing will be written to this file. If the argument is of Ref_Type, the listing will be returned in this buffer. This argument functionality works analog to the default list_par function.
See also: par_load, par_save, save_par, load_par, list_par
par_load
Synopsis
Loads fit function and parameters for given component from file
Usage
par_load(String_Type filename [, String_Type component]);
Qualifiers
- clean[=1]: Remove temporary parameter files for individual components after calling load_par.
- dryrun[=0]: Generate parameter file for component but do not load it, i.e., do not call load_par. Implies clean=0.
- iterate[=0]: Iterate through components. Returns the name of the current component or NULL if no more components are available.
Description
Creates a copy of the given parameter file and modifies it such that only the fit function associated with the given component is active. This file is then loaded using the standart load_par function. This way individual model components, or alternative fit functions, can be defined in the same parameter file using the following format: #[name1] fitFunction1 #[name2] fitFunction2 defaultFitFunction The rest of the file contains the parameters in the usual format used by list_par. The name "DEFAULT" is reserved for the (uncommented) default fit function. The function returns the name of the loaded component. It returns NULL if the desired component does not exist or if no more components are available during iteration.
See also: par_save, load_par, list_par
par_save
Synopsis
Save fit function and parameters to labeled component in file
Usage
Int_Type par_save(String_Type filename [, String_Type component]);
Qualifiers
- dryrun[=0]: generate parameter file for component but do not load it, i.e., do not call load_par. Implies clean=0.
Description
Saves the current fit function and parameter list to the given parameter file. If a component name is given, the current fit function will be saved as a named and commented out component, which can loaded using par_load. Otherwise the main difference to save_par is that comment lines, which are only loaded if par_load is used, are saved to the parameter file as well. Calling this function is equivalent to calling save_par if no comment lines are present or if the parameter file has been loaded using load_par. The function returns the number of components written to the file, or -1 upon error.
See also: par_load, save_par, load_par, list_par
plot_xyfit
Synopsis
plot xy-data and its current xy-model
Usage
plot_xyfit(Integer_Type data_id);
Description
A simple plot function of the xy-data (given by define_xydata
)
and -model (last evaluation of the xy-fit-function, see xyfit_fun
).
This functions basically calls:
plot_with_err( get_xydata(data_id) );
oplot( get_xymodel(data_id) );
See also: get_xydata, get_xymodel, define_xydata, xyfit_fun, plot_with_err
powerlaw_xyfit
Synopsis
linear xy fit function to be used with xyfit_fun
Usage
xyfit_fun ("powerlaw");
Description
This function is not meant to be called directly!
Calling xyfit_fun ("powerlawlinear");
sets up a powerlaw fit
function for xy-data. It has the form y = norm*x^{-index}
See also: xyfit_fun, define_xydata, plot_xyfit, linear_regression
pulsarorbit_fluxerror_mc
Synopsis
estimates additional uncertainties caused by the flux measurements
Usage
Double_Type[] pulsarorbit_fluxerror_mc(Integer_Type dataset);
Qualifiers
runs - number of MC loops (default: 100) save - save the uncertainty estimation to the assigned FITS-filename collect - file-pattern used by 'glob' to read and merge all FITS-files from previous runs modify - add the estimated uncertainties to the dataset(s) assigned to this qualifier (see below for a detailed description) chatty - be chatty if > 0 (default: 0)
Description
The flux measurements used to calculate the evolution of the spin-period in the fit-function 'pulsarorbit' usually have uncertainties. These uncertainties are not taken into account during an ordinary fit. This function performs Monte Carlo simulations to estimate the uncertainties of the modelled period induced by the flux uncertainties.
During each run the flux evolution associated to the dataset 'id' is varied using flux = flux + grand * flux_err such that synthetic flux evolutions are created. Then a fit is performed using only the given dataset 'id'. This results in many modelled period evolutions. Their standard deviation at each time is finally considered as an additional uncertainty in the period space. These uncertainties are returned by the function.
If the 'modify'-qualifier is set, the dataset(s) assigned to that qualifier or, in case of NULL, the dataset 'id' is modified as follows: new_error = sqrt(sqr(data_error) + sqr(mc_error)) where data_error is the current 'error'-field of the dataset and mc_error is the estimated additional uncertainty as calculated by this function. In case of multiple given datasets, the time range of 'id' should include all of these datasets to get a proper period evolution.
See also: pulsarorbit
pulsartaylor_set_order
Synopsis
changes the order of the Taylor series used in 'pulsartaylor'
Usage
pulsartaylor_set_order(Integer_Type new_order);
Description
By default the Taylor series used in the 'pulsartaylor' fit- function is computed up to the second order. This function allows to change this order starting at zero up to the 7th order. The number of fit-parameters are adapted and named accordingly.
NOTE: changing a fit-function and its parameters on the fly is not supported by ISIS. In order to still achieve this feature here, the fit-function is first deleted using 'del_function' and defined again using 'add_slang_function'. Testing revealed, however, that this trick only works once!
See also: pulsartaylor
pvm_fit_pars
Synopsis
computes confidence intervals with PVM
Usage
Struct_Type results = pvm_fit_pars(String_Type SetupFile[, Integer_Type pars[]]);
Description
With SetupFile, one has to provide an ISIS-script which loads/rebins the spectra
and loads/assigns the response. If the model requires additional modules,
they have to be activated as well in SetupFile
. It is, however, not necessary
to define/load the model itself, as the currently defined model will be saved
into a file <dir
>/<basefilename
>_initial.par
.
pars
is an array of parameters, for which the confidence levels are to be fitted.
If pars
is not specified, all free parameters of the current model are used.
The best fit which is eventually found is always saved in <dir
>/<basefilename
>.par
.
The verbosity of pvm_fit_pars
is controlled by the intrinsic variable Fit_Verbose
.
The return value results = struct { index, name, value, min, max, conf_min, conf_max, buf_below, buf_above, tex }
is a table with the following information for each parameter:
min
and max
are the minimum/maximum values allowed.
conf_min
and conf_max
are the confidence limits.
buf_below
(buf_above
) is the fraction of the allowed range [min:max]
which seperates the lower (upper) confidence limit from min
(max
).
If one of these buffers is 0, your confidence interval has bounced.
The same infomation is stored in the files <dir
>/<basefilename
>_conf.txt
and <dir
>/<basefilename
>_conf.fits
.
In case of any error, the return value is NULL
.
Qualifiers
- level: specifies the confidence level to be computed. As for conf, 0 means 68%, 1 means 90% [default], and 2 means 99% confidence level.
- tolerance: the tolerance for chi^2 improvements without interrupting the search
for the confidence intervals, see
help("conf");
. The default is1e-3
. - fitmethod: fit-method to be used, see
help("set_fit_method");
Default is the currently used fit-method returned byget_fit_method()
. - nph: the number of processes per host, see
pvm_ms
. - debug [=1]: prints additional debug information from
pvm_ms
. (Default=0) - dir [="."]: specifies the directory in which the logfiles shall be stored. It may be a relative path to the current working directory.
- basefilename [=startdate]
- verbose: log every output -- from the master script or any slave --
in the file <
dir
>/<basefilename
>_stdout.log
, and keep the initial parameters. - isisscript [="isis-script"]: command to start ISIS for slaves.
See also: fit_pars; conf, set_fit_method, cl_master/cl_slave [Houck/Noble], pvm_ms [S-Lang module]
pvm_fit_pars_txt2fits
Usage
pvm_fit_pars_txt2fits(String_Type txt_filename);
save_par_to_FITS_header_struct
Synopsis
saves fit-function and paramters to a FITS header structure
Usage
Struct_Type save_par_to_FITS_header_struct()
Description
The returned structure can be used as header keys
that are written to a FITS file.
This header can be read with load_par_from_FITS_header
.
See also: load_par_from_FITS_header, load_par, save_par, fits_write_binary_table
save_statistics
Synopsis
saves the fit-statistic in a textfile
Usage
save_statistics(String_Type filename);
See also: eval_counts
save_xypar
Synopsis
save current xy-fit-parameter in file
Usage
save_xypar(String_Type file);
Description
Save current xy-parameter and xy-function in file.
See also: load_xypar, get_xyfit_fun, list_xypar
set_2d_data_grid
Usage
set_2d_data_grid(Double_Type X[], Double_Type Y[]);
or
```c
set_2d_data_grid(Double_Type X_lo[], Double_Type X_hi[], Double_Type Y_lo[], Double_Type Y_hi[]);
##### Synopsis
define a two dimensional data grid required for 2D fits
##### Description
For fitting 2d data the corresponding grid is set with this function.
If <code>set_2d_data_grid</code> is not called, the function <code>define_counts_2d</code>
uses the indices of the image as grid.
For binned fit functions bin_lo and bin_hi have to be provided.
If only single X and Y arrays are provided, only fit functions
which are evaluated on these grid points can be used.
__See also__: define_counts_2d, gauss_2d_integrated, gauss_2d
#### set_gauss_line_par
##### Synopsis
initializes a line in the lines-model with the parameters of a gauss-line
##### Usage
```c
set_gauss_line_par([id,] line, area, center, sigma);
Description
If id
is not specified, id=1
is used.
line
is the name in the lines-model, appearing as parameters
line_lam
, line_EW
, line_FWHM
and line_A
.
See also: gauss, lines
set_lines_par_fun
Synopsis
sets the derived amplitude parameter in a lines-model
Usage
set_lines_par_fun([Integer_Type id]);
Description
The amplitude parameters of the lines-model are set for every line:
set_par_fun("lines(id).line_A", "lines(id).line_EW/lines(id).line_FWHM");
If code{id} is not specified, id=1 is used.
See also: gauss, lines, unset_lines_par_fun
set_par_from_confmap_table
Synopsis
set parameters from a table obtained by get_confmap
Usage
set_par_from_confmap_results(Struct_Type table, Integer_Type i);
Description
The function sets the parameters of table
's row i
.
As parameter names are infered from column names, the FITS
table may have to be read with the casesen
qualifier.
See also: get_confmap
set_xyfit_qualifier
Synopsis
modify the meta data of an xy-dataset defined by define_xydata
and used for an xy-fit
Usage
set_xyfit_qualifier(data_id; qualifiers);
Description
This function can be used to modify the information for the xy-data.
The used qualifiers are combined with the data structure. Normally
the qualifiers to be set should be x_mdl
or curve_parameter
.
Example
set_xyfit_qualifier(id; curve_parameter=[0:2*PI:#3000]);
See also: define_xydata, xyfit_fun, plot_xyfit
set_xyfit_sys_err_frac
Synopsis
adds systematic uncertainties to an xy-dataset defined by define_xydata
Usage
set_xyfit_sys_err_frac(data_id, [xsyserr,] ysyserr);
Description
A systematic uncertainty is added in quadrature to either
the x- and y-data or to the latter only. The combined
uncertainty considered by xyfit_residuals
then is
err_new = sqrt( err^2 + (data * syserr)^2 )
where data
is the x- or y-data as defined using
define_xydata
and err
is the corresponding
defined uncertainty.
By default, no systematics uncertainties are considered.
Example
% adds 0.5% systematics to the y-data only set_xyfit_sys_err_frac(1, .005);
% adds systematics to both, x- (0.5%) and y-data (1%) set_xyfit_sys_err_frac(1, .005, 0.01);
See also: xyfit_residuals, define_xydata, set_sys_err_frac
shift_intpol
Synopsis
Shifts the elements of an array continuously
Usage
Array_Type shift_intpol(Array_Type array, Double_Type n)
Description
This function does in principle work like the 'shift' function, with the exception that the amount of the shift may be a floating point number. The values of the resulting array are in that case re-distributed by linear interpolation. Thereby, the the sum of the array values is still preserved.
See also: shift
steppar
Synopsis
performs a fit while stepping the value of a fit parameter through a given range
Usage
Struct_Type info = steppar(String/Integer_Type par [, Double_Type val1, val2, step] );
or
```c
(Struct_Type info, keys) = steppar( String/Integer_Type par [, Double_Type val1, val2, step]; keys);
##### Qualifiers
* keys: An additional structure is returned that can be used as FITS header keys
* frozen[=0]: Perform steppar also for frozen Parameters.
* range[parmin,parmax]: Stepping range. Default is the
minimal/maximal allowed parameter value.
* nsteps[=10]: Number of steps the parameter 'par' is
stepped from range[0] to range[1].
* reset: If given after each step the initial parameter set, which was
valid before this function was called, is restored.
* fit[=&fit_counts]: Reference to the function running the fit algorithm.
* fitargs: Arguments required by the 'fit' function. See __push_list for
format information!
* rerun: Reruns a stepping procedure based on results of a previous run,
i.e., before each step the according parameter set of the previous
run is loaded, e.g., to improve the results using another fit_method.
* resume: Missing steps in the given steppar-file will be calculated based
on the previous steps, i.e., resuming the stepping where it was
stopped.
* check[=0]: Before each step saved steppar informations of other stepped
parameters are gathered and checked for a parameter set with a
better chi2 (using steppar_get_bestparams). In case a better
parameter set was found the stepping will be restarted.
\* ATTENTION: 'save' qualifier is required !!!
\* Gathered are steppar-files, which match the pattern
given with 'save',e.g., if save is "steppar_PID00001.fits"
all files "steppar_PID?????.fits" are globed!
Note that the affix "_PID???" is automaticcaly appended to
the save string if it does not exist (see 'save' qualifier!)
\* The Integer 'check' is set to is the maximal number of
restarts.
\* A parameter set is considered better if
chi2_new < chi2_init \* ( 1 - dchi2 )
\* NOTE: Parameter grouping is possible (see steppar_get_bestparams)
* dchi2[=0.1]: Percental limit for the chi2 of a new parameter set to be
considered as a better parameter set (see 'check'):
chi2_new < chi2_init \* ( 1 - dchi2 ).
* save: After each stepping the result is saved in the file given
(as String_Type) with this qualifier. The chi2 of undone steps
are set to 0.! Also note that the filename is appended with
the parameterindex: 'steppar.fits' -> 'steppar_PID00001.fits'
* force: Forces to overwrite an existing file given with 'save'.
* chatty: Prints fitting information.
##### Description
The given parameter is stepped through in the given parameter 'range',
which is devided into 'nsteps' equidistant value points. If 'val1', 'val2'
and 'step' are given 'range' = ['val1','val2'] and
'nsteps' = ('val2'-'val1')/'step'.
At each of this points a fit is performed. The fitting starts with the
value point closed to the best fit value and alternatingly progresses outwards
to each side. The 'reset' qualifier restores the initial parameter set
after each step, otherwise the parameter set of the nearest stepping point
is used.
The 'rerun' qualifier allows to rerun a stepping using the steppar information
of a previous run, i.e., at each step the according parameter set of that
previous run is loaded before the fit algorithm is started.
In case the steppar function was killed, the 'resume' qualifier
can be used to resume the stepping (given that 'save' was used!).
If the 'save' qualifier is given the results of the stepping are stored
as a .fits file after each step! NOTE that the affix "_PID?????" is
automatically appended to the filename (if not already included), where
the ??? are the ID of the stepped parameter. If the specified file
already exists an error is thrown if the 'force' qualifier for overwriting
is not set.
The 'save' qualifier is also requiered if the 'check' for a better
parameter set is enabled, i.e., before each step it is checked if there
is a parameter set amongst other stepped parameters with
chi2 < chi2_init \* ( 1 - 'dchi2') leading to a restart of the stepping
using the better parameter set, where chi2_init is the chi2 of the parameter
set the stepping was initialized with (which will be updated after a restart).
The maximal number of restarts is given by 'check'.
This qualifier is useful if several steppar processes are running at the same
time saving their results after each step to a fits-file, as in this case
a better fit will be automatically applied! NOTE THAT using 'check'
can lead to inconsistent steppar resulsts in terms of inital parameter sets,
e.g., one steppar process is already finished and afterwards in another one
a better parameter set is found leading to a reastart in the remaining
steppar processes!
=> After using 'check' either make sure all steppar run with the same initial
parameter set or manually extract the best parameter set and run all steppars
once more!
The fitting itself is performed using the 'fit' function, to which
all qualifiers are passed, which gets the 'fitargs' as arguments (see
__push_list).
IMPORTANT:
steppar is based on the current version of the parameter set!
KEYS:
fit_method: fit method used for fitting (see get_fit_method)
statistic: chisqr according to the parameter set the function was callled with
num_variable_params:
num_bins:
pval: initial value of the stepped parameter
pname: exact name of the stepped parameter
%_freeze, %_min, %_max: additional information about the parameters, where
% is the escapedParameterName
__See also__:
#### steppar_get_bestparams
##### Synopsis
Extracts new best fit parameter values out of steppar information
##### Usage
```c
Struct_Type[] params = steppar_get_bestparams( String_Type[] File );
or
```c
Struct_Type[] params = steppar_get_bestparams( Struct_Type[] steppar );
##### Qualifiers
* chatty: Information output
* minchi2: Chi2 limit the new parameter set has to beat
to be taken into accounts!
Default: eval_stat_counts.statistic
* groups: Allows to extract best parameter sets for defined parameter
groups. 'groups' has to be an Array_Type, where each entry
represents a group and contains an Integer/String array
with the according parameter indices/names.
Useful in combination with 'simultaneous_fit' settings, e.i.
groups = %.model.groups!
##### Description
This function searches for the minimal chisqr value within the given
files/steppar information and returns a parameter structure with the
according parameters (see get_params). With the groups qualifier a
groupping can be specified, i.e., the search for a minimal chi2 is
done for each individual groups. The returned structure array
only contains those parameter, which lead to the better chi2 value.
If no better chi2 was found or there was no better chi2 than the
specified minchi2 value, the function returns Struct_Type[0].
ATTENTION:
It is neccessary that the model with which the steppar was executed
is loaded as this functions uses get_params and only changes those
values of the freeParameters as the values of the frozen ones are
not saved!
If another parameter set is loaded there will be a difference in
the new chi2 value this function gives (use 'chatty') and that
chi2 an eval_counts will return!
__See also__: get_params
#### steppar_get_conf
##### Synopsis
Obtains confidence limits out of steppar information
##### Usage
```c
Struct_Type[] conf = steppar_get_conf( String_Type[] File );
or
```c
Struct_Type[] conf = steppar_get_conf( Struct_Type[] steppar );
##### Qualifiers
* chatty: Information output
* dchi2[=2.71]: Delta Chisqr
##### Description
Tries to obtain confidence level related to the given 'dchi2'
value (default: 2.71) based on the steppar information.
To do so this function calculates interpolated intersections
of the chi2 landscape and min(chi2)+'dchi2'.
Only if 2 or more such intersections are found the confidence
limits are set. In case of more then 2 solutions always the
minimal/maximal solutions are taken.
__See also__: interpol
#### steppar_load
##### Synopsis
loads saved steppar information
##### Usage
```c
Struct_Type[] steppar = steppar_load( String_Typep[] pat );
or
```c
Struct_Type[] steppar, keys = steppar_load( String_Type[] pat ; keys );
##### Qualifiers
* keys: If given also the key structure is returned (using fits_read_header).
If keys is a List_Type with keynames, only these keys are read using
fits_read_key_struct, which is faster!
* ext: Only loads extension fitting 'ext' (String_Type)!
##### Description
Loads a \*.fits file storing the steppar information saved with
steppar_save. The given string 'pat' can be a single file
including several extension, an array with files or used as
a pattern for multiple files in globbing format (see glob).
__See also__: steppar, steppar_save, glob
#### steppar_plot
##### Synopsis
xfig plot of the chi2 landscape of (a) stepped parameter(s)
##### Usage
```c
steppar_plot( Struct_Type steppar, key );
or
```c
steppar_plot( String_Type stepparfile );
##### Qualifiers
* norender: If given xfig plots are returned instead of rendered
* pdfunite: If given the rendered plots are united into a single one
* ignorez: Ignores Chi2 values equal to Zero
* size=[15,11]: Size of the plot
* path="steppar.pdf": Path for the rendered file
* ext=".pdf": File Type, e.g., "png"
* yoff: Constant offset for the y-axis. Set to the initial statistic
by default
* yrange: Range of the y-axis. Either Double_Type[1] or [2].
If only one value is given it is taken as ymax!
* dchi2=2.71: Delta Chisqr
#### steppar_save
##### Synopsis
Saves steppar information (& keys) to a \*.fits file
##### Usage
```c
steppar_save( String_Type file, Struct_Type[] steppar [, keys]);
Description
Saves the output of 'steppar' to a *.fits file.
See also: steppar
switch_tbnew_rel_abund
Usage
switch_tbnew_rel_abund([String_Type parnames]);
Description
Unless one or more parnames
are given, all elements are switched.
Qualifiers
- inst [=1]: instance of tbnew
- verbose
thawedParameters
Synopsis
find all parameters of the current fit-function that are not frozen
Usage
Integer_Type[] thawedParameters()
Description
Note that thawedParameters
may include ones that are
tied to another one, or derived as functions of other parameters.
See also: freeParameters
unset_lines_par_fun
Synopsis
removes the par_fun's in a lines-model to speed up the model
Usage
unset_lines_par_fun([Integer_Type id]);
Description
The amplitude parameters of the lines-model are reset for every line:
set_par_fun("lines(id).line_A", NULL);
If id
is not specified, code{id=1} is used.
See also: gauss, lines, set_lines_par_fun
xspec_to_isis
Synopsis
Parse xspec parameter file to isis parameter file
Usage
Integer_Type t = xspec_to_isis(String_Type xspec_par)
Qualifiers
- set: set loadad parameters
- save [=String_Type filename]: save parameters as isis parameter file if filename is not specified it is saved as the .xcm file but with .par suffix
- nonverbose: suppress any output not produced by errors
Description
Parse an xspec parameter file .xcm
to an isis parameter file.
If desired parameters can be set after parsing.
*** Warning:
Xspec tying expressions are only supported in the form of
= p1
*** Warning:
Convolution models are not supported!
If tied parameters is out of range of the respective parameter
the limits are set to fit and a warning is given.
Example
isis> t=xspec_to_isis ("test.xcm"; save); Running Xspec................. parameters saved to test.par as: diskbb(1) + nthComp(2) idx param tie-to freeze value min max 1 diskbb(1).norm 0 0 21.7378 0 1e+10 2 diskbb(1).Tin 0 0 0.230239 0.001 10 keV 3 nthComp(2).norm 0 0 0.00019705 0 1e+10 4 nthComp(2).Gamma 0 0 1.9752 1.001 5 5 nthComp(2).kT_e 0 0 1.68497 1.68497 1000 keV 6 nthComp(2).kT_bb 2 0 0.230239 0.001 10 keV 7 nthComp(2).inp_type 0 1 1 0 1 0/1 8 nthComp(2).Redshift 0 1 0 -0.999 10
See also: set_par, load_par
xyfit_fun
Synopsis
define xy-function to fit data defined via define_xydata
Usage
xyfit_fun(String_Type function_expression);
Description
Setting up an xy-fit-function with fitfun
with xyfit_fun("fitfun");
is done by interpreting the string "fitfun" and creates a fit function that can
be understood by the isis routines. The string is searched for known functions
and special symbols. Every thing else is interpreted as a new fit parameter belonging
to a generic function F
.
The known functions can either be a registered isis function with name fun_xyfit
or an slang intrinsic (see examples). If a symbol starts with '#' it is replaced
with the x-axis of the current data set.
If the xy-fit-function describes the graph a function,
it usually computes @yref
in terms of @xref
and the par
-array.
This is the only option for xy-data without xerr
, see define_xydata
.
If the xy-fit-function describes a parameterized curve,
it usually computes (@xref, @yref)
in terms of par
and probably further (constant) parameters passed to fitfun_xyfit
as qualifiers, which have been defined by set_xyfit_qualifier
If a function of the form fitfun_xyfit
is loaded and a function
fitfun_xyfit_default
exists, this will be passed to
set_param_default_hook
.
Importand Notes:
The routine will first search for functions with the appendix _xyfit
and afterwards for intrinsic functions. This means if a function fun
exists
and there is also a function fun_xyfit
registered the routine will use the
latter.
Calling a parameterized function together with functions of the form f(x) = y or two parameterized functions redults in undefined behavior. Calling a parameterized alone behaves as expected.
The internal structure of the routine requires it that a call to list_par
,
save_par
or load_par
do not work as expected. Equivalent _xypar functions
exist.
Examples
xyfit_fun("linear"); % or xyfit_fun("linear(1)"); % sets up xyfit-function linear_xyfit % in this form it is the xy-equivalent to fit_fun
% example for defining a proper _xyfit function: % (example for y = x*a+b; as available already with: xyfit_fun("linear");) define another_linear_regression_xyfit () { variable xref, yref, par; switch(_NARGS) { case 0: return ["a [unit_a]", "b [unit_b]"];} { case 3: (xref, yref, par) = (); }
@yref = par[0] * @xref + par[1]; } define another_linear_regression_xyfit_default(i) { switch(i) { case 0: return (1, 0, -10, 10); } { case 1: return (0, 0, -5, 10); } } xyfit_fun("another_linear_regression"); list_xypar;
% example for specifying normalization parameters % (see 'norm_indexes' parameter of 'add_slang_function') define fun_with_norm_xyfit () { variable xref, yref, par; switch(_NARGS) { case 0: return struct { pars = ["a [unit_a]", "b [unit_b]"], norm = [0] }; } { case 3: (xref, yref, par) = (); }
@yref = par[0] * (@xref ^ par[1]); } xyfit_fun("fun_with_norm");
% example for a simple function call xyfit_fun("Norm*sin(#x)/exp(#x-xoff)"); % results in fit-function of the form % Norm*sin(x)/exp(x-xoff) % with two parameters: Norm, xoff
% example of a combination of the previous cases xyfit_fun("linear(1)+tan(#x^2-xoff)/linear(2)"); list_xypar; % output: % linear(1)+tan(#x^2-xoff)/linear(2) % idx param tie-to freeze value min max % 1 linear(1).a 0 0 1 -100000 100000 coefficient of x % 2 linear(1).b 0 0 0 -100000 100000 additive constant % 3 linear(2).a 0 0 1 -100000 100000 coefficient of x % 4 linear(2).b 0 0 0 -100000 100000 additive constant % 5 F(1).xoff 0 0 0 0 0
See also: define_xydata, set_xyfit_qualifier, list_xypar, save_xypar, load_xypar, plot_xyfit
xyfit_residuals
Synopsis
calculates the difference between xy-data and xy-model
Usage
Double_Type res[] = xyfit_residuals(Integer_Type data_id);
Description
The residuals res[i]
are determined differently for xy-data with
uncertainties in y only or in both dimensions.
If the xy-data have no x-uncertainties xerr
:
res[i] = (data.y[i] - model.y[i]) / data.yerr[i];
If the xy-data have uncertainties xerr
as well:
res[i] = min( relative_distance_from_curve[i] );
where relative_distance_from_curve[i]
is composed of
(model.x - data.x[i]) / data.xerr[i]
and
(model.y - data.y[i]) / data.yerr[i]
.
See also: define_xydata, xyfit_fun