| Larch: Data Analysis Tools for X-ray Spectroscopy

# Larch

Larch is a open-source library and set of applications for processing and analyzing X-ray absorption and fluorescence spectroscopy data and X-ray fluorescence and diffraction image data from synchrotron beamlines. It aims to be a complete analysis toolkit for X-ray absorption fine-structure spectroscopy (XAFS) including X-ray absorption near-edge spectroscopy (XANES) and extended X-ray absorption fine-structure spectroscopy (EXAFS). It also supports visualization and analysis tools for X-ray fluorescence (XRF) spectra and XRF and X-ray diffraction (XRD) images as collected at scanning X-ray microprobe beamlines.

Larch is written in Python, making heavy use of the excellent scientific python libraries including numpy, scipy, h5py, matplotlib, and provides a Python library for processing and analyzing X-ray spectroscopy and imaging data. There are a few GUI applications written using this library for common data visualization and analysis tasks, notably XAS Viewer, GSE Map Viewer, and XRF Viewer as described in more detail below.

While Larch can be used as a Python library, the applications built with Larch use a Python-like macro language - the “Larch language” - for interactive and batch processing. This macro language is available from an interactive command-line interface through either larch or Larch GUI and intended to be very easy to use for novices while also being complete enough to automate data processing and analysis. Most of the GUIs can generate and save “Larch code” for an analysis session to make reproducible analysis sessions, and to encourage and facilitate a gentle transition to transition from GUI-only analyses to scripted and programmatic analysis of larger data sets. This macro language also allows Larch to be run as a background service that other processes can use Larch as the analysis engine. The popular Demeter XAFS application suite can use Larch in this way.

Larch is distribute under an open-source license that is nearly identical to the BSD license. It is under active and open development centered at the GeoScoilEnviroCARS sector of Center for Advanced Radiation Sources at the University of Chicago has been supported by the US National Science Foundation - Earth Sciences (EAR-1128799), and Department of Energy GeoSciences (DE-FG02-94ER14466). In addition, funding specifically for Larch was granted by the National Science Foundation - Advanced CyberInfrastructure (ACI-1450468).

Table of Larch Applications

> > These applications installed with Larch, in addition to a basic Python library. Here, GUI = Graphical User Interface, CLI = Command Line Interface, and beta indicates a work in progress. The Feff6L and Feff8L codes are the open-source versions of Feff6 and Feff8, written by the Feff Project, and included with Larch by permission and with license to redistrubute.

> Application Name | GUI/CLI | Description
> --- | --- | ---
> XAS Viewer | GUI | XAFS Processing and Analysis: XANES pre-edge peak fitting, linear analysis, PCA/LASSO, EXAFS extraction
> larch | CLI | simple shell command-line interface
> Larch GUI | GUI | enhanced command-line interface with data browser
> GSE Map Viewer | GUI | XRF Map Viewer for GSECARS X-ray microprobe data.
> XRF Viewer | GUI | Display and Analyze XRF Spectra.
> feff6l | CLI | Feff 6 EXAFS calculations
> feff8l | CLI | Feff 8 EXAFS calculations (no XANES)
> 1D XRD Viewer | GUI beta | Display and work with 1-D XRD patterns
> 2D XRD Viewer | GUI beta | Display XRD images
> qtrixs | GUI beta | Display RIXS planes, take profiles

Note that the Dioptas program for viewing and calibrating 2-D XRD patterns, written and maintained by Clemens Prescher has been included with earlier versions of Larch. It is no longer included, but we recommend downloading and installing that for working with XRD image data.

## Table of Contents

- 1. Downloading and Installation
  - 1.1. Single-File Installers and Source Installation Files
  - 1.2. Using Installation Scripts GetLarch.sh and GetLarch.bat
  - 1.3. Install with Python
  - 1.4. Getting Help
  - 1.5. Docs and Examples
  - 1.6. Citing Larch
  - 1.7. Funding and Support
  - 1.8. Acknowledgements
  - 1.9. License
