ARTEMISDOC(1)

📦

version 071~svn537 · 2 versions

071~svn537 · debian bookworm, ubuntu jammy, ubuntu noble (latest)
071~svn537 · debian trixie, ubuntu resolute, ubuntu stonking

, in debian bookworm, ubuntu jammy, ubuntu noble

💖 ARTEMISDOC(1) 💖

welcome to the manual page for Artemis, bestie!! it lives in the User Contributed Perl Documentation part of the man pages, it's called ARTEMISDOC(1), and it is long, so we're doing it in parts. this is part one. hydrate, sit criss-cross, let's go. 🎀

✨ NAME ✨

Artemis — interactive EXAFS data analysis

short, sweet, iconic. no notes. 👑

🌸 DESCRIPTION 🌸

okay so Artemis is a program for analyzing EXAFS data using theoretical standards from Feff. it ships with interfaces to Atoms and Feff, plus forms where you define parameters and then apply those parameters to the paths that came out of the Feff calculation. the whole pipeline is giving organized. 🫶

Artemis takes chi(k) as its input. and this part matters, bestie: it does not do any data processing chores. like, none. converting raw data to mu(E)? not it. background removal? also not it. that is simply not this program's job. 🚫

who handles all that? its sister program Athena, which is the data processing program. sisters supporting sisters, that's the vibe. 💖

🔥 SYNOPSIS 🔥

Artemis is a graphical and interactive program, written in the perl programming language, and it's built on the Tk display engine, the Ifeffit EXAFS library, and the PGPLOT plotting library. (there's a list of relevant URLs further down the page, iykyk. 👀)

Artemis helps you organize every single aspect of a fitting project, including:

running the Feff calculation
setting parameters for the Fourier transform and for fitting the data
parameterizing the paths from the Feff calculation
running the fit
plotting the results

🦋 the window, and its three panels 🦋

the Artemis window is divided into three panels.

the largest panel is where most of the work happens. its content is modal, and it depends on the state of the Data and Paths List.
the center, skinny panel is where that Data and Paths List lives.
the other skinny panel holds the controls you use to specify how plots get made.

at the top of the window you've got the menubar and the project bar. the project bar displays the name of the current project file, and it also has an indicator that tells you whether the project has been modified since the last time it was saved. clicking that modified indicator saves the project — literally the same thing as C-s or the "Save project" item in the File menu. cute, right? 💅

and at the bottom of the screen is the echo area, where Artemis writes all sorts of helpful messages as you use the program. it's basically the group chat of the app. 💬

🌈 the Data and Paths List 🌈

the Data and Paths List is a tree-like list of all the objects you can manipulate while using 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 get added to the list. it just keeps growing, main character energy. ✨

in total there are five kinds of entries in this list, and each one controls a different aspect of Artemis:

fitting parameters
data
fits
Feff calculation
Feff path

when you click on an item in the Data and Paths List, that item becomes "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 decides the mode of the large panel. for example, when the "Guess, Def, Set" item is anchored, the main panel shows a page used for setting the fitting parameters. when a data item is anchored, the main panel shows a page for setting the Fourier transform parameters, the fitting range, and the other parameters associated with that data. many functions in Artemis depend on the mode of the main panel, and some features are only available in certain modes. each mode gets described in its own document section — see "SECTIONS OF THE DOCUMENT". 📖

plots in Artemis are always made using the selected items. so if you want to plot, say, some data, a fit, and several individual paths, you have to select each of those items. and it's not just plots — many other functions in Artemis also operate on the set of selected items. select wisely, bestie. 🎯

🐭 mouse and keyboard: how to move around 🐭

anchoring and setting paths is usually done with the mouse in the Data and Paths List, although there are several other ways of changing the anchor and the selection using the mouse or the keyboard. here's the list of mouse events that are useful in the Data and Paths List:

