hyperspy.io module


Escapes pairs of square brackets in strings for glob.glob().


text (str) – The text to escape


The escaped string

Return type



>>> # Say there are two files like this:
>>> # /home/data/afile[1x1].txt
>>> # /home/data/afile[1x2].txt
>>> path = "/home/data/afile[*].txt"
>>> glob.glob(path)
>>> glob.glob(_escape_square_brackets(path))
['/home/data/afile[1x2].txt', '/home/data/afile[1x1].txt']

Return a file reader from the plugins list based on the file extension.

If the extension is not found or understood, returns the Python imaging library as the file reader.


extension (str) – File extension, without initial “.” separator


reader – The inferred file reader.

Return type


hyperspy.io.assign_signal_subclass(dtype, signal_dimension, signal_type='', lazy=False)

Given dtype, signal_dimension and signal_type, return the matching Signal subclass.

See hs.print_known_signal_types() for a list of known signal_types, and the developer guide for details on how to add new signal_types.

  • dtype (dtype) – Signal dtype

  • signal_dimension (int) – Signal dimension

  • signal_type (str, default "") – Signal type. Optional. Will log a warning if it is unknown to HyperSpy.

  • lazy (bool, default False) – If True, returns the matching LazySignal subclass.


Return type

Signal or subclass

hyperspy.io.dict2signal(signal_dict, lazy=False)

Create a signal (or subclass) instance defined by a dictionary


signal_dict (dictionary) –



Return type

Signal or subclass

hyperspy.io.load(filenames=None, signal_type=None, stack=False, stack_axis=None, new_axis_name='stack_element', lazy=False, convert_units=False, escape_square_brackets=False, **kwds)

Load potentially multiple supported files into HyperSpy.

Supported formats: hspy (HDF5), msa, Gatan dm3, Ripple (rpl+raw), Bruker bcf and spx, FEI ser and emi, SEMPER unf, EMD, EDAX spd/spc, tif, and a number of image formats.

Depending on the number of datasets to load in the file, this function will return a HyperSpy signal instance or list of HyperSpy signal instances.

