Ifeffit::Demeter::Data - OO interface to Data for EXAFS data analysis with Ifeffit
This documentation refers to Ifeffit::Demeter version 0.0.1
my $data = Ifeffit::Demeter::Data ->
new({group => 'data0',});
$data -> set({file => "example/cu/cu10k.chi",
fft_kmax => 3, # \ note that this gets
fft_kmin => 14,# / fixed automagically
bft_rmax => 4.3,
fit_k1 => 1,
fit_k3 => 1,
label => 'My copper data',
});
$data -> plot("r");
This subclass of the Ifeffit::Demeter class is inteded to hold information pertaining to data for use in data processing and analysis.
The following are the attributes of the Data object. Attempting to access an attribute not on this list will throw an exception.
The type of argument expected in given in parentheses. i.e. number, integer, string, and so on. The default value, if one exists, is given in square brackets.
For a Data object to be included in a fit, it is necessary that it be an attribute of a Fit object. See the Ifeffit::Demeter::Fit manpage for details.
This is the name associated with the data. It's primary use is as the group name for the arrays associated with the data in Ifeffit. That is, its arrays will be called group.k, group.chi, and so on. It is best if this is a reasonably short word and it must follow the conventions of a valid group name in Ifeffit. The default group is a random four-letter string generated automatically when the object is created.
Use to disambiguate guess parameter names when doing variable name substitution for local parameters.
This is the file containing the chi(k) associated with this data object.
This is true if the file indicated by the file attribute contains
mu(E) data. See the description of the read_data method for how
this gets set automatically and when you may need to set it by hand.
This is true if the file indicated by the file attribute contains
chi(k) data. See the description of the read_data method for how
this gets set automatically and when you may need to set it by hand.
This is a text string used to describe this object in a user interface. Like
the group attribute, this should be short, but it can be a bit more
verbose. It should be a single line, unlike the title attibute.
This is true if the file indicated by the file attribute contains
column data that needs to be converted into mu(E) data. See the
description of the read_data method for how this gets set
automatically and when you may need to set it by hand.
This string contains Ifeffit's $column_label string from importing
the data file.
This string uses gnuplot-like notation to indicate which column in the
data file contains the energy axis. As an example, if the first
column contains the energy, this string should be $1.
This string uses gnuplot-like notation to indicate how to convert
columns from the data file into the numerator of the expression for
computing mu(E). For example, if these are transmission data and I0
is in the 2nd column, this string should be $2.
If these are fluorescence data measured with a multichannel analyzer
and the MCA channels are in columns 7 - 10, then this string would be
$7+$8+$9+$10.
This string uses gnuplot-like notation to indicate how to convert
columns from the data file into the denominator of the expression for
computing mu(E). For example, if these are transmission data and
transmission is in the 3nd column, this string should be $3.
This is true for transmission data, i.e. if cponversion from columns
to mu(E) requires that the natural log be taken.
The E0 value of mu(E) data. This is determined from the data when the
read_data method is called.
An energy shift to apply to the data before doing any further processing.
The k-weight to use during the background removal using the Autobk algorithm.
The Rbkg value in the Autobk algorithm.
The dk value to be used in the Fourier transform as part of the Autobk algorithm.
The lower end of the range of the pre-edge regression, relative to E0.
The upper end of the range of the pre-edge regression, relative to E0.
The lower end of the range of the post-edge regression, relative to E0.
The upper end of the range of the post-edge regression, relative to E0.
The lower end in k of the spline range in the Autobk algorithm. The value of bkg_spl1e is updated whenever this is updated.
The upper end in k of the spline range in the Autobk algorithm. The value of bkg_spl2e is updated whenever this is updated.
The lower end in energy of the spline range in the Autobk algorithm, relative to E0. The value of bkg_spl1 is updated whenever this is updated.
The upper end in energy of the spline range in the Autobk algorithm, relative to E0. The value of bkg_spl2 is updated whenever this is updated.
This is the functional form of the Fourier transform window used in the Autobk algorithm. It is one of
Kaiser-Bessel Hanning Welch Parzen Sine Gaussian
The slope of the pre-edge line. This is set as part of the normalize method.
The intercept of the pre-edge line. This is set as part of the normalize method.
The edge step found by the normalize method. This attribute will be overwritten the next time the normalize method is called unless the bkg_fixstep is set true.
The value of edge step found by the normalize method, regardless of the setting of bkg_fixstep. This is needed to correctly flatten data.
When true, the value of the bkg_step will not be overwritten by the normalize method.
The constant parameter in the post-edge regression. This is set as part of the normalize method.
The linear parameter in the post-edge regression. This is set as part of the normalize method.
The cubic parameter in the post-edge regression. This is set as part of the normalize method.
When true, a plot of normalize mu(E) data will be flattened.
When true, a functional normalization is performed. not yet iplemented
This can be either 2 or 3 and specifies the order of the post-edge regression. When this is 2, bkg_nc2 will be forced to 0 in the regression. not yet iplemented
The background removal standard. This can be either a Data object or a Path object. not yet iplemented
The value of the low-end spline clamp.
The value of the high-end spline clamp.
The number of data points to use in evaluating the clamp.
When true, use Cromer-Liberman normalization rather than the Autobk algorithm. not yet implemented
The Z number of the absorber for these data. This is determined as part of the normalize method but can also be set by hand. To deal with edge energy confusions, certain K and L3 edges are prefered over nearby L2 and L3 edges when this attribute is set automatically.
prefer over
----------------
Fe K Nd L1
Mn K Ce L1
Bi K Ir L1
Se K Tl L2
Pt L3 W L2
Se K Pb L2
Np L3 At L1
Cr K Ba L1
Note that there is not an fft_kw attribute. For all plotting and data
processing purposes, the Plot object's kweight attribute is used, while in
fits the Fit object's k1, k2, and k3 attributes are used.
fft_edge (edge symbol) [K]
The absorption edge measured by the input data. This is used doing a central-atom-only phase correction to the Fourier transform.
fft_kmin (number) [2]
The lower end of the k-range for the forward transform. fft_kmin and
fft_kmax will be sorted by Demeter.
fft_kmax (number) [12]
The upper end of the k-range for the forward transform. fft_kmin and
fft_kmax will be sorted by Demeter.
fft_dk (number) [2]
The width of the window sill used for the forward transform. The meaning of this parameter depends on the functional form of the window. See the Ifeffit document for a full discussion of the functional forms.
fft_kwindow (list) [Kaiser-Bessel]
This is the functional form of the Fourier transform window used in the forward transform. It is one of
Kaiser-Bessel Hanning Welch Parzen Sine Gaussian
fft_pc (Path object) [0]
This is set to the Path object to be used for a full phase correction to the Fourier transform.
rmax_out (number) [10]
This tells Ifeffit how to size output arrays after doing a Fourier transform.
bft_rwindow (number) [Kaiser-Bessel]
This is the functional form of the Fourier transform window used in the backward transform. It is one of
Kaiser-Bessel Hanning Welch Parzen Sine Gaussian
bft_rmin (number) [1]
The lower end of the R-range for the backward transform or the fitting range.
bft_rmin and bft_rmax will be sorted by Demeter.
bft_rmax (number) [3]
The upper end of the R-range for the backward transform or the fitting range.
bft_rmin and bft_rmax will be sorted by Demeter.
bft_dr (number) [0.2]
The width of the window sill used for the backward transform. The meaning of this parameter depends on the functional form of the window. See the Ifeffit document for a full discussion of the functional forms.
Note that parameters with fft_ and bft_ analogs such as
fft_kmin have been deprecated along with the process mode.
This is set to true when a Data object is used in a fit. It is used by plotting methods to determine whether data parts (fit, background, residual) should be considered for plotting.
If true, then k-weight of 1 will be used in the fit.
If true, then k-weight of 2 will be used in the fit.
If true, then k-weight of 3 will be used in the fit.
If true, then the user-supplied, arbitrary k-weight will be used in the fit.
This is the value of the arbitrary k-weight which will be used in the
fit is fit_karb is true.
This is the space in which the fit will be evaluated. It is one of
k, r, or q.
If this number is non-zero, it will be used as the measurement uncertainty in k-space when the fit is evaluated. If it is zero, then Ifeffit's default will be used.
This is the minimum value of correlation to be reported in the log file after a fit.
This is the Path object to use for phase correction when these data and it paths are plotted. It takes the reference to a Path object as its value.
When this is true, the data will be included in the next fit.
This is a flag for use by a user interface to indicate that after a fit is finished, this data set should be plotted.
When true, the background function will be corefined for this data set and the ``bkg'' part of the data will be created.
These are title lines associated with this Data object. These lines will be written to log files, output data files, etc.
This attribute indicates whether the Fit objects fit or ff2chi
mehthod was most recently called. It is one of fit or sum.
It's purpose is to allow the fit part of the data object to be labeled
correctly in a plot.
Most aspects of how plots are made are handled by the attributes of the Plot object. These Data attributes are specific to a particular Data object and influence how that object is plotted.
y_offset (number) [0]
The vertical displacement given to this data when plotted. This is useful for making stacked plots.
plot_multiplier (number) [1]
An over-all scaling factor for this data when plotted. It is probably a bad idea for this to be 0.
This subclass inherits from Ifeffit::Demeter, so all of the methods of the parent class are available.
These methods handle the details of file I/O. See also the save
method of the parent class.
save
This method returns the Ifeffit commands necessary to write column data files based on the data object. This method takes two arguments, the output filename and the type of the output file. The types are:
This is a 7 column file: energy, mu(E), bkg(E), pre(E), post(E), derivative of mu(E), and second derivative of mu(E).
This is a 7 column file: energy, normalized mu(E), normalized bkg(E), flattened mu(E), flattened bkg(E), derivative of norm(E), and second derivative of norm(E).
This is a 6 or 7 column file: k, chi(k), window, k*chi(k), k^2*chi(k), and
k^3*chi(k). If the fft_karb attribute is true, then seventh column containg
the fft_karb_value-weighted chi(k) will be included.
This is a 6 column file: R, real part, imaginary part, magnitude, phase, and window.
This is a 7 column file: back transform k, real part, imaginary part,
magnitude, phase, and window in k. The last column is the original chi(k)
weighted by the k-weight used in the Fourier transform.
This is a 5 or 6 column file: k, chi(k), fit(k), residual(k), and k-window.
If the fit_do_bkg attribute is true, then the background in k will be the
column between the residual and the window.
$command = $dobject->save("cufit.fit", "fit");
This method will automatically generate useful headers for the output
data file. These headers will include the title lines associated with
the data in Ifeffit and the text of the fit_parameter_report method.
data_parameter_report
This method returns a simple, textual summary of the attributes of the data object related to background removal and data processing. It is used in log files, output data files, and elsewhere. It may also be useful as a way of interactively describing the data.
fit_parameter_report
This method returns a simple, textual summary of the attributes of the data object related to the fit. It is used in log files, output data files, and elsewhere. It may also be useful as a way of interactively describing the data. The two optional arguments control whether the r-factor is computed as part of the report.
r_factor
This returns an evaluation of the R-factor from a fit for a single data set. This is different from the R-factor for a multiple data set fit as reported by Ifeffit in that this number includes only the misfit of the single data set.
$r = $data_object -> r_factor;
nidp
This returns the number of independent points associated with this data set, as determined from the values of the k- and R-range parameters.
$n = $data_object->nidp;
The Athena-like fft and bft ranges are used if the processing mode is set to ``fft''. The Artemis-like fit ranges are used if the processing mode is set to ``fit''.
The Data object has several parts associated with it. Before a fit
(or ff2chi) is done, there are two parts: the data itself and the
window. After the fit, there is a residual, a fit, and (if the
fit_do_bkg attribute is true) a background. The various methods for
Fourier transforming, plotting, and saving column data files can be
made to operate on one or more of the parts.
These methods are called by the plot method of the parent class
or by other methods. Indeed, it may never be necessary to call any of
these directly, but they are documented here to allow fine-grained
control over the Data object.
read_data
This method returns the command needed to import data from a column
data file into Ifeffit. These data must be either mu(E) or chi(k)
data. If they are mu(E) data, then methods of this object will be
used to extract chi(k) using the Autobk algorithm.
$command .= $data_object->read_data;
This method also tries to figure out whether the data are raw data,
mu(E) or chi(k) data, if that has not already been determined. The
heuristics are as follows:
If the numerator or denominator attributes are set, this is data
is assumed to be column data that will be interpreted as raw data and
converted in mu(E) data.
The data will be read by Ifeffit. If the first data point is greater
than 100, it will be assumed that these data are mu(E) and that the
energy axis is absolute energy.
If the last data point is greater than 35, it will be assumed that
these data are mu(E) and that the energy axis si relative energy.
If none of the above are true, then the data must be chi(k) data.
If your data will be misintepreted by these heuristics, then you
must set the is_xmu of is_chi attributes by hand.
part_fft
This method returns the Ifeffit command needed to forward Fourier transform the fit, residual, or background parts of the Data object.
$command = $data_object->part_fft($part);
part_bft
This method returns the Ifeffit command needed to backward Fourier transform the fit, residual, or background parts of the Data object.
$command = $data_object->part_bft($part);
part_plot
This method returns the Ifeffit command needed to plot the fit, residual, or background parts of the Data object.
$command = $data_object->part_plot($part, $space);
plot_window
This method disposes the command to plot a Fourier transform window
$data_object->plot_window($space);
_plot_window_command
This methods return the Ifeffit command needed to plot the window in the plotting space. The window will be scaled to the size of the data.
$command = $data_object->plot_window($space);
set_windows
This is a shortcut to setting the functional form of all Fourier
transform windows used by the Data object. In one swoop, this method
sets bkg_kwindow, fit_kwindow, fit_rwindow, fft_kwindow,
and bft_rwindow to the specified window type.
$data_object -> set_windows("Hanning");
The window type must be one of Kaiser-Bessel, Hanning, Parzen, Welch, Sine, or Gaussian.
This method returns the reference to the data object itself. This is
less silly than it seems. Having a data method defined for both
Data and Path objects allows a loop over both kinds of objects and
provides a simple way to identify the correct Data object.
foreach my $obj (@data_objects, @paths_objects) {
my $d = $obj->data;
## do something with $d
};
When the reference to the Data object is used in string context, it returns the group name. So
my $data = Ifeffit::Demeter::Data ->
new({group => 'data0',
file => "example/cu/cu10k.chi",
label => 'My copper data',
});
print "This is $data.\n";
will print
This is data0.
Rather than
This is Ifeffit::Demeter::Data.
These messages are classified as follows (listed in increasing order of desperation):
(W) A warning (optional).
(F) A fatal error (trappable).
(W) You have attempted to access an attribute that does not exist. Check the spelling of the attribute at the point where you called the accessor.
(F) You have used a group name that does not follow Ifeffit's rules for group names. The group name must start with a letter. After that only letters, numbers, &, ?, _, and : are acceptable characters. The group name must be no longer than 64 characters.
(F) You have attempted to set a numerical attribute with something that cannot be interpretted as a number.
(W) You have called the display method on a Data object with an invalid part. The valid parts are
data fit bkg res win
(F) You have called teh save_fit method without supplying a filename for the output file.
(F) You have attempted to call the part_fft method on a part that does not exist of that cannot be Fourier transformed. For this method, part must be one of
fit res bkg
(F) You have attempted to call the part_bft method on a part that does not exist of that cannot be Fourier transformed. For this method, part must be one of
fit res bkg
(F) You have attempted to call the part_plot method on a part that does not exist of that cannot be Fourier transformed. For this method, part must be one of
fit res bkg
The window has its own plotting method: plot_window.
The serialization format of a data object is as a YAML file. The YAML
serialization begins with a mapping of the Data object attributes. This is
followed by sequences representing the data. For mu(E) data, the sequences
are energy and xmu. If the data was column data, the xmu sequence is followed
by a sequence representing the i0 array. For chi(k) data, the mapping is
followed by sequences representing k and chi(k).
What about standard deviation for a merged object?
To serialize a Data object for a file:
$data -> serialize($filename);
To import the serialized data and create a Data object to hold it:
$data -> deserialize($filename);
As a convenience Dump and freeze are synonyms for serialize. Load
and thaw are synonyms for deserialize.
Among the many attractive features of YAML as a serialization format is that YAML is supported by lots of programming languages. So Demeter serialization can be imported easily into other analysis software.
See the Ifeffit::Demeter manpage for a description of the configuration system.
The dependencies of the Ifeffit::Demeter system are in the DemeterBundle.pm file.
None of the Athena-like data process methods (alignment, merging, and so on) have been implemented at this time.
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.