stmapy

STMapy (Scanning Tunneling Microscopy Analysis in PYthon)

Presentation

STMapy (previously STM_Data_Analysis and Scampy) is a Graphical User Interface (GUI) to analyse CITS recorded under Nanonis (.3ds), MATRIX (spip exported .asc or _mtrx) or RHK (.sm4). It is written in Python using PyQt for the GUI.

Installation

STMapy can also be installed using PyPI : pip install stmapy

STMapy can also be installed from its source code.

To do this:

• Fetch the sources from its git repository. Ex: git clone https://github.com/cea-lateqs/STMapy/
• Once downloaded, move in the source folder and run the install with pip:

cd stmapy
pip install [-e] . [--user]

If needed, put -e for an install in editable mode (useful for development as sources will be directly linked to package) and/or --user to install it only for the current user (local installation).

You can test if the installation succedeed by importing stmapy in a Python console:

>>> import stmapy
>>> print(stmapy.__version__)

Requirements

Requirements should automatically be installed when running the install with pip. Using stmapy requires the following installations :

• Python 3 (tested under Python 3.10) with the following packages
  • Numpy (tested under 1.23)
  • Scipy (tested under 1.10)
  • Matplotlib, at least version 2.0 (tested under 3.7.0)
• PyQt 5 -acces2thematrix

Using Stmapy

Starting

To start Stmapy, run stmapy in the console:

stmapy

It should display the following interface.

If it is not working, run directly the main.py file from Stmapy sources:

python3 stmapy/main.py

File selection

To load a CITS, click on the Open CITS button on top-left corner. A window will appear, prompting to select a CITS of supported format (either .3ds, .sm4 or .asc). The filenames can be filtered according to the format by selecting 3D binary file (.3ds) or RHK File (.sm4) or Ascii files (.asc) or mtrx files (_mtrx).

Topography

Once the CITS was selected, Stmapy will load the spectroscopic data and will attempt to read the topography to plot it in a seperate window.

This always succeeds for .3ds and .sm4 as it plots the topography contained in the file. For .asc and mtrx however, it will search for a file 'Topo.txt' in the same folder of the selected file. This 'Topo.txt' can be created by using the Export to TXT method of Gwyddion. If no topographic file is found, no topography will be plotted.

No checks are done to see if 'Topo.txt' corresponds to the loaded CITS. Always check that the topography file was taken at the same location as the CITS.

End of loading

If the loading succeed, a 2D plot should appear on the bottom-left widget. If not, check the console for error messages and report them (see Further information at the end).

List of commands

Clicks on 2D plot

• Left-click: plots the spectrum at this location.
• Right-click: plots a spectrum averaged around this location.
• Dragging left-click: draws a line to plot a cut of the data along it in a separate window.
• Dragging right-click: draws a rectangle to average the data over it and plot the resulting spectrum.

Clicks on spectrum window

• Any click: displays the 2D plot at the clicked voltage value.

Basic operations

• Open CITS (button): allows to select a CITS to load. If several are selected, they will be averaged.
• Draw topo (button): redraws the topo without any shape on it.

CITS parameters

• Displayed channel (dropdown): selects the working channel. It will be displayed in the 2D plot and all operations will be used on this channel.
• Normalize current channel (button): normalises the current channel. The result of this normalisation will be added as a new channel named 'Normalised' followed by the channel name.
• V/Z index (spinbox): changes the index of the voltage/altitude at which the 2D plot is displayed. The corresponding value is shown in the header of the 2D plot.
• Open I(V) CITS channel (button): Open I(V) data from folder. The data is added in a new channel. Only works for ascii files, and if a dIdV CITS has already been oppened.
• Force CITS aspect to equal (checkbox): When next updated, the CITS aspect will be set to equal.

Additional CITS Channels

The following buttons add a new channel in the last position of the Displayed channel (dropdown).

• Open I(V) CITS as new channel (button): allows to select an additional I(V) CITS, if dIdV channel has already been loaded.
• FFT (CITS channel) (button): Calculates the 2D FFT of the currently displayed CITS channel.
• derivative (CITS channel) (button): Calculates the 2D derivative of the currently displayed CITS channel. Usually used on I(V) channels.
• Calculate dIdV*V/I (button): Calculates the Feenstra renormalisation. The result of will be added as a new channel. Only tested for ascii files. Needs both dIdV and I(V) CITS to be already oppened. The Lock in sensitivity ; Modulation amplitude and Gain of the current can be specified for consistency of the results.

