Demeter

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

NAME

Demeter::Fit::Happiness - Semantic evaluation of an EXAFS fit

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

After a fit finishes, Demeter evaluates a semantic (i.e. non-statistical) parameter for the fit based on the R-factor, path parameter values, restraints, and other aspects of the fit. This parameter is a tunable, ad hoc measure of how happy the fit will make the person running the fit.

DESCRIPTION

Ifeffit and Larch, and therefor Demeter, offers a number of parameters after the completion of the fit. These include the chi-square, the reduced chi-square, an R-factor, error bars, uncertainties, and restraint evaluations. These various parameters serve different purposes. The chi-square is the actual fitting metric, i.e. the quantity which is minimized in the fit. The reduced chi-square is the fitting metric normalized by the degrees of freedom (i.e. the difference in the number of independent points and the number of guess parameters used) and is a true statistical parameter. The reduced chi-square can be used to compare two different fitting models against a data set. The R-factor is merely a percentage misfit, a numerical measure of how well the fit over-plots the data. Taken together the reduced chi-square and the R-factor go a long way towards helping you evaluate your fit.

Unfortunately, the EXAFS fitting problem is not a well-defined Gaussian fitting problem. That's a shame, given that Ifeffit & Larch apply the concepts of Gaussian statistics. In principle, one can do much better than a simple application of Gaussian statistics. Several workers, notably Krappe and Rossner, have applied Bayesian concepts to the EXAFS problem. In practice Demeter uses Ifeffit or Larch because they offer so many useful tools for arbitrary model building. Consequently, Demeter and its users need to find a way to live with the shortcomings of the Gaussian approach to the EXAFS problem.

A blind reliance on the reduced chi-square and the R-factor is not a good idea. Because the EXAFS problem is so ill-posed in the Gaussian sense, reduced chi-square is almost never close to 1 -- even tough that is the definition of a good a fit in Gaussian statistics. Consequently, reduced chi-square can only be used to compare fits. It may not be used to evaluate the quality of a single fit.

The R-factor is even more problematic. It merely tells you whether the fit closely over-plots the data. It does nothing to evaluate whether the results of the fit make any kind of physical sense. Those sorts of value judgments are the responsibility of the EXAFS practitioner. She must consider whether the best fit values are physically sensible, whether the error bars and correlations are acceptible, and whether the path parameters evaluate to sensible values. These value judgments, along the reduced chi-square and the R-factor, go into the assessment of the fit.

Fortunately, we know a lot about what an EXAFS fit should do. For instance,

This module introduces an entirely semantic (i.e. non-statistical, ad hoc, and non-publishable) parameter which attempts to quantify all of the above. This parameter is called the happiness. This name is chosen , in part, because it can serve as an indication of how happy the fit should make you and, in part, because it is a silly idea that should not be taken too seriously. (I feel obliged to point out that happiness in the abstract is not silly, merely the notion that your EXAFS software can quantify happiness!)

The output is a number between 0 and 100. A happiness of 100 is the happiest possible fit. A happiness of 0 should make you very sad indeed. The happiness number is reported in the log file. A good use of the happiness would be to provide a visual cue in a graphical interface. For example, a region of the screen could glow green when the happiness is above 90 and red when it is below 60, with values in between producing colors that run the spectrum between red and green. That is the sense in which happiness is a semantic parameter. It does not provide you with a number that you can quote in the scientific literature, but it provides a way for software to suggest how pleased you are liable to be once the fit completes. Even better, it provides a clue that something may have gone awry in a bad fit. In particular, it evaluates more of the fit than just the percentage misfit. A fit with a small R-factor and unreasonable path parameter values should be an unhappy fit.

