Artemis - interactive EXAFS data analysis
Artemis is a program for analyzing EXAFS data using theoretical standards
from
Feff.
Artemis includes interfaces to
Atoms and
Feff as well as forms for defining parameters and applying those
parameters to the paths from the
Feff calculation.
Artemis uses
chi(k) as it's input. It does not handle any data processing chores, such as
converting raw data to mu(E) or doing background removal.
Artemis's
sister program
Athena is the data processing program.
Artemis is a graphical and interactive program written in the perl
programming language, using the Tk display engine, the
Ifeffit EXAFS
library, and the PGPLOT plotting library. (See below for a list of relevant
URLs.)
Artemis helps you organize all aspects of a fitting project, including
running the
Feff calculation, settings parameters for the Fourier
transform and fitting of the data, parameterizing the paths from the
Feff calculation, running the fit, and plotting the results. The
Artemis window is divided into three panels. The largest panel is the
space where most of the work happens. Its content is model and depends on the
state of the Data and Paths List. This list is in the center, skinny panel.
The other skinny panel contains the controls the are used to specify how plots
are made.
At the top of the window are the menubar and the project bar. The project bar
displays the name of the current project file. It also contains an indicator
that tells you if the project has been modified since the last time it was
saved. Clicking on the modified indicator will save the project (just like C-s
or the "Save project" item in the File menu). At the bottom of the
screen is the echo area, where
Artemis writes all sorts of helpful
messages as you use the program.
The Data and Paths list contains a tree-like list of all of the objects that can
be manipulated as you use
Artemis. When the program starts, two such
items are displayed. As you run
Feff calculations, import
Feff
paths and other data sets, and run fits, more items are added to this list. In
total, there are five kinds of entries in this list, each of which controls a
diffferent aspect of
Artemis. These five kinds of list entries are: (1)
fitting parameters, (2) data, (3) fits, (4)
Feff calculation, or (5)
Feff path. When you click on an item in the Data and Paths List, that
item will be "selected" and "anchored". A selected item is
highlighted in orange. An anchored item is outlined with a dashed line. Only
one item can be anchored. 0, 1, or more items can be selected.
The anchored item determines the mode of the large panel. For instance, when the
"Guess, Def, Set" item is anchored, the main panel will display a
page used for setting the fitting parameters. When a data item is anchored,
the main panel will display a page for setting Fourier tranform parameters,
the fitting range, and other parameters associated with the data. Many
functions in
Artemis depend upon the mode of the main panel. Some
features are available only in certain modes. Each of the modes is described
in its own document section. See "SECTIONS OF THE DOCUMENT".
Plots in
Artemis are always made using the selected items. To plot, for
example, data, a fit, and several individual paths, it is necessary to select
each of those items. Many other functions in
Artemis also work on the
set of selected items.
Anchoring and setting paths is usually done by using the mouse in the Data and
Paths List, although there are several other ways of changing the anchor and
selection using the mouse or the keyboard. Here is a list of mouse events
useful in the Data and Paths List:
- Left mouse button
- Clicking the left mouse button will clear all selections
then select and anchor the item clicked. The main panel will display the
page apporpriate to the anchored item.
- Center mouse button
- Clicking the center mouse button will anchor the item
clicked without changing the selection. The main panel will display the
page apporpriate to the anchored item.
- Right mouse button
- Clicking the right mouse button will anchor the item
clicked without changing the selection. It will also post a menu of
functions appopriate to the item clicked. These menus are the same as the
menus in the menubar at the top of the window. The main panel will display
the page appopriate to the anchored item.
- Control key + left mouse button
- Clicking the left mouse button while holding down the
control key will add the item clicked to the group of selected items. The
anchor is not changed.
- Shift key + left mouse button
- Clicking the left mouse button while holding down the shift
key will select all items between the anchor and the item clicked,
inclusively. The anchor is not changed.
- Left mouse button + mouse drag
- Clicking the left mouse button then dragging the mouse
while holding down the button will select all items that you drag the
cursor over. The item initially clicked will be anchored and the main
panel will display the page appopriate to the anchored item.
- Control-k, Control-j
- Hitting the k or j keys while holdong the control key will
move the anchor to the previous or next item in the list without changing
the selection. The main panel will display the page appopriate to the
anchored item. These two key sequences, behave differently when the Guess,
Def, Set item is anchored. See The Guess, Def, Set page for details
- Control-l
- Hitting the l key while holding down the control key will
put focus on the Data and Path List. This allows you to navigate the list
using the arrow keys.
The color and font of the text in the Data and Paths List indicates the status
of each item. Any item written in black, upright text is an item that can be
plotted. When a data set or
Feff path is excluded from the fit, it will
be written in brown text. The Guess, Def, Set item and the
Feff
calculation items are written in italic text. The italic text indicates items
that cannot be plotted. Although these non-plotable items can be selected,
they will be ignored when a plot is made.
ARTEMIS - The data page
The data page is displayed in
Artemis's main panel when a data item is
anchored in the Data and Paths List. See the main document section for an
explanation of anchoring and selecting items in the Data and Paths List.
The data page is divided into five sections. At the top is a box containing the
title lines associated with these data. These are read from the input data
file, but can be edited at any time by the user. When the data are written to
output files, the contents of this box are written as headers. Below the
titles box is the name of the data file that was imported. Below that are four
boxes containing groups of related controls.
This box contains three toggles that control certain aspects of the fit. The
first two are only relevant in a multiple data set fit. When setting up a
project containing a multiple data set fit, it is sometimes useful to exclude
an entire data set from the fit without deleting it from the project. This can
be done with the first toggle. When a data set is excluded, it and all items
beneath it are shown in brown text in the Data and Paths List to indicate that
they have been excluded from the fit.
After the fit is complete,
Artemis wants to show off her handiwork and
display a plot of the data and the just-finished fit. In the case of a
multiple data set fit, you might have a preference about which data set gets
plotting. Click this toggle on for your prefered data set.
The third toggle tells
Artemis to do a corefinement of the background
spline when it performs the fit. This corefinement is, effectively, the same
operation that was performed by
Athena to remove the background from
the data. The "rmin" parameter serves the same purpose as
Athena's "rbkg" parameter. When the fit is performed with the
background corefinement, a spline is used to fit the Fourier components of the
data below "rmin" and the
Feff paths are used to fit the
Fourier components between "rmin" and "rmax". The number
of parameters used to determine the spline is the number of independent points
in that portion of the data: "2*delta_k*delta_R/pi", where
"delta_k" is the range of the Fourier transform and
"delta_R" is the range between 0 and "rmin". The advantage
of doing the background corefinement, other than the possibility of making the
fit look nicer at low R, is that correlations between the background
parameters and the fitting parameters can be measured.
This box contains the controls used to set the ranges of the forward Fourier
transform and of the fit. The fit range is also used as the backward Fourier
transform range when a plot is q space is made. See "Pluck buttons"
for a discussion of the little quare buttons marked with a blue x.
Other controls are used to set the functional forms of the Fourier transform
window used in k and R. The widths of the sills of those functions are set
usng the entry boxes labeled "dk" and "dr".
The controls in this box are used to set the values of k-weight to be used in
the fits. There are togles for turning on k-weight of 1, 2, or 3. There is
also a toggle for specifying an arbitrary value of k-weight.
These are the k-weight values used in the fit but not the k-weight used to plot
the data. These two purposes of k-weight are handled independently by
Artemis. See Plotting in Artemis for a discussion of the plotting
k-weight controls.
People sometimes get confused by the concept of multipl k-weights for fitting.
The prupose of choosing a low or high value for k-weight is to attempt to
emphasize either the low- or high-k end of the data. Because different regions
of the data are sensitive to different kinds of parameters, one might choose a
low or high value to increase the precision of measurement of certain
parameters. Doing multiple k-weight fits is a sort of compromise -- a way of
emphasizing both ends of the data in the fit.
The fit is determined by minimizing a quantity called chi-square. Chi-square is
evaluated by summing the squares of the difference between the data and the
theory. Since the FT is complex, there is a real part and an imaginary part.
So chi-square is proporitional to:
/ \
sum < Re[ data(R) - th(R) ]^2 + Im[ data(R) - th(R)]^2 >
R \ /
In a multiple k-weight fit, there are simply more terms in the sum. Let's take a
kw=1&3 fit as an example. This summation is made for the kw=1 data and
theory.
And the summation is made for the kw=3 data and theory. The
summations are added together and the full sum is used to evaluate chi-square.
At the end of the day, there is only one set of guess parameters that have been
optimized by the fit. These guess parameters along with the set parameters are
used to evaluate the def parameters and the path parameters. The path
parameters are used to evaluate the exafs equation for each path. The exafs
equations for the paths are summed up to make the best-fit theoretical chi(k).
You have a data chi(k) and a best-fit chi(k). Those can then be plotted
however you like -- even using a k-weight that was not used in determining the
fit.
The last box contains several controls that did not fit into theother boxes.
There is a menu for selecting the fitting space. You can choose to fit the
data in any of k, R, or q space. The default is to fit in R.
Epsilon is the uncertainty used to evaluate chi-square. Normally it is fine to
let
Artemis use the default value (which is determined from the RMS
value of the data between 15 and 25 angstroms in R-space). In some situations,
you may find it useful to explicitly set a value for epsilon.
After the fit,
Artemis writes a log file documenting the fit. Among the
information in that log file are the correlations between all the fitting
parameters. You can set the level below which
Artemis will exclude a
correlation from this report.
Finally, there is a menu for selecting the path to use for phase corrected
plots. This menu contains the first five paths from each
Feff
calculation used with the data set. When a path is selected for phase
corrected plots, the full phase shift of that path -- both the central atom
and scattering atom portions -- will be subtracted from anything that is
Fourier transformed before it is plotted. If a path is selected for phase
correction and you make a plot of, say, the data, the fit, and several paths,
the selected phase shift will be subtracted from each item before it is
plotted. Phase correction is for plotting only. Fits are always done on
non-phase-corrected data.
Several of the controls on this page a have a small button with a blue x next to
them. These are called pluck buttons and are used for grabbing values from the
plot window. When you click on one of these buttons, a prompt will be written
to echo area asking you to click on a pointin the plot. When you do so, the
value that you clicked on will be inserted into the entry box adjacent to the
pluck button.
Artemis is careful not to let you pluck a k-value from a
plot in R, or vice versa.
As you pass the mouse over labels on the data page, the text under the mouse
will change color. This color change is an indication that mouse clicks will
do something. A left mouse click on one of these labels will cause a brief
description of that parameter to be displayed in the echo area. Many of these
descriptions also suggest reasonable values for the parameter.
Clicking the right mouse button on one of the labels will post a context menu of
useful function. One such function is restore that parameter to its default
value. If you have a muliple data set fit, the other menu options allow you to
constrain the parameter between data sets.
The labels at the top of the boxes are all sensitive to the left mouse button.
The labels atop the Fourier transform and fit range box and the k-weights box
are also sensitive to the right mouse click.
ARTEMIS - Guess, set, def parameters
This page is used to define the parameters of the fitting model. In
Artemis there are six kinds of parameters:
- Guess
- Guess parameters are the ones that are optimize during the
course of the fit to best-fit the theory to the data.
- Def
- Def parameters are typically expressed as math expressions
which may be functionally dependant upon other parameters. These math
expressions are updated throughout the course of the fit. As the guess
parameters are update, so are the def parameters.
- Set
- Set parameters are evaluated at the beginning of the fit
and not updated throughout the fit. This is the main difference between
def and set parameters. Set parameters can be numbers or math
expressions.
- Restraint
- Restraints are math expressions which, like def parameters,
are updated throughout the course of the fit, but which take on a special
role in the fit. A restraint is evaluated and added in quadrature to the
evaluation of the chi-square parameter. A restraint, therefore, can be
used to incorporate a a bias in the fitting result towards a piece of
prior knowledge about the physical system. See the Ifeffit for a
complete discussion of restraints.
- Skip
- Skip parameters are maintained in the project but are not
used in any capacity in the fit. The point of a skip parameter is to
maintain but not use a complicated parameter with a complicated math
expression.
- After
- An after is similar to a def parameter in that it may be a
math expression dependent upon other parameters. An after is not, however,
a part of the fitting model. Instead it is a parameter that will be
evaluated upon completion of the fit using the best fit values. The list
of after parameters will be reported in the log file. Using an after
parameter anywhere in your fitting model will result in Artemis reporting
an error in the model. Afters can depend upon other afters, but you should
take care in with the order that the afters appear in the list. The after
parameters will be evaulated only once after the fit, thus circular or
out-of-order dependencies will not be resolved.
The Guess, Def, Set page is divided into two sections. At the top is a listbox
containing the list of all defined parameters. At the bottom is the edit area
which contains the controls used to establish the parameters.
This area contains a four-column list of all the parameters defined in a
project. The left-most column counts the parameters. The second column
contains a tag identifying the type of the parameter. The third column
contains the parameter name. The right-most column contains the parameter's
math expression.
Parameters are coded by color and by the tag in the second column. Guess
parameters are written in purple text and have the "g:" tag. Def
parameters are written in green text and have the "d:" tag. Set
parameters are written in black text and have the "s:" tag.
Restraints are written in pink text and have the "r:" tag. Skip
parameters are written in grey text and have no tag. After parameters are
written in blue-grey text and have the "a:" tag.
There are a large number of mouse clicks and key sequences that serve a purpose
in the listbox:
- 1.
- A left mouse click selects a parameter and displays it in
the edit area.
- 2.
- A double click of the left mouse button selects a
parameter, displays it in the edit area, and prompts you for the parameter
annotation. See "Parameter annotations".
- 3.
- A right mouse click selects a parameter, displays it in the
edit area, and posts a contextual menu about that parameter. The menu has
several items in it. The "Move" submenu is sued to reposition
the current parameter in the list. The "Make" submenu serves to
change the type of the parameter. The "Copy" item will replicate
the anchored parameter, appending a few characters to the end of its name.
The "Build restraint" item is discussed below. The
"Annotate" menu item prompts for the parameter annotation. The
"Find" menu item will search through all parameter and path
parameter math expressions and show you how that parameter is used in the
project. The "Grab" menu item is only enabled for guess
parameters and will insert the best-fit value from a fit as the value for
that parameter. Finally the "Discard" menu item will remove that
parameter from the list after prompting for confirmation.
- 4.
- Control-d will define the parameter in the edit area.
- 5.
- Control-g will grab the current parameters best-fit value
from a fit.
- 6.
- Control-e will show the editing area if it is hidden.
- 7.
- Control-k and control-j will move the selection up and down
in the list. Note that these two key-sequences serve to move the anchor up
and down in the Data and Path List when the Guess, Def, Set page is not
showing.
- 8.
- Control-n will clear the selection and focus on the
parameter name entry box so that you can create a new parameter.
- 9.
- Control-y will prompt you to then hit any of the g, d, s,
r, k or e keys to set the type of the parameter. This is only way of
setting the parameter type that does not involve the mouse.
Multiple items in the list of parameters can be selected using the
control-click, shift-click, and click-drag sequences described for the Data
and Paths List and for the log viewer. Only the anchored list item (i.e. the
one surreounded by a dashed line and displayed in the edit area) can have its
name and math expression edited.
The advantage of extended selection is that certain of the context menu options
discussed above in item #3 can operate on many parameters at once. By doing
extended selection then clicking the right mouse button somewhere in the
selected region, the context menu will be posted with options for the group of
selected parameters. Currently, groups of parameters can have their types set
and can be discarded in this manner.
If you right-click outside the selected region, the extended selection will be
cleared and the parameter clicked on will be anchored and selected.
There are three rows of controls in the edit area. The top row has two entry
boxes. The smaller one on the left is for entering the name of the parameter.
The larger one on the right is for entering the parameter's math expression.
Below the entry boxes are a set of five radiobuttons for selecting the type of
parameter being edited.
At the bottom of the edit area are five buttons for acting upon the parameter
being edited. The "Undo edit" button clears the entry boxes and
discards whatever changes were just made. The "New" button is used
to define a brand new parameter. It clears the entry boxes, unselects
parameters in the listbox, and gives focus to entry box for entering the
parameter name. The "Grab" button becomes enabled after a fit is
run. It inserts the best-fit value for a guess parameter. The
"Discard" button deletes a parameter from the list. A dialog pops up
confirming deletion. Finally, the "Hide" button removes the edit
area from view to allow more parameters to be visible in the listbox. When the
edit area is hidden, it is replaced by a button for restoring the edit area.
Here are the details of the behavior of these controls:
- 1.
- Hitting return in the parameter name entry box defines the
parameter, inserts or updates it in the listbox, and puts focus on the
math expression entry box. If a math expression has not yet been defined,
the parameter will be defined as 0.
- 2.
- Hitting return in the math expression entry box defines the
parameter, inserts or updates it in the listbox, and leaves focus on the
math expression entry box.
- 3.
- Clicking on any of the radiobuttons defines the the
parameter, inserts or updates it in the listbox, and leaves the focus
unchanged.
An annotation is a short text string that is associated with the parameter. This
string is written to the echo area whenever the parameter is selected in the
listbox on the Guess, Def, Set page. The purpose of he annotation is to write
a little hint about the role played by the parameter in the fiting model. If a
guess parameters has no annotation when a fit is run, its annotation will be
generated automatically. The automatic annotation for a guess parameter is its
best fit value +/- its error bar. The automatic annotation for a def, after,
or restrain parameter is its evaluated value after the fit.
One of the items in the context menu displayed when right-clicking on a
parameter is for building restraints based on guess or def parameters. This
tool provides a dialog for constructing one particular type of restraint --
the type that coerces a parameter to stay within a boundries for its value.
The dialog prompts for a minimum and maximum value and for a term called the
"amplifier". The math expression constructed is this one:
restrain param_res = penalty(param, min, max) * amp
The penalty function evaluates to 0 when "param" is between
"min" and "max", to "abs(min-param)" when
"param" is less than "min", and to
"abs(param-max)" when "param" is greater than
"max". This is added in quadrature to reduced chi-square as the fit
is evaluated.
The amplifier term determines the magnitude of the penalty. A large value for
"amp" will force the fitted value of "param" not to stray
too far outside its bounds. A small value will allow the fit more freedom to
let "param" deviate from your initial guess.
See the
Ifeffit FAQ, question 8.1 for more discussion of restraints,
including discussion of other ways to set restraints that do not involve the
"penalty()" function.
A cautionary note: restraints are not always appropriate. As an example, if a
fit is returning a negative value for sigma^2, it may not be appropriate to
apply a stiff restraint as a way of forcing that sigma^2 to be a value that
you expect. Often, a negative sigma^2 is indicative of some other problem in
the fitting model such as excessive structural disorder, a coordination number
that is forced to be too small, the incorrect atomic species for a
backscatterer, or some such. Using a restraint on sigma^2 in a case like this
would not fix the problem. Quite the opposite, it might foster a false sense
of accomplishment by "fixing" the sigma^2 "problem"
without actually addressing the actual problem in the fitting model.
There is an option in the GDS menu for highlighting parameters. This prompts you
for a text string. Any parameter names or math expressions that match that
string will be marked with a green background. This is particularly useful for
large parameter lists. The text string is interpreted as a perl regular
expression and so any valid perl metacharacters can be used. (This includes
regular expressions using "(?{ code })" and other similar
constructions, a practice the author of
Artemis does not recommend, but
does not prevent.)
For large, complex fitting models, it may be convenient to edit the parameter
list with a text editor or even to write a program which generates the
parameters and writes them to a text file. In that case, it is convenient to
be able to import and export a textual respresentation of the parameter list.
These files are of a simple format. Any line like these:
guess a 5
set b 6
def c a+b
can imported to and exported from the Guess, Def, Set page via the GDS menu. In
an imported file, any line beginning with any of "guess",
"def", "set", "restrain", "after", or
"skip" will be imported as a parameter. The second word on the line
will be taken as the parameter name and the remaining words on the line will
be concatinated to form the math expression. On export lines will follow this
format:
type name = math_expression
Very little error checking is performed upon import to verify that the parameter
is defined sensibly, so use this feature with caution.
ARTEMIS -
ATOMS, The Crystallographic Front End to
FEFF
The purpose of
Atoms is to generate a "feff.inp" file from
crystallographic data. The hard part of making a "feff.inp" file is
creating the long list of atomic coordinates.
Atoms thus makes the hard
part of running
Feff easy, at least for crystalline matrials.
This page can be used to create input data for
Atoms from scratch. It
will also be used to display crystallography data imported from an
"atoms.inp" file or a CIF file. To import an "atoms.inp"
file or CIF file, use the normal file import dialog.
At the top is a text box for entering title lines identifying the
crystallographic data. These lines will be written to the "feff.inp"
file and to the top of the
Feff interpretation page. This is a good
place to cite the literature reference or to provide other important
information about the crystal.
To the left side of the page are entry boxes for entering space group, lattice
constants, and lattice angles of the crystal. A space group must always be
provided.
Atoms is very flexible about how the space group symbol is
entered. You can use the Hermann-Maguin or Scheonflies symbols or the index of
the space group from the International Tables. The algorithm that interprets
the symbol is insensitive to white space and capitalization -- "P m -3
m" and "PM-3M" are interpreted the same. For complete details
about how the symbols are interpreted, see the
Atoms docuemntation on
Bruce's web site.
Lattice constants are entered in units of Angstroms, angles are entered as
decimal numbers in degrees (and not in arc minutes -- i.e. 89 and a half
degrees is entered as 89.5 rather than 89'30"). Many space groups have
symmetries that make some lattice angles and constants the same. In those
situations, it is only necesary to fill in the essential values. For instance,
a cubic space group only requires a value for the "a" constant.
Atoms will know to set the other lattice constants the same and to set
the angles to 90 degrees. For lower symmetry groups, you must provide all the
necessary information.
Below the lattice constants are entry boxes for "Rmax" and the shift
vector and a menu for selecting the absorption edge of the
Feff
calculation. "Rmax" is the radial extent of the cluster that will be
written to the "feff.inp" file. Some space groups are given in the
International Tables with two different origins -- i.e. the origin is placed
at sites with two different point symmetries. The fractional coordinates of
the sites are different for the two different settings of the crystal. In
those cases,
Atoms requires that you use a particular one of the two
choices. If your input data has used the other origin choice, it should be
fairly obvious. In that case, coordination numbers and distances to the
coordination shells will usually be obviously wrong. When you use one of the
space groups for which two origin choices exist,
Artemis will issue a
warning. If you suspect that the wrong origin choice has been used, insert the
values for the shift vector that were reported in the warning message.
On occassion, crystals are reported in the literature using origins other than
the standard one used in the International Tables. A famous example is
germanium oxide. Here is the crystal data for GeO2:
title GeO2 (hexagonal)
space p 32 2 1
a=4.98502 c=5.64800
rmax=6.0 core=Ge
shift 0 0 0.66667
atoms
Ge 0.4513 0.0 0.0
O 0.3969 0.3021 0.0909
For some reason, the crystallography reference for this material uses an origin
that is shifted by 2/3 in the z direction relative to the origin used in the
International Tables. To get
Atoms to compute this structure correctly,
the shift vector given above must be used.
To the right side of the page is the list of unique crystallographic sites. As
new sites are created, they are inserted into the list. The sites are not
edited directly, instead the editing area at the bottom of the screen is used
and the list of all sites is displayed here. This works much the same as the
Guess, Def, Set page.
To edit a site, left-click on its entry in the list. It's element symbols,
coordinates, and site tag will be displayed in the edit area. A right click on
a site in the list will post a context menu with several functions that can be
perfromed on that site. You can re-order the list using the "Move"
menu item. A site can be copied and the copy added to the list using the
"Copy" menu item. The "Discard" menu item completely
removes the site from the list. The list supports extended selection. When
many sites are selected (i.e. highlighted in yellow), the "Discard"
menu item will work on all the selected sites.
Sites can also be reordered using the keyboard. "Alt-k" and
"Alt-j" can be used to move the selected site up or down in the
list.
At the bottom of the page is the collection of widgets used to actually create
and edit unique crystallographic sites. The element box is used to insert the
two-letter element symbol for the site. The site will not be created if this
is not a valid symbol. The tag can be any 10-letter string used to identify
the site. The tag is used to differentiate sites that contain the same
element.
The boxes for the "x", "y", and "z" coordinates
can be filled with floating point numbers or simple fractions. That is, 0.5
and "1/2" are both acceptable. These coordinates are fractional
positions in the unit cell and are not Cartesian coordinates.
Once you have created all sites in your crystal, click the "Run Atoms"
button. This will process the crystallographic data, create the
"feff.inp" file, display the "feff.inp" page.
The "feff.inp" data that is generated when the "Run Atoms"
button is pressed is determined by the contents of a special template file.
Artemis is distributed with a number of template files serving
different purposes. The structure of the "feff.inp" data is set by
the value of the "atoms->template" preference. The default value
is "feff", which tells
Artemis to use the template file
suitable for running
Feff6.
If you want to run some other version of
Feff, you should set the
"atoms->template" preference variable to the appropriate value.
Templates are provided with
Artemis for writing
Feff7 and
Feff8 input files.
Feff8 input files can be written which are
suitable for XANES or non-self-consistent EXAFS calculations.
Sometimes, it is useful to modify template files for writing out specialized
"feff.inp" data. If these modified template files are placed in
"~/.horae/atp/" (unix) or "C:Program
Files\Ifeffit\horae\atp" (windows),
Artemis will be able to find
them.
A full explanation of how the
Atoms algorithms works is beyond the scope
of this document page.
ARTEMIS - The
FEFF input file
This page displays the
Feff input data, which includes some control
parameters and a long list of atomic coordinates. This page is no more
sophisticated than a text box which serves as a primitive editor and a button
at the bottom for running
Feff. Explaining
Feff is beyond the
scope of this document.
When
feff is finished, you will presented with a dialog asking how many
paths to import. The choices are none, the first path, the first 10 paths, and
all paths. The number in the third option is configurable in the preferences
dialog. Should you ever need to rerun
Feff after starting a project,
"none" is usually the right answer. The other options may result in
one or more paths being defined twice in the project -- a confusing situation.
If
Feff fails to run to completion,
Artemis will try to recognize
the problem and post a suggestion for how to solve the problem. If
Artemis does not recognize your problem, explain it Bruce so he can add
that problem to
Artemis's database of troubleshooting solutions.
ARTEMIS - Interpretation of the
FEFF calculation
This page provides a concise overview of the
Feff calculation. At the top
of the page is a summary of some of the statistics of the calculation. Below
that is a chart showing the details of each path from the calculation. For
each path, the degeneracy, the half path length and the amplitude factor are
shown. The last column shows a tokenized summary of the scattering path --
this allows you to see at a glance which atoms were involved in the path.
The information and context menus available on this page allow you organize,
understand, and manipulate the paths in this
Feff calculation. Pretty
much all functions involving the paths
except writing math expressions
for the path parameters are available on this page.
The colors and fonts used in the chart convey information:
- Bold, black font
- These are paths that have been imported into the project
and are included in the fit.
- Bold, brown font
- These are paths that have been imported into the project
but are excluded in the fit.
- Normal, black text
- These are paths that have not been imported into the
project but which are available to be imported.
- Normal, grey text
- These are paths that are unavailable for importation into
the project. These can be made available by re-running the Feff
calculation. After the Feff run, it is best to choose the
"import no paths" to avoid reimporting paths already in the
project. After that, these paths will be written in normal, black text,
indicating that they are available for import.
- Light brown background
- The light brown background is used to indicate single
scattering paths.
- Light blue background
- The light blue background is used to indicate collinear or
nearly collinear multiple scattering paths.
There are interesting and useful context menus on every part of this page. These
menus are available by right clicking.
Right clicking anywhere in the text box at the top of the page will pop up a
menu with options for viewing files from the
Feff calculation.
Right clicking in the interpretation chart will post a menu of options relevant
to the path on the line on which you clicked. Each of the four kinds of paths
given by the four fonts described above has its own menu.
For paths that are imported in the fit, the menu offers options for plotting the
path, displaying that path's page, including or excluding the path in the fit,
selecting or deselecting that path for plotting, making that path the default
for evaluation of def parameters after a fit, displaying the text of the file
containing the path, or discarding the path. The choices for including or
excluding and for selecting or deselecting depend on the state of that path in
the Data and Paths List. Also some options might be greyed out depending on
the state of that path.
For paths that have not been imported into the project, the context menu allows
you to import the path with the option of displaying its page or leaving the
display on the
Feff interpretation. For paths that are unavailable for
import, a message saying so is posted when one of those lines is
right-clicked.
The interpretation chart allows for extended selection of lines in the chart.
You can select additional paths by holding the control key while clicking with
the left mouse button. Holding the shift key while left clicking selects all
line between the anchor (the one outlined with a dashed line) and the one you
click on. You can also click and drag to select all the lines you drag over.
When more than one line is selected, the content of the context menu change to
reflect functionality that makes sense for many paths. Extended selection in
the interpretation chart is therefore a good way of including/excluding,
selecting/deselecting, or plotting a large number of paths.
The context menu that pops up when many lines are selected may be a little
surprising. Its contents depend upon the state of the anchored line, which in
this case is the one that you right-click on to post the menu. The options in
the context menu will be suitable to the state of the anchored selection
regardless of the states of the other selected lines. If you choose a menu
item that does not make sense for some of the selected lines, those lines will
be ignored.
Here is a concrete example. Suppose that you select a number of lines, some of
which are included in the fit and some of which have not been imported in the
fit. If you then right click on one of the included paths, you will get
options appropriate to included paths. If you then ask to plot the selected
paths along with the data, the included paths will be plotted and the imported
paths will be ignored. If, instead, you click on one of the paths that has not
been imported yet, the context menu will give you the option of importing the
selected paths. In that case, the paths that have already been imported will
be ignored.
On occassion you might see that lines in the
Feff interpretation do not
properly report on the contents of the path. When this happens, site tags are
replaced by this string: "<?>". There are a couple common
reasons you might see the "<?>" tags:
- 1.
- You have done some advanced voodoo with Feff,
editing the "files.dat" or "paths.dat" files then
rerunning the last module to produce specialized output.
- 2.
- You have discovered a bug in the algorithm Artemis
uses to harvest information from the Feff calculation. IN that
case, you should send the "feff.inp" file or the Artemis
project file to Bruce so he can fix the problem.
Note that the appearance of the "<?>" tags is probably not an
indication that
Feff has misbehaved. The
Feff calculation has to
run to completion and generate its normal output before this problem can
manifest itself. The
Feff calculation is almost certainly usable to
analyze the data. The
Feff interpretation page is
Artemis's
attempt to organize information about the
Feff calculation in some
user-friendly format. That this organizational effort failed is not
necessarily an indication that
Feff failed.
ARTEMIS - The path page
The path page is displayed whenever a
Feff path is selected from the Data
and Paths List. This page is used to establish the math expressions of the
path parameters for this path.
At the top of the page is a line identifying which
Feff calculation this
path is from. Below that are three toggles. One is used to include of inlcude
or exclude the path from use in the fit. There are many other ways in
Artemis to include and exclude paths other than to use this toggle. See
The Feff interpretation page and "artemis_menubar" for more
discussion of this. Also Control-t is the same as clicking this toggle.
The second toggle is used to specify paths that you would like plotted after a
fit (or sum of paths) is finished. By default, the data and the fit (or sum)
is plotted after the fit (or sum) and no paths are plotted. Any paths selected
for plotting will be added to the plot after the fit (or sum) is finished.
The third toggle is used to set which path is the default path for evaluation of
Def parameters after the fit. It is possible to write math expressions which
evaluate differently for different paths. An example might be a math
expression using the "reff" parameter. For any such Def parameters,
it is necessary to tell
Artemis which path should be used for the
reporting of those parameters in the log file. The default is to use the first
path listed in the Data and Paths List.
Below that is a box which summarizes the path. This gives some statistics about
the path as well as displaying a color-coded "map" of the scattering
path. The central atom is always displayed in red text. Other atoms are in
black text. The grey text shows the length and scattering angle of each leg of
the path. In the case of a high-order multiple scattering path which has legs
which have a non-zero Eulerian eta angle between them, the eta angle will be
displayed as well. If that last sentence was gibberish, it suffices to know
that paths of that sort are almost never observable in real EXAFS data.
At the bottom of the page is the list of path parameters. This is the most
important section of the page because it is here that the details of the
fitting model are realized. There is an entry box for each of the various
types of path parameters. The math expression approporiate for each parameter
should be entered in the entry box.
When a
Feff calculation is imported into
Artemis, a set of
automatic parameters are generated, entered into the list on the Guess, Def,
Set page, and entered into the path parameetr boxes for each path imported.
The default behavior of
Artemis is to generate a set of parameters
appropriate for a simple, single scattering, first shell fit. While it might
be OK to immediately click the big green button, most fitting models will
require substantial editing.
The right mouse button serves many important purposes on the path page. Clicking
the right mouse button anywhere in one of the entry boxes will highlight the
word underneath the cursor and post a menu. The entries in the menu are for
for defining the word as a parameter on the Guess, Def, Set page. For each
parameter type there is the option of jumping or staying. In either case, the
parameter is defined and added to the list on the GDS page. For jumping, the
GDS page is then displayed. For staying, the current path page remains
displayed.
Right clicking on one of the path parameter labels will post a menu of functions
related to defining path parameter math expressions. The "Edit"
option will pop up a dialog used for entering a math expression and then
optionally exporting its value to other paths. The "Clear" option
doies just that.
The various "Export" options are ways of constraining path parameters
to be the same for other paths. The "Grab" options make the current
path parameter the same as the path parameter in the previous or following
path.
The "sigma^2" label has some additional options. These insert the
syntactically correct text appropriate to using either the Correlated Debye or
single frequency Einstein models for the sigma^2 of the path.
To enable the display of spaces for the "dphase", "k_array",
"amp_array", or "phase_array" path parameters, you must
click on the "Extended path parameters" button in the Paths menu.
ARTEMIS - The log viewer
When a fit is anchored in the Data and Paths list, the log file viewer is
displayed in the main panel. The purpose of this page is to examine log files
from the most recent fit or from previous fits. These log files can be read
individually or reports can be generated based on their contents.
When this page is displayed, each fit is entered into the list box on the left
side of the page. Double clicking the left mouse button on a fit in the
listbox will display that fit's raw log file. Right clicking on a fit will
post a menu with choices for displaying that fit's log file in raw, quick, or
columnar form or for performing some other tasks related to that fit.
Much more interesting than displaying the log files, though, is to generate
reports on the log files. Near the top of the page is a combo box for
selecting among the parameters on the Guess, Def, Set page. Choosing one, then
clicking on the "Write report" button will find extract that
parameters best-fit value and uncertainty from each log file. This feature
allows you to track the evolution of individual fitting parameters as you
develop your fitting model.
The combo box containing the names of the fitting parameters is filled using the
contents of the Guess, Def, Set page. Sometimes it may be useful instead to
fill the combo box with the parameter names extracted from a log file. This
would be useful, for instance, for examining a parameter that is was used at
one point, but is no longer on the GDS page or has been made into a skip
parameter (and so is not included in the combo box by default). To do this,
right click on a fit and select the "Get parameter list" item.
Some modifications can be made to the reports generated by the log viewer.
Clicking on the "Compute the average value" button tells
Artemis to compute the arithmetic mean and standard deviation of the
parameter from the values extracted from the various log files. These will be
displayed in the header of the report.
Clicking on the "Fit Einstein temperature" button will tell
Artemis to fit sigma^2 data to a model consisting of a single frequency
oscillator plus a constant offset. The report header will then contain the
best fit values and uncertainties for the characteristic temperature and
constant offset. This calculation will only happen is the figures of merit for
the selected log files are temperatures and the best fit values for the chosen
parameter are reasonable sigma^2 values. This function makes a series of
checks on the figures of merit and best fit values to determine if they seem
to be data appropriate for this calculation. These heuristics can be tuned by
setting parameters in the logview section of the preferences dialog.
The final item in the context menu that is displayed when right clicking on an
item in the log files list is an option to restore that fitting model. Among
the information that is saved every time a fit is made is a complete
description of the fitting model, including which data file is being fit, the
complete list of
Feff path used, and all fitting, data, and path
parameters. This feature allow you to revert
Artemis to the state it
was in when a past fit was made. When you do this reversion,
Artemis
will clear out the contents of the Data and Paths List and then recreate the
project in the form of the selected fitting model. This is more that just a
change of parameter values.
Artemis keeps track of all data and
Feff paths used throughout the course of the project and can restore
even fits that are significantly different from the current fit.
Importing
Athena project data || Output files ||
Artemis project
files ||
ARTEMIS - Plotting data
Plots in
Artemis are made using the selected items in the Data and Paths
List, which are the ones highlighted in orange. See the main document section
for an explanation of how to selected items for plotting.
At the top of the plot panel are three big, red buttons. One is for making a
plot in k-space, one is for R-space, and the third is for q-space (i.e.
back-transformed k-space).
Below the plot buttons are a set of radiobuttons for setting the k-weight to use
in the plots. The k-weight chosen will be used to weight a plot in k-space or
to weight data for Fourier transforming. The same k-weight is used for each
selected item. The button marked "kw" needs some explanation. When
this button is chosen, the k-weight to use in the plot will be determined from
the data being plotted. If the arbitrary k-weight enabled for the data set,the
value for the arbitrary k-weight will be used, other wise the smallest
k-weight value enabled will be used. There are two reason to use the
"kw" button. One is to plot using your arbitrary weight. The other
is to make a plot of two or more data sets using a different k-weight for each
data set.
Note that these k-weight controls are unrelated to the controls which set the
k-weight used in the fit. K-weighting for fitting and plotting are controlled
independently.
Below the k-weight radiobuttons are menus for choosing which part of the complex
functions chi(R) or chi(q) to plot. Plots involving multiple parts of the
complex functions (e.g. real+envelope) are not currently possible.
Below these menus are three checkbuttons used for plotting the Fourier transform
window, the background function, and the residual. If the window button is
pressed, the appropriate window function will be plotted in any plot. The
background and residual functions are only plotted if one of the selected
items is a fit. The background will only be plotted if a background
corefinement was made for that fit. If a fit is not among the selected items,
the background and residual will not be plotted. Note that a plot with more
than one selected fit may be quite confusing if the background or residual
buttons are depressed since the background and residual will be plotted for
each fit.
The ranges over which the plot will be made in the three spaces are controlled
by the three sets of entry boxes.
The two additional tabs in the plotting panel contain the controls for the
following utilities:
Indicators
Indicators are vertical bars that can be placed at user-chosen locations in k-,
R-, or q-space. These indicators will get displayed every time a plot is made.
The idea is that indicators are a guide to the eye, drawing attention to a
place of interest as the data being plotted changes.
Indicators selected in either k- or q-space will be plotted in both k- and
q-space, but not in R-space. Likewise, indicators selected in R-space will not
be plotted in k- or q-space.
Several characteristics of the indicators, including the number, the linetype,
and the color, can be set in the Plot section of the preferences dialog.
The indicators play well with each of the plotting options described below.
Stacking
Stacking refers to a vertical displacement the various traces. This is most
useful for plotting the various path contributions in k-space, but is
sometimes useful in other kinds of plots as well. Stacking requires three
parameters which are set in the stacking notecard. The first control is series
of radio buttons for choosing whether stacking happens in k-space, always, or
never. If the k-space option is chosen, then q-space plots of the real or
imaginary parts will also be stacked. (Basically, the "k-space"
choice refers to any wiggly function of wavenumber.) The other two controls
set the initial offset value and the increment between staces.
Inverting
Inverting is a useful tool for displaying the path contributions in
"|chi(R)|" plots. When this is selected, the "|chi(R)|"
from any paths included in the plot will be multiplied by -1 so that they
stick down below the zero-axis. Hopefully this kind of plot help reduce
clutter while still helping to show which paths contribut where. The
radiobuttons on this notecard allow you choose between never inverting,
inverting "|chi(R)|", or inverting both "|chi(R)|" and
"|chi(q)|". The real and imaginary parts in R- or q-space are never
inverted. chi(k) is also never inverted. Inverting is turned off whenever
stacking is selected and would effect the current plot (i.e. you cannot stack
and invert at the same time).
Data set offsets
This feat ure is useful for multiple data set plots. This is similar to stacking
in that the parameter denotes a vertical offset for use i the plot. Each trace
associated with a particular data set is plotted at the same lavel, but the
data sets will be offset by the amount specified by this control. This
provides a way of simultaneously visualizing all parts of a multiple data set
fit. Negative values are recommended, with a negative offset, the traces will
be plotted in the same order from top to bottom as in the plot legend.
Stacking is disabled when data set offsets are used. Inverting is used with data
set offsets, although I think this results in confusing plots.
Palettes || Using the Data and Paths List || =head1 ARTEMIS: Editing Math
Expressions
ARTEMIS - Editing math expressions
The math expression editing dialog is a way of setting path parameter math
expressions for many paths at once. It works on a given path parameter, e.g.
it sets e0 or sigma^2 for many paths but does not touch other path parameters.
This dialog is available in two different context menus. If you right click on
a path parameter label on the path page and selection "Edit for many
paths", then the dialog will pop up for editing that parameter. If you
right click on an entry on the
Feff interpretation page and select the
"Edit path parameters" cascade, then select a path parameter, the
dialog will pop up for editing that parameter.
The dialog is fairly simple. At the top is a text entry box for typing in your
math expression. Below that are various radiobuttons for specifying how to
apply the math expression to the various paths in your project. The options
are:
- 1.
- Add the math expression to every path in the current
Feff calculation.
- 2.
- Add the math expression to every path in the each
Feff calculation.
- 3.
- Add the math expression to every path in the each
Feff calculation associated with the current data set.
- 4.
- Add the math expression to selected paths (i.e. the ones
highlighted in orange in the Data and Paths list).
You can write your math expressions using token. Tokens are short character
strings which will be replaced by path-specific information as the math
expression is applied to each path. The tokens are:
- %i
- The path index from the Feff calculation. This is
actually computed from the name of the `feffNNNN.dat' file from the
Feff calculation. For instance, if the file is `feff0029.dat', then
%i will expand to 29.
- %I
- The path index from the Feff calculation, padded to
fill four characters. For instance, if the file is `feff0029.dat', then %I
will expand to 0029.
- %r
- The effective path length (or "reff") from the
Feff calculation for the path.
- %d
- The degeneracy of the path.
- %D
- A template for the Debye function. This always expands to
the string "debye(temp,thetad)" and may need be edited after the
fact to use the correct variable names. This is offered because the author
finds it hard to remember the order of the arguments to the Debye
function.
- %E
- A template for the Einstein function. This always expands
to the string "eins(temp,thetae)" and may need be edited after
the fact to use the correct variable names. This is offered because the
author finds it hard to remember the order of the arguments to the
Einstein function.
ARTEMIS - Automated first shell theory
Sometimes thinking about a fitting model is more than a problem merits. You just
want a quick 'n' dirty stab at the first shell -- perhaps to measure the
centroid of the distribution, perhaps to tell if a sample is 4- or
6-coordinated. Whatever.
Artemis is not extremely well suited to rapid-fire, first shell analysis.
By design,
Artemis tends to force the user to slow down and think hard
about every step.
Artemis is powerful, but she ain't simple.
The quick first shell (QFS) theory tool is an attempt at addressing this
shortcoming. It works like this:
- 1.
- Import some data. Set the Fourier transform and fitting
parameters to suitable values. Specifically, be sure to set the fitting
range such that it encloses the first peak of the data.
- 2.
- Select "Quick first shell theory" from the Theory
menu. This will display the QFS dialog.
- 3.
- The QFS dialog provides spaces for selecting the parameters
for a simple first shell theory. These include the atomic species of the
absorber and the scatterer, the absorption edge of the experiment, the
approximate distance between the absorber and scatterer, and the
coordination geometry to use in the Feff calculation.
Currently the following coordination geomatries are available:
- •
- 4-coordinate crystal
- •
- 6-coordinate crystal
- •
- octahedral molecule
- •
- tetrahedral molecule
- •
- square-planar molecule
The QFS theory is probably not highly sensitive to the choice of coordination
geometry. Since the unknown sample is probably not well described by any of
these geometries, they are all merely approximations for use in a quick 'n'
dirty fit.
- 4.
- Once you have set up the parameters for the QFS theory,
click the "Do it!" button. This will step through the following
without pausing:
- a.
- Build an input file for the Feff calculation
- b.
- Run Feff
- c.
- Import the first path from the Feff calculation
- d.
- Create a set of guess parameters for the amplitude, the
sigma^2, the e0, and the delta R. Also created are set parameters for the
third and fourth cumulants, but they are set to zero. These higher
cumulant set parameters are created to make it easy to consider higher
cumulants in subsequent fits merely by changing them from set to
guess.
If you have a mixed first shell, you might choose to repeat steps 2 through 4
two or more times.
At the end of this sequence, you are left with
Artemis in its normal
state. You may need to adjust the parameters used in the fit. The QFS dialog
is really just a tool for initially setting up the project. It in no way
changes the normal operation of
Artemis.
If you import data from an
Athena project file, the species of the
absorber and the edge will be set correctly when you start the dialog.
The Menubar || The preferences dialog ||
Here are the relevant URLs:
- IFEFFIT
-
http://cars.uchicago.edu/ifeffit
- PGPLOT
-
http://www.astro.caltech.edu/~tjp/pgplot/
- Perl
-
http://www.perl.com
- perl/Tk
-
http://www.lehigh.edu/~sol0/ptk/
You betcha!
Artemis was the goddess of the hunt, an apt metaphor doing EXAFS
analysis.
ARTemis is also a pun on the nature of EXAFS analysis that
works in English and in the romance languages.
Bruce Ravel <[email protected]> (c) 2001 - 2006
http://cars.uchicago.edu/~ravel/software/
Ifeffit is copyright (c) 1992 - 2006 Matt Newville
[email protected]
http://cars.uchicago.edu/ifeffit/