Any extra keywords are passed to the corresponding reader. For available options, see their individual documentation.

  • filenames (None or str or list(str) or pathlib.Path or list(pathlib.Path)) – The filename to be loaded. If None, a window will open to select a file to load. If a valid filename is passed in that single file is loaded. If multiple file names are passed in a list, a list of objects or a single object containing the data of the individual files stacked are returned. This behaviour is controlled by the stack parameter (see bellow). Multiple files can be loaded by using simple shell-style wildcards, e.g. ‘my_file*.msa’ loads all the files that starts by ‘my_file’ and has the ‘.msa’ extension.

  • signal_type ({None, "EELS", "EDS_SEM", "EDS_TEM", "", str}) – The acronym that identifies the signal type. The value provided may determine the Signal subclass assigned to the data. If None the value is read/guessed from the file. Any other value overrides the value stored in the file if any. For electron energy-loss spectroscopy use “EELS”. For energy dispersive x-rays use “EDS_TEM” if acquired from an electron-transparent sample — as it is usually the case in a transmission electron microscope (TEM) —, “EDS_SEM” if acquired from a non electron-transparent sample — as it is usually the case in a scanning electron microscope (SEM). If “” (empty string) the value is not read from the file and is considered undefined.

  • stack (bool) – If True and multiple filenames are passed in, stacking all the data into a single object is attempted. All files must match in shape. If each file contains multiple (N) signals, N stacks will be created, with the requirement that each file contains the same number of signals.

  • stack_axis ({None, int, str}) – If None, the signals are stacked over a new axis. The data must have the same dimensions. Otherwise the signals are stacked over the axis given by its integer index or its name. The data must have the same shape, except in the dimension corresponding to axis.

  • new_axis_name (string) – The name of the new axis when axis is None. If an axis with this name already exists it automatically append ‘-i’, where i are integers, until it finds a name that is not yet in use.

  • lazy ({None, bool}) – Open the data lazily - i.e. without actually reading the data from the disk until required. Allows opening arbitrary-sized datasets. The default is False.

  • convert_units ({bool}) – If True, convert the units using the convert_to_units method of the axes_manager. If False, does nothing. The default is False.

  • escape_square_brackets (bool, default False) – If True, and filenames is a str containing square brackets, then square brackets are escaped before wildcard matching with glob.glob(). If False, square brackets are used to represent character classes (e.g. [a-z] matches lowercase letters.

  • reader (None or str or custom file reader object, default None) – Specify the file reader to use when loading the file(s). If None, will use the file extension to infer the file type and appropriate reader. If str, will select the appropriate file reader from the list of available readers in HyperSpy. If a custom reader object, it should implement the file_reader function, which returns a dictionary containing the data and metadata for conversion to a HyperSpy signal.

  • print_info (bool, default False) – For SEMPER unf- and EMD (Berkeley)-files, if True additional information read during loading is printed for a quick overview.

  • downsample (int (1–4095)) – For Bruker bcf files, if set to integer (>=2) (default 1) bcf is parsed into down-sampled size array by given integer factor, multiple values from original bcf pixels are summed forming downsampled pixel. This allows to improve signal and conserve the memory with the cost of lower resolution.

  • cutoff_at_kV ({None, int, float}) – For Bruker bcf files, if set to numerical (default is None) bcf is parsed into array with depth cutoff at coresponding given energy. This allows to conserve the memory, with cutting-off unused spectra’s tail, or force enlargement of the spectra size.

  • select_type ({'spectrum_image', 'image', 'single_spectrum', None}) – If None (default), all data are loaded. For Bruker bcf and Velox emd files: if one of ‘spectrum_image’, ‘image’ or ‘single_spectrum’, the loader return single_spectrumns either only the spectrum image or only the images (including EDS map for Velox emd files) or only the single spectra (for Velox emd files).

  • first_frame (int (default 0)) – Only for Velox emd files: load only the data acquired after the specified fname.

  • last_frame (None or int (default None)) – Only for Velox emd files: load only the data acquired up to specified fname. If None, load up the data to the end.

  • sum_frames (bool (default is True)) – Only for Velox emd files: if False, load each EDS frame individually.

  • sum_EDS_detectors (bool (default is True)) – Only for Velox emd files: if True, the signal from the different detector are summed. If False, a distinct signal is returned for each EDS detectors.

  • rebin_energy (int, a multiple of the length of the energy dimension (default 1)) – Only for Velox emd files: rebin the energy axis by the integer provided during loading in order to save memory space.

  • SI_dtype (numpy.dtype) – Only for Velox emd files: set the dtype of the spectrum image data in order to save memory space. If None, the default dtype from the Velox emd file is used.

  • load_SI_image_stack (bool (default False)) – Only for Velox emd files: if True, load the stack of STEM images acquired simultaneously as the EDS spectrum image.

  • dataset_path (None, str or list of str, optional) – For filetypes which support several datasets in the same file, this will only load the specified dataset. Several datasets can be loaded by using a list of strings. Only for EMD (NCEM) and hdf5 (USID) files.

  • stack_group (bool, optional) – Only for EMD NCEM. Stack datasets of groups with common name. Relevant for emd file version >= 0.5 where groups can be named ‘group0000’, ‘group0001’, etc.

  • ignore_non_linear_dims (bool, default is True) – Only for HDF5 USID. If True, parameters that were varied non-linearly in the desired dataset will result in Exceptions. Else, all such non-linearly varied parameters will be treated as linearly varied parameters and a Signal object will be generated.

  • only_valid_data (bool, optional) – Only for FEI emi/ser file in case of series or linescan with the acquisition stopped before the end: if True, load only the acquired data. If False, fill empty data with zeros. Default is False and this default value will change to True in version 2.0.


Return type

Signal instance or list of signal instances


Loading a single file providing the signal type:

>>> d = hs.load('file.dm3', signal_type="EDS_TEM")

Loading multiple files:

>>> d = hs.load('file1.dm3','file2.dm3')

Loading multiple files matching the pattern:

>>> d = hs.load('file*.dm3')

Loading multiple files containing square brackets:

>>> d = hs.load('file[*].dm3', escape_square_brackets=True)

Loading (potentially larger than the available memory) files lazily and stacking:

>>> s = hs.load('file*.blo', lazy=True, stack=True)

Specify the file reader to use

>>> s = hs.load('a_nexus_file.h5', reader='nxs')
hyperspy.io.load_single_file(filename, **kwds)

Load any supported file into an HyperSpy structure.

Supported formats: netCDF, msa, Gatan dm3, Ripple (rpl+raw), Bruker bcf, FEI ser and emi, EDAX spc and spd, hspy (HDF5), and SEMPER unf.

  • filename (string) – File name including the extension.

  • **kwds – Keyword arguments passed to specific file reader.


Data loaded from the file.

Return type


hyperspy.io.load_with_reader(filename, reader, signal_type=None, convert_units=False, **kwds)

Load a supported file with a given reader.

hyperspy.io.save(filename, signal, overwrite=None, **kwds)

Save hyperspy signal to a file.

A list of plugins supporting file saving can be found here: http://hyperspy.org/hyperspy-doc/current/user_guide/io.html#supported-formats

Any extra keywords are passed to the corresponding save method in the io_plugin. For available options, see their individual documentation.

  • filename (None or str or pathlib.Path) – The filename to save the signal to.

  • signal (Hyperspy signal) – The signal to be saved to file.

  • overwrite (None or bool, default None) – If None and a file exists the user will be prompted to on whether to overwrite. If False and a file exists the file will not be written. If True and a file exists the file will be overwritten without prompting


Return type