Demeter

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

NAME

Demeter::UI::Standards - Interactions with standard reference data

VERSION

This documentation refers to Demeter version 0.9.26.

SYNOPSIS

  use Demeter;
  use Demeter::UI::Standards;
  my $standards = Demeter::UI::Standards -> new;

DESCRIPTION

This module provides methods for an attempt to expand and improve upon the pictures of metal foils spectra that come with a box of foils from EXAFS Materials.

That document is fine as far as it goes, but the spectra are not all of the highest resolution and it only includes foils of a few select elements. This implementation expands upon that by including reference spectra other than foils. It is extensible in the sense that new materials can be added easily. Thus this visualization of standard reference spectra can cover more of the periodic table and include various common (or even uncommon) species of any element.

A small database of reference data ships with Demeter and various mechanisms are provided for extending the list of materials in the database. You can use files on your own computer simply by pointing the program at that file's location. You can also grab data from the web by pointing the program at the data file's URL.

Ideally, adequate metadata is provided about each material such that a useful and thorough presentation of the data can be made. This metadata includes some comments identifying the provenance of the data, the crystal type used to measure the data, enough information to properly calibrate the data, and lists of points to mark in mu(E) or the derivative of mu(E). The program behaves well in the absence of any of this metadata, but the utility of the program is dimished.

This module is a wrapper around four distinct ways of visualizing standards data. It can be used to interactively plot standards, selecting elements from an on-screen periodic table or with a GUI. It can be used to generate a sequence of web pages that can be dropped on a web site. It can be used to generate a latex document that can be converted to PDF and printed to replace the one from EXAFS Materials. Finally, is can be used to create an Athena project file containing a subset of the reference materials.

METHODS

General methods

These are the methods for handling the Standards object, which encapsolates the metadata describing the standard reference materials.

material_exists

This method returns true if the argument string identifies a material in the database.

  $exists = $standards -> material_exists("Zn");
element_exists

This method returns true if the argument string identifies an element represented by one or more materials in the data base.

  $exists = $standards -> element_exists("U");
get

This method returns one of the attributes of a database entry.

  $comment = $standards -> get("fe", "comment");
config

This method returns one of the plotting configuration parameters.

  $emin = $standards -> config("emin");

Currently, the Standards-specific configuration parameters control the plotting range and the placement of the legend. The keywords are emin, emax, key_x, and key_y

material_list

This returns a list of all keys identifying the materials in the database. The list is sorted first by Z number of the absorber then alphabetically by material name.

Formatting methods

These methods are used to control the output for the various visualization modes. Available modes are

LaTeX mode is not yet working.

plot

This is the workhorse. It reads and processes a data file according to the metadata and prepares the data for display in the chosen output mode.

  $response = $standards -> plot($material, $plot_type, $target);

$material is a material contained in the database. $plot_type is an integer between 1 and 3. A value of 1 says to prepare to plot XANES data. A value of 2 says to prepare to plot the derivative spectrum. A value of 3 says to prepare a plot explaining the use of a fluorescence filter.

$target identifies the visualization mode and takes one of four values:

screen

The data will be plotted on screen. For this target the return value will be an empty string is no problems are encountered or a error message explaining the source of the error.

athena

The data processing will be stopped before any plotting actually happens. In this case, the return value is a reference to a Data object conatining that standard. This can then be written to an athena project file or otherwise handled in the manner of Data object.

filename.png

If the target ends in .png, then the plot will be written to a PNG file with that name. When using PGPLOT, it is recommended that you set the PGPLOT_DEV environment variable to /null. That will suppress all plots to the screen before the PNG file is generated. The return value is the same as for the screen target.

filename.ps

If the target ends in .ps, then the plot will be written to a postscript file with that name. When using PGPLOT, it is recommended that you set the PGPLOT_DEV environment variable to /null. That will suppress all plots to the screen before the postscript file is generated. The return value is the same as for the screen target.

html_index

This method writes an index file for the html output. The index file contains links to each of the individual material files in a simple table. The argument is the fully resolved name for the index file.

  $standard -> html_index($indexfile);