Left mouse button — clicking the left mouse button clears all selections, then selects and anchors the item you clicked. the main panel will display the page appropriate to the anchored item.
Center mouse button — clicking the center mouse button anchors the item you clicked without changing the selection. the main panel will display the page appropriate to the anchored item.
Right mouse button — clicking the right mouse button anchors the item you clicked without changing the selection. it also posts a menu of functions appropriate to the item you 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 appropriate to the anchored item.
Control key + left mouse button — clicking the left mouse button while holding down the control key adds the item you 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 selects all items between the anchor and the item you clicked, inclusively. the anchor is not changed.
Left mouse button + mouse drag — clicking the left mouse button and then dragging the mouse while holding the button down selects all the items you drag the cursor over. the item you initially clicked will be anchored, and the main panel will display the page appropriate to the anchored item.
Control-k, Control-j — hitting the k or j keys while holding the control key moves the anchor to the previous or next item in the list, without changing the selection. the main panel will display the page appropriate to the anchored item. heads up though: 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 puts focus on the Data and Paths List. this is what lets you navigate the list using the arrow keys. 🏹

🎨 what the colors and fonts are telling you 🎨

the color and font of the text in the Data and Paths List tells you the status of each item, and it is very informative, so pay attention:

any item written in black, upright text is an item that can be plotted.
when a data set or a 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.
that italic text means those items cannot be plotted.

and yes, you can still select those non-plottable items — but they will be ignored when a plot is made. so don't be surprised, bestie. 🙈

🌸 ARTEMIS: The Data Page 🌸

okay bestie, this is the page you'll be staring at a lot — it's what shows up in Artemis's main panel when you've anchored a data item over in the Data and Paths List. Not sure what "anchoring" or "selecting" even means? Go peek at the main document section, it's all explained there. 🫶

The data page is split into five sections. At the very top there's a box holding the title lines for these data. They get read in from the input data file, but you can edit them whenever you want. When the data get written out to output files, whatever's sitting in this box gets written as headers. Below the titles box is the name of the data file that got imported. And below that? Four boxes stuffed with groups of related controls. ✨

🎀 Data toggles

This box has three toggles that control certain aspects of the fit. The first two only matter in a multiple data set fit.

When you're setting up a project with a multiple data set fit, sometimes it's handy to kick a whole data set out of the fit without deleting it from the project. That's toggle number one, babes. When a data set is excluded, it and everything beneath it shows up in brown text in the Data and Paths List, so you can see it's been excluded from the fit.

Then — once the fit is done — Artemis wants to show off her handiwork and plot the data plus the fit she just finished. In a multiple data set fit you might have opinions about which data set gets to be the star. Click this toggle on for your preferred data set. 👑

The third toggle tells Artemis to do a corefinement of the background spline when it runs the fit. That corefinement is, effectively, the same thing Athena did to remove the background from the data. The "rmin" parameter does the same job as Athena's "rbkg" parameter. When you fit with background corefinement, a spline fits the Fourier components of the data below "rmin", and the Feff paths fit the Fourier components between "rmin" and "rmax". The number of parameters used to determine that 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 upside of doing the background corefinement — beyond possibly making the fit look cuter at low R — is that you can actually measure the correlations between the background parameters and the fitting parameters. 💅

✨ Fourier transform and fitting parameters ✨

This box holds the controls for setting the ranges of the forward Fourier transform and of the fit. That fit range also doubles as the backward Fourier transform range whenever you make a plot in q space. Curious about those tiny square buttons marked with a blue x? Go read "Pluck buttons" below, bestie.

The other controls set the functional forms of the Fourier transform window used in k and R. The widths of the sills of those functions get set with the entry boxes labeled "dk" and "dr". 🎀

💖 k-weight parameters

The controls in this box set the k-weight values used in the fits. There are toggles for turning on k-weight of 1, 2, or 3, plus another toggle for specifying an arbitrary k-weight value.

Heads up: these are the k-weight values used in the fit, not the k-weight used to plot the data. Artemis handles those two purposes of k-weight independently. Want the deets on plotting k-weight controls? That's over in Plotting in Artemis.

People get confused by multiple k-weights for fitting all the time, so let's unpack it. The whole point of picking a low or high k-weight value is to try to emphasize either the low-k end or the high-k end of the data. Since different regions of the data are sensitive to different kinds of parameters, you might pick a low or high value to bump up the precision of measuring certain parameters. Doing multiple k-weight fits is like a compromise — a way to emphasize both ends of the data in the fit. 🤝

The fit works by minimizing a quantity called chi-square. Chi-square gets evaluated by summing the squares of the difference between the data and the theory. And since the FT is complex, there's a real part and an imaginary part. So chi-square is proportional to:

     /                                                    \
