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 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 magnify control changes the magnification setting of the graph, which is useful to enlarge / shrink graphs without changing their (physical) size.

Set Axis Controls

This area contains controls for modifying axis labels and ticks with two modes. Use the switch mode button in the top right corner to switch modes.

Mode 1:

• the Axis check-boxes control whether the ticks and axis labels are displayed for the axis
• the Tick control changes the margin (distance) from the axis for ticks
• the Label control changes the margin (distance) of the label from the graph edge

Mode 2:

• the Grid check-boxes control whether a grid is displayed for the axis
• the Tick control changes the length of the ticks
• the Label control changes the offset (lateral shift) of the label against the axis

Set & Copy Sizes / Styles

This area is for copying and applying graph style macros. Select the desired Style in the drop-down box and press Apply to apply this style to the top graph. The style can be reverted to the previous style for the current graph by pressing Revert. This function only saves the state of the current graph when pressing Apply. Undo states for multiple graphs are not saved. The project includes a standard style, named 'BoxStyle', which applies mirror axes and a few tweaks to the graph. Holding 'ctrl' (Win) / 'command' (Mac) will suppress the ticks and labels on the left axis while applying the BoxStyle style.

The Copy buttons save the current style of the top graph to apply the same style to another graph later. Here, the Sizes button specifically only saves size, margin and axis relevant settings to make graphs similar in size but not necessarily style. The Style button saves the whole style (including font sizes, magnification etc.). A Copied Size or 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 'to Clip' (or hold the shift key while pressing the Copy button) 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. If the 'with Axis Range' checkbox is active then the current X and Y axis range limits are copied and applied as well.

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 default is setting the aspect ratio via the height. Use the as Width checkbox if you instead want to set the aspect ratio via width constraint.

The Apply Format 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).

Set & Add Legend

You can also modify and add legends to the top graph by using the controls in this area. If annotations are already present, they can be modified by using the controls in the panel. Any changes will take immediate effect. The top-most (last) annotation is already selected when the panel is updated. Select one of the other annotations (if available) by using the down arrow of the Select control in the left corner. The Rename field shows the name of the currently selected annotation, and can also be used to rename the annotation. Just enter a different name, but a warning will appear should the name already be in use. Use the Remove button to kill the selected annotation in the target graph. This works for any annotation, not only the ones created via the panel.

Choose the anchor of the legend in the leftmost field of 9 anchor points; these anchor points represent positions within the plot area. Note that the annotation will be moved to the default location of this anchor. You can choose the display options (Frame and Background) as desired. By using the Add Info drop-down menu, it is possible to include trace information to a legend, such as offsets and scaling, which update dynamically. Press the Add New button to create a new legend with the current settings. If the Replace checkbox is active then the selected annotation will be replaced by the new one. Select the Textbox option to convert the annotation into a textbox. Changes in the trace list will not be reflected in the legend for text boxes, i.e., trace details will not be added or deleted dynamically.

You can also choose additional text styling options: The Color checkbox will yield trace descriptions which are colored the same as the trace itself. Use this option after you have decided on the trace colors, since the colors will not update automatically. The Cols. option is for arranging the trace legend in multiple columns. This is useful if many traces are displayed, which would otherwise make the legend very tall. Use the Size option to enlarge / shrink the text.

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 Legend 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 dynamic, which means that the displayed values get updated whenever any change happens. (Note: This feature adds a function named GT_LiveInfo() 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' mode for the y axis.
• Left Axis: Autoscale From Zero - Sets 'Autoscale from zero' 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 (All Traces tab):

• ← → arrow keys   = shift all traces left / right in x direction
• ↑ ↓ arrow keys       = shift all traces up / down in y direction
• ctrl / cmd + ← →   = change the offset between traces in x
• ctrl / cmd + ↑ ↓      = change the offset between traces in y
• Hold ctrl / cmd while using 'Scale Offset per Trace' to scale all offsets from zero instead of relative to the first trace.                                                

Keyboard shortcuts (Individual Traces tab):

• a, b, c or d keys     = select cursor A, B, C or D.
• h                             = set the active cursor to the maximum (high point) of the currently selected trace.
• l (small L)               = set the cursor to the minimum (low point) of the trace.
• page up / down      = move the cursor to the next / previous trace in the graph.
• ← → arrow keys    = shift the trace left / right in x direction
• ↑ ↓ arrow keys       = shift the trace up / down in y direction
• ctrl / cmd + ← →   = scale the trace in x direction
• ctrl / cmd + ↑ ↓      = scale the trace in y direction
• shift + above controls = move in 10x larger changes per step
• alt + ← →              = move the graph cursors instead of shifting the trace (with the graph in focus).

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