html

This method writes a page for a given material. All arguments are passed as a hash reference. The folder argument is the output location for the html file and all image files. The skip argument says to skip this material if the html file already exists in the output folder. Setting verbose to 0 turns off all messages to STDOUT.

  $standards -> html({
                      material => "fe",
                      folder   => "html",
                      verbose  => 1,
                      skip     => 0,
                     });
latex

Not written yet.

athena

This method generates an Athena project file for all materials with an absorber in the list specified by the elements key of the has reference which is passed as the sole argument. The output project file is specified by prjfile. It will be written to standards.prj in the current directory if not otherwise stated. Setting verbose to 0 turns off all messages to STDOUT.

  $standards -> athena({
                        elements => \@list_of_elements,
                        prjfile  => "standards.prj",
                        verbose  => 1,
                       });

CONFIGURATION AND ENVIRONMENT

The meta data -- that is the data about the reference data -- is contained in the standards.ini file. Here is an example:

  [fe]
  tag         = Iron foil
  comment     = Iron foil
  crystal     = Si(111)
  location    = NSLS X11A
  people      = BR
  date        = 10/4/2002
  file        = %share%/standards/data/fe.stan
  energy      = $1
  numerator   = $2
  denominator = $3
  ln          = 1
  calibrate   = 7106.135, 7112
  xanes       = 7112, 7116.41, 7131.22, 7141.83
  deriv       = 7112, 7120.88, 7129.263

The first few lines describe the data. The file line identifies the data file containing the reference. The "%share%" token is replaced with the actual installation location of Demeter. The next four lines explain how to for mu(E) data from the columns in the file. The last three lines are used to calibrate the data and mark the interesting points in the XANES or derivative spectra.

The comment keyword is intended to describe the physical sample. The location, people and date are intended to establish provenance. The location is the facility and syncherotron. The people are the experimenters who were present for the measurement. The date is the date of the measurement. The use of the ISO-8601 combined date and time representations is encouraged, but not enforced at this time.

The keywords coordination and oxidation can be used to specify the structural environment and oxidation state of the absorber. These are not used at this time.

Another option is to import data from an Athena project file. Here is an example:

  [cd]
  tag         = Cadmium foil
  comment     = Cadmium foil
  location    = APS 10ID
  people      = Saengdao Khoakaew, Ryan Tappero, and BR
  date        = November 18, 2006
  crystal     = Si(111)
  file        = %share%/standards/data/Cd.prj
  record      = 1
  xanes       = 26711, 26720.06, 25740.66, 25772.57
  deriv       = 26711, 26714, 26734.60, 26745.10

In this case, the record parameter is used to identify the location of the data in the project file. The Athena project file is presumed to contain well processed data, thus the rebinning and calibration steps are never performed for data from an project file.

The first section of the standards.ini file contains the configuration data and is used to control some aspects of the plots made of the reference data.

This code will also look for a file called standards.ini located in the the Demeter configuration folder, $HOME/.horae/ on linux, %APPDATA%\demeter on Windows. The system file is read first, then the private file is read. Their contents are simply concatanted, although an entry with the same key -- the bit in [brackets] -- in the private file will overwrite the similarly named entry in the system file.

There are a few more keywords not discussed above. If rebin = 1, then the data will be rebinned onto a conventional grid. The calibrate keyword is used to put data from a file onto the absolute energy grid. The comma separated arguments are the energy value to choose as the edge and the energy value to assign to that point.

The output html and latex files are formatted using Text::Template templates, which can be found in the share directory of the Demeter installation. This is the same formatting system as used for Demeter's output, but the template files are in a different location.

All other configuration is handled using Demeter's configuration system.

DEPENDENCIES

This uses Demeter and its dependencies.

BUGS AND LIMITATIONS

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

Patches are welcome.

AUTHOR

Bruce Ravel (http://bruceravel.github.io/home)

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

LICENCE AND COPYRIGHT

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

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

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

generated by Pod::ProjectDocs