TopSpin App5#

RosettaSciIO can read the app5 format used by NanoMegas in their TopSpin software. These files use the hdf5 file format (and thus can be read with h5py) to store scanning precession electron diffraction (SPED) measurements, as well as standard STEM images.

Data for 2D images is stored as HDF5 Datasets, 4D datasets are stored as HDF5 groups, and Metadata is stored as XML formatted binarized text strings.

Each individual data collection operation is assigned a unique 32-character alphaneumeric ID, which is used for it’s address within the App5 file. Depending on how the file was exported from TopSpin, these can be further grouped into 32-character session ID’s, where all files within the session correspond to the same collection area.

Additonally, as App5 files can be large, the file_reader can be ran with dryrun=True to quickly scan the contents of an app5 file without loading it in its entirety, or subset='id' to only load a single experiment from the file. see the docstring for more details.

Warning

While App5 is supported, it is a proprietary format, and future versions of the format might therefore not be readable. Additionally, the organization of MetaData files changes based on the local hardware setup.

API functions#

rsciio.topspin.file_reader(filename, lazy=False, dataset_path=None, dryrun=False, show_progressbar=True)#

Read .app5 file format both read in and exported by NanoMegas’s Topspin software.

.app5 files use the hdf5 file format, with metadata stored as binarized XML-style text strings. Each individual SPED (Scanning Precession Electron Diffraction) or STEM result is initially saved by Topspin as a simplified .app5, and groups of these files can then also be exported as a single .app5 file representing a larger experiment. Both methods can be read, with only the values of dataset_path being changed.

Parameters:
filenamestr, pathlib.Path

Filename of the file to read or corresponding pathlib.Path.

lazybool, default=False

Lazy loading is not supported.

dataset_pathNone, str, default=None

If None, no absolute path is searched and every dataset in the .app5 file is returned. If a string is given, only the STEM or SPED dataset with the matching absolute path within the .app5 file will be returned. See examples section for details.

dryrunbool

If True, the .app5 files are scanned without being loaded, and a summary is printed to the log. Default is False.

show_progressbarbool, default=True

Whether to show the progressbar or not.

Returns:
list of dict

List of dictionaries containing the following fields:

  • ‘data’ – multidimensional numpy.ndarray or dask.array.Array

  • ‘axes’ – list of dictionaries describing the axes containing the fields ‘name’, ‘units’, ‘index_in_array’, and either ‘size’, ‘offset’, and ‘scale’ or a numpy array ‘axis’ containing the full axes vector

  • ‘metadata’ – dictionary containing the parsed metadata

  • ‘original_metadata’ – dictionary containing the full metadata tree from the input file

When the file contains several datasets, each dataset will be loaded as separate dictionary.

Notes

The hierarchy of the Metadata objects stored in app5 files changes based on Topspin Procedure and microscope setup. RosettaSciIO does not need this information to populate the metadata or axes results, but be aware the organization of the original_metadata can change if the experimental setup changes.

Examples

Load all datasets from an .app5 file:

>>> from rsciio.topspin import file_reader
>>> signals = file_reader("fname.app5")

Load a single dataset from an .app5 file by specifying the dataset_path:

>>> signals = rsciio.topspin.file_reader(
        "fname.app5", dataset_path="18d9446f-22bf-4fb1-8d13-338174e75d20"
    )

The dryrun argument ble can be used to list all allowable addresses without requiring loading from disk.

>>> file_reader("fname.app5", dryrun=True)
On this page

This Page