There is an updated version available, reload the page to see the most recent version.

General

LLWP is a software for using Loomis-Wood plots to efficiently assign lines in spectra. It is published under GNU GPL v3 as it is based on a GUI library with the same copyright.

The program is not biased in regards to input or output formats as well as units, allowing the use of all fixed-width formats and all units. However, LLWP is configured to work out of the box with the SPFIT/SPCAT formats.

If you want to acknowledge LLWP, please cite the paper LLWP — A new Loomis-Wood software at the example of Acetone-13C1.

Also check out the video guides which explain LLWP and some possible usecases in video format.

Installation

LLWP is listed on PyPi and therefore we recommend the installation via pythons package manager pip:

					
						pip install llwp

Then you can start the program from the command line with the simple command

					
						llwp

If you want to start LLWP in ASAP mode run

					
						lasap

Additionally, LLWP is available as python source code via Github. LLWP requires python version 3.9 or higher. In addition to the standard libraries please install recent versions of pandas, scipy, numpy, matplotlib, wrapt, pyqt6 and pyckett.

User Interface

The center piece of the program is the Loomis-Wood Plot with its subplots. Above the plot is a toolbar with controls for navigating the plot and the menubar. The reference frequencies can be provided by different methods, which can be selected in the Reference Series window. When a line is assigned, it is added to the New Assignments window, which also allows to edit the values, delete all or specific assignments and save the assignments. The Log window presents notifications. All the beforehand mentioned windows can be positioned freely allowing for a custom layout.

Additional functionality can be accessed through the modules, which can be accessed by selecting Modules in the menu bar.

The number of rows and columns can be set by the two input fields in the top right corner. With in and out the zoom can be altered and with left and right the current view can be shifted to lower or higher frequencies. Selecting a range of the plot with the mouse while holding Shift will zoom to this range. All these actions are also connected to keyboard shortcuts. Additionally, under Plot > Set Offset the center frequency can be set manually, under Plot > Set Width a specific width can be set. Both of the previous dialogs also allow to enter expressions depending on the quantum numbers, frequencies and so on. With Plot > # Plots the number of rows (and columns) can be changed. For setting only the columns value enter one integer, for rows and columns enter two integers separated by an x.

When hovering the plot with the mouse, the current position of the cursor can be seen in the bottom right corner. Additionally, the closest predicted and assigned transitions can be seen in the Close-By-Lines window which can be shown/hidden under View > Close-By-Lines.

Loading Data and accepted Filetypes

The first step to using LLWP is loading data. The software distinguishes between three different kinds of files, being spectrum files, *.cat files and *.lin files.

Spectrum files are experimental measurements. By default they are tab separated and the frequencies are in the first column, the intensities in the second. To change the default behaviour refer to the Configuration section. The program expects by default data with upward facing peaks.

When using peaklists instead of experimental data, choose Pgopher as the fit function and set Is Stick Spectrum to True in the additional settings dialog for the experimental file (accessed via the small cog symbol behind the file in the Files > Edit Files window).

*.cat files are catalog files, they provide predictions for transitions. The default format is according to the SPCAT specifications but all fixed-width-formats (FWF) can be used.

*.lin files hold already assigned lines, so that they can be marked in the plots. The default format is according to the SPFIT specifications but all FWF can be used.

To use FWF formats instead of the *.cat and *.lin formats, use the flag_catformats and flag_linformats flags in the configuration. The value of the flag has to be a dictionary with the keys being the file extensions and the values being the arguments that should be passed to pandas read_fwf function. Additionally, if for flag_predictionformats intensity_log is a truthy value the intensities are treated as logaritmic intensities.
For custom output formats use flag_saveformat. The underlying function is numpys savetxt function. The value of the flag has to be a dictionary with names being the array of columns, format being an array of the according formats, and delimiter specifying the delimiter.

Reference Series

The Reference Series tab provides four methods to define a reference series.

Transition allows to enter a transition of 1 to 10 quantum numbers (controlled by the series_qns flag in the config). It is important to also check the according increase checkboxes (labelled with Inc), for example a-type transitions (in the typical SPFIT/SPCAT notation) can be followed by checking the first and third increase checkbox. They define which quantum numbers are increased for each plot. If a transition is not found, a reference frequency of 0 will be used.

To increase quantum numbers by a value different than +1, press ⇄ to switch to free input. The Incr checkboxes will be swapped for inputs that accept any integer value.
If you struggle to set up the correct values for the Transition tab, use the Series Finder module and press Start on a transition, which will transfer the correct values to the Transition tab.
The program distinguishes between quantum numbers with a defined value and empty quantum numbers. E.g. if your catalog file only provides three quantum numbers per state, the remaining quantum numbers will be empty. As quantum numbers are internally integers, a sentinel value is needed to indicate empty quantum numbers. The sentinel is implemented as np.iinfo(np.int64).min = -9223372036854775808, meaning the absolute values of your quantum numbers have to be smaller than 9223372036854775808.

List allows for lists of frequencies. The list should contain frequencies that are separated by whitespace (which includes space, newline and tab characters), comma or semicolon. With Start at Index you can set the first frequency that will be used. If the index of the plot is higher than the list the reference frequency will be 0.