sum <   Re[ data(R) - th(R) ]^2 + Im[ data(R) - th(R)]^2   >
 R   \                                                    /

In a multiple k-weight fit there are just more terms in the sum. Say you're doing a kw=1&3 fit: the summation happens for the kw=1 data and theory, and it happens for the kw=3 data and theory. Then those summations get added together, and the full sum evaluates chi-square.

At the end of the day there's only one set of guess parameters that the fit has optimized. Those guess parameters, together with the set parameters, are used to evaluate the def parameters and the path parameters. The path parameters evaluate the exafs equation for each path. All those exafs equations get summed up to make the best-fit theoretical chi(k). So now you've got a data chi(k) and a best-fit chi(k) — plot them however you like, bestie, even with a k-weight that had nothing to do with determining the fit. 🦋

🌈 Other parameters

The last box is the catch-all — several controls that didn't fit in the other boxes.

There's a menu for picking the fitting space. You can fit the data in any of k, R, or q space. The default is fitting in R.

Epsilon is the uncertainty used to evaluate chi-square. Normally it's totally 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). But sometimes you might find it useful to explicitly set a value for epsilon.

After the fit, Artemis writes a log file documenting it. Among the info in that log are the correlations between all the fitting parameters. You can set the level below which Artemis will exclude a correlation from this report.

And finally, there's 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 — gets subtracted from anything that's Fourier transformed before it's plotted. So if a path is selected for phase correction and you plot, say, the data, the fit, and several paths, that selected phase shift gets subtracted from each item before it's plotted. Phase correction is for plotting only. Fits are always done on non-phase-corrected data. No cap. 🔥

💀 Pluck buttons

Several of the controls on this page have a little button with a blue x next to them. These are called pluck buttons, and they're for grabbing values straight from the plot window. Click one and a prompt shows up in the echo area asking you to click on a point in the plot. Do that, and the value you clicked on gets inserted into the entry box right next to the pluck button. Artemis is careful not to let you pluck a k-value from a plot in R, or the other way around. 🙈

🧚 Context menus

As you pass the mouse over labels on the data page, the text under the mouse changes color. That color change means clicks will actually do something. A left mouse click on one of these labels pops a brief description of that parameter into the echo area — and a lot of those descriptions even suggest reasonable values for the parameter. 🫶

Right-clicking one of the labels posts a context menu of useful functions. One of them restores that parameter to its default value. If you're running a multiple data set fit, the other menu options let you 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 where you define the parameters of your fitting model. In Artemis there are six kinds of parameters:

⭐ Guess

Guess parameters are the ones that get optimized during the course of the fit to best-fit the theory to the data.

⭐ Def

Def parameters are typically written as math expressions that may depend functionally on other parameters. Those math expressions get updated throughout the course of the fit. As the guess parameters update, so do the def parameters.

⭐ Set

Set parameters are evaluated at the beginning of the fit and not updated throughout the fit — that's the main difference between def and set parameters. Set parameters can be numbers or math expressions.

⭐ Restraint

Restraints are math expressions that, like def parameters, get updated throughout the course of the fit, but they take on a special role in the fit. A restraint is evaluated and added in quadrature to the evaluation of the chi-square parameter. So a restraint can incorporate a bias in the fitting result toward some piece of prior knowledge about the physical system. Want the full discussion of restraints? That's over in the Ifeffit. ✨

⭐ Skip

Skip parameters stick around in the project but aren't used in any capacity in the fit. The whole point of a skip parameter is to keep — but not use — a complicated parameter with a complicated math expression.

⭐ After

An after is similar to a def parameter in that it can be a math expression depending on other parameters. An after is not, however, part of the fitting model. Instead it's a parameter that gets evaluated upon completion of the fit, using the best fit values. The list of after parameters gets reported in the log file.

⚠️ Using an after parameter anywhere in your fitting model will make Artemis report an error in the model.

Afters can depend on other afters, but be careful about the order the afters appear in the list. After parameters get evaluated only once after the fit, so 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 with the list of all defined parameters. At the bottom is the edit area, which holds the controls used to establish the parameters. 🎀

🎀 The parameter listbox 🎀

