mrc

Read and write .dv (deltavision) and some mrc image file format.

Note, this module is designed to read the MRC variant used by deltavision microscopes (.dv) and the IVE library from UCSF. For the MRC2014 file format frequently used for structural biology, see mrcfile

(though dv and mrc formats are very similar, priism/dv files that evolved from the IVE library at UCSF have a slightly different header format, preventing mrcfile from working).

Install

pip install mrc

usage and API

new API: Oct 2021

DVFile is a rewrite of the reader, and will be the only maintained reader going forward. It does not write files (see the legacy API for that).

from mrc import DVFile, imread
import numpy as np

my_array = imread('some_file.dv')                          # read to numpy array
my_array = imread('some_file.dv', dask=True)               # read to dask array
my_array = imread('some_file.dv', xarray=True)             # read to xarray
my_array = imread('some_file.dv', xarray=True, dask=True)  # read to dask-xarray

# or open a file with DVFile
f = DVFile('some_file.dv')

# attributes:   # example output
f.path          # 'some_file.dv'
f.shape         # (10, 2, 256, 256)
f.ndim          # 4
f.dtype         # np.dtype('uint16')
f.sizes         # {'T': 10, 'C': 2, 'Y': 256, 'X': 256}

# array output
f.asarray()                # in-memory np.ndarray
np.asarray(f)              # alternative to f.asarray()
f.to_dask()                # delayed dask.array.Array
f.to_xarray()              # in-memory xarray.DataArray, with labeled axes/coords
f.to_xarray(delayed=True)  # delayed xarray.DataArray
               
# metadata     
f.hdr           # Header as a named tuple
f.ext_hdr       # (optional) extended header info
f.voxel_size    # VoxelSize(x=0.65, y=0.65, z=1.0)

f.close()       # don't forget to close when done!
f.closed        # boolean, whether the file is closed

# ... or you can use it as a context manager
with DVFile('some_file.dv') as dvf:
    xarr = dvf.to_xarray()

legacy API

The following older API still exists in this package under the mrc namespace.

This module was extracted from the priithon package, written by Sebastian Haase.

import mrc
import numpy as np

# Read a dv file
arr = mrc.imread('/path/to/file.dv')
# just a numpy array with the data...
isinstance(arr, np.ndarray)  # True

# additional info in stored in the arr.Mrc object.
# print it
arr.Mrc.info()
# or access particular fields:
print(arr.Mrc.header)
# dv files may have additional info in the extended header:
arr.Mrc.extended_header
# for instsance, timestamps for each channel at each timepoint:
arr.Mrc.extended_header['timeStampSeconds']

# or you can write a numpy array to DV format
arr = np.random.rand(23,3,256,256).astype('single')
mrc.imsave("/path/to/output.dv", arr,
    metadata={
        'dx': 0.08,
        'dy': 0.08,
        'dz': 0.125,
        'wave': [445, 528, 615, 0, 0]
    }
)

Priism (DV) MRC Header Format

this information is archived from the no-longer-existing page at http://www.msg.ucsf.edu/IVE/IVE4_HTML/priism_mrc_header.html

The MRC header is 1024 bytes layed out as described below. Each field is in one of these formats:

n Is a 2-byte signed integer (NPY_INT16)

i Is a 4-byte signed integer (NPY_INT32)

f Is a 4-byte floating-point value in IEEE format (NPY_FLOAT32)

cn Is a string of characters that is n bytes long.

Pixel Data Types

The data type used for image pixel values, stored as a signed 32-bit integer in bytes 13 through 16, is designated by one of the code numbers in the following table.

Type codes 5, 6, and 7 are not standard MRC types and are not likely to be correctly interpreted by other software that uses MRC files.

Image Types

The type of a Priism image is given by the signed 16-bit integer in header bytes 161 and 162. The meaning of these types is given in the table below. The floating-point attributes, v1 and v2, used by some image types are stored as 16-bit signed integers in the header; to do so the values are multiplied by 100 and rounded to the nearest integer when stored and are divided by 100 when retrieved.

0 (IM_NORMAL_IMAGES)

Used for normal image data.

1 (IM_TILT_SERIES)

Used for single axis tilt series with a uniform angle increment. n1 specifies the tilt axis (1 for x, 2 for y, 3 for z) and v1 the angle increment in degrees. n2 relates the coordinates in the tilt series to coordinates in a 3D volume: the assumed center of rotation is the z origin from the header plus n2 times one half of the z pixel spacing from the header. v2 is always zero.

2 (IM_STEREO_TILT_SERIES)

Used for stereo tilt series. n1 specifies the tilt axis (1 for x, 2 for y, 3 for z), v1 the angle increment in degrees, and v2 is the angular separation in degrees for the stereo pairs. n2 is always zero.

3 (IM_AVERAGED_IMAGES)

Used for averaged images. n1 is the number of averaged sections and n2 is the number of sections between averaged sections. v1 and v2 are always zero.

4 (IM_AVERAGED_STEREO_PAIRS)

Used for averaged stereo pairs. n1 is the number of averaged sections, n2 is the number of sections between averaged sections, and v2 is the angular separation in degrees for the stereo pairs. v2 is always zero.

5 (IM_EM_TILT_SERIES)

Used for EM tomography data. The tilt angles are stored in the extended header.

20 (IM_MULTIPOSITION)

Used for images of well plates. The following quantities are bit-encoded in n1 (valid range for each is show in parentheses): iwell (0-3), ishape (0-1), ibin (0-15), ispeed (0-2), igain (0-3), and mag (0-1). n2 is the number of fields per well. v1 is the fill factor (.01 to 1.5 in .01 steps). v2 is not used.

8000 (IM_PUPIL_FUNCTION)

Used for images of pupil functions. n1 and n2 are not used. v1 is the numerical aperture times ten. v2 is the immersion media refractive index times one hundred. The pixel spacings and origin have units of cycles per micron rather than microns.

Credits

This package was created by Sebastian Haase as a part of the priithon package. It is updated and maintained by Talley Lambert.