Merge pull request #311 from CSSFrancis/de_mrc_auto

De MRC Auto get Metadata

doc/conf.py

@@ -39,6 +39,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.napoleon",
     "sphinxcontrib.towncrier",
+    "sphinx_copybutton",
 ]
 
 intersphinx_mapping = {
@@ -120,6 +121,13 @@
 towncrier_draft_include_empty = False
 towncrier_draft_working_directory = ".."
 
+# -- Options for CopyButton extension -----------------------------------
+
+# CopyButton configuration
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+copybutton_line_continuation_character = "\\"
+
 
 linkcheck_ignore = [
     "https://www.biorxiv.org",  # 403 Client Error: Forbidden for url

doc/file_specification/index.rst

@@ -27,3 +27,19 @@ Ripple (Lispix)
 
 :ref:`Format description <ripple-file_specification>` for the :ref:`ripple
 <ripple-format>` file format.
+
+
+MRC (CCP-EM)
+------------
+
+The :ref:`MRC <mrc-format>` file format is a standard open file format for electron microscopy data and is
+defined by  `Cheng et al <https://doi.org/10.1016/j.jsb.2015.04.002>`_. The file format is described in
+detail following the link as well:  `MRC2014 <https://www.ccpem.ac.uk/mrc_format/mrc2014.php>`_.
+
+Additionally Direct Electron saves a couple of files along with the ``.mrc`` file. In general, the file naming
+scheme is CurrentDate_MovieNumber_suffix_movie.mrc with the metadata file named CurrentDate_MovieNumber_suffix_info.txt.
+and different external detectors or virtual images are saved as CurrentDate_MovieNumber_suffix_ext#_extName.mrc or
+CurrentDate_MovieNumber_suffix_#_virtualName.mrc respectively. The suffix is optional and can be any
+string or left empty. By default Virtual image 0 is the sum at each navigation point and is equivalent to the
+navigation image.
+

doc/user_guide/supported_formats/mrc.rst

@@ -14,10 +14,10 @@ and has partial support for FEI's custom header.
     specify the shape of the navigation space.
 
 .. Note::
-    For ``.mrc`` files, the ``file_reader`` takes the ``mmap_mode`` keyword argument
-    to load the file using a different mode (default is copy-on-write) . However,
-    note that lazy loading does not support in-place writing (i.e lazy loading and
-    the ``r+`` mode are incompatible).
+    For ``.mrc`` files, the :func:`~rsciio.mrc.file_reader` takes the ``mmap_mode``
+    keyword argument to load the file using a different mode (default is copy-on-write).
+    However, note that lazy loading does not support in-place writing (i.e lazy loading
+    and the ``r+`` mode are incompatible).
 
 See also the `format documentation <https://www.ccpem.ac.uk/mrc_format/mrc_format.php>`_
 by the Collaborative Computational Project for Electron cryo-Microscopy (CCP-EM).
@@ -30,38 +30,77 @@ not be passed (Default is ``None``):
 
 .. code-block:: python
 
-    import numpy as np
-    from rsciio import mrcz
+    >>> import numpy as np
+    >>> from rsciio import mrcz
 
-    data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
-    s = hs.signals.Signal2D(data)
-    s_dict = s.as_dictionary()
+    >>> data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
+    >>> s = hs.signals.Signal2D(data)
+    >>> s_dict = s.as_dictionary()
 
-    mrcz.file_writer('test.mrc', s_dict)
+    >>> mrcz.file_writer('test.mrc', s_dict)
 
-Alternatively, use :py:meth:`hyperspy.api.signals.BaseSignal.save`, which will pick the
+Alternatively, use :meth:`hyperspy.api.signals.BaseSignal.save`, which will pick the
 ``mrcz`` plugin automatically:
 
 .. code-block:: python
 
-    import hyperspy.api as hs
-    import numpy as np
+    >>> import hyperspy.api as hs
+    >>> import numpy as np
 
-    data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
-    s = hs.signals.Signal2D(data)
-    s.save("data.mrc")
+    >>> data = np.random.randint(100, size=(10, 100, 100)).astype('int16')
+    >>> s = hs.signals.Signal2D(data)
+    >>> s.save("data.mrc")
 
 MRC Format (Direct Electron)
 ----------------------------
 Loading from Direct Electron's ``.mrc`` as well as reading the metadata from the .txt file
 saved by the software is supported by passing the ``metadata_file`` argument to the
 ``file_reader`` function. The ``metadata_file`` argument can be a string or a file-like
-object.
+object. Additionally, the ``metadata_file`` argument can be automatically inferred.  This requires
+that the file name is of the form ``uniqueid_suffix_movie.mrc`` and that the metadata file is
+named ``uniqueid_suffix_info.txt``.
 
 This will automatically set the navigation shape based on the ``Scan - Size X`` and                                                   = 256
-``Scan - Size Y`` as well as the ``Scan - Repeats`` and ``Scan - Point Repeats``
-parameters in the metadata file. The navigation shape can be overridden
-by passing the ``navigation_shape`` argument to the ``file_reader`` function.
+``Scan - Size Y`` parameters in the metadata file. The navigation shape can be overridden
+by passing the ``navigation_shape`` argument to the :func:`~rsciio.mrc.file_reader` function.
+
+Additionally virtual_images/ external detectors can be loaded by passing a list of file names to the
+``external_images`` or the ``virtual_images`` parameter.  This will also automatically be inferred
+if the file names are of the form ``uniqueid_suffix_ext1_extName.mrc`` and
+``uniqueid_suffix_1_virtualName.mrc``. The first virtual image will be used as the navigation image
+for fast plotting.
+
+.. code-block:: python
+
+    >>> import hyperspy.api as hs
+
+    # Automatically load metadata_file="20220101_0001_info.txt" and
+    # any external/virtual images with the same naming convention
+    
+    >>> hs.load("20220101_0001_movie.mrc")
+    <Signal2D, title: 20220101_0001_movie, dimensions: (32, 32|256, 256)>
+    
+    # Load metadata from data_info.txt
+    
+    >>> hs.load("data.mrc", metadata_file="data_info.txt") 
+
+    # Load external image 1
+
+    >>> s = hs.load(
+    ...     "20220101_0001_movie.mrc",
+    ...     external_images=["20220101_0001_ext1_Ext #1.mrc"]
+    ... )
+    >>> s.metadata["General"]["external_detectors"][0]
+    <Signal2D, title:, dimensions: (|32,32)>
+
+    # Will load virtual image 1
+
+    >>> s = hs.load(
+    ...     "20220101_0001_movie.mrc",
+    ...     virtual_images=["20220101_0001_1_Virtual #1.mrc"]
+    ... )
+    >>> s.metadata["General"]["virtual_images"][0]
+    <Signal2D, title:, dimensions: (|32,32)>
 
 
 API functions

pyproject.toml

@@ -116,6 +116,7 @@ doc = [
   "sphinx",
   "sphinx-favicon",
   "sphinxcontrib-towncrier",
+  "sphinx-copybutton",
   # unpin when sphinxcontrib-towncrier supports towncrier >=24
   "towncrier<24",
 ]