Okay bestie, this is the area — a four-column list of literally every parameter defined in your project. Left-most column counts the parameters (numbering, periodt). Second column has a tag identifying the type of the parameter. Third column has the parameter name. And the right-most column has the parameter's math expression. Four columns, no notes. ✨

Parameters are coded by color and by the tag in that second column, so you can clock the vibe at a glance:

Guess parameters — written in purple text, tagged g:
Def parameters — written in green text, tagged d:
Set parameters — written in black text, tagged s:
Restraints — written in pink text, tagged r:
Skip parameters — written in grey text, and they have no tag
After parameters — written in blue-grey text, tagged a:

There are a large number of mouse clicks and key sequences that serve a purpose in the listbox, and here's every single one, no skipping:

A left mouse click selects a parameter and displays it in the edit area.
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".
A right mouse click selects a parameter, displays it in the edit area, and posts a contextual menu about that parameter. That menu has several items in it:
- The "Move" submenu is used 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.
Control-d will define the parameter in the edit area.
Control-g will grab the current parameters best-fit value from a fit.
Control-e will show the editing area if it is hidden.
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.
Control-n will clear the selection and focus on the parameter name entry box so that you can create a new parameter.
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 the only way of setting the parameter type that does not involve the mouse. 🖱️🚫

🦋 Extended selection 🦋

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. But here's the catch, bestie: only the anchored list item (i.e. the one surrounded by a dashed line and displayed in the edit area) can have its name and math expression edited. That's the main character, everyone else is just the ensemble. 💅

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. Simple as that. ✨

🌸 The edit area 🌸

There are three rows of controls in the edit area, bestie, three whole rows:

Top row: 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: a set of five radiobuttons for selecting the type of parameter being edited.
Bottom of the edit area: five buttons for acting upon the parameter being edited.

Let me introduce you to the five buttons, they're all iconic in their own way:

"Undo edit" — clears the entry boxes and discards whatever changes were just made.
"New" — used to define a brand new parameter. It clears the entry boxes, unselects parameters in the listbox, and gives focus to the entry box for entering the parameter name.
"Grab" — becomes enabled after a fit is run. It inserts the best-fit value for a guess parameter.
"Discard" — deletes a parameter from the list. A dialog pops up confirming deletion. (It's giving safety net. 🫶)
"Hide" — 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, fr fr:

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.
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.
Clicking on any of the radiobuttons defines the parameter, inserts or updates it in the listbox, and leaves the focus unchanged.

💜 Parameter annotations 💜

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 the annotation is to write a little hint about the role played by the parameter in the fitting model. 🎀

If a guess parameter 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.

🔥 Building restraints 🔥

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 boundaries 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, bestie, listen up: 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. 😭

🌈 Highlighting 🌈

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.) 💀

🍓 Importing and exporting text files 🍓

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 representation 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 be 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 concatenated 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 🎀

Okay bestie, so here's the whole vibe of Atoms: its entire purpose in life is to take crystallographic data and generate a feff.inp file from it. The genuinely hard part of building a feff.inp is writing out that long, long list of atomic coordinates — and Atoms just… handles it for you. So it makes the hard part of running Feff easy, at least for crystalline materials.

You can use this page to build Atoms input data from scratch, no cap. It also doubles as the display for crystallography data you've imported from an atoms.inp file or a CIF file. Wanna import one? Use the normal file import dialog, periodt.

✨ The title box ✨

Up at the top there's a text box where you drop your title lines identifying the crystallographic data. These lines get written into the feff.inp file, and also to the top of the Feff interpretation page. Pro tip: it's a great spot to cite your literature reference or add any other important info about the crystal. 🦋

💎 Crystal parameters 💎

Over on the left side of the page you've got entry boxes for the space group, the lattice constants, and the lattice angles of the crystal. Heads up: a space group must always be provided. No skipping it.

Atoms is genuinely so chill about how you enter the space group symbol. You can use the Hermann-Maguin or Scheonflies symbols, or the index of the space group from the International Tables. The algorithm that reads the symbol does not care about white space or capitalization — P m -3 m and PM-3M get interpreted exactly the same. Slay. For the complete details on how symbols get interpreted, see the Atoms documentation on Bruce's web site.

