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, be aware that the output files will use the input units.
If you want to acknowledge LLWP, please cite the paper LLWP — A new Loomis-Wood software at the example of Acetone-13C1.
Installation
LLWP is now 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
Additionally, LLWP is available as python source code (.pyw) or as a Windows executable (.exe). The .exe file includes the python interpreter and the required libraries for Windows 10 and greater. It only needs to be downloaded with a single click (meaning you can skip the rest of this section).
The .pyw file 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 plot canvas with its subplots. Above the plot is a toolbar with controls for navigating the plot and the menubar. The Configure Plots window provides options for the scaling, annotations and more. 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 Catalog of newly assigned Lines 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.
Navigating the Plots
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. By default, selecting a range of the plot with the mouse will zoom to this range. All these actions are also connected to keyboard shortcuts. Additionally, under Plot > Go to … the center frequency can be set manually, under Plot > Set Zoom a specific width can be set and under Plot > # Plots the number of rows (and columns) can be set. 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 on top of the plot. Additionally, the closest predicted and assigned transitions can be seen in the Hover window. The Hover windows visibility can be toggled under View > Hover.
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 data with upward facing peaks.
*.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.
For the three file types, there are two actions each, which are located in the menubar under Files. The load action replaces the old files, whereas add keeps already loaded files.
You can find an overview of all opened files under Files > Edit Files. Additionally, you can find here options to delete, hide, or scale files as well as to change its color. All spectra are expected to have positive peaks. Should your spectra have downwards facing peaks use a negative scaling factor.
For convenience, project files can be saved and loaded. They are identified by the .llwp extension and follow the .ini format. A project consists of the paths to all spectrum, *.cat and *.lin files as well as their options.
Reference Series
The Reference Series tab provides four methods to define a reference series.
Transition allows to enter a transition of 1 to 6 quantum numbers (use QN + and QN - to alter the number of QNs). It is important to also check the according increase checkboxes (labelled with Incr), 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, the frequency will be set to 0.
If you struggle to set up the correct values for the Transition tab, use the seriesfinder window and press Start on a transition, which will transfer the correct values to the Transition tab.
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 Min 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
Fortrat shows a Fortrat diagram with the specified starting value for J. It consists of subplots that display the intensity against the frequency divided by 2J. The J values starts with the specified value and increases by one with each plot. This allows to easily find series without any a priori knowledge. Just vary the center value and see if transitions appear. Due to the nature of Fortrat diagrams, certain options take no effect or are adapted, e.g. the go to dialog specifies the frequency/2J value and not the frequency.
Apply updates the series definition and recenters the plots to the predicted frequency, as you are still able to move inside the plots to higher or lower frequencies.
Assigning Lines
If you do not specify otherwise, you can fit a transition by pressing shift and 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 Catalog of newly assigned Lines table. The uncertainty will be set according to the Default Uncertainty value, which can be found beneath the Catalog of newly assigned Lines 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.
All assigned lines can be seen in the Catalog of newly assigned Lines window. The values 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 tight button in the top right corner resizes the columns to their content.
The assigned lines can be saved by pressing Save and the append 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.
Assigned lines are marked with a star symbol. The color of the stars can be changed under Files > Edit Files.
If Fit > Always Assign is checked, every assignment will be added to the Catalog of newly assigned Lines table. Otherwise, the Fit > Manual Assign action can be used to add the last assignment to the Catalog of newly assigned Lines table.
Configure Plots
This tab controls the plot options. The minimum and maximum of the y-axis of the experimental and cat data are controlled by y-scale. Per Plot scales each plot indepentendently and also scales experimental and cat data independently. The other options scale experimental and cat data in a fixed ratio given by y-Exp/y-Cat. Global uses the global minimum and maximum for the scaling while Custom allows the user to set the minimum and maximum. Please be aware, that always a margin, specified in the config, is added to the y-range.
Furthermore the plots can be decoupled to allow to move only certain plots, and plots can be annotated, displaying the corresponding transition or frequency (depending on which series method is used).
The binning field sets the binning parameter, which specifies the number of datapoints each subplot has to handle. If the number of datapoints in the subplots range is lower than the binning parameter, no downsampling occurs. Are there more datapoints in the range of the subplot than specified by the binning parameter, then the data in the subplots range is grouped into equidistant bins, with widths corresponding to the binning parameter, and only each bins maximum value is displayed, resulting in an positive envelope. If you set the binning parameter too low the visual quality of your plots may suffer. If the value is set too high, updating the plot could get slow and unresponsive.
In other words the binning parameter can be seen as your personal matplotlib trust parameter, as a higher value will transfer computing cost from the main program (caused by binning) to the matplotlib library (caused by drawing more points). A sensible lower minimum is the horizontal resolution of your screen, the maximum depends on how many datapoints you trust matplotlib to handle without getting unresponsive or running into problems. Additionally, the optimal value depends on the number of subplots you plan to display, as more subplots increase the stress on the underlying matplotlib library.
If still unsure, it is feasible to set the binning parameter to 2-10 times your displays horizontal resolution, as you will not benefit from signifcantly more pixels than your monitor can display. However, this might not be the most performant choice.
More Features
Blend Dialog
The blend dialog allows to assign multiple transitions as a single blend. Make sure, that the Transition method is used to define a series and Blend Dialog is checked. Additionally, at least one additional line has to lie within the distance specified by Blend Width of the assigned line. Then you are presented with a dialog which allows to assign multiple lines to the same peak. The blend dialog is a tool to speed up the assignment of blended series.
Blended Lines
By clicking Modules > Blended Lines the current section of the plot is opened in an additional window and multiple peaks and a baseline can be fit to it. Possible lineshapes are Gaussian, Lorentzian, Voigt and the first and second derivatives of the previous. By clicking in the spectrum an additional peak can be added. The default values for the center frequency and the amplitude of the new peak will be according to the position that was clicked. The individual peaks as well as the sum are shown. A baseline polynom can be added by specifying a non negative rank.
Resulting middle positions can be directly assigned with the Assign button or be assigned to other quantum numbers. This module allows to assign resolvable blends, as it allows to determine an individual center frequencies for each peak in the blend.
Additionally, all parameters of the fit can be saved via the Save button. The parameters are appended in json format to the file ~/.llwp/.lin (with ~ being the users home directory).
Seriesfinder
The seriesfinder window can be found under Modules > Seriesfinder and allows to search the predicted transitions. A range, only specific transition types or a custom query can be used to filter the lines. The matches are ordered by intensity and presented in a table.
By clicking start in the according row, the transition is transferred to the main window. Please doublecheck, which QNs you want to increase, as the values for the increase checkboxes are guessed by the program and might be wrong. Also be aware, that the transition might be at the upper limit of your spectrum and therefore you might want to shift to lower QNs with Decr.
For the additional condition all properties of the *.cat file can be used, being 'x', 'error', 'y', 'degfreed', 'elower', 'usd', 'tag', 'qnfmt', 'qnu1', 'qnu2', 'qnu3', 'qnu4', 'qnu5', 'qnu6', 'qnl1', 'qnl2', 'qnl3', 'qnl4', 'qnl5', 'qnl6', in combination with typical operators, e.g. “+”, “-”, “==”, “<”, “>”, “>=”, “<=”.
Peakfinder
The peakfinder module can be found under Modules > Peakfinder and allows to create peaklists from the spectrum. A plot marks the currently found peaks for confirmation. Beneath the plot are buttons to run the peakfinder, export all found peaks, an uncertainty input and the Only unassigned Lines checkbox. If this is checked, all peaks that are within the uncertainty value from an allready assigned line are excluded from the output.
The arguments for the peakfinder are found beneath the buttons. See the scipy documentation of find_peaks for further information on the arguments (e.g. the distance is in samples and not in units of a frequency). Always check if the found peaks are sensible in the plot after running the peakfinder.
Residuals
The residual window module can be found under Modules > Residuals and allows to display e.g. obs-calc values. The intersection of the *.cat and *.lin files is used. The x- and y-axis can be chosen as any expression of the resulting values, e.g. use x_lin-x_cat for the y-axis and x_lin to plot the obs-calc values against the frequency. In addition a query field is present to allow for selecting only a subset of transitions and a custom color field which allows to define custom colors for specific transitions. Check the Blend checkbox to consider assignments with the same assigned frequency as a blend. The predicted frequencies will then be adjusted accordingly.
Energy Levels
The energy levels window can be found under Modules > Energy Levels and allows to plot quantities from the .egy files. The x- and y-axis can be chosen as any expression of the columns. Some examples would be plotting egy against qn1 or reduced energy plots. In addition a query field is present to allow for selecting only a subset of energy levels and a custom color field which allows to define custom colors for specific levels.
Spectra Resolver
The spectra resolver window can be found under Modules > Spectra Resolver and allows to create a single overlap-free spectrum out of many overlapping spectra. The currently loaded spectrum files can be ordered by dragging them with the mouse. By pressing Save overlap free the files are merged into a single overlap free spectrum according to the given order.
Lineshape
The lineshape module can be found under Modules > Show Lineshape and allows to compare the experimental spectrum with a simulated spectrum (from the prediction files). The lineshape and widths can be varied to match the experimental spectrum.
Series Fit
The series fit module can be found under Modules > Series Fit and allows to fit a custom expression to a supposed series. If the window is open, assigned lines are added to the table in there instead of to the Catalog of newly assigned Lines. Using the assigned quantum numbers, an expression can be fit to the lines.
The table on top holds the lines that will be used. Underneath the current series is selected. As only lines matching this series will be used, entries with no quantum numbers will never be used.
Underneath is the field for the function. Enter the quantum numbers with the same label that is used in the table header. For example to fit a linear rotor model 2B*J*(J+1) enter 2*B*(qnl1+1). The fit button will start the procedure of fitting. Messages are displayed in the field at the bottom.
By pressing Show, the calculated frequencies will be transfered into the List tab of Define Series, allowing to examine the fit.
Create Report
The create report module can be found under Modules > Create Report and allows to create a report of the currently loaded (and not hidden) data. A query field can be used to filter the assigned transitions and the Blend checkbox controls if blends are considered or not.
Create Figure
The create figure module can be found under Modules > Create Figure and allows to create publication quality figures. The data from the main plot is shown and the size, dpi, font-size, axis labels, and annotations can be customized. Further options are available via the config. The resulting figure can be previewed and saved to a user-selected format.
Pipe
The pipe module can be found under Modules > Pipe and allows to execute command line commands from within the program. New tabs can be opened by double clicking in the tab bar. Each tab can hold one command and gives the option to reload each of the three file types after the command has finished.
Drag the tabs to reorder or press X to close them.
The current tab can be run with the keyboard shortcut Ctrl+P. You can switch to other tabs by clicking them in the pipe module or by pressing Ctrl+L. This means, that after initially setting up your commands, you do not have to reopen the Pipe window.
The pipe commands are the same command you would enter in the command line, to e.g. run your fitting program or generate your predictions. Newline characters are replaced by ’ && ’, allowing the user to use newline to separate commands.
Saving Current Values
With Files > Save current values as default the current options can be saved into a .ini config file, which is located in the users home folder in the .llwp folder. On the next startup this file will be read to set the default values. The values can also be changed by hand in the .ini file, refer to the Configuration section for more information.
Matplotlib Toolbox
There is an option to show the matplotlib toolbox under View. This allows to fine tune the plots, save a picture of the figure or do other matplotlib related tasks.
Manual Drawing
To reduce stress from your system, there is an option to disable automatic drawing of the plots under Plot > Automatic Draw and an option to draw them manually Plot > Manual Draw. Then the canvas will be only redrawn on manual draw and not on each update to the plots. This might be especially handy for huge datasets or huge amounts of plots, as those can make the underlying matplotlib library slow.
If your experience suffers from poor performance, consider changing your binning parameter, if it is set to a value higher than the magnitude of your screen resolution, try reducing it.
Console Input
By pressing Shift+K the console input window opens, in which you can execute python code. This option is very powerful and should not be used thoughtlessly.
Configuration
The configuration holds the important settings of the program. It can be inspected under Modules > 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 Make current values default in the menu bar. On program start the .ini file is read and the configuration is updated accordingly. In addition to changing the values in the configuration window, many values can be changed in the graphical user interface or the .ini file can be edited by hand.
In the following the configuration parameters, their allowed values and meanings are described.
| Parameter | Allowed Values | Info |
|---|---|---|
| layout_theme | {str} | The current theme of the layout. Options are ‘light’, ‘dark’ or ‘custom’ |
| layout_owntheme | {dict} | The custom theme as a dictionary |
| layout_mpltoolbar | {bool} | Visibility of the Matplotlib toolbar in the LWP |
| color_exp | {color} | Default color for spectrum data |
| color_cat | {color} | Default color for prediction data |
| color_lin | {color} | Default color for assigned markers and annotations |
| color_cur | {color} | Color for the current reference series |
| color_fit | {color} | Color for the fit function |
| fit_error | {float} | Value of ‘Default Uncertainty’ field |
| fit_function | {str} | Fit function to be used |
| fit_alwaysfit | {bool} | True: always fit on selecting range with mouse; False: fit if shift is pressed, zoom otherwise |
| fit_alwaysassign | {bool} | True: add assigned line automatically |
| fit_polynomrank | {int} | Rank of polynom for fitting |
| fit_polynommaxrank | {int} | Max rank of Polynom Autorank fitting procedure |
| fit_uncertaintystep | {float} | Step for ‘Default Uncertainty’ field |
| fit_xpoints | {int} | Number of xpoints in selected range for fitting |
| fit_offset | {bool} | True: fit uses offset; False: no offset |
| fit_comment | {str} | Default comment for newly assigned lines |
| fit_clipboard | {bool} | Copy frequency of fit to clipboard |
| plot_dpi | {float} | DPI for plots |
| plot_annotations_dict | {dict} | Dict for annotations passed to matplotlib |
| plot_font_dict | {dict} | Dict for fonts passed to matplotlib |
| plot_matplotlibkwargs | {dict} | Dict for figure passed to matplotlib |
| plot_coupled | {bool} | Value of ‘Plots are Coupled’ field |
| plot_ymargin | {float} | Margin in y-direction for plots in percent |
| plot_annotate | {bool} | Value of ‘Annotate Plots’ checkbox |
| plot_hover_cutoff | {float} | Cutoff for closest transition |
| plot_rows | {int} | Number of rows of LWP |
| plot_cols | {int} | Number of columns of LWP |
| plot_ticks | {int} | Number of xticks for LWP |
| plot_offsetticks | {int} | If xticks are offset (1) or not (0) or in scientific format (2) |
| plot_yscale | {str} | Value of ‘y-scale’ field |
| plot_expcat_factor | {float} | Factor of ‘y-Exp/y-Cat’ field |
| plot_expcat_exponent | {int} | Exponent of ‘y-Exp/y-Cat’ field |
| plot_yscale_min | {float} | Value of ‘y-min’ field |
| plot_yscale_max | {float} | Value of ‘y-max’ field |
| plot_offset | {float} | Offset from reference series of LWP |
| plot_width | {float} | Width of LWP |
| plot_bins | {int} | Number of bins of LWP |
| plot_skipbinning | {int} | Threshold of dataframe length under which binning procedure is skipped |
| plot_expasstickspectrum | {bool} | Plot spectrum as sticks instead of line (useful for peakfinder data) |
| plot_relativegoto | {bool} | If value of the go to dialog is relative or absolute |
| series_qns | {int} | Number of quantum numbers |
| series_annotate_xs | {bool} | Annotate frequencies instead of transition |
| series_blendwidth | {float} | Cutoff for possible blended lines |
| series_blenddialog | {bool} | If blend dialog should be shown |
| series_currenttab | {int} | The number of the current series tab |
| series_references | {list} | Data of the series tabs |
| flag_automatic_draw | {bool} | If plot is updated automatically |
| flag_appendonsave | {bool} | If saving lines should append or overwrite |
| flag_hidecatalog | {bool} | Visibility of newly assigned lines |
| flag_xcolumn | {int} | Column for x-data in spectrum files |
| flag_ycolumn | {int} | Column for y-data in spectrum files |
| flag_separator | {int} | Separator for spectrum files in ascii characters; 9 is tab, 44 is comma, 59 is semicolon |
| flag_debug | {bool} | Debug mode |
| flag_alwaysshowlog | {bool} | If log should be shown when a new notification is received |
| flag_extensions | {dict} | Dict to connect extensions to file types |
| flag_autosetqns | {bool} | If number of quantum number should be set according to data |
| flag_predictionformats | {dict} | Dict to specify prediction format |
| flag_assignmentformats | {dict} | Dict to specify assignment format |
| flag_assignmentsavefmt | {dict} | Dict to specify format to save assignments |
| flag_loadfilesthreaded | {bool} | If files should be loaded in main thread or own thread |
| flag_shownotification | {bool} | If notifications should be shown in top right corner |
| flag_notificationtime | {int} | Time notifications stay visible |
| flag_showmainplotcontrols | {bool} | If controls left, right, in, and out should be shown on top of the LWP |
| flag_showmainplotposition | {bool} | Controls if the cursor position is shown on top of the LWP |
| flag_showmainplotwidth | {bool} | If width field should be shown on top of the LWP |
| flag_showmainplotrowscols | {bool} | If rows and columns number fields are shown on top of LWP |
| flag_referencenumberlocked | {bool} | If number of series tabs should be locked to number of columns |
| flag_logmaxrows | {int} | Max number of rows in log window |
| flag_tableformatint | {str} | Format for integers in tables |
| flag_tableformatfloat | {str} | Format for floats in tables |
| flag_autosave | {int} | Time interval in seconds between autosaves. Assigned lines are saved to the file ~/.llwp/.lin. 0 disables autosaving. |
| pipe_current | {int} | Current pipe tab |
| pipe_commands | {list} | Commands of pipe tabs |
Shortcuts
Only shortcuts that are not shown next to their respective actions are listed. The shortcuts for menubar actions are shown next to the actions.
| 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 |
| Shift+K | open console input |
| Ctrl+P | run pipe command |
| Ctrl+L | next pipe command |
| F11 | toggle fullscreen |
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
Two versions of the program are currently available, an .exe file and an .pyw file. The .pyw file is useful if you want to inspect or borrow code and has a faster startup. The .exe file is handy for all those, who despise the python package manager.
The .exe version is compiled to start without the console window, the .pyw file does also start without a console window. If you want to see the python console, change the ending from .pyw to .py.
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 or it crashed? In the first case you are lucky as the transitions are saved to the ~/.llwp/.lin file everytime the program is shut down properly. If the program crashed, the ~/.llwp/.lin file will hold the assignments from the last autosave (which by default runs every two minutes).
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, but if you are keen to push the limits, please have first a dry run without any assigned lines, as on my machine 1000 subplots caused the program to become unresponsive for about 50 seconds, however no crashes occurred.
FAQ - Frequently Asked Questions
Can I doubleclick projects to open?
You can open projects by doubleclicking a project file on windows with the .exe version. To do so right click an .llwp project file and selct Open with and then select LLWP.exe under Choose another app. Be sure to check Always use this app to open .llwp files.
For the python files a little workaround is needed which depends on your installation method. Create a batch file with the name LLWP.bat. If LLWP was installed as a library add the following content
llwp %1
cd %~dp0
START .\LLWP.pyw %1
Then repeat the same steps as for the .exe version but choose the LLWP.bat file.
Please note, that using this technique will open a new instance on every doubleclick, if you want to open a project in an already running instance of LLWP you can drag and drop the project onto the running instance or use the Load Project action.
Where do I find the Video Guides?
Go to the video guides to get a quick introduction in the short guide or a more detailed presentation in the exhaustive guide.