msa format

docs/supported_formats/msa.rst

@@ -11,33 +11,19 @@ with Gatan's Digital Micrograph or other software packages. A wide range of
 programs supports exporting to and reading from the ``.msa`` format.
 
 .. WARNING::
-    If several spectra are loaded and stacked (``hs.load('pattern', stack_signals=True``)
-    the calibration read from the first spectrum and applied to all other spectra.
-
-Extra saving arguments
-^^^^^^^^^^^^^^^^^^^^^^
-
-For the ``.msa`` format the ``format`` argument is used to specify whether the
-energy axis should also be saved with the data.  The default, 'Y' omits the
-energy axis in the file.  The alternative, 'XY', saves a second column with the
-calibrated energy data. It is possible to personalise the separator with the
-`separator` keyword.
-
-.. Warning::
-
-    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.
-
-The default encoding is `latin-1`. It is possible to set a different encoding
-using the `encoding` argument, e.g.:
-
-.. code-block:: python
-
-    >>> s.save('file.msa', encoding = 'utf8')
+    If several spectra are loaded and stacked in `HyperSpy <https://hyperspy.org>`_
+    (``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 <https://www.microscopy.org/resources/scientific_data/>`_.
+
+
+API functions
+^^^^^^^^^^^^^
+
+.. automodule:: rsciio.msa
+   :members:

rsciio/__init__.py

@@ -42,6 +42,7 @@
                 "JobinYvon",
                 "MRC",
                 "MRCZ",
+                "MSA",
                 "netCDF",
                 "NeXus",
                 "Phenom",

rsciio/docstrings.py

@@ -36,6 +36,11 @@
         Whether to open the file lazily or not.
     """
 
+ENCODING_DOC = """encoding : 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.
+    """
+
 ENDIANESS_DOC = """endianess : str, Default="<"
         ``"<"`` or ``">"``, depending on how the bits are written to 
         the file.

rsciio/msa/__init__.py

@@ -1 +1,14 @@
+from ._api import (
+    file_reader,
+    file_writer,
+)
 
+
+__all__ = [
+    "file_reader",
+    "file_writer",
+]
+
+
+def __dir__():
+    return sorted(__all__)

rsciio/msa/api.py → rsciio/msa/_api.py

@@ -24,6 +24,12 @@
 
 import numpy as np
 
+from rsciio.docstrings import (
+    FILENAME_DOC,
+    ENCODING_DOC,
+    RETURNS_DOC,
+    SIGNAL_DOC,
+)
 from rsciio.version import __version__
 from rsciio.utils.tools import DTBox
 
@@ -337,11 +343,46 @@ def parse_msa_string(string, filename=None):
 
 
 def file_reader(filename, encoding="latin-1", **kwds):
+    """
+    Read an MSA file.
+
+    Parameters
+    ----------
+    %s
+    %s
+
+    %s
+    """
     with codecs.open(filename, encoding=encoding, errors="replace") as spectrum_file:
         return parse_msa_string(string=spectrum_file, filename=filename)
 
 
+file_reader.__doc__ %= (FILENAME_DOC, ENCODING_DOC, RETURNS_DOC)
+
+
 def file_writer(filename, signal, format=None, separator=", ", encoding="latin-1"):
+    """
+    Write signal to an MSA file.
+
+    Parameters
+    ----------
+    %s
+    %s
+    format : 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: 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.
+    %s
+
+    Examples
+    --------
+    >>> from rsciio.msa import file_writer
+    >>> file_writer("file.msa", signal, encoding="utf8")
+    """
     loc_kwds = {}
     FORMAT = "EMSA/MAS Spectral Data File"
     md = DTBox(signal["metadata"], box_dots=True)
@@ -469,3 +510,10 @@ def file_writer(filename, signal, format=None, separator=", ", encoding="latin-1
             raise ValueError("format must be one of: None, 'XY' or 'Y'")
 
         f.write("#%-12s: End Of Data and File" % "ENDOFDATA")
+
+
+file_writer.__doc__ %= (
+    FILENAME_DOC.replace("read", "write to"),
+    SIGNAL_DOC,
+    ENCODING_DOC.replace("read", "write"),
+)

rsciio/ripple/_api.py

@@ -31,6 +31,7 @@
 from rsciio.docstrings import (
     FILENAME_DOC,
     LAZY_DOC,
+    ENCODING_DOC,
     RETURNS_DOC,
     SIGNAL_DOC,
 )
@@ -265,10 +266,7 @@ def file_reader(
         A dictionary containing the keywords in order to read a ``.raw`` file
         without corresponding ``.rpl`` file. If ``None``, the keywords are parsed
         automatically from the ``.rpl`` file.
-    enconding : str, optional
-        The encoding used to read the content of the ``rpl`` file. The default
-        encoding is ``latin-1``. Different file encodings, such as ``utf8`` can be
-        set via this argument.
+    %s
     mmap_mode : str, optional
         Default is copy-on-write ``"c"``, but different modes can be set. However,
         note that lazy loading does not support in-place writing (i.e lazy loading
@@ -466,7 +464,7 @@ def file_reader(
     ]
 
 
-file_reader.__doc__ %= (FILENAME_DOC, LAZY_DOC, RETURNS_DOC)
+file_reader.__doc__ %= (FILENAME_DOC, LAZY_DOC, ENCODING_DOC, RETURNS_DOC)
 
 
 def file_writer(filename, signal, encoding="latin-1", *args, **kwds):
@@ -477,10 +475,7 @@ def file_writer(filename, signal, encoding="latin-1", *args, **kwds):
     ----------
     %s
     %s
-    enconding : str, optional
-        The encoding used to write the content of the ``rpl`` file. The default
-        encoding is ``latin-1``. Different file encodings, such as ``utf8`` can be
-        set via this argument.
+    %s
     """
 
     # Set the optional keys to None
@@ -606,7 +601,11 @@ def file_writer(filename, signal, encoding="latin-1", *args, **kwds):
     write_raw(filename, signal, record_by, sig_axes, nav_axes)
 
 
-file_writer.__doc__ %= (FILENAME_DOC.replace("read", "write to"), SIGNAL_DOC)
+file_writer.__doc__ %= (
+    FILENAME_DOC.replace("read", "write to"),
+    SIGNAL_DOC,
+    ENCODING_DOC.replace("read", "write"),
+)
 
 
 def write_rpl(filename, keys_dictionary, encoding="ascii"):

rsciio/tests/test_import.py

@@ -141,6 +141,10 @@ def test_dir_plugins():
 
     assert dir(mrcz) == ["file_reader", "file_writer"]
 
+    from rsciio import msa
+
+    assert dir(msa) == ["file_reader", "file_writer"]
+
     from rsciio import netcdf
 
     assert dir(netcdf) == ["file_reader"]

rsciio/tests/test_io.py

@@ -304,7 +304,7 @@ def test_load_save_filereader_metadata():
 
     my_path = os.path.dirname(__file__)
     s = hs.load(os.path.join(my_path, "msa_files", "example1.msa"))
-    assert s.metadata.General.FileIO.Number_0.io_plugin == "rsciio.msa.api"
+    assert s.metadata.General.FileIO.Number_0.io_plugin == "rsciio.msa"
     assert s.metadata.General.FileIO.Number_0.operation == "load"
     assert s.metadata.General.FileIO.Number_0.hyperspy_version == hs.__version__
 
@@ -313,7 +313,7 @@ def test_load_save_filereader_metadata():
         s.save(f)
         expected = {
             "0": {
-                "io_plugin": "rsciio.msa.api",
+                "io_plugin": "rsciio.msa",
                 "operation": "load",
                 "hyperspy_version": hs.__version__,
             },

rsciio/tests/test_msa.py

@@ -38,7 +38,7 @@
             "0": {
                 "operation": "load",
                 "hyperspy_version": hs.__version__,
-                "io_plugin": "rsciio.msa.api",
+                "io_plugin": "rsciio.msa",
             }
         },
     },
@@ -135,7 +135,7 @@
             "0": {
                 "operation": "load",
                 "hyperspy_version": hs.__version__,
-                "io_plugin": "rsciio.msa.api",
+                "io_plugin": "rsciio.msa",
             }
         },
     },