Lattice constants go in units of Angstroms. Angles go in as decimal numbers in degrees — and not in arc minutes, okay? Like, 89 and a half degrees is entered as 89.5, not 89'30".

Here's the cute part: many space groups have symmetries that make some lattice angles and constants identical. In those situations you only need to fill in the essential values. For instance, a cubic space group only needs 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 though? You gotta provide all the necessary information. 🙈

Below the lattice constants there are entry boxes for Rmax and the shift vector, plus a menu for selecting the absorption edge of the Feff calculation. Rmax is the radial extent of the cluster that gets written to the feff.inp file.

Okay so some space groups are listed in the International Tables with two different origins — meaning the origin sits 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 one particular choice of the two. If your input data used the other origin choice, it should be pretty obvious — 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 the wrong origin choice got used, insert the values for the shift vector that were reported in the warning message.

On occasion, crystals get reported in the literature using origins other than the standard one from the International Tables. A famous example is germanium oxide. Here's 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's 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. No cap. 💅

🌸 The atoms list 🌸

On the right side of the page lives the list of unique crystallographic sites. As new sites get created, they're inserted into the list. You don't edit the sites directly in the list — instead you use the editing area at the bottom of the screen, and the list of all sites displays up here. It works pretty much exactly like the Guess, Def, Set page.

To edit a site, left-click on its entry in the list — its element symbol, coordinates, and site tag show up in the edit area. A right click on a site in the list posts a context menu with several functions you can perform 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 too. When many sites are selected (i.e. highlighted in yellow), the Discard menu item works on all the selected sites. 🫶

Sites can also be reordered with the keyboard — Alt-k and Alt-j move the selected site up or down in the list. Keyboard girlies, we see you. 👑

✨ The edit area ✨

Down at the bottom of the page is the collection of widgets you actually use to create and edit unique crystallographic sites.

The element box is where you insert the two-letter element symbol for the site. Fair warning: the site will not be created if it isn't a valid symbol.
The tag can be any 10-letter string used to identify the site. The tag is what differentiates sites containing the same element.

The boxes for the x, y, and z coordinates can be filled with floating point numbers or simple fractions — so 0.5 and 1/2 are both acceptable. Note that these coordinates are fractional positions in the unit cell, not Cartesian coordinates. Important distinction, bestie.

Once you've created all the sites in your crystal, click the Run Atoms button. That processes the crystallographic data, creates the feff.inp file, and displays the feff.inp page. Boom. 🎀

🦋 Atoms template files 🦋

The feff.inp data generated when you hit Run Atoms is determined by the contents of a special template file. Artemis ships with a bunch 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.

Wanna run some other version of Feff? Then 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. Iconic range, honestly.

Sometimes it's useful to modify template files for writing out specialized feff.inp data. If you place those modified template files in:

~/.horae/atp/ (unix)
C:Program Files\Ifeffit\horae\atp (windows)

…then Artemis will be able to find them. 🫶

💜 Final note 💜

A full explanation of how the Atoms algorithms work is beyond the scope of this document page. (iykyk — go read the docs.)

💖 ARTEMIS: The FEFF Input File 💖

Bestie, this page is exactly what it sounds like: it displays the Feff input data, which includes some control parameters and a long list of atomic coordinates. And ngl, this page is no more sophisticated than a text box serving as a primitive editor, plus a button at the bottom for running Feff. Explaining Feff itself is beyond the scope of this document. 🙈

When feff finishes, you'll be presented with a dialog asking how many paths to import. Your choices are:

none
the first path
the first 10 paths
all paths

The number in that 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 — which is, like, a genuinely confusing situation. 💀

If Feff fails to run to completion, Artemis will try to recognize the problem and post a suggestion for how to solve it. And if Artemis doesn't recognize your problem, explain it to Bruce so he can add that problem to Artemis's database of troubleshooting solutions. 🧚

🌈 ARTEMIS: Interpretation of the FEFF Calculation 🌈

okay bestie, this page is literally a little dashboard for your Feff calculation 💅 and it's giving "spreadsheet but make it cute."

Up at the top you get a summary of some of the statistics of the calculation. Below that is a chart showing the details of every single path from the calculation. For each path you get the degeneracy, the half path length, and the amplitude factor. And the last column? A tokenized summary of the scattering path — so you can clock at a glance which atoms were involved in that path. iykyk ✨

