10. Larch Macro Language Tutorial

Larch provides both a Python programming library and Python-like programming or macro language (which we’ll call Larch macro language here) for processing of scientific data. You can use either of these to interact with the X-ray analysis functions described throughout this document. If you already know Python or are interested in learning and using Python, we definitely encourage to use the Python interface.

Here, the Larch macro language is described in some detail. This macro language is a dialect of Python and is used for the Larch command-line shell program. This macro language is also used for communication between the Larch server process and Athena/Artemis. Perhaps most importantly, it is also embedded in the Larch GUI applications so that you can “open the Larch buffer” and use the Larch/Python functions on the data that has been loaded into the GUI. The Larix program really does all of its work with the Larch buffer so that you can see the complete (if somewhat) verbose list of commands and functions it is running when processing your data. You can take these commands as documentation of the processing steps or use them as examples for writing batch processing scripts or more complex programs.

This chapter describes the Larch language and using it for data processing. An important goal of Larch is to make writing and modifying data analysis scripts as simple as possible. Although aimed at the novice programmer, this tutorial does make a few assumptions about the readers experience with scientific programming. For example, the reader is expected to have a technical background and some familiarity with using scientific data analysis programs. Some understanding of the concepts of how scientific data is stored on computers and of the basics of programming will greatly help the reader.

The Larch language is implemented in Python, and heavily based upon it. Knowledge of Python will greatly simplify learning Larch, and vice versa. This shared syntax is intentional, so that as you learn Larch, you will also be learning Python, which can be used to extend Larch. Alternatively, knowledge of Python will make Larch easy to learn. For further details on Python, including tutorials, see the Python documentation at https://python.org/

Contents:

• 10.1. Getting Started
  • 10.1.1. Larch as a Basic Calculator
• 10.2. Basic and Complex Data Types
  • 10.2.1. Basic Data Types
  • 10.2.2. Objects and Groups
  • 10.2.3. More Complex Data Structures: Lists, Arrays, Dictionaries
  • 10.2.4. Object identities, copying, and equality vs. identity
• 10.3. Basic Array Manipulation
  • 10.3.1. Functions for creating arrays
  • 10.3.2. The array dtype – datatype
  • 10.3.3. Basic array manipulation
  • 10.3.4. Slicing and extracting sub-arrays
  • 10.3.5. Array attributes and methods
  • 10.3.6. Mathematical functions for arrays
• 10.4. Conditional Execution and Flow Control
  • 10.4.1. Conditional Evaluation with if and else
  • 10.4.2. For loops
  • 10.4.3. While loops
• 10.5. Dealing With Errors
  • 10.5.1. Syntax Errors
  • 10.5.2. Exceptions
  • 10.5.3. Try and Except
  • 10.5.4. Raising your own exceptions
• 10.6. Writing Functions or Procedures
  • 10.6.1. Def statement
  • 10.6.2. Namespace and “Scope” inside a Procedure
  • 10.6.3. The return statement, and multiple Return values
  • 10.6.4. Keyword arguments
  • 10.6.5. Documentation Strings
• 10.7. Running Larch Scripts, and Modules
  • 10.7.1. Running a larch script with run()
  • 10.7.2. Importing a Larch Script as a Module
• 10.8. Builtin Functions
  • 10.8.1. Builtin data values
  • 10.8.2. Larch-Specific Builtin functions
  • 10.8.3. Builtin functions inherited from Python
• 10.9. Differences between Larch and Python
  • 10.9.1. Code Block Ends
  • 10.9.2. Groups vs Modules
  • 10.9.3. Symbol Lookup Rules
  • 10.9.4. Unimplemented features