Spectra Trace Offset and Graph Size Tools - Quick-access to common graph and trace modify commands

This project provides three panels and menu functions for quickly and conveniently changing traces and common graphs style options. The panels always operate on the topmost graph. You can select another graph and then switch back to the panel, which updates all settings automatically. Panels other than the Quick-Scale tool (which always works directly on the data; see below) do not modify the underlying data unless explicitly told to do so.

The original code and the idea for the Offset Traces right-click menu has been kindly provided by Tony (https://www.wavemetrics.com/user/tony) from his StackTraces toolset. I tried my best to test everything thoroughly, but sometimes bugs slip through. Bug reports and suggestions for new features are always welcome.

The Graph Size panel

Use this panel to change the graph size, margins or axis labels and to apply style macros quickly. All changes are live. Settings can also be copied and applied to other graphs. Start the panel by selecting 'Spectra Tools' -> 'Graph Size Panel ...' from menu bar or executing:

Here is a quick overview of all functions:

In the top area you can set margins, plot area and graph sizes. In short, most settings of the Modify Graph dialog are recreated here for quick access. This panel shows the current dimensions even when the graph scaling is in 'auto' mode, which is convenient for checking all sizes. Furthermore, the total graph size (plot area + margins) can be set directly (green arrows), which is not possible from the Modify Graph dialog.

Numbers rendered in bold font show that these properties are locked to a specific value (fixed mode). In other words, these values will not change/cannot be changed dynamically, for example, by scaling the graph with the mouse. Insert 0 (zero) into the respective field to unlock the value (revert back to 'Auto' mode). If 'Keep Auto Mode' is checked, then changing the graph or plot area sizes will not lock these values. Margin sizes will get always locked upon changing the value, since margin sizes are predefined in Auto mode and cannot be modified.

The font control will change the global graph font size (as found in the Modify Graph dialog), or alternatively when holding the shift key the global axes font size (as found in the Modify Axis dialog). Font sizes specified for individual axes etc. override the global graph font size. The global graph font size will scale all fonts and adjusts margins etc. accordingly.

Activate the print checkbox and most changes (other than Format or Copy/Paste actions) will be printed to the history.

The magn. control changes the magnification setting of the graph, which is useful to enlarge / shrink graphs without changing their (physical) size.

The Aspect Ratio setting, as the name implies, locks the aspect ratio of the plot area (without the margins) to certain common presets, such as 3:2 or 16:9.

The Format drop-down menu allows to quickly set the graph to common formats (useful for copy-pasting or graphics export):

• Paper Half / Full: Publication size figures of one column (3.25 inch) or double-column (7 inch) width.
• PPT 4:3 / 16:9: Power-point size plots for 4:3 or 16:9 format slides (full and half each).

The Copy Sizes and Paste to Top buttons are for copying margin and graph size settings to another graph. Press Copy to save the current settings, then bring another graph to the top and press Paste.

The bottom-most area is for applying graph style macros. Select the desired style in the drop-down box and press Apply to Top. The style can be reverted to the previous style for the current graph by pressing Revert to Last. This function only saves the state of the current graph when pressing Apply. Undo states for multiple graphs are not saved.

The Copy Style button saves the current style of the top graph to apply the same style to another graph later. If the 'Include Axis Scaling' checkbox is active then the current X and Y axis range limits are copied and applied as well. A 'Copied Style' will appear in the list after pressing the button, which can be applied to other graphs with the Apply button just as a regular style macro. Check 'Copy to Clipboard' (or hold the shift key) to copy the style to the clipboard instead. This is useful for editing the style in a text editor before application or to apply the style in another experiment. Choose 'From Clipboard' in the style selector in this case.

The project includes a standard style, named 'BoxStyle', and several label style macros, which apply labels from a few spectroscopic techniques to the graph. Holding 'ctrl' (Win) / 'command' (Mac) will suppress the ticks and labels on the left axis while applying the BoxStyle style, and will label the x axis with 'Binding energy' instead of 'Kinetic energy' while applying the PKE_Label style.

Graph and Traces Right-click Menus

New functionality has been added to ...

• the marquee right-click menu (after you drag open a marquee box):

The options for the marquee menu use the x-range of the marquee to search for maxima or average values. The range (height) in y-direction of the marquee does not matter here.

•  the trace right-click menu (which appears when right-clicking on a trace).
• the graph's right-click menu (when you right-click on an empty area of the graph):

The 'Traces: Normalize' submenu:

This menu contains the following options and can be used to normalize traces to a common value via y-scaling and y-offsets.

• to One - Normalize to y = 1.
  • Maxima - Normalize to the maximum y-value.
  • Area - Normalize area.
  • at [Mouse, A, B, C...] Cursor x Position - Normalize to the y-value at the cursor position.
  • Maxima / Average around [Mouse, A, B, C...] Cursor - The y-values are searched around the cursor position (in a range of 3 % of the data's full x-scale).
• to Global Maximum - Normalize to y = value of highest trace (i.e., the trace with the highest value stays unmodified).
  • Same as above but for the global maximum as target value.
• at [Mouse, A, B, C...] Cursor - Normalize to the y-value at the cursor position.

     The options for normalization are:

• Select Cursor - Set the used cursor for above menu options.
• Smoothing Factor ... - If set, the data will be smoothed before normalization. This can help with noisy data.
• Keep y-Offset at Zero - If activated, each y-offset will be set to 0. Otherwise the y-Offset will be adjusted to bring the trace's baseline to zero.
• Keep Current y-Offset - If activated then the current y-offset of each trace will not be altered.
• Export Offsets to Wave - A wave named 'Offsets_GRAPHNAME' will be created in the current folder logging the y-offset and scaling for each trace in the graph.
  ------
• Undo All Scaling - y-scaling of all traces will be reset to 0. 
• Undo All Offsets - y-offsets of all traces will be reset to 0.

The 'Traces: Offset and Sort' submenu:

This menu contains the following options. All these options work with the current y-axis range of the graph. You may want to increase the y-range before applying these options for maximum effect.

• y-Order Traces Alphanumerically - Traces are rearranged according to their name in alphabetical order
  ------
• Spread Traces Across y Range - Adds offsets to each trace to distribute traces across the current y-range (initial offsets are preserved).
• Spread Traces: Equal Offset - Adds equal offset steps to each trace to distribute traces across the current y-range.
• Spread Traces: Equal Gap - Adds offsets to each trace to distribute traces across the current y-range in a way which keeps the gap between traces (= maximum of previous trace to minimum of next trace) constant.

Furthermore, the traces right-click menu (when you right-click on a trace) contains the following additional functions:

• y-Offset: Align Traces Here - Sets the offset of all traces so that they align at the cursor position. Hold ctrl / command to align all traces to y = 0.
• y-Scale: Match Traces Here - Sets the multiplicator of all traces so that they align at the cursor position. Hold ctrl / command to scale all traces to y = 1.
• y-Order Traces Here - Sorts the traces (trace display order in the graph) so that the y-value at the cursor position is in ascending order. Hold ctrl / command to sort in descending order.

Additional Options in the Graph Menu:

• Add Annotation with Live Offset ...: This will add a standard legend with extra information about trace offsets (x/y offset or x/y scale). A small prompt will appear, which lets you choose the desired information, numerical precision and placement of the legend within the graph. The offset information is live, which means that the displayed values get updated whenever any change happens. (Note: This feature adds a function named GT_LiveOff() to the current experiment to achieve the effect. Don't delete the function or the display will not work.)

• Left Axis: Autoscale Only Visible - Sets 'Zero isn't special' scaling mode for the y axis.
• Left Axis: Autoscale From Zero - Sets 'Autoscale from zero' scaling mode for the y axis.

Waterfall plots and the Modify Traces panel

The main purpose of the Modify Traces panel is to work with (pseudo) waterfall plots. First, note that Igor Pro also provides an official package for creating waterfall plots (See: Windows -> New -> Packages -> Waterfall Plot). The current project instead creates (pseudo-)waterfall plots by offsetting traces in a graph, and is not compatible with the official Waterfall Plot package.

The provided menu entries inside the Spectra Tools menu are:

• Waterfall Plot of 2D Data or Folder - Creates a pseudo-waterfall plot from a 2D wave or a folder of 1D waves selected in the Data Browser (select one 1D wave inside the folder for the latter).
• Normalize Traces to 1 - Scales all traces in the top graph to y = 1. The baseline is set to 0 unless 'shift' is pressed while selecting this entry.
• Normalize Traces to 1 at Cursor A - Scales all traces in the top graph to y = 1 at cursor A (if set on the graph). The baseline is set to 0 unless 'shift' is pressed.
• Normalize Traces to Area - Scales all traces to unit area.
• Quick Colorize Traces - Applies up to 13 different colors to the traces in the top graph.

Start the Modify Traces panel by going to 'Spectra Tools' -> 'Trace Offset Panel ...' or execute:

The panel has two tabs for modifying all traces at once and for modifying individual traces. A quick overview of both tabs is found below:

All Traces tab

Here all traces are modified together. Traces can be omitted from modifications by hiding the traces (uncheck Include Hidden Traces in this case) or by a name filter (see below). The top part is used to set the trace offsets in Y and X directions. There are two modes: The offsets are either set (= the relative offset between traces will be exactly the inserted value) or added (the relative offset is added to the already set trace offsets).

When to use the Scale Offset function: If you have offset the traces in the graph with uneven spacing (e.g., to represent some sort of relation between the traces) and only want to bring the traces closer together / space them further apart, then use this functionality, which preserves the relative offset. 

The Reverse Sorting button reverses the trace sorting in the graph, so that the bottom-most trace will be the topmost etc. afterwards.

The Colorize button colors the traces according to the selected range successively. This button works on images as well but otherwise the panel is not very useful for image plots.

The Filter region can be used to limit the range of traces for which changes are made. If you enter, for example, 'atrace_*' (note the use of the asterisk wildcard here) then only traces which begin with 'atrace_' will be modified by the controls. If you check Filter Excludes Traces then instead traces with this name will be omitted. This field also accepts lists such as "myTrace1;myTrace2;" and even lists including wildcards such as "atrace*;btrace*;". You can right-click on the filter to get a list of all traces in the top graph for easy addition to the filter list.

The Profile drop-down list can be used to append an 1D wave vertically. This is useful to show a certain trend or integrated data which is representative of the traces shown in the graph, and at the same time serves as the (third) waterfall axis. The axis of this profile is scaled together with the top trace when Y-offsetting traces. A waterfall with an attached profile looks, for example, like this:

Individual Trace tab

The trace to work on is selected with a cursor (A-D), so you need to set at least one of these cursors onto the graph. The active cursor can be switched between traces with the Prev Trace and Next Trace buttons. New in version 1.3: Press the Cursor button to add a new cursor to the current graph until all four cursors are set.

The Go to Max and Go to Min buttons will set the cursor to the minimum / maximum Y-value of the current trace. The cursor works also as a position indicator. With the Reposition at Cursor controls you can set the which X and Y value the point of the cursor should have. The whole trace is then repositioned to reflect this. The trace can also be normalized to a certain Y value at the cursor position (which scales the trace accordingly).

The Apply All to Data (All Traces tab) and Apply to This Data (Individual Trace tab) buttons will (try to) apply the offsets and scaling to the data (and then reset the graph offsets). This will overwrite the original data, so be careful! The applied offsets and multipliers are saved in the wave's note, which makes it in principle possible to reverse this action (this is not provided at the moment, but can be easily added if there is demand). Note that applying x-offsets to XY-data where all traces have the same x wave will likely give undesired results: Since the x wave is modified, all traces will shift over by the set x offset. These buttons do not work for graphs displaying 2D data sets at the moment.

Keyboard shortcuts (Individual Traces tab):

Some aspects of the Individual Traces controls (right side of the panel) can be controlled with the keyboard when the panel is in focus:

• The a, b, c or d keys select cursor A, B, C or D.
• h sets the active cursor to the maximum (high point) of the currently selected trace.
• l (small L) sets the cursor to the minimum (low point) of the trace.
• page up / page down moves the cursor to the next / previous trace in the graph.
• The left / right arrow keys shifts the trace left / right in x direction
• The up / down arrow keys shifts the trace up / down in y direction
• Press the left / right arrow keys while holding the ctrl / command key to scale the trace in x direction
• Press the up / down arrow keys while holding the ctrl / command key to scale the trace in y direction

The dx/dy fields and user-provided update functions

The dx/dy fields at the bottom of the Individual Traces area are used to add (+) or subtract (-) constant values to the x / y offset of the selected trace using the respective buttons. Inserting a negative value will additionally invert the respective axis (the trace is flipped). The main use is to add or subtract pre-defined offsets such as the photon energy of a measured spectrum (in this case, addition/subtraction will remove or include the photon energy value to the energy axis).

These fields can be pre-filled with information from the data using the TraceTool_FetchXShift() and TraceTool_FetchYShift() functions, which are called upon selecting a different trace or graph. You can modify these two functions directly at the beginning of the procedure file, but it is more convenient to provide your own code in a separate file or inside the experiment environment. Use the Override keyword in front of the Function statement to override the standard definitions inside the package. The following code shows the current implementation inside the project’s procedure, which is used to extract the used photon energy value from measurement data:

The Quick-Scale panel

This panel attaches directly to the top graph and provides a sub-set of the functionality of the Trace Offset panel. The difference is that all changes are immediately applied to the data (i.e., the wave is directly modified) and that images can be worked on as well. Attach the panel to a graph by choosing 'Spectra Tools' -> 'Attach Quick-Scale Panel ...' or executing the following in the command line:

This is a quick overview over the controls of the attached panel:

The panel works with the current cursor (the cursor which was moved / placed on the graph last) to select the trace or image point to work on. If there is not cursor yet then you can add a new cursor to the graph by pressing the 'Add Csr' button in the panel. The cursor can be moved to the previous or next trace in the graph by using the 'Prev Tr' and 'Next Tr' buttons. The Min Val and Max Val buttons move the cursor to the position of the minimal or maximal data value (either of the current trace or image).

The Delete buttons < (left), > (right), and also ^ (up), v (down) in case of 2D data, can be used to crop the data by deleting all data points, left or right (above or below) the current cursor location. Note that this change cannot be undone. Work on a backup if you want to preserve the data for later.

The Normalize field shows the intensity at the cursor location. Dial in a value here and the data will be multiplied the cursor position will reflect this value. The Undo Normalization button reverts this change.

The data scaling can be changed by modifying the Set X field, which changes the x-scaling so that the cursor ends up at this new position. The Set Y checkbox switches the controls to y-scaling for images (2D data). You can also adjust the Relative Shift from the initial position.

The KE <> BE button is used to switch between kinetic / binding energy scales for photoelectron spectra or emission energy / energy loss scales for (X-ray) emission spectra. For this, you need to first provide the correct Photon Energy. The photon energy value is read automatically (if available) from the data by utilizing the TraceTool_FetchXShift() function above.

The Arithmetic Op. field provides functionality to add, subtract, multiply or divide the data by a value or simple function. The expression should start with the +, -, * or / character. Otherwise it works the same as if you would write the expression into the command line (e.g., entering '/3' is the same as executing 'mydata /= 3' in the command line). The operation will only work on the current trace or selected column (for an image). If you uncheck One Column then the operation will be applied to the whole image / 2D data.

Using Trace Normalization from the Command Line

You can also normalize all traces by directly calling the ScaleAllTraces() function. This function has optional parameters to modify the result. If called without any parameters then all traces will be scaled between 0 and 1 on the main y-axis:

The options are:

• name = the target graph's name
• csr = cursor name such as "A"
• smth = smoothing (factor) before normalization
• xpos = center coordinate for limited-range normalization
• ypos = optional target y-value
• normMode = how to normalize: [0] = to one, [1] = to global max, [2] = to given y-value, [3] = area to one, [4] = area to global area
• offMode = how to handle offsets: [0] = to zero, [1] = no offset, [2] = keep offset
• rangeMode = use range around xpos: [0] = off, [1] = find maximum, [2] = calculate average
• xRange = absolute x-range around center position
• relRange = relative x-range around center position (1 = 100 %)
• export = if set, exports wave with y-offsets and scales