Averaging

Multiple spectra

• Select spectra with left-click (checkbox): allows to select several spectra by left-clicking to average them. Unchecking the box will display the result of the averaging in the bottom-right widget.
• Number of pixels for right-click average (spinbox): Right-clicking on the 2D plot at (X, Y) triggers an average over X - N, X + N, Y - N, Y + N. This box allows to change the value of N (default : 2).

Whole CITS

• Plot average spectrum (button): plots the average of all spectra of the current channel.
• Average CITS (button): averages the neighbouring spectra of the CITS along the X direction and replaces the CITS with the result. The number of spectrum to average together can be changed in the spinbox Number of spectra to average along X direction. Useful for line spectroscopies.
• Average with respect to value (checkbox): triggers the display of the averaging widget. This widget allows to plot two spectra: one resulting from the average of all spectra that have a value at the current voltage below a certain value (Minimum value for the below averaging) and the other resulting from the average of all spectra that have a value at the current voltage above a certain value (Maximum value for the above averaging). This operation can be started by clicking Start the averaging (may be lengthy).

Cuts

• Waterfall or 2D plot (radio buttons): sets the type of representation for cuts.
• View selected spectra (checkbox): shows the pixels in the 2D plot that are chosen when doing a cut (debugging purposes).
• Plot FFT of cut (checkbox): shows the FFT of the chosen cut with respect to the energy.
• Whole length cut (button): does a cut of the 2D plot along the great diagonal.

Spectra plot

• Clear spectra (button): clears the spectra window.
• Shift plot along X (text): shifts the plotted spectra along the voltage axis by the given value. If 'topo' is given, the spectra will be shifted by the Z value at this position (unstable !).
• Shift plot along Y (text): shifts the plotted spectra along the channel axis by the given value.
• Plot log of the spectrum (checkbox): plots the logarithm of the spectrum instead of the spectrum.
• Statistics Gap and position (checkbox): Calculates statistics in the shape defined by the user - this feature is highly data dependent and should be tuned carefully in the code first.
• Plot derivative (checkbox): plots the derivative of the spectrum in addition to the spectrum. The derivative is computed by a Savitzy-Golay filter with a window length that can be changed in the spinbox Window length.
• Fit spectra (button): tries to fit the last spectra plotted by a linear function. The range on which the fit must be computed can be set by checking Use a custom range and setting the lower and upper limits.

Display parameters

• Scale in Volts (checkbox): sets voltage axis in Volts for cuts and spectra. Uses indexes otherwise.
• Scale in metric units (checkbox): sets the X and Y axis in metric units. Uses pixels otherwise.
• Voltage index guideline (checkbox): shows a dashed line in the bottom-right widget at the voltage selected in V/Z index.
• Deactivate legend (checkbox): removes the legend when plotting spectra. Can be useful when many spectra are plotted.
• Colorbar settings (checkbox): opens the colorbar widget where the colorbar to use can be changed. Custom limits can also be forced on the colormap by checking Use custom limits. In this case, you must set both the lower AND the upper limit.
• Make Gif (button): Creates a gif from the current channel. The number of images is tuned through start, stop, and step boxes using V/Z index labels. Result is saved in the CITS folder.

Various parameters for the plotting can be adjusted in the stmapy.mplstyle file located in the stmapy folder.

Configuration

It is possible to set various parameters in the config.json file located in the stmapy folder:

• working_directory: Name of a directory that will be taken as root when asking to load a CITS. Default: HOME directory.
• matplotlib_stylesheet: Name of a valid stylesheet to be imported at launch to tune matplotlib aspect. Default: None.
• autoload: Boolean to trigger the loading of a CITS at launch. Default: false.
• default_cmap: Name of the colormap to use for the CITS map. Note that this is only at launch as the colormap can be changed afterwards in stmapy. Default: magma_r.
• topo_cmap: Name of the colormap to use for the topography. This colormap cannot be changed after launch. Default: afm_hot.
• level_topo: Type of leveling to use before plotting for the topo: can be line, plane or no to deactivate leveling. Default: no.

Any missing entry in config.json will be set to its default value.

Further information

The code is available on the Git repo. Bugs can be reported as Issues on the repository. It includes use of the access2thematrix package developed by the Stephan J. M. Zevenhuizen.

Trouble shooting

• Stmapy not found issues : change spyder path. If it doesn't solve the problem, you can try to copy main.py out of the stmapy folder.