The info and context menus on this page let you organize, understand, and manipulate the paths in this Feff calculation. Basically pretty much all functions involving the paths except writing math expressions for the path parameters are available right here. no cap 🫶

🎨 The interpretation chart

The colors and fonts in the chart are all telling you something, like a little vibe check for every path:

Bold, black font — these are paths that have been imported into the project and are included in the fit. 💖
Bold, brown font — imported into the project but excluded from the fit. 🙈
Normal, black text — not imported into the project, but they are available to be imported. ✨
Normal, grey text — unavailable for importation into the project. You can make them available by re-running the Feff calculation. After the Feff run, it's best to choose the "import no paths" option so you don't reimport paths that are already in the project. After that, these paths will be written in normal, black text, which means they're available for import. 🦋
Light brown background — this marks single scattering paths. 🍓
Light blue background — this marks collinear or nearly collinear multiple scattering paths. 💙

🖱️ Context menus

There are interesting and useful context menus on every part of this page. You get them by right clicking. 👑

Right clicking anywhere in the text box at the top of the page pops up a menu with options for viewing files from the Feff calculation.

Right clicking in the interpretation chart posts a menu of options relevant to the path on the line you clicked. Each of the four kinds of paths — 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
discarding the path

The choices for including/excluding and for selecting/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 lets you import the path — with the option of displaying its page, or leaving the display on the Feff interpretation. And for paths that are unavailable for import? A message saying so gets posted when you right-click one of those lines. 😭

✨ Extended selection

The interpretation chart allows for extended selection of lines in the chart, and it's honestly so convenient:

Hold the control key while clicking with the left mouse button to select additional paths.
Hold the shift key while left clicking to select all lines 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 changes to reflect functionality that makes sense for many paths. So extended selection in the interpretation chart is a great way of including/excluding, selecting/deselecting, or plotting a large number of paths. slay 🔥

Heads up though — the context menu that pops up when many lines are selected may be a little surprising.

Its contents depend on the state of the anchored line, which in this case is the one 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 doesn't make sense for some of the selected lines, those lines will just be ignored. 💀

Here's a concrete example. Suppose 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'll 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 gives you the option of importing the selected paths. In that case, the paths that have already been imported will be ignored. 🧚

🩹 Trouble shooting

On occassion you might see that lines in the Feff interpretation don't properly report on the contents of the path. When this happens, site tags are replaced by this string: "<?>". There are a couple of common reasons you might see the "<?>" tags:

You've done some advanced voodoo with Feff — editing the "files.dat" or "paths.dat" files, then rerunning the last module to produce specialized output. 🔮
You've 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 👑

ARTEMIS — the path page 💜

The path page is displayed whenever a Feff path is selected from the Data and Paths List. This page is where you establish the math expressions of the path parameters for this path. It's giving "the main character of your fit." 🌟

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 or exclude the path from use in the fit. There are many other ways in Artemis to include and exclude paths besides this toggle — see The Feff interpretation page and "artemis_menubar" for more discussion. Also, Control-t is the same as clicking this toggle. ⌨️
The second toggle is used to specify paths that you'd 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's 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's 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 with 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's an entry box for each of the various types of path parameters, and the math expression appropriate 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 parameter 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. 🛠️

🖱️ Right-clicking on the path page

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 defining the word as a parameter on the Guess, Def, Set page. For each parameter type there's 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 posts a menu of functions related to defining path parameter math expressions:

The "Edit" option pops 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 💖

So like, the moment a fit gets anchored in the Data and Paths list, guess what shows up in the main panel? The log file viewer. ✨ And bestie, the whole point of this page is to let you peek at log files — either from the fit you just ran or from fits you did a million years ago. You can read them one at a time, or you can have Artemis cook up whole reports based on what's inside them. Obsessed.

When this page pops up, every fit gets dropped into the list box on the left side of the page. From there:

Double click (left mouse button) on a fit → it shows you that fit's raw log file. Just like that. 💅
Right click on a fit → a little menu shows up with options for displaying that fit's log file in raw, quick, or columnar form, plus some other tasks related to that fit.

But ngl, displaying log files is the boring part. The real main character energy? Generating reports. 🌈

