API Reference

mrcz.readMRC(MRCfilename, idx=None, endian='le', pixelunits='\AA', fileConvention='ccpem', useMemmap=False, n_threads=None, slices=None)

Imports an MRC/Z file as a NumPy array and a meta-data dict.

Parameters:

image: numpy.ndarray

a 1-3 dimension numpy.ndarray with one of the supported data types in mrcz.REVERSE_CCPEM_ENUM

meta: dict

a dict with various fields relating to the MRC header information. Can also hold arbitrary meta-data, but the use of large numerical data is not recommended as it is encoded as text via JSON.

idx: Tuple[int]

Index tuple (first, last) where first (inclusive) and last (not inclusive) indices of images to be read from the stack. Index of first image is 0. Negative indices can be used to count backwards. A singleton integer can be provided to read only one image. If omitted, will read whole file. Compression is currently not supported with this option.

pixelunits: str

can be 'AA' (Angstoms), 'nm', '\mum', or 'pm'. Internally pixel sizes are always encoded in Angstroms in the MRC file.

fileConvention: str

can be 'ccpem' (equivalent to IMOD) or 'eman2', which is only partially supported at present.

endian: str

can be big-endian as 'be' or little-endian as 'le'. Defaults to ‘le’ as the vast majority of modern computers are little-endian.

n_threads: int

is the number of threads to use for decompression, defaults to use all virtual cores.

useMemmap: bool = True

returns a numpy.memmap instead of a numpy.ndarray. Not recommended as it will not work with compression.

slices: Optional[int] = None

Reflects the number of slices per frame. For example, in time-series with multi-channel STEM, would be 4 for a 4-quadrant detector. Data is always written contiguously in MRC, but will be returned as a list of [slices, *shape]-shaped arrays. The default option None will check for a 'slices' field in the meta-data and use that, otherwise it defaults to 0 which is one 3D array.

Returns:

image: Union[list[numpy.ndarray], numpy.ndarray]

If slices == 0 then a monolithic array is returned, else a list of [slices, *shape]-shaped arrays.

meta: dict

the stored meta-data in a dictionary. Note that arrays are generally returned as lists due to the JSON serialization.

mrcz.writeMRC(input_image, MRCfilename, meta=None, endian='le', dtype=None, pixelsize=[0.1, 0.1, 0.1], pixelunits='\AA', shape=None, voltage=0.0, C3=0.0, gain=1.0, compressor=None, clevel=1, n_threads=None, quickStats=True, idx=None)

Write a conventional MRC file, or a compressed MRCZ file to disk. If compressor is None, then backwards compatibility with other MRC libraries should be preserved. Other libraries will not, however, recognize the JSON extended meta-data.

Parameters:

input_image: Union[numpy.ndarray, list[numpy.ndarray]]

The image data to write, should be a 1-3 dimension numpy.ndarray or a list of 2-dimensional ``numpy.ndarray``s.

meta: dict

will be serialized by JSON and written into the extended header. Note that rapidjson (the default) or json (the fallback) cannot serialize all Python objects, so sanitizing meta to remove non-standard library data structures is advisable, including numpy.ndarray values.

dtype: Union[numpy.dtype, str]

will cast the data before writing it.

pixelsize: Tuple[x,y,z]

is [z,y,x] pixel size (singleton values are ok for square/cubic pixels)

pixelunits: str = u’AA’

one of - '\AA' for Angstroms - 'pm' for picometers - '\mum' for micrometers - 'nm' for nanometers. MRC standard is always Angstroms, so pixelsize is converted internally from nm to Angstroms as needed.

shape: Optional[Tuple[int]]

is only used if you want to later append to the file, such as merging together Relion particles for Frealign. Not recommended and only present for legacy reasons.

voltage: float = 300.0

accelerating potential in keV

C3: float = 2.7

spherical aberration in mm

gain: float = 1.0

detector gain in units (counts/primary electron)

compressor: str = None

is a choice of None, 'lz4', 'zlib', 'zstd', plus 'blosclz', 'lz4hc' - 'lz4' is generally the fastest. - 'zstd' generally gives the best compression performance, and is still almost

as fast as ‘lz4’ with clevel == 1.

clevel: int = 1

the compression level, 1 is fastest, 9 is slowest. The compression ratio will rise slowly with clevel (but not as fast as the write time slows down).

n_threads: int = None

number of threads to use for blosc compression. Defaults to number of virtual cores if == None.

quickStats: bool = True

estimates the image mean, min, max from the first frame only, which saves computational time for image stacks. Generally strongly advised to be True.

idx

can be used to write an image or set of images starting at a specific position in the MRC file (which may already exist). Index of first image is 0. A negative index can be used to count backwards. If omitted, will write whole stack to file. If writing to an existing file, compression or extended MRC2014 headers are currently not supported with this option.

Returns:

None

mrcz.asyncReadMRC(*args, **kwargs)

Calls readMRC in a separate thread and executes it in the background.

Parameters:

Valid arguments are as for `readMRC()`.

Returns:

future

A concurrent.futures.Future() object. Calling future.result() will halt until the read is finished and returns the image and meta-data as per a normal call to readMRC.

mrcz.asyncWriteMRC(*args, **kwargs)

Calls writeMRC in a seperate thread and executes it in the background.

Parameters:

Valid arguments are as for `writeMRC()`.

Returns:

future

A concurrent.futures.Future object. If needed, you can call future.result() to wait for the write to finish, or check with future.done(). Most of the time you can ignore the return and let the system write unmonitored. An exception would be if you need to pass in the output to a subprocess.

class mrcz.readDM4(filename, verbose=False)

A fast DM4 file reader to strip the data out of the large movie-mode files generated by K2 detectors along with important tags. Due to the emphasis on speed it’s not a general file parser with dynamic allocation, so if Gatan changes the format a lot it will break the script.

Parameters:

filename: str

the

verbose: bool

whether to output debugging info or not.

discardTag(self)

Quickly parse to the end of tag that we don’t care about its information

parseTag(self, parent)

Parse a tag at the given file handle location

parseTagDir(self, parent)

Parse a tag directory at the given file handle location

retrieveTagData(self, tag_ninfo)

Get the actual data from the tag, which is then stored in one of the dicts or imageData

mrcz.test(verbosity=2)

Run unittest suite for mrcz package.

mrcz.__version__

The version of Python MRCZ.