The idea for a semantic parameter of this sort came from a radio piece (I think it was Eight Forty-Eight on Chicago Public Radio) I heard on a device called The Ambient Orb. The idea of this device is that it snarfs stock data from the internet and glows green when the market is up and red when the market is down. This provides a semantic, ambient indication of the state of one's stock portfolio. The part that interested me when I first heard about this is that users of the orb tend to be less anxious about their stock portfolios. Rather than needing to continuously check etrade.com, one can glance a splash of color out of the corner of the eye. I like the thought of having a visual indicator of how well a fit is working out while in the middle of a lengthy analysis session.

The current version of the happiness parameter works like this:

initial value

The happiness starts at 100%, i.e. fully happy. Each of the parameters used to evaluate the happiness can only subtract from the happiness. Each parameter is checked in turn for its diminution of the happiness.

R-factor

An R-factor below 0.02 is a happy R-factor. An R-factor between 0.02 and 0.06 diminishes the happiness by this formula:

     (R - 0.02) * 1000

Thus an R-factor of 0.03 reduces the happiness by 10. An R-factor in excess of 0.06 incurs the full hit of 40 to the happiness.

The R-factor of a fit in k-space will almost always be large due the effect of higher frequencies on the evaluation of the R-factor. Thus the scaling factor for the R-factor penalty is made 1/10 as big.

parameter values

Perform the sanity checks in Demeter::Path::Sanity. Penalize the happiness by 2 for each path parameter that fails a sanity check.

restraints

The restraints are added as fractional contributions to the evaluated chi-square and multiplied by a scaling factor.

     (restraint / chi-square) * scale

Thus a restraint that involves a guess parameter wandering farther away from its nominal value diminishes the happiness more. This works well with the penalty function. When the guess parameter is within its boundaries, the restraint will not diminish happiness.

nidp

Diminish happiness if the number of variables used is too large compared to the number of independent points. The full penalty is applied when all independent points are used. No penalty is applied if less than 2/3 of the independent points are used.

correlations

Diminish happiness for each correlation above a certain value. No penalty is applied if no correlations are too high.

METHODS

happiness

This method evaluates the happiness for a fit.

In list context, the return values are the net numerical value of the happiness and a text string summarizing each of the penalties against the happiness.

   ($happpiness_value, $happiness_summary) = $fitobject -> happiness;

In scalar context, just the numerical value is returned.

   $happpiness_value = $fitobject -> happiness;
color

This method returns a color representation of the happiness as a hexadecimal triplet.

   print $fit->color;
    ==prints==>
     #E2E995

This is intended as a visual representation of the happiness and could be used to color a GUI element as an ambient cue as to the quality of the fit. It takes four parameters. Three are colors representing the best fit, the worst fit, and an average fit. The last parameter is the happiness value that represents the worst fit. For instance:

   good fit           #C5E49A   a greenish color
   average fit        #FFEE90   a yellowish color
   bad fit            #FD7E6F   a reddish color
   minimum happiness  60

For happiness values between 60 and 80, the color is the linear interpolation between the bad and average colors. For happiness values between 80 and 100, the color is the linear interpolation between the average and good colors.

CONFIGURATION AND ENVIRONMENT

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

The following parameters are configurable so that the happiness algorithm can be tuned. See the happiness group of configuration parameters.

R-factor

The boundary values and the scaling factor. Defaults: 0.02, 0.06, 1000. The scaling factor is reduced to 1/10 its value for a fit in k-space.

parameter values

The per-failure penalty. Default: 2. Each penalty is configurable using the parameters in the warnings group.

restraints

The scaling factor. Default: 10.

nidp

The cutoff and the scaling factor. Defaults: 2/3 and 40.

correlations

The cutoff and the penalty for each high correlation. Defaults: 0.95 and 3.

DEPENDENCIES

Demeter's dependencies are in the Build.PL file.

BUGS AND LIMITATIONS

Aside from the obvious limitation that happiness is a non-statistical, ad hoc, non-reportable, and possibly ridiculous parameter, work needs to be done to tune the various happiness and warnings parameters.

Other possible penalties:

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.