hyperspy.io module

hyperspy.io._escape_square_brackets(text)

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

Parameters:

text (str) – The text to escape

Returns:

The escaped string

Return type:

str

Example

>>> # 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']
hyperspy.io._infer_file_reader(string)

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

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

Parameters:

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

Returns:

reader – The inferred file reader.

Return type:

func

hyperspy.io._parse_path(arg)

Convenience function to get the path from zarr store or string.

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.

Parameters:

  • dtype (dtype) – Signal dtype

  • signal_dimension (int) – Signal dimension

  • signal_type (str, optional) – Signal type. Default ‘’. Will log a warning if it is unknown to HyperSpy.

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

Return type:

Signal class or subclass

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

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

Parameters:

signal_dict (dictionary) –

Returns:

s

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, stack_metadata=True, load_original_metadata=True, show_progressbar=None, **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.

Parameters:

  • filenames (None, str, list(str), pathlib.Path, 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, that single file is loaded. If multiple file names are passed in a list, a list of objects or a single object containing multiple datasets, a list of signals or a stack of signals is returned. This behaviour is controlled by the stack parameter (see below). Multiple files can be loaded by using simple shell-style wildcards, e.g. ‘my_file*.msa’ loads all the files that start by ‘my_file’ and have the ‘.msa’ extension. Alternatively, regular expression type character classes can be used (e.g. [a-z] matches lowercase letters). See also the escape_square_brackets parameter.

  • signal_type (None, str, '', optional) – The acronym that identifies the signal type. May be any signal type provided by HyperSpy or by installed extensions as listed by hs.print_known_signal_types(). The value provided may determines the Signal subclass assigned to the data. If None (default), the value is read/guessed from the file. Any other value would override the value potentially stored in the file. For example, for electron energy-loss spectroscopy use ‘EELS’. If ‘’ (empty string) the value is not read from the file and is considered undefined.

  • stack (bool, optional) – Default False. If True and multiple filenames are passed, 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, optional) – If None (default), 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 (str, optional) – The name of the new axis (default ‘stack_element’), when axis is None. If an axis with this name already exists, it automatically appends ‘-i’, where i are integers, until it finds a name that is not yet in use.

  • lazy (None, bool, optional) – 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, optional) – If True, convert the units using the convert_to_units method of the axes_manager. If False (default), does nothing.

  • 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).

  • stack_metadata ({bool, int}) – If integer, this value defines the index of the signal in the signal list, from which the metadata and original_metadata are taken. If True, the original_metadata and metadata of each signals are stacked and saved in original_metadata.stack_elements of the returned signal. In this case, the metadata are copied from the first signal in the list. If False, the metadata and original_metadata are not copied.

  • show_progressbar (None or bool) – If True, display a progress bar. If None, the default from the preferences settings is used. Only used with stack=True.

  • load_original_metadata (bool) – If True, all metadata contained in the input file will be added to original_metadata. This does not affect parsing the metadata to metadata.

  • reader (None, str, custom file reader object, optional) – Specify the file reader to use when loading the file(s). If None (default), 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, optional) – For SEMPER unf- and EMD (Berkeley)-files. If True, additional information read during loading is printed for a quick overview. Default False.

  • downsample (int (1–4095), optional) – 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, optional) – For Bruker bcf files and Jeol, if set to numerical (default is None), hypermap is parsed into array with depth cutoff at set energy value. This allows to conserve the memory by cutting-off unused spectral tails, or force enlargement of the spectra size. Bruker bcf reader accepts additional values for semi-automatic cutoff. “zealous” value truncates to the last non zero channel (this option should not be used for stacks, as low beam current EDS can have different last non zero channel per slice). “auto” truncates channels to SEM/TEM acceleration voltage or energy at last channel, depending which is smaller. In case the hv info is not there or hv is off (0 kV) then it fallbacks to full channel range.

  • select_type ('spectrum_image', 'image', 'single_spectrum', None, optional) – 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 returns either only the spectrum image, only the images (including EDS map for Velox emd files), or only the single spectra (for Velox emd files).

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

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

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

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

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

  • SI_dtype (numpy.dtype, None, optional) – 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, optional) – Only for Velox emd files: if True, load the stack of STEM images acquired simultaneously as the EDS spectrum image. Default is False.

  • dataset_path (None, str, 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, optional) – Only for HDF5 USID files: if True (default), 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 files 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

Examples

Loading a single file providing the signal type:

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

Loading multiple files:

>>> d = hs.load(['file1.hspy','file2.hspy'])

Loading multiple files matching the pattern:

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

Loading multiple files containing square brackets in the filename:

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

Loading multiple files containing character classes (regular expression):

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

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')

Loading a file containing several datasets:

>>> s = hs.load("spameggsandham.nxs")
>>> s
[<Signal1D, title: spam, dimensions: (32,32|1024)>,
 <Signal1D, title: eggs, dimensions: (32,32|1024)>,
 <Signal1D, title: ham, dimensions: (32,32|1024)>]
>>> # Use list indexation to access single signal
>>> s[0]
<Signal1D, title: spam, dimensions: (32,32|1024)>
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.

Parameters:

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

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

Returns:

Data loaded from the file.

Return type:

object

hyperspy.io.load_with_reader(filename, reader, signal_type=None, convert_units=False, load_original_metadata=True, **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.

Parameters:

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

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

  • overwrite (None, bool, optional) – If None (default) and a file exists, the user will be prompted 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:

None