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.

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.

API functions#

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

File reader for the MRC format for tomographic data.

Parameters:

filenamestr, pathlib.Path: Filename of the file to read or corresponding pathlib.Path.
lazybool, default=False: Whether to open the file lazily or not.
mmap_mode{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".
endianessstr, default=”<”: "<" or ">", depending on how the bits are written to the file.
navigation_shapetuple or 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.
distributedbool, 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.
chunkstuple of int or 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_filestr: The filename of the metadata file.

Returns:

list of 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.