Skip to main content
`Ctrl`+`K`

# 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.

Additionally, 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:
    filename `python:str`, `pathlib.Path`

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

    lazy bool, default=False

      Lazy loading is not supported.

    dataset_path `python:None`, `python: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.

    dryrun bool

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

    show_progressbar bool, default=True

      Whether to show the progressbar or not.

  Returns:
    `python:list` of `python: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)