\(\newcommand{\AA}{\unicode{x212B}}\)

Larch

Larch is an open-source Python 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. Larch provides a comprehensive set fo analysis tools for X-ray absorption fine-structure spectroscopy (XAFS), including both X-ray absorption near-edge spectroscopy (XANES) and extended X-ray absorption fine-structure spectroscopy (EXAFS). Larch also provides 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 and relies on the excellent scientific python libraries including numpy, scipy, h5py, matplotlib. In turn, Larch provides a comprehensive Python library for processing and analyzing X-ray spectroscopy and imaging data. Several Python libraries - xraydb, larixite, lmfit, asteval, wxmplot, and pyshortcuts - were originally built for or Larch, or as a part of Larch and then spun-off into separate libraries that can be used by the broader X-ray and scientific programming communities.

Larch includes a few GUI applications that provide user-friendly and interactive data visualization for many common X-ray analysis tasks. The most notable of these are Larix, GSE Map Viewer, and Larch XRF.

Larch includes a Python-like macro language - the “Larch language” - for interactive and batch processing. This macro language is an isolated, restricted “mini-Python” (from asteval), intended to be easy to use and complete enough to automate data processing and analysis available as an interactive command-line interface. This command-line interface is available either from the larch or Larch GUI. While not recommended for serious programming, it is an important part of the Larch package and the bridge between the GUI applications and writing batch-processing analysis scripts.

Most of the GUIs (notably, Larix) work by generating and executing this “Larch code”, with all of the real work done through this macro language. This allows for self-documented and reproducible analysis sessions, and facilitates transitioning from GUI-only analyses to scripting, batch processing, and programmatic analysis of larger data sets. That is, with a few simple changes and added boilerplate code, the Larch macro code saved from a GUI session becomes a Python program. This macro language also allows Larch to be run as a background service so that other processes can use Larch as the analysis engine - this was the original motivation and is still an important consideration. The popular Demeter XAFS application suite can use Larch in this way, though the Larix now contains almost all of the features of Demeter and is much more actively being developed and maintained.

Larch is distribute under the open-source MIT license. Larch is under active and open development centered at the GeoScoilEnviroCARS sector of Center for Advanced Radiation Sources at the University of Chicago. Support has come from the US National Science Foundation Earth Sciences Division, currently through SEES: Synchrotron Earth and Environmental Science (EAR-222327), and previously from NSF Earth Sciences Division (EAR-1128799), and Department of Energy GeoSciences (DE-FG02-94ER14466). 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, the Application Type will be GUI = Graphical User Interface, CLI = Command Line Interface, or Broswer to indictate that it runs in a browser. beta indicates a work in progress, and dep indicates that it is deprecated and not recommended for primary use. 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 redistribute.

Application Name	Type	Description
Larix	GUI	XAFS Processing and Analysis: XANES, EXAFS, run Feff, Feff-fitting, more.
XRFMap Viewer	GUI	XRF Map Viewer for GSECARS-style X-ray microprobe data.
Larch_XRF	GUI	Display and Analyze XRF Spectra.
Larch_XRD1D	GUI beta	Display and work with 1-D XRD patterns
sitka spruce	GUI beta	Data Browser for HDF5 and Zarr data
qtrixs	GUI beta	Display RIXS planes, take profiles
Jupyter Lab	Browser	Run Jupyter Lab in a browser using the Python installed with X-ray Larch.
feff8l	CLI	Feff 8 EXAFS calculations (no XANES)
feff6l	CLI dep	Feff 6 EXAFS calculations
larch	CLI dep	simple shell command-line interface
Larch GUI	GUI dep	enhanced command-line interface with data browser

Table of Contents

• 1. Downloading and Installation
  • 1.1. Installing with Binary Installers
  • 1.2. Installing with the GetLarch.sh and GetLarch.bat scripts
  • 1.3. Installing into an existing Anaconda Python environment
  • 1.4. Installing with pip into an existing Python environment
  • 1.5. Updating X-ray Larch
  • 1.6. Installing the development version
  • 1.7. Making Desktop shortcuts to Link to the Applications
  • 1.8. Larch for developers (source installation)
  • 1.9. Getting Help
  • 1.10. Docs and Examples
  • 1.11. Citing Larch
  • 1.12. Funding and Support
  • 1.13. Acknowledgements
  • 1.14. License
