Basic Usage — HyperSpy 2.5.0 documentation

Fundamentals and Usage
If you used the bundle installation you should be able to use the context menus to get started. Right-click on the folder containing the data you wish to analyse and select “Jupyter notebook here” or “Jupyter qtconsole here”. We recommend the former, since notebooks have many advantages over conventional consoles, as will be illustrated in later sections. The examples in some later sections assume Notebook operation. A new tab should appear in your default browser listing the files in the selected folder. To start a python notebook choose “Python 3” in the “New” drop-down menu at the top right of the page. Another new tab will open which is your Notebook.
You can start IPython by opening a system terminal and executing ipython, (optionally followed by the “frontend”: “qtconsole” for example). However, in most cases, the most agreeable way to work with HyperSpy interactively is using the Jupyter Notebook (previously known as the IPython Notebook), which can be started as follows:
Linux users may find it more convenient to start Jupyter/IPython from the file manager context menu. In either OS you can also start by double-clicking a notebook file if one already exists.
Typically you will need to set up IPython for interactive plotting with matplotlib using %matplotlib (which is known as a ‘Jupyter magic’) before executing any plotting command. So, typically, after starting IPython, you can import HyperSpy and set up interactive matplotlib plotting by executing the following two lines in the IPython terminal (In these docs we normally use the general Python prompt symbol >>> but you will probably see In [1]: etc.):
Note that to execute lines of code in the notebook you must press Shift+Return. (For details about notebooks and their functionality try the help menu in the notebook). Next, import two useful modules: numpy and matplotlib.pyplot, as follows:
The rest of the documentation will assume you have done this. It also assumes that you have installed at least one of HyperSpy’s GUI packages: jupyter widgets GUI, the traitsui GUI, or the anywidget GUI.
HyperSpy supports different GUIs and matplotlib backends which in specific cases can lead to warnings when importing HyperSpy. Most of the time there is nothing to worry about — the warnings simply inform you of several choices you have. There may be several causes for a warning, for example:
not all the GUI packages are installed. If none is installed, we recommend installing at least the hyperspy_gui_ipywidgets package if you are planning to perform interactive data analysis in the Jupyter Notebook. If you are using a platform that does not support ipywidgets, such as Marimo, install hyperspy_gui_anywidget instead. Otherwise, you can simply disable the warning in preferences as explained below.
the hyperspy_gui_traitsui package is installed and you are using an incompatible matplotlib backend (e.g. notebook, nbagg or widget).
If you want to use the traitsui GUI, use the qt matplotlib backend instead.
Alternatively, if you prefer to use the notebook or widget matplotlib backend, and if you don’t want to see the (harmless) warning, make sure that you have the hyperspy_gui_ipywidgets installed and disable the traitsui GUI in the preferences.
Changed in version v1.3: HyperSpy works with all matplotlib backends, including the notebook (also called nbAgg) backend that enables interactive plotting embedded in the jupyter notebook.
When running in a headless system it is necessary to set the matplotlib backend appropiately to avoid a cannot connect to X server error, for example as follows:
When using IPython, the documentation (docstring in Python jargon) can be accessed by adding a question mark to the name of a function. e.g.:
This syntax is a shortcut to the standard way one of displaying the help associated to a given functions (docstring in Python jargon) and it is one of the many features of IPython, which is the interactive python shell that HyperSpy uses under the hood.
Another useful IPython feature is the autocompletion of commands and filenames using the tab and arrow keys. It is highly recommended to read the Ipython introduction for many more useful features that will boost your efficiency when working with HyperSpy/Python interactively.
HyperSpy can operate on any numpy array by assigning it to a BaseSignal class. This is useful e.g. for loading data stored in a format that is not yet supported by RosettaSciIO—supposing that they can be read with another Python library—or to explore numpy arrays generated by other Python libraries. Simply select the most appropriate signal from the signals module and create a new instance by passing a numpy array to the constructor e.g.
The numpy array is stored in the data attribute of the signal class:
In HyperSpy the data is interpreted as a signal array and, therefore, the data axes are not equivalent. HyperSpy distinguishes between signal and navigation axes and most functions operate on the signal axes and iterate on the navigation axes. For example, an EELS spectrum image (i.e. a 2D array of spectra) has three dimensions X, Y and energy-loss. In HyperSpy, X and Y are the navigation dimensions and the energy-loss is the signal dimension. To make this distinction more explicit the representation of the object includes a separator | between the navigation and signal dimensions e.g.
In HyperSpy a spectrum image has signal dimension 1 and navigation dimension 2 and is stored in the Signal1D subclass.
An image stack has signal dimension 2 and navigation dimension 1 and is stored in the Signal2D subclass.
Note that HyperSpy rearranges the axes when compared to the array order. The following few paragraphs explain how and why it does it.
Depending how the array is arranged, some axes are faster to iterate than others. Consider an example of a book as the dataset in question. It is trivially simple to look at letters in a line, and then lines down the page, and finally pages in t