Expression allows to enter an expression depending on N and N0 (written as N and N0). Then the value for N0 can be changed with the second input field. Please note, that the expression is evaluated with pythons eval command. An exemplary command for lines with a distance of about 4000 units would be 

					
						(N+N0)*4000

Assigning Lines

You can fit a transition by selecting the according range with your mouse. Then the lineshape of the fit and the middle position will be indicated in the plot. The assigned line is added to the New Assignments table. The uncertainty will be set according to the Default Uncertainty value, which can be found beneath the New Assignments table. Non negative integers are interpreted as numeric values while negative values have a special meaning. For 0 > x >= -1 the absolute value of obs-calc will be calculated and -1 > x >= -2 will prompt for user input, for -2 > x >= -3 the uncertainty from the fitting routine will be used (currently no intrinsic uncertainty is available for the polynom and pgopher fitting routines).

The fit method can be changed under Fit > Change Function, which switches to the next mehtod or a specific method can be selected under Fit > Choose Fit Function.

The assigned transitions in the New Assignments window can be edited or rows can be deleted by selecting the whole row and pressing the delete symbol X in the top left of the window. To delete all rows use Del All. Pressing the Resize button in the top right corner resizes the columns to their content.

The assigned lines can be saved by pressing Save and the flag_appendonsave checkbox specifies if the lines should be appended to the chosen file or if the file should be overwritten. The default format is the *.lin format, but all fixed-width formats can be used.

To use a custom fixed-width format, set the flag_saveformat flag in the configuration. The dicionary, consisting of the keys names, delimiter and format is passed to numpys savetxt function.

Assigned lines are marked with a star symbol. The color of the stars can be changed under Files > Edit Files.

Automated Spectral Assignment Procedure [BETA]

The Automated Spectral Assignment Procedure (ASAP) uses the power of cross-correlation to immensely speed up the assignment process of rovibrational spectra if one of the two vibrational states is known (see the original publication for more detailed information: Martin-Drumel et al.).

If multiple transitions have the same energy level in the unknown state, they all are offset by a common value from the predicted transitions. This allows to cross-correlate the respective parts of the spectum which typically results in only a single strong peak which makes assigning the correct transitions very easy.

To further increase confidence and efficiency multiple cross-correlation plots can be arranged in a Loomis-Wood fashion. This is implemented in LLWP and can be used by starting LLWP in ASAP mode by running lasap from the command line.

More Features

There are so many more features to explore. Assign blended lines via the Blend Dialog or separate them in a multi-component fit in the Blended Lines module. Find series or unassigned transitions in the Series Finder module. Similarly, the Peakfinder module allows to find peaks in the experimental spectrum that are so-far unassgined. Plot residuals or quantum-number coverage plots in the Residuals module. Watch the video guides to see all capabilities of LLWP.

Configuration

The configuration holds the important settings of the program. It can be inspected under View > Config (or under Preferences on Mac). All entries of the configuration are shown and can be changed. The label at the end of the line indicates if the new value is understood or not. The configuration and other values will be saved into a file with the name .ini by pressing Save as default in the configuration window or Files > Save current values as default in the menu bar. On program start the .ini file is read and the configuration is updated accordingly.

Only advanced parameters of the config cannot be changed from the graphical user interface. Thus, beginners can mostly ignore the config.

Shortcuts

Only shortcuts that are not indicated in the graphical user interface are listed here..

Shortcut Command
W zoom in (hold Shift for finer control)
S zoom out (hold Shift for finer control)
A go to lower frequency (hold Shift for finer control)
D go to higher frequency (hold Shift for finer control)
Mousewheel Up zoom in
Mousewheel Down zoom out
Ctrl+S Save Assignments
Ctrl+Space Assign All Dialog
Ctrl+Shift+F Freeze Cursor for Close-By-Lines Window

Questions and Feedback

All kinds of feedback and criticism are welcome, especially bug reports and ideas for improvement. Special praise is earned for feedback on parts, that are newly added or still in an experimental state. In all cases send an email to .

Tipps and Tricks

You can also add files via drag and drop, just release them over the program and choose the correct file class in the pop up dialog. This will add the new files (keeping the currently loaded files).

Instead of pressing the Increase and Decrease buttons in theTransition tab of Define Series, you can also use your mousewheel, gone are the days of wound fingertips.

You assigned some beautiful transitions and accidentally closed the program? You are lucky as the transitions are saved to the ~/.llwp/.lin file everytime the program is shut down properly.

All fields with little arrows at the right hand side, indicating a numeric field, can also be altered with the mousewheel when selected and the Ctrl modifier will increase the step size, so before your mousewheel starts to get hot, try to use Ctrl

It is not recommended to set the number of subplots to an absurdly high number, as this action is not threaded, meaning it will block other actions, and the underlying process of creating a figure with many subplots and the needed initial setup is quite slow. Everything in the range of low houndreds should be perfectly fine.

Go to the video guides to get a quick introduction in the short guide or a more detailed presentation in the exhaustive guide.