- 2. Getting Started with Larch
  - 2.1. First, install Larch
  - 2.2. Second, use XAS Viewer and/or GSE MapViewer
  - 2.3. Third, start scripting with Larch and/or Python
- 3. Larch: Motivation and Overview
  - 3.1. Key Concepts of Larch
  - 3.2. Capabilities
- 4. Larch GUIs
  - 4.1. Larch Command-Line Application
  - 4.2. Basic Larch GUI
- 5. XASViewer
  - 5.1. Reading Data into XAS Viewer
  - 5.2. Common XAS Processing Dialogs
  - 5.3. Pre-edge subtraction and Normalization
  - 5.4. Pre-edge peak fitting
  - 5.5. Linear Combination Analysis
  - 5.6. Principal Component and Non-negative Factor Analysis
  - 5.7. EXAFS Processing: Background Subtraction
  - 5.8. EXAFS Processing: Fourier Transforms
- 6. GSECARS Mapviewr
- 7. QtRIXS
  - 7.1. Reading RIXS data
  - 7.2. Plotting RIXS data
- 8. Programming with Larch from Python
  - 8.1. creating and using a larch interpreter in Python
  - 8.2. The Larch Group
  - 8.3. The optional _larch argument
  - 8.4. Converting “Larch code” into Python
  - 8.5. Larch submodules
- 9. Larch Macro Language Tutorial
  - 9.1. Getting Started
  - 9.2. Basic and Complex Data Types
  - 9.3. Basic Array Manipulation
  - 9.4. Conditional Execution and Flow Control
  - 9.5. Dealing With Errors
  - 9.6. Writing Functions or Procedures
  - 9.7. Running Larch Scripts, and Modules
  - 9.8. Builtin Functions
  - 9.9. Differences between Larch and Python
- 10. Reading and Writing Data
  - 10.1. Simple ASCII Column Files
  - 10.2. Athena Project Files
  - 10.3. Reading HDF5 Files
  - 10.4. Reading NetCDF Files
  - 10.5. Reading TIFF Images
  - 10.6. Working with Epics Channel Access
  - 10.7. Reading Scan Data from APS Beamlines
  - 10.8. Reading XAFS Data Interchange (XDI) Files
  - 10.9. Saving and Restoring Larch Groups
  - 10.10. Reading Spec/BLISS files via silx.io.open
- 11. Plotting and Displaying Data
  - 11.1. Line Plots
  - 11.2. Image Display and Contour
  - 11.3. Advanced Plotting: using matplotlib
- 12. Fitting and Modeling Data
  - 12.1. Fitting Overview
  - 12.2. Parameters
  - 12.3. `minimize()` and objective Functions
  - 12.4. Fit Results and Outputs
  - 12.5. Some Builtin Line-shape Functions
  - 12.6. Fit Examples
  - 12.7. Simplified Peak Fitting with `fit_peak()`
  - 12.8. Advanced Confidence Intervals and Chi-square maps
- 13. XAFS Analysis
  - 13.1. XAFS Functions: Overview and Naming Conventions
  - 13.2. XAFS: Pre-edge Subtraction, Normalization, and data treatment
  - 13.3. XANES Analysis: Linear Combination Analysis, Principal Component Analysis, Pre-edge Peak Fitting
  - 13.4. XAFS: Post-edge Background Subtraction
  - 13.5. XAFS: Fourier Transforms for XAFS
  - 13.6. XAFS: Wavelet Transforms for XAFS
  - 13.7. XAFS: Reading and using Feff Paths
  - 13.8. XAFS: Fitting XAFS to Feff Paths
  - 13.9. XAFS: Computing anomalous scattering factors from XAFS data
- 14. X-ray Databases
  - 14.1. X-ray Properties of the Elements
  - 14.2. X-ray Properties of Materials and Chemicals
- 15. X-ray Fluorescence Analysis
  - 15.1. XRF Data: MCA and ROI objects
  - 15.2. The XRF Viewer Application
  - 15.3. Modelling XRF Data
- 16. References