Demeter

Description Perl tools for X-ray Absorption Spectroscopy
Demeter > Perl Modules > Demeter::Fit
Source

NAME

Demeter::Fit - Fit EXAFS data using Ifeffit or Larch

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

  my $fitobject = Demeter::Fit -> new(gds   => \@gds_objects,
                                      data  => [$data_object],
                                      paths => \@path_objects,
                                     );
  $fitobject -> fit;
  $fitobject -> evaluate;
  $fitobject -> logfile("cufit.log");

DESCRIPTION

This class collects and organizes all the components of a fit using Ifeffit or Larch. The bulk of a script to fit EXAFS data involves setting up all the data, paths, and parameters that go into the fit. Once that is done, you pass that information to the Fit object as array references. It collates all of the information, resolves the connections between Path and Data objects, performs a number of sanity checks on the input information, and generates the sequence of Ifeffit or Larch commands needed to perform the fit. After the hard work of setting up the Data, Path, and GDS objects is done, you are just a few lines away from a complete fitting script!

ATTRIBUTES

Three attributes define a fit. These are gds, data, and paths. Each takes an reference to an array of other objects. The gds attribute takes a reference to an array of GDS objects, and so on. All other attributes of a Fit object are scalar valued.

The set method will throw an exception if the argument to gds, data, and paths is not a reference to an array. Similarly, the get method returns array references for those three attributes.

Here is a list of the scalar valued attributes. Many of these get set automatically when the fit is performed. All of them are optional.

vpaths

Like the gds, data, and paths attributes, this takes a reference to an array. This array contains all the VPath objects defined with the fit. Note that, unlike the other three, this is not required and is not a part of the definition of the fit. In fact, the only use for this attribute is to have a collection of VPaths saved to a serialization file and recovered when the fit is deserialized.

label

Short descriptive text for this fit.

description

Longer descriptive text for this fit. This will be written to the log file after a fit.

fom

A figure of merit for this fit. This is intended for reports on multiple fits. An example might be the temperature of the data fit where the report is then intended to show the temperature dependence of the fit.

environment

This is filled in with information about the versions of Demeter and perl and the operating system used.

interface

This is filled in with text identifying the user interface. The default value is 'Demeter-based script'. This should be set to the name of the program using Demeter.

time_of_fit

This is filled in with the time stamp when the fit finishes.

prepared_by

This is filled in with an attempt to identify the person performing the fit.

contact

This may be filled in with information about how to contact the person performing the fit.

cormin

Minimum correlation reported in the log file. This must be a number between 0 and 1.

ignore_nidp

If this boolean attribute is true, Demeter will not perform the sanity check which verifies that the number of guess parameters is smaller than the number of independent points. Just because this parameter exists, do not presume that this is a good idea. If you run a fit with too many free parameters, best fit values, error bars and correlations will not be meaningful and the fit that you run cannot be reliably interpreted in a statistical sense.

METHODS

fit

This method returns the sequence of commands to perform a fit in Ifeffit or Larch. This sequence will include lines defining each guess, def, set, and restrain parameter. The data will be imported by the read_data command. Each path associated with the data set will be defined. Then the text of the Ifeffit's feffit or Larch's ... command is generated. Finally, commands for defining the after parameters and for computing the residual arrays are made.

   $fitobject -> fit;

A number of sanity checks are made on the fitting model before the fit is performed. For the complete list of these sanity checks, see Demeter::Fit::Sanity.

sum

This method returns a VPath object containing all paths associated with the fit and with the specified Data object. If the data argument is not supplied, the first data set in the data attribute will be used. Ths, for a one-data-set fit, the data argument is optional.

  my $sum = $fit->sum($data);
  $data -> plot('r');
  $sum  -> plot('r');
rm

Clean up all on-disk trace of this fit project, typically at the end of script involving deserialization of project file.

  $fitobject -> rm;
gds

This method returns a reference to the list of GDS objects in this fit.

  @list_of_parameters = @{ $fit -> gds };
data

This method returns a reference to the list of Data objects in this fit.

  @list_of_data = @{ $fit -> data };
paths

This method returns a reference to the list of Path objects in this fit.

  @list_of_paths = @{ $fit -> paths };
set_all

NOT WORKING AT THIS TIME.

This method is used to set attributes of every Data, Path, or GDS in a fit. For instance, this example sets rmin for each data set to 1.2:

  $fitobject -> set_all('data', {rmin=>1.2});

