Skip to main content
`Ctrl`+`K`

# EMSA/MSA format

The `.msa` format is an open standard format widely used to exchange single spectrum data, but does not support multidimensional data. It can for example be used to exchange single spectra with Gatan’s Digital Micrograph or other software packages. A wide range of programs supports exporting to and reading from the `.msa` format.

Note

If several spectra are loaded and stacked in HyperSpy (`hs.load('pattern', stack_signals=True)`) the calibration is read from the first spectrum and applied to all other spectra.

## Reference

For specifications of the format, see the documentation by the Microscopy Society of America and the ISO 22029:2022 standard.

## API functions

rsciio.msa.file_reader(filename, lazy=False, encoding='latin-1')

  Read an MSA file.

  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.

    encoding `python:str`, default=”latin-1”

      The encoding used to read the content of the file. Different file encodings, such as `"utf8"` can be set via this argument.

  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.

rsciio.msa.file_writer(filename, signal, format='Y', separator=', ', encoding='latin-1')

  Write signal to an MSA file.

  Parameters:
    filename `python:str`, `pathlib.Path`

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

    signal `python:dict`

      Dictionary containing the signal object. Should contain the following fields:

      - ‘data’ – multidimensional numpy 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 metadata tree

    format `python:str`, default=”Y”

      Specify whether the X-axis (energy/wavelength) should also be saved with the data. The default, `"Y"` omits the X-axis in the file. The alternative, `"XY"`, saves the calibrated signal axis as first column.

    separator `python:str`, Default=”, “

      Change the column separator. However, if a different separator is chosen the resulting file will not comply with the MSA/EMSA standard and RosettaSciIO and other software may not be able to read it.

    encoding `python:str`, default=”latin-1”

      The encoding used to write the content of the file. Different file encodings, such as `"utf8"` can be set via this argument.

  Examples

      >>> from rsciio.msa import file_writer
      >>> file_writer("file.msa", signal, encoding="utf8")

rsciio.msa.parse_msa_string(string, filename=None)

  Parse an EMSA/MSA file content.

  Parameters:
    string `python:str`

      It must complain with the EMSA/MSA standard.

    filename `python:str`, `python:None`

      The filename.

  Returns:
    `python:list`

      List of a single dictionary to be returned by `file_reader`.