ncempy.io.mrc module

A module to read MRC files in python and numpy. Written according to MRC specification at http://bio3d.colorado.edu/imod/betaDoc/mrc_format.txt Also works with FEI MRC files which include a special header block with experimental information.

Note

General users:

Use the simplified mrc.mrcReader() function to load the data and meta data as a python dictionary.

Advanced users and developers:

Access the file internals through the mrc.fileMRC() class.

ncempy.io.mrc.appendData(filename, data)[source]

Append a binary set of data to the end of a MRC file. This should only be used in conjunction with writeHeader() above.

Parameters:

  • filename (str) – Name of the MRC file with pre-initiated header and some data already written.

  • data (ndarray) – Data to append to the file.

ncempy.io.mrc.emd2mrc(filename, dsetPath)[source]

Convert EMD data set into MRC data set. The final data type is float32 for convenience.

Parameters:

  • filename (str) – The name of the EMD file

  • dsetPath (str) – The HDF5 path to the top group holding the data. ex. ‘/data/raw/’

class ncempy.io.mrc.fileMRC(filename, verbose=False)[source]

Bases: object

Read in the data in MRC format and other useful information like metadata. Follows the specification published at http://bio3d.colorado.edu/imod/betaDoc/mrc_format.txt

Variables:

  • file_name (str) – The name of the file

  • file_path (pathlib.Path) – A pathlib.Path object for the open file

  • fid (file) – The file handle to the opened MRC file.

  • mrcType (int) – The internal MRC data type.

  • dataType (np.dtype) – The numpy dtype corresponding to the mrcType.

  • dataSize (np.ndarray) – The number of pixels along each dimension. Corresponds to the shape attribute of a np.ndarray

  • gridSize (np.ndarray) – The size of the grid. Usually the same as dataSize

  • volumeSize (np.ndarray) – The size of the volume along each direction in Angstroms.

  • voxelSize (np.ndarray) – The size of the voxel along each direction in Angstroms.

  • cellAngles (np.ndarray) – The angles of the cell. Ignored in most cases including ncempy.

  • axisOrientations (np.ndarray) – Mapping the orientations of the data to real space directions X, Y, Z. Ignored by ncempy

  • minMaxMean (np.ndarray) – The minimum, maximum and mean value of the data to avoid computing this every time.

  • extra (np.ndarray) – Extra mbinary metadata if it exists.

  • FEIinfo (dict) – A dictionary of metadata used by FEI (Thermo Fischer) microsocpes for important metadata. This metadata overwrites the voxelsize attribute if it exists.

  • dataOffset (int) – The integer offset in bytes to the start of the raw data.

  • dataOut (dict) – Will hold the data and metadata to output to the user after getDataset() call.

  • v (bool) – More output for debugging. False by default

Examples

Read in all data and metadata into memory. >> import ncempy.io as nio >> mrc0 = nio.mrc.mrcReader(‘file.mrc’)

Low level operations to get 1 slice of the 3D data >> import ncempy.io as nio >> with nio.mrc.fileMRC(‘file.mrc’) as f1: >> single_slice = f1.getSlice(0)

getDataset()[source]

Read in the full data block and reshape to an ndarray with C-style ordering.

getMemmap()[source]

Return a numpy memmap object (read-only) for the dataset. This is very useful for very large datasets to avoid loading the entire data set into memory. No meta data is returned.

Returns:

A read-only numpy memmap object with access to the data on disk.

Return type:

numpy.core.memmap

getMetadata()[source]
getSlice(num)[source]

Read in a slice of an MRC file. Useful for parsing through a large file without reading the entire data set into memory.

Parameters:

num (int) – Get the requested image.

Returns:

out – A 2D slice or a 3D set of slices along the first index

Return type:

ndarray

Raises:

IndexError – If num > the number of slices.

parseHeader()[source]

Read the header information which includes data type, data size, data shape, and metadata.

Note

This header uses Fortran-style ordering. Numpy uses C-style ordering. The header is read in and then some attributes are reversed [::-1] at the end for output to the user to match C-ordering in numpy.

Todo

Implement special dtype to read the entire header at once. Read everything at once using special dtype. ~5x faster than multiple np.fromfile() reads:

Untested but works in theory headerDtype = np.dtype([(‘head1’,’10int32’),(‘head2’,’6float32’),(‘axisOrientations’,’3int32’), (‘minMaxMean’,’3int32’),(‘extra’,’32int32’)]) head = np.fromfile(self.fid,dtype=headerDtype,count=1)

ncempy.io.mrc.mrc2emd(file_name)[source]

Write an MRC file as an HDF5 file in EMD format with same file name and .emd ending. Header information is retained as attributes.

Parameters:

file_name (str) – The name of the file to convert from MRC to EMD format.

Returns:

out – 1 if successful.

Return type:

int

Todo

Update this to use ncempy.emd class

ncempy.io.mrc.mrc2raw(file_name)[source]

Convert an MRC type file to raw binary. The entire data is read into memory and then written to a new raw file in the same location with the data type and shape (C-ordering) written into the filename. No other meta data is retained.

Parameters:

file_name (str or pathlib.Path) – The file name to convert.

ncempy.io.mrc.mrcReader(file_name)[source]

A simple function to read open a MRC, parse the header, and read the full data set.

Parameters:

file_name (str or pathlib.Path) – The path to the file to load.

Returns:

out – A dictionary containing the data and interesting metadata. The data is attached to the ‘data’ key.

Return type:

dict

Example

Read in all data from disk into memory. This assumes the dataset is 3 dimensional: >> from ncempy.io.mrc import mrcReader >> import matplotlib.pyplot as plt >> mrc1 = mrcReader(‘filename.mrc’) >> plt.imshow(mrc1[‘data’][0, :, :]) # show the first image in the data set

ncempy.io.mrc.mrcWriter(filename, data, pixelSize, forceWrite=False)[source]

Write out a MRC type file according to the specification at http://bio3d.colorado.edu/imod/doc/mrc_format.txt

Parameters:

  • filename (str or pathlib.Path) – The name or Path of the file to write out to.

  • data (ndarray) – The array data to write to disk.

  • pixelSize (tuple) – The size of the pixel along each direction (in Angstroms) as a 3 element vector (sizeZ,sizeY,sizeX).

  • forceWrite (bool) – This will write the data as a C-contiguous array. It is not suggested to use this option and it will be removed in future versions.

ncempy.io.mrc.writeHeader(filename, shape, dtype, pixelSize)[source]

Write out a MRC type file header according to the specification at http://bio3d.colorado.edu/imod/doc/mrc_format.txt. This is useful for initializing an MRC file and then writing to it manually or see appendData() function below.

Parameters:

  • filename (str) – The name of the EMD file

  • shape (tuple) – The shape of the data to write

  • dtype (numpy.dtype) – The dtype to write out the data as. Only some numpy dtypes are supported byt his format. It is suggested to use np.float32 in most cases for maximum compatibility.

  • pixelSize (tuple) – The size of the pixel along each direction (in Angstroms) as a 3 element vector (sizeX,sizeY,sizeZ). sizeZ could be the angular step for a tilt series