Near the top of the page there's a combo box where you pick among the parameters from the Guess, Def, Set page. Pick one, hit the "Write report" button, and Artemis will go dig that parameter's best-fit value and uncertainty out of every single log file. Which means you can literally track the evolution of individual fitting parameters as your fitting model grows and changes. It's giving character development fr fr. 😭

That combo box gets filled up using the contents of the Guess, Def, Set page. But sometimes it's way more useful to fill it with parameter names pulled straight out of a log file instead. Like when? Say you wanna examine a parameter that was around at one point but isn't on the GDS page anymore, or one that got turned into a skip parameter (so it doesn't show up in the combo box by default). 🙈 To do that: right click on a fit and select the "Get parameter list" item. Boom. Done. ✨

🌸 Report Modifications 🌸

You can tweak the reports the log viewer makes, and there are two buttons for that:

"Compute the average value" — tells Artemis to compute the arithmetic mean and standard deviation of the parameter, using the values it extracted from the various log files. Both of those get displayed up in the header of the report. 🎀
"Fit Einstein temperature" — tells Artemis to fit sigma^2 data to a model made of a single frequency oscillator plus a constant offset. The report header will then hold the best fit values and uncertainties for the characteristic temperature and the constant offset.

Heads up though: the Einstein temperature thing only happens if 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. Artemis runs a whole series of checks on the figures of merit and best fit values to decide whether they look like data that's appropriate for this calculation. Those heuristics can be tuned by setting parameters in the logview section of the preferences dialog. 🧚

👑 Restoring a Fitting Model 👑

The final item in that context menu (the one you get when you right click on an item in the log files list) is an option to restore that fitting model. And this is the iconic part, okay?

Every single time a fit is made, Artemis saves a complete description of the fitting model, including:

which data file is being fit
the complete list of Feff paths used
all fitting, data, and path parameters

So this feature lets you revert Artemis right back to the state it was in when a past fit was made. 🤯 When you do that reversion, Artemis clears out the contents of the Data and Paths List and then recreates the project in the form of the selected fitting model. And that's way more than just swapping out parameter values — Artemis keeps track of all data and Feff paths used throughout the course of the project, so it can restore even fits that are significantly different from your current fit. No cap. 💜

Importing Athena project data || Output files || Artemis project files ||

🎀 ARTEMIS: Plotting Data 🎀

ARTEMIS - Plotting data

okay so plotting in Artemis is all about the stuff you've selected in the Data and Paths List — aka the items sitting there highlighted in orange. Need a refresher on how selecting items for plotting even works? The main document section has the whole explanation, bestie. 🧡

Up at the top of the plot panel there are three big red buttons. One makes a plot in k-space, one is for R-space, and the third is for q-space (which is just back-transformed k-space, iykyk). ✨

🫶 k-Weighting

Below those plot buttons lives a set of radiobuttons for setting the k-weight to use in the plots. The k-weight you choose is what weights a plot in k-space, or weights the data for Fourier transforming. And note: the same k-weight gets used for every single selected item. No mixing, no matching. 🙅‍♀️

Now the button marked "kw" needs a lil explanation. When you choose "kw", the k-weight used in the plot gets figured out from the data being plotted. If the arbitrary k-weight is enabled for the data set, then the value of that arbitrary k-weight gets used. Otherwise, the smallest k-weight value that's enabled gets used. There are two reasons to reach for the "kw" button:

to plot using your arbitrary weight, or
to make a plot of two or more data sets using a different k-weight for each data set. 👑

🚨 Okay real talk though — these k-weight controls are completely unrelated to the controls that set the k-weight used in the fit. K-weighting for fitting and k-weighting for plotting are controlled independently. Periodt.

🌈 Selecting What Gets Plotted

Below the k-weight radiobuttons are menus for choosing which part of the complex functions chi(R) or chi(q) to plot. And no, plots involving multiple parts of the complex functions (think real+envelope) are not currently possible. 🙈

Below those menus are three checkbuttons, used for plotting the Fourier transform window, the background function, and the residual:

Hit the window button and the appropriate window function gets plotted in any plot.
The background and residual functions only get plotted if one of the selected items is a fit.
The background will only get plotted if a background corefinement was made for that fit.
If a fit is not among the selected items, the background and residual don't get plotted at all. Sorry bestie. 😭

💀 Also, a plot with more than one selected fit can get quite confusing if the background or residual buttons are depressed, because the background and residual get plotted for each fit.

The ranges over which the plot gets made in the three spaces are controlled by the three sets of entry boxes. 📐

✨ Extra Plotting Features ✨

The two additional tabs in the plotting panel hold the controls for these utilities:

🎯 Indicators

Indicators are vertical bars that you can place at user-chosen locations in k-, R-, or q-space. They get displayed every single time a plot is made. The idea here? Indicators are a guide to the eye — drawing attention to a place of interest as the data being plotted changes. 👀

Indicators selected in 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.

And the good news: the indicators play well with each of the plotting options described below. 💅

📚 Stacking

Stacking refers to a vertical displacement of the various traces. It's most useful for plotting the various path contributions in k-space, but sometimes it comes in handy for other kinds of plots too. Stacking needs three parameters, which you set in the stacking notecard:

The first control is a series of radio buttons for choosing whether stacking happens in k-space, always, or never. If you pick the k-space option, then q-space plots of the real or imaginary parts will also get 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 stacked traces.

🙃 Inverting

Inverting is a genuinely useful tool for displaying path contributions in |chi(R)| plots. When it's selected, the |chi(R)| from any paths included in the plot gets multiplied by -1 so they stick down below the zero-axis. Hopefully this kind of plot helps reduce clutter while still showing which paths contribute where. 🙏

The radiobuttons on this notecard let 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. And inverting gets turned off whenever stacking is selected and would affect the current plot — i.e. you cannot stack and invert at the same time. 🚫

📏 Data set offsets

This feature is useful for multiple data set plots. It's similar to stacking, in that the parameter denotes a vertical offset for use in the plot. Each trace associated with a particular data set gets plotted at the same level, but the data sets themselves get offset by the amount specified by this control. This gives you a way of simultaneously visualizing all parts of a multiple data set fit. 👑

Negative values are recommended — with a negative offset, the traces get 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 the author thinks this results in confusing plots. 🙈

prev / next breadcrumbs:

Palettes || Using the Data and Paths List || =head1 ARTEMIS: Editing Math Expressions

🦋 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 — like, it sets e0 or sigma^2 for a bunch of paths but does not touch other path parameters. This dialog is available in two different context menus:

Right click on a path parameter label on the path page and select "Edit for many paths" → the dialog pops up for editing that parameter.
Right click on an entry on the Feff interpretation page, select the "Edit path parameters" cascade, then select a path parameter → the dialog pops up for editing that parameter.

🛠️ Operation of the dialog

The dialog is fairly simple, bestie. 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:

Add the math expression to every path in the current Feff calculation.
Add the math expression to every path in the each Feff calculation.
Add the math expression to every path in the each Feff calculation associated with the current data set.
Add the math expression to selected paths (i.e. the ones highlighted in orange in the Data and Paths list).

🔤 Tokens

You can write your math expressions using tokens. Tokens are short character strings that get 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 to 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 to 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 ✨

ARTEMIS - Automated first shell theory

Okay bestie, sometimes you just need a quick 'n' dirty first-shell fit. Like, thinking about a whole fitting model is more than the problem merits, you know? You just want to measure the centroid of the distribution, or figure out if your 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 you to slow down and think hard about every step. Artemis is powerful, but she ain't simple. Periodt. 👑

The quick first shell (QFS) theory tool is an attempt at addressing this shortcoming. It works like this:

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.
Select "Quick first shell theory" from the Theory menu. This will display the QFS dialog.
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 (yes, that's the original spelling, bestie, I'm just the messenger 🫶) 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.

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 ||

📚 REFERENCES 📚

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/

🚫 MISSING FEATURES 🚫

You betcha!

🌸 WHAT'S IN A NAME? 🌸

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.

👑 AUTHOR 👑

And that's the whole page, bestie! This was rendered from perl v5.32.1 on 2021-11-22, and the manual page is ARTEMISDOC(1). Slay. 💖

📦 where this page comes from

debian bookworm: horae 071~svn537+ds1-1 · horae
ubuntu jammy: horae 071~svn537+ds1-1 · horae
ubuntu noble: horae 071~svn537+ds1-1 · horae
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms