Loading and saving data#

Changed in version 2.0: The IO plugins formerly developed within HyperSpy have been moved to the separate package RosettaSciIO in order to facilitate a wider use also by other packages. Plugins supporting additional formats or corrections/enhancements to existing plugins should now be contributed to the RosettaSciIO repository and file format specific issues should be reported to the RosettaSciIO issue tracker.

Loading#

Basic usage#

HyperSpy can read and write to multiple formats (see Supported formats). To load data use the load() command. For example, to load the image spam.jpg, you can type:

>>> s = hs.load("spam.jpg")

If loading was successful, the variable s contains a HyperSpy signal or any type of signal defined in one of the HyperSpy extensions, see Specifying signal type for more details.

Note

When the file contains several datasets, the load() function will return a list of HyperSpy signals, instead of a single HyperSpy signal. Each signal can then be accessed using list indexation.

>>> s = hs.load("spameggsandham.hspy") 
>>> s 
[<Signal1D, title: spam, dimensions: (32,32|1024)>,
 <Signal1D, title: eggs, dimensions: (32,32|1024)>,
 <Signal1D, title: ham, dimensions: (32,32|1024)>]

Using indexation to access the first signal (index 0):

>>> s[0] 
<Signal1D, title: spam, dimensions: (32,32|1024)>

Hint

The load function returns an object that contains data read from the file. We assign this object to the variable s but you can choose any (valid) variable name you like. for the filename, don't forget to include the quotation marks and the file extension.

If no argument is passed to the load function, a window will be raised that allows to select a single file through your OS file manager, e.g.:

>>> # This raises the load user interface
>>> s = hs.load()

It is also possible to load multiple files at once or even stack multiple files. For more details read Loading multiple files.

Specifying reader#

HyperSpy will attempt to infer the appropriate file reader to use based on the file extension (for example. .hspy, .emd and so on). You can override this using the reader keyword:

# Load a .hspy file with an unknown extension
>>> s = hs.load("filename.some_extension", reader="hspy") # doctest: +SKIP

Specifying signal type#

HyperSpy will attempt to infer the most suitable signal type for the data being loaded. Domain specific signal types are provided by extension libraries. To list the signal types available on your local installation use:

>>> hs.print_known_signal_types()

When loading data, the signal type can be specified by providing the signal_type keyword, which has to correspond to one of the available subclasses of signal:

>>> s = hs.load("filename", signal_type="EELS")

If the loaded file contains several datasets, the load() function will return a list of the corresponding signals:

>>> s = hs.load("spameggsandham.hspy") 
>>> s 
[<Signal1D, title: spam, dimensions: (32,32|1024)>,
<Signal1D, title: eggs, dimensions: (32,32|1024)>,
<Signal1D, title: ham, dimensions: (32,32|1024)>]

Note

Note for python programmers: the data is stored in a numpy array in the data attribute, but you will not normally need to access it there.

Metadata#

Most scientific file formats store some extra information about the data and the conditions under which it was acquired (metadata). HyperSpy reads most of them and stores them in the original_metadata attribute. Also, depending on the file format, a part of this information will be mapped by HyperSpy to the metadata attribute, where it can for example be used by routines operating on the signal. See the metadata structure for details.

Note

Extensive metadata can slow down loading and processing, and loading the original_metadata can be disabled using the load_original_metadata argument of the load() function. If this argument is set to False, the metadata will still be populated.

To print the content of the attributes simply use:

>>> s.original_metadata 
>>> s.metadata

The original_metadata and metadata can be exported to text files using the export() method, e.g.:

>>> s.original_metadata.export('parameters')

Lazy loading of large datasets#

Added in version 1.2: lazy keyword argument.

Almost all file readers support lazy loading, which means accessing the data without loading it to memory (see Supported formats for a list). This feature can be useful when analysing large files. To use this feature, set lazy to True e.g.:

>>> s = hs.load("filename.hspy", lazy=True)

More details on lazy evaluation support can be found in Working with big data.

The units of the navigation and signal axes can be converted automatically during loading using the convert_units parameter. If True, the convert_to_units method of the axes_manager will be used for the conversion and if set to False, the units will not be converted (default).

Loading multiple files#

Rather than loading files individually, several files can be loaded with a single command. This can be done by passing a list of filenames to the load functions, e.g.:

>>> s = hs.load(["file1.hspy", "file2.hspy"])

or by using shell-style wildcards:

>>> s = hs.load("file*.hspy")

Alternatively, regular expression type character classes can be used such as [a-z] for lowercase letters or [0-9] for one digit integers:

>>> s = hs.load('file[0-9].hspy')

Note

Wildcards are implemented using glob.glob(), which treats *, [ and ] as special characters for pattern matching. If your filename or path contains square brackets, you may want to set escape_square_brackets=True:

>>> # Say there are two files like this:
>>> # /home/data/afile[1x1].hspy
>>> # /home/data/afile[1x2].hspy

>>> s = hs.load("/home/data/afile[*].hspy", escape_square_brackets=True)

HyperSpy also supports `pathlib.Path <https://docs.python.org/3/library/pathlib.html>`_ objects, for example:

>>> import hyperspy.api as hs
>>> from pathlib import Path

>>> # Use pathlib.Path
>>> p = Path("/path/to/a/file.hspy") 
>>> s = hs.load(p) 

>>> # Use pathlib.Path.glob
>>> p = Path("/path/to/some/files/").glob("*.hspy") 
>>> s = hs.load(p)

By default HyperSpy will return a list of all the files loaded. Alternatively, by setting stack=True, HyperSpy can be instructed to stack the data - given that the files contain data with exactly the same dimensions. If this is not the case, an error is raised. If each file contains multiple (N) signals, N stacks will be created. Here, the number of signals per file must also match, or an error will be raised.

>>> ls 
CL1.raw  CL1.rpl  CL2.raw  CL2.rpl  CL3.raw  CL3.rpl  CL4.raw  CL4.rpl
LL3.raw  LL3.rpl  shift_map-SI3.npy  hdf5/
>>> s = hs.load('*.rpl') 
>>> s 
[<EELSSpectrum, title: CL1, dimensions: (64, 64, 1024)>,
<EELSSpectrum, title: CL2, dimensions: (64, 64, 1024)>,
<EELSSpectrum, title: CL3, dimensions: (64, 64, 1024)>,
<EELSSpectrum, title: CL4, dimensions: (64, 64, 1024)>,
<EELSSpectrum, title: LL3, dimensions: (64, 64, 1024)>]
>>> s = hs.load('*.rpl', stack=True) 
>>> s 
<EELSSpectrum, title: mva, dimensions: (5, 64, 64, 1024)>

Loading example data and data from online databases#

HyperSpy is distributed with some example data that can be found in data:

>>> s = hs.data.two_gaussians()
>>> s.plot()

Added in version 1.4: data (formerly hyperspy.api.datasets.artificial_data)

There are also artificial datasets, which are made to resemble real experimental data.

>>> s = hs.data.atomic_resolution_image()
>>> s.plot()

Saving#

To save data to a file use the save() method. The first argument is the filename and the format is defined by the filename extension. If the filename does not contain the extension, the default format (HSpy-HDF5) is used. For example, if the s variable contains the BaseSignal that you want to write to a file, the following will write the data to a file called spectrum.hspy in the default HSpy-HDF5 format:

>>> s.save('spectrum')

If you want to save to the ripple format instead, write:

>>> s.save('spectrum.rpl')

Some formats take extra arguments. See the corresponding pages at Supported formats for more information.

On this page
Show Source