This example sets the sigma2 math expression for each Path in the fit:

  $fitobject -> set_all('path', {sigma2=>'debye(temp, thetad)'});

This example converts all parameters to be set parameters:

  $fitobject -> set_all('gds', {type => 'set'});

The first argument is one of "data", "paths", "gds" and the second is a reference to a hash of valid attributes for the object type.

This returns the Fit object reference if the arguments can be properly interpreted and return 0 otherwise.

evaluate

This method is called after the fit or ff2chi method. This will evaluate all path parameters, all GDS parameters, and all correlations between guess parameters and store them in the appropriate objects. This is always called by the fit method once the fit is finished, thus it is rarely necessary for you to need to make an explicit call.

   $fitobject -> fit;
   $fitobject -> evaluate;
logfile

This write a log file from the results of a fit and an ff2chi.

   $fitobject -> logfile($filename, $header, $footer);

The first argument is the name of the output file. The other two arguments are arbitrary text that will be added to the top and bottom of the log file.

statistic

This returns the value of one of the fitting statistics, assuming the evaluate method has been called.

   $fitobject -> statistic("chi_reduced");

An exception is thrown is the argument is not one of the following:

   n_idp n_varys chi_square chi_reduced r_factor
   epsilon_k epsilon_r data_total
correl

This returns the correlation between any two parameters, assuming the evaluate method has been called.

   my $cor = $fitobject->correl("delr", "enot");
all_correl

This returns a complete hash of correlations between parameters, assuming the evaluate method has been called.

   my %correls = $fitobject -> all_correl;
correl_report

This method returns a block of text summarizing all the correlations above the value given as the first argument, assuming the evaluate method has been called. This method is used by the logfile method.

   my $text = $fitobject -> correl_report(0.4);
happiness

This returns the happiness evaluation of the fit and is writtent to the log file. The two return values are the happiness measurement and a text summary of how the happiness was evaluated. See Demeter::Fit::Happiness.

   ($happiness, $summery) = $fit -> happiness;

SERIALIZATION AND DESERIALIZATION

A fit can be serialized to a zip file containing YAML serializations of the various parts of the fit.

  $fitobject->serialize("projectfile");

One of these zip files can be deserialized to a Fit object:

  $newfitobject = Demeter::Fit->new(project=>"projectfile");

The files are normal zip files and can be opened using a normal zip tool.

freeze and thaw are aliases for the serialize and deserialize methods.

The constituents of the deserialized fit can be recovered by dereferencing the arrays stored in the gds, data, and paths attributes.

  my @gds   = @{ $newfitobject->gds };
  my @data  = @{ $newfitobject->data };
  my @paths = @{ $newfitobject->paths };

DIAGNOSTICS

These messages are classified as follows (listed in increasing order of desperation):

    (W) A warning (optional).
    (F) A fatal error (trappable).
Demeter::Fit: component not an array reference

(F) You have attempted to set one of the array-valued Fit attributes to something that is not a reference to an array.

Demeter::Fit: <key> is not a component of this fit

(W) You have attempted to get an attribute value that is not one of gds, data, paths or one of the scalar values.

No gds component is defined for this fit
No data component is defined for this fit
No paths component is defined for this fit

(F) You have neglected to define one of the attributes of the Fit object.

This fit is ill-defined. Giving up...
This summation is ill-defined. Giving up...

(F) One or more of the sanity checks has failed. Other diagnostic messages with more details will be issued.

'$stat' is not a fitting statistic ($STAT_TEXT)

(W) You have asked for a fitting statitstic that is not one of the ones available (n_idp n_varys chi_square chi_reduced r_factor epsilon_k epsilon_r data_total).

CONFIGURATION AND ENVIRONMENT

See Demeter::Config for a description of the configuration system. See the fit group of configuration parameters.

DEPENDENCIES

The dependencies of the Demeter system are in the Build.PL file.

BUGS AND LIMITATIONS

Please report problems to the Ifeffit Mailing List (http://cars9.uchicago.edu/mailman/listinfo/ifeffit/)

Patches are welcome.

AUTHOR

Bruce Ravel, http://bruceravel.github.io/home

http://bruceravel.github.io/demeter/

LICENCE AND COPYRIGHT

Copyright (c) 2006-2018 Bruce Ravel (http://bruceravel.github.io/home). All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlgpl.

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.

generated by Pod::ProjectDocs