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:

BuildGraphSizePanel()

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:

BuildTraceOffsetPanel()

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:

Static Function TraceTool_FetchXShift(input, unit)
    Wave input
    String &unit        // optional unit string
    Variable xShift = NaN   // the shift value
    Variable neg = 1
    String notes = note(input)
    String energy = StringByKey("Xray energy", notes, "=","\r") // find the photon energy
    if (!strlen(energy))
        energy = StringByKey("photon energy ", notes, "=","\r") // try a different key
    endif
    if (!strlen(energy))
        energy = StringByKey("Excitation Energy", notes, "=","\r")  // try yet a different key
        neg = -1    // this data requires flipping
    endif
    unit = "eV"
    xShift = str2num(energy)*neg
    return xShift   // return NaN for no change and return negative values for flipping the trace
End

Static Function TraceTool_FetchYShift(input,unit)
    Wave input
    String &unit
    return NaN
End

 

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:

AttachQuickScalePanel()

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 '+' button in the panel. The cursor can be moved to the previous or next trace in the graph by using the Prev and Next buttons. The Min and Max buttons move the cursor to the position of the minimal or maximal data value (either of the current trace or image).

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 Revert Norm. button reverts this change.

The data scaling can be changed by modifying the X pos. field, which changes the x-scaling so that the cursor ends up at this new position. The do 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:

ScaleAllTraces([name, smth, xpos, ypos, normMode, offMode, rangeMode, xRange, relRange, csr, export])

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

Project Details

Current Project Release

Release File: Graph Tools_v2.00.zip
Version: IGOR.8.00.x-2.00
Version Date: Tue, 07/25/2023 - 01:25 am
Version Major: 2
Version Patch Level: 0
OS Compatibility: Windows Mac-Intel
Release Notes:
  • Fixed bug: Quick-scaling failed sometimes when data had NaNs.
  • Fixed bug: Quick-scaling was not working for the zero-offset setting.
  • The Y Reset and X Reset buttons honor filter settings now.
  • Upgraded code to Igor 8.
  • Alphanumerical sorting now works for plots of 2D data.
  • Improved XY-plot support for scaling/offsetting and the Trace Tool.
  • Fixed various small inconsistencies and edge cases.
  • Fixed bug: Copy Style did not work properly with swapped axes and a fixed aspect ratio.
  • Graph Size and Trace Offset panels are now displayed next to the top graph and otherwise centered on the screen.
  • Overhauled the Trace Normalize menu to be less confusing.
  • Added 'Export Offsets' option to normalize menu.
View All Releases

nice project.

a little bug: if cursor is on an image in the top graph an error occurs when the panel is built.

Tony, thanks! Oops, I have fixed this now. Somehow I had checking for images in place but commented out. I will look into working your StackTraces functions into this package, so that everything is neatly in one place. Thank you for your manual in the other thread.

EDIT: Now I know why I had commented this out: Because it was not working properly. The current version should work fine with image plots (i.e., no error message). Of course the panel is not that useful for images yet. I have another small panel which can shift image data around, but this involves changing the wave's scaling, since there is no offset option for images. I could implement this in the future. Would you find shifting and scaling images useful?

Hi Tony,

I went now through your StackTraces code. I found it very useful and have modified (reinterpreted) it with some new functionality. I would like to put this into the next GraphTools update, but first I would like to hear your opinion. Does the new version still work well with your workflow and data? If you look at the code you will see that I have rewritten a lot of details. This is my way of translating the functionality so that I understand what is going on (this included renaming menu entries a bit... I couldn't really wrap my head around the word 'stack' for most of the options). Also, I want to keep Igor 6.3 compatibility as much as possible for now.

The code is now useable with 2D waterfall plots and honors x-offsets as well as y-scaling (I don't have x-scaling awareness in yet, but this will hopefully not be a problem). Now it is also possible to scale all traces (set a multiplier) to the same value at the cursor position. I have taken out addOffsets(), since this is probably already covered with the panel (if you find this more convenient this tool could go back in, of course).

I have added alternative functionality when ctrl / command is pressed:

  • 'y-Offset: Align Traces' will align to zero instead of the cursors y value
  • 'y-Scale: Match Traces' will scale to 1 instead of the cursors y value
  • 'y-Order Traces' will sort in descending order

Please let me know if you have any comments or suggestions for improvements. 

newStackTraces.zip

@Tony: I went ahead and merged the right-click menus into the project. I hope you like it. :)

I do like it!

The thing I still look for in the panel is 'shift offset per trace', the equivalent to the equivalent of my 'add offsets per trace' graph menu.

Something that will add an additional offset of value*i to each trace. Is there a way to do that? Perhaps I'm missing something.

Great! Let me know if I should add something else.

The 'add offsets per trace' functionality is implemented in the panel as 'Set Offset per Trace' in the top right corner for both x and y directions. Just dial in a number or user the up/down arrows. This will add the inserted number as value*i to the traces. Also, 'Shift Offset of All Traces' will add the same offset to all traces, i.e., shift the whole bunch.

I was trying to add rather than set the offsets. So the result is current offset + i*value.

The idea is to able to quickly 'align' the traces by setting variable offsets, then add something to each offset to spread the traces apart from one another, with the possibility of adding or subtracting a bit more to spread them further or closer to one another.

It looks like 'set offset per trace' discards the current offsets, ie it does what it says!

Ah I see! Yes, the initial offsets and any alignment are not preserved. It should be no problem and make no difference for me to convert this into an add offset function. I'll think about it.

Here is a version where I have added checkboxes to toggle between Set (the current behavior) and Add modes (this should recreate the 'add offsets per trace'). :) Let me know how well this works for you. If everything is fine then I will submit an update after doing a few more tests tomorrow.

As a somewhat related side note, you may be shocked to hear that I have opened the All Traces Popup menu for the first time today. One learns something new every day. ;-p

Graph Tools_v1.21-dev.zip

My packages supports menu keyboard shortcuts which are loaded from a settings file. If you want to add keyboard shortcuts to common menu entries, place the content (Spectra Tools settings.dat) of the attached zip file in the same folder as the package procedure and edit as necessary.

Spectra Tools settings_2.zip

Forum

Support

Gallery

Igor Pro 9

Learn More

Igor XOP Toolkit

Learn More

Igor NIDAQ Tools MX

Learn More