Skip to main content
`Ctrl`+`K`

# MRC format

The `.mrc` format is widely used for tomographic data. The implementation of this plugin is based on this specification and has partial support for FEI’s custom header.

Note

When reading 4D-STEM data saved by the Velox software, the data are read as a stack of diffraction patterns, but the `navigation_shape` argument can be used to 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).

See also the format documentation by the Collaborative Computational Project for Electron cryo-Microscopy (CCP-EM).

This plugin does not support writing `.mrc` files, which can however be done using the mrcz plugin. No additional feature of the mrcz format should be used in order to write a `.mrc` compliant file. In particular, the `compressor` argument should not be passed (Default is `None`):

    >>> 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()

    >>> mrcz.file_writer('test.mrc', s_dict)

Alternatively, use `hyperspy.api.signals.BaseSignal.save()`, which will pick the `mrcz` plugin automatically:

    >>> 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")

# 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. 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` parameters in the metadata file. The navigation shape can be overridden by passing the `navigation_shape` argument to the `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.

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

rsciio.mrc.file_reader(filename, lazy=False, mmap_mode=None, endianess='<', navigation_shape=None, distributed=False, chunks='auto', metadata_file='auto', virtual_images=None, external_images=None)

  File reader for the MRC format for tomographic and 4D-STEM data.

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

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

    lazy bool, default=False

      Whether to open the file lazily or not. The file will stay open until closed in `compute()` or closed manually. `get_file_handle()` can be used to access the file handler and close it manually.

    mmap_mode{`python:None`, “r+”, “r”, “w+”, “c”}, default=None

      Argument passed to `numpy.memmap`. A memory-mapped array is stored on disk, and not directly loaded into memory. However, it can be accessed and sliced like any ndarray. Lazy loading does not support in-place writing (i.e lazy loading and the `"r+"` mode are incompatible). If `None` (default), the value is `"r"` when `lazy=True`, otherwise it is `"c"`.

    endianess `python:str`, default=”<”

      `"<"` or `">"`, depending on how the bits are written to the file.

    navigation_shape `python:tuple` or `python:None`, default=None

      Specify the shape of the navigation space. If `None`, the navigation shape will be infer from metadata and if not possible, the data will be loaded as a stack with a navigation dimension equal to one.

    distributed bool, default=False

      Whether to load the data using memory-mapping in a way that is compatible with dask-distributed. This can sometimes improve performance when reading large files. And splitting the data loading/processing over multiple workers.

    chunks `python:tuple` of `python:int` or `python:None`, default=None

      Define the chunking used for saving the dataset. If `None`, calculates chunks for the signal, with preferably at least one chunk per signal space.

    metadata_file `python:str`

      The filename of the metadata file, if “auto” it will try to find the metadata file automatically. For DE movies of 4D STEM datasets this defines the shape and metadata.

    virtual_images `python:list`

      A list of filenames of virtual images. For DE movies these are automatically loaded.

    external_images `python:list`

      A list of filenames of external images (e.g. external detectors) to be loaded alongside the main data. For DE movies these are automatically loaded.

  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.