Ifeffit::Demeter - OO interface to Ifeffit for EXAFS data analysis
This documentation refers to Ifeffit::Demeter version 0.0.1
$gds_object = Ifeffit::Demeter::GDS ->
new({type => 'guess',
name => 'alpha',
mathexp => 0,
});
$gds_object -> report;
## after a fit....
$gds_object -> evaluate;
This subclass of the Ifeffit::Demeter class is inteded to hold information pertaining to guess, def, set, and other parameters for use in a fit.
A GDS object has 8 attributes:
This is the name of the parameter. It must respect the conventions for a parameter name in Ifeffit.
This is one of
guess def set restrain after skip merge
The first three types are exactly as in Ifeffit.
A restrain parameter is defined in an Ifeffit script as a def
parameter but is used as a restraint in the call to the ifeffit()
function. In a multiple data set fit, all restraints are defined in
the first call to ifeffit().
An after is a def parameter which is not defined until after the fit
is complete. As far as Ifeffit is concerned, this is a meaningless
distinction. However, in the logfile method of the fit class,
afters are reported distinctly from defs, so they provide a way of
organizing the results of the fit.
A skip is a parameter that is defined but then ignored. Setting a variable to a skip is kinda like commenting it out.
A merge is the type given to a parameter that cannot be unambiguously resolved when two Fit objects are merged into a single Fit object.
This is the math expression assigned to the parameter. For a guess parameter this is often just a number -- the initial guess.
This is the math expression as provided by the user before any rewriting for local parameters.
After the fit is evaluated, this contains the result of the fit for this
parameter. This is normally not set explicitly with the set method.
Rather it is set using the evaluate method so that the math expression is
correctly evaluated by Ifeffit.
After the fit is evaluated, this contains the error on this guess parameter.
For all other types, this is 0. This is normally not set explicitly with the
set method. Rather it is set using the evaluate method after a fit.
This is true if the parameter has been modified but not evaluated.
This is a text string -- an annotation -- used to describe something about the parameter.
When this is true, the annotation is set automatically when the parameter is evaluated.
This is a flag disables the use of a global restraint or a glocal after when local guess parameters are in play.
The GDS object uses the new, clone, set, and get methods
described in the the Ifeffit::Demeter manpage documentation.
annotate
This method sets the note and autonote attributes in a stroke. It takes a single argument, the annotation string for the parameter.
$gds_object -> annotate($string)
$gds_object -> annotate(q{})
If the string is not empty, the note will be set to the string and the autonote attribute will be set to 0. If the string is empty, the note attribute will be cleared and the autonote attribute will be set to 1. These are completely equivalent to
$gds_object -> set({note=>$string, autonote=>0});
$gds_object -> set({note=>q{}, autonote=>1});
but using this method saves you the bother of remembering to toggle the autonote attribute.
A number of convenience methods exist for probing attribute values.
These all have equivalent calls to the get method.
name
Returns the parameter name.
$name = $gds_object -> name;
type
Returns the parameter type.
$type = $gds_object -> type;
mathexp
Returns the parameter's math expression.
$mathexp = $gds_object -> mathexp;
bestfit
Returns the value of the parameter after the fit has been evaluated.
$value = $gds_object -> bestfit;
Before a fit is evaluated, this method returns 0.
error
Returns the uncertainty of a guess parameter after the fit has been evaluated.
$name = $gds_object -> name;
Before a fit is evaluated and for all parameters which are not of type guess, this method returns 0.
note
Returns the parameter's annotation.
$string = $gds_object -> note;
autonote
Returns true if the parameter is flagged for automatic annotation after a fit.
$is_automatic = $gds_object -> autonote;
write_gds
This returns a string which is the command to define the parameter in Ifeffit.
$string = $gds_object -> write_gds
This returns a string something like
guess enot = 0.0
The first word is the parameter type. ``def'' is used for after and restrain parameters. Other parameter types (skip and merge) return string which will not be valid Ifeffit commands.
report
This returns a string which reports on the value of a parameter after
a fit is complete. This method is used in the logfile method of
the Fit subclass.
$string = $gds_object -> report;
The strings returned for the various parameter types are different. All contain the best fit value and the math expression (or initial guess). The error is included for guess parameters.
full_report
This is like the report method, but it returns a more verbose,
multiline string and includes the annotation.
$string = $gds_object -> report;
This is not used in the logfile, but may be useful in interactive use.
evaluate
This method is called after a fit is performed to evaluate the bestfit and error attributes of the object. It also sets the annotation is the autonote attribute is true. It returns 1 in most cases, but returns 0 for unevaluatable parameter types (skip and merge).
$is_ok = $gds_object -> evaluate;
This is called as part of the evaluate method of the Fit class on
all parameters used in the fit. Thus, it normally does not need to be
called explicitly. However, it may be useful in interactive use.
When the reference to the GDS object is used in string context, it returns the
string from the write_gds method. That string looks something like:
guess alpha = 0.0
When the reference to the GDS object is used in numerical context, it returns the the bestfit value of the parameter. These two lines of perl are the same:
printf("%s is %.7f\n", $gdsobjects[0]->name, $gdsobjects[0]->bestfit);
printf("%s is %.7f\n", $gdsobjects[0]->name, $gdsobjects[0]);
These messages are classified as follows (listed in increasing order of desperation):
(W) A warning (optional).
(F) A fatal error (trappable).
(F) You have attempted to set a numerical attribute with something that cannot be interpretted as a number.
(F) You have used a parameter name that does not follow Ifeffit's rules for group names. The parameter name must start with a letter. After that only letters, numbers, &, ?, _, and : are acceptable characters. The name must be no longer than 64 characters.
(F) The complete list of valid parameter types is guess, def, set, after, merge, restrain (without a ``t'' at the end), and skip.
Describe serialize/deserialize methods
Dump/Load
freeze/thaw
describe file format
See the Ifeffit::Demeter manpage for a description of the configuration system.
See the Ifeffit::Demeter manpage for a list of dependencies.
There are no known bugs in this module.
Please report problems to Bruce Ravel (bravel AT anl DOT gov)
Patches are welcome.
Bruce Ravel (bravel AT anl DOT gov)
http://cars9.uchicago.edu/~ravel/software/
Copyright (c) 2006-2007 Bruce Ravel (bravel AT anl DOT gov). All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.