• 2. Getting Started with Larch
  • 2.1. First, install Larch
  • 2.2. Second, use Larix (was 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
• 4. Other Larch GUIs
  • 4.1. Larch Command-Line Application
  • 4.2. Basic Larch GUI
• 5. Larix
  • 5.1. Larix Overview
  • 5.2. Reading and Saving Data into Larix
  • 5.3. Pre-edge subtraction and Normalization
  • 5.4. Common XAS Processing Dialogs
  • 5.5. Pre-edge peak fitting
  • 5.6. Linear Combination Analysis
  • 5.7. Principal Component and Non-negative Factor Analysis
  • 5.8. Linear Regression with LASSO and PLS to predict external variable
  • 5.9. EXAFS Processing: Background Subtraction
  • 5.10. EXAFS Processing: Fourier Transforms
  • 5.11. Fitting EXAFS data to Feff Paths
• 6. XRFMap Viewr
• 7. Larch XRD1D Viewer
• 8. QtRIXS
  • 8.1. Reading RIXS data
  • 8.2. Plotting RIXS data
• 9. Programming with Larch from Python
  • 9.1. creating and using a larch interpreter in Python
  • 9.2. The Larch Group
  • 9.3. The optional _larch argument
  • 9.4. Converting “Larch code” into Python
  • 9.5. Larch submodules
• 10. Larch Macro Language Tutorial
  • 10.1. Getting Started
  • 10.2. Basic and Complex Data Types
  • 10.3. Basic Array Manipulation
  • 10.4. Conditional Execution and Flow Control
  • 10.5. Dealing With Errors
  • 10.6. Writing Functions or Procedures
  • 10.7. Running Larch Scripts, and Modules
  • 10.8. Builtin Functions
  • 10.9. Differences between Larch and Python
• 11. Reading and Writing Data
  • 11.1. Simple Plaintext (ASCII or UTF-8) Column Files
  • 11.2. Reading XAFS Data Interchange (XDI) Files
  • 11.3. Athena Project Files
  • 11.4. Reading HDF5 Files
  • 11.5. Reading NetCDF Files
  • 11.6. Reading TIFF Images
  • 11.7. Working with Epics Channel Access
  • 11.8. Reading Scan Data from APS Beamlines
  • 11.9. Reading Spec/BLISS files via silx.io.open
  • 11.10. Reading FDMNES output files
  • 11.11. Saving and Loading Larch Session Files: .larix Files
• 12. Plotting and Displaying Data
  • 12.1. Line Plots
  • 12.2. Image Display and Contour
  • 12.3. Advanced Plotting: using matplotlib
• 13. Fitting and Modeling Data
  • 13.1. Fitting Overview
  • 13.2. Parameters
  • 13.3. minimize() and objective Functions
  • 13.4. Fit Results and Outputs
  • 13.5. Some Builtin Line-shape Functions
  • 13.6. Fit Examples
  • 13.7. Simplified Peak Fitting with fit_peak()
  • 13.8. Advanced Confidence Intervals and Chi-square maps
• 14. XAFS Analysis
  • 14.1. XAFS Functions: Overview and Naming Conventions
  • 14.2. XAFS: Pre-edge Subtraction, Normalization, and data treatment
  • 14.3. XANES Analysis: Linear Methods, Pre-edge Peak Fitting
  • 14.4. XAFS: Post-edge Background Subtraction
  • 14.5. XAFS: Fourier Transforms for XAFS
  • 14.6. XAFS: Wavelet Transforms for XAFS
  • 14.7. XAFS: Reading and using Feff Paths
  • 14.8. XAFS: Fitting XAFS to Feff Paths
  • 14.9. XAFS: Computing anomalous scattering factors from XAFS data
• 15. X-ray Databases
  • 15.1. X-ray Properties of the Elements
  • 15.2. X-ray Properties of Materials and Chemicals
• 16. X-ray Fluorescence Analysis
  • 16.1. XRF Data: MCA and ROI objects
  • 16.2. The Larch XRF Application
  • 16.3. Modelling XRF Data
• 17. References