.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "MRCFILE" "1" "Feb 17, 2023" "1.4.3" "mrcfile"
.SH NAME
mrcfile \- mrcfile Documentation
.sp
Get started by reading the \fI\%Overview of mrcfile.py\fP and the \fI\%Usage Guide\fP\&.
.sp
You can also look at the \fI\%Source documentation\fP\&.
.SH OVERVIEW OF MRCFILE.PY
.sp
\fBmrcfile\fP is a Python implementation of the \fI\%MRC2014 file format\fP, which
is used in structural biology to store image and volume data.
.sp
It allows MRC files to be created and opened easily using a very simple API,
which exposes the file\(aqs header and data as \fI\%numpy\fP arrays. The code runs in
Python 2 and 3 and is fully unit\-tested.
.sp
This library aims to allow users and developers to read and write
standard\-compliant MRC files in Python as easily as possible, and with no
dependencies on any compiled libraries except \fI\%numpy\fP\&. You can use it
interactively to inspect files, correct headers and so on, or in scripts and
larger software packages to provide basic MRC file I/O functions.
.SS Key Features
.INDENT 0.0
.IP \(bu 2
Clean, simple API for access to MRC files
.IP \(bu 2
Easy to install and use
.IP \(bu 2
Validation of files according to the MRC2014 format
.IP \(bu 2
Seamless support for gzip and bzip2 files
.IP \(bu 2
Memory\-mapped file option for fast random access to very large files
.IP \(bu 2
Asynchronous opening option for background loading of multiple files
.IP \(bu 2
Runs in Python 2 & 3, on Linux, Mac OS X and Windows
.UNINDENT
.SS Installation
.sp
The \fBmrcfile\fP library is available from the \fI\%Python package index\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
pip install mrcfile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Or from \fI\%conda\-forge\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
conda install \-\-channel conda\-forge mrcfile
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
It is also included in the \fBccpem\-python\fP environment in the  \fI\%CCP\-EM\fP
software suite.
.sp
The source code (including the full test suite) can be found \fI\%on GitHub\fP\&.
.SS Basic usage
.sp
The easiest way to open a file is with the \fI\%mrcfile.open\fP and \fI\%mrcfile.new\fP
functions. These return an \fI\%MrcFile\fP object which represents an MRC file on
disk.
.sp
To open an MRC file and read a slice of data:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> import mrcfile
>>> with mrcfile.open(\(aqtests/test_data/EMD\-3197.map\(aq) as mrc:
\&...     mrc.data[10,10]
\&...
array([ 2.58179283,  3.1406002 ,  3.64495397,  3.63812137,  3.61837363,
        4.0115056 ,  3.66981959,  2.07317996,  0.1251585 , \-0.87975615,
        0.12517013,  2.07319379,  3.66982722,  4.0115037 ,  3.61837196,
        3.6381247 ,  3.64495087,  3.14059472,  2.58178973,  1.92690361], dtype=float32)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To create a new file with a 2D data array, and change some values:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> array = np.zeros((5, 5), dtype=np.int8)
>>> with mrcfile.new(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc.set_data(array)
\&...     mrc.data[1:4,1:4] = 10
\&...     mrc.data
\&...
array([[ 0,  0,  0,  0,  0],
       [ 0, 10, 10, 10,  0],
       [ 0, 10, 10, 10,  0],
       [ 0, 10, 10, 10,  0],
       [ 0,  0,  0,  0,  0]], dtype=int8)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The data will be saved to disk when the file is closed, either automatically at
the end of the \fBwith\fP block (like a normal Python file object) or manually by
calling \fBclose()\fP\&. You can also call \fBflush()\fP to write any changes to disk
and keep the file open.
.sp
To validate an MRC file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrcfile.validate(\(aqtests/test_data/EMD\-3197.map\(aq)
File does not declare MRC format version 20140 or 20141: nversion = 0
False

>>> mrcfile.validate(\(aqtmp.mrc\(aq)
True
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Documentation
.sp
Full documentation is available on \fI\%Read the Docs\fP\&.
.SS Citing mrcfile
.sp
If you find \fBmrcfile\fP useful in your work, please cite:
.sp
Burnley T, Palmer C & Winn M (2017) Recent developments in the CCP\-EM
software suite. \fIActa Cryst.\fP D\fB73\fP:469\-\-477.
\fI\%doi: 10.1107/S2059798317007859\fP
.SS Contributing
.sp
Please use the \fI\%GitHub issue tracker\fP for bug reports and feature requests, or
\fI\%email CCP\-EM\fP\&.
.sp
Code contributions are also welcome, please submit pull requests to the
\fI\%GitHub repository\fP\&.
.sp
To run the test suite, go to the top\-level project directory (which contains
the \fBmrcfile\fP and \fBtests\fP packages) and run \fBpython \-m unittest tests\fP\&.
(Or, if you have \fI\%tox\fP installed, run \fBtox\fP\&.)
.SS Licence
.sp
The project is released under the BSD licence.
.SH USAGE GUIDE
.sp
This is a detailed guide to using the \fBmrcfile\fP Python library. For a brief
introduction, see the \fI\%overview\fP\&.
.SS Opening MRC files
.SS Normal file access
.sp
MRC files can be opened using the \fI\%mrcfile.new()\fP or
\fI\%mrcfile.open()\fP functions. These return an instance of the
\fI\%MrcFile\fP class, which represents an MRC file on disk
and makes the file\(aqs header, extended header and data available for read and
write access as \fI\%numpy arrays\fP\&. :
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # First, create a simple dataset
>>> import numpy as np
>>> example_data = np.arange(12, dtype=np.int8).reshape(3, 4)

>>> # Make a new MRC file and write the data to it:
>>> import mrcfile
>>> with mrcfile.new(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc.set_data(example_data)
\&...
>>> # The file is now saved on disk. Open it again and check the data:
>>> with mrcfile.open(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc.data
\&...
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]], dtype=int8)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Simple data access
.sp
Alternatively, for even quicker access to MRC data but with minimal control of
the file header, you can use the \fI\%read()\fP and
\fI\%write()\fP functions. These do not return
\fI\%MrcFile\fP objects but instead work directly with
\fI\%numpy arrays\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # First, create a simple dataset
>>> import numpy as np
>>> example_data_2 = np.arange(6, dtype=np.int8).reshape(3, 2)

>>> # Write the data to a new MRC file:
>>> mrcfile.write(\(aqtmp2.mrc\(aq, example_data_2)

>>> # Read it back:
>>> mrcfile.read(\(aqtmp2.mrc\(aq)
array([[0, 1],
       [2, 3],
       [4, 5]], dtype=int8)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Handling compressed files
.sp
All of the functions shown above can also handle gzip\- or bzip2\-compressed
files very easily:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Make a new gzipped MRC file:
>>> with mrcfile.new(\(aqtmp.mrc.gz\(aq, compression=\(aqgzip\(aq) as mrc:
\&...     mrc.set_data(example_data * 2)
\&...
>>> # Open it again with the normal open function:
>>> with mrcfile.open(\(aqtmp.mrc.gz\(aq) as mrc:
\&...     mrc.data
\&...
array([[ 0,  2,  4,  6],
       [ 8, 10, 12, 14],
       [16, 18, 20, 22]], dtype=int8)

>>> # Same again for bzip2:
>>> with mrcfile.new(\(aqtmp.mrc.bz2\(aq, compression=\(aqbzip2\(aq) as mrc:
\&...     mrc.set_data(example_data * 3)
\&...
>>> # Open it again with the normal read function:
>>> mrcfile.read(\(aqtmp.mrc.bz2\(aq)
array([[ 0,  3,  6,  9],
       [12, 15, 18, 21],
       [24, 27, 30, 33]], dtype=int8)

>>> # The write function applies compression automatically based on the file name
>>> mrcfile.write(\(aqtmp2.mrc.gz\(aq, example_data * 4)

>>> # The new file is opened as a GzipMrcFile object:
>>> with mrcfile.open(\(aqtmp2.mrc.gz\(aq) as mrc:
\&...     print(mrc)
\&...
GzipMrcFile(\(aqtmp2.mrc.gz\(aq, mode=\(aqr\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Closing files and writing to disk
.sp
\fI\%MrcFile\fP objects should be closed when they are
finished with, to ensure any changes are flushed to disk and the underlying
file object is closed:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> # do things...
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As we saw in the examples above, \fI\%MrcFile\fP objects
support Python\(aqs \fI\%with\fP statement, which will ensure the file is
closed properly after use (like a normal Python file object). It\(aqs generally a
good idea to use \fI\%with\fP if possible, but sometimes when running Python
interactively (as in some of these examples), it\(aqs more convenient to open a
file and keep using it without having to work in an indented block. If you do
this, remember to close the file at the end!
.sp
There\(aqs also a \fI\%flush()\fP method that
writes the MRC data to disk but leaves the file open:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> # do things...
>>> mrc.flush()  # make sure changes are written to disk
>>> # continue using the file...
>>> mrc.close()  # close the file when finished
.ft P
.fi
.UNINDENT
.UNINDENT
.SS MrcFile subclasses
.sp
For most purposes, the top\-level functions in \fI\%mrcfile\fP should be all you
need to open MRC files, but it is also possible to directly instantiate
\fI\%MrcFile\fP and its subclasses,
\fI\%GzipMrcFile\fP,
\fI\%Bzip2MrcFile\fP and
\fI\%MrcMemmap\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> with mrcfile.mrcfile.MrcFile(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc
\&...
MrcFile(\(aqtmp.mrc\(aq, mode=\(aqr\(aq)

>>> with mrcfile.gzipmrcfile.GzipMrcFile(\(aqtmp.mrc.gz\(aq) as mrc:
\&...     mrc
\&...
GzipMrcFile(\(aqtmp.mrc.gz\(aq, mode=\(aqr\(aq)

>>> with mrcfile.bzip2mrcfile.Bzip2MrcFile(\(aqtmp.mrc.bz2\(aq) as mrc:
\&...     mrc
\&...
Bzip2MrcFile(\(aqtmp.mrc.bz2\(aq, mode=\(aqr\(aq)

>>> with mrcfile.mrcmemmap.MrcMemmap(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc
\&...
MrcMemmap(\(aqtmp.mrc\(aq, mode=\(aqr\(aq)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS File modes
.sp
\fI\%MrcFile\fP objects can be opened in three modes: \fBr\fP,
\fBr+\fP and \fBw+\fP\&. These correspond to the standard Python file modes, so \fBr\fP
opens a file in read\-only mode:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # The default mode is \(aqr\(aq, for read\-only access:
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq)
>>> mrc
MrcFile(\(aqtmp.mrc\(aq, mode=\(aqr\(aq)
>>> mrc.set_data(example_data)
Traceback (most recent call last):
  ...
ValueError: MRC object is read\-only
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBr+\fP opens it for reading and writing:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Using mode \(aqr+\(aq allows read and write access:
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> mrc
MrcFile(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> mrc.set_data(example_data)
>>> mrc.data
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]], dtype=int8)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and \fBw+\fP opens a new, empty file (also for both reading and writing):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Mode \(aqw+\(aq creates a new empty file:
>>> mrc = mrcfile.open(\(aqempty.mrc\(aq, mode=\(aqw+\(aq)
>>> mrc
MrcFile(\(aqempty.mrc\(aq, mode=\(aqw+\(aq)
>>> mrc.data
array([], dtype=int8)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The \fI\%new()\fP function is effectively shorthand for
\fBopen(name, mode=\(aqw+\(aq)\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Make a new file
>>> mrc = mrcfile.new(\(aqempty.mrc\(aq)
Traceback (most recent call last):
  ...
ValueError: File \(aqempty.mrc\(aq already exists; set overwrite=True to overwrite it
>>> # Ooops, we\(aqve already got a file with that name!
>>> # If we\(aqre sure we want to overwrite it, we can try again:
>>> mrc = mrcfile.new(\(aqempty.mrc\(aq, overwrite=True)
>>> mrc
MrcFile(\(aqempty.mrc\(aq, mode=\(aqw+\(aq)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Permissive read mode
.sp
Normally, if an MRC file is badly invalid, an exception is raised when the file
is opened. This can be a problem if we want to, say, open a file and fix a
header problem. To deal with this situation, \fI\%open()\fP and
\fI\%mmap()\fP provide an optional \fBpermissive\fP argument. If this is
set to \fI\%True\fP, problems with the file will cause warnings to be issued
(using Python\(aqs \fI\%warnings\fP module) instead of raising exceptions, and the
file will continue to be interpreted as far as possible.
.sp
Let\(aqs see an example. First we\(aqll deliberately make an invalid file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Make a new file and deliberately make a mistake in the header
>>> with mrcfile.new(\(aqinvalid.mrc\(aq) as mrc:
\&...     mrc.header.map = b\(aqmap \(aq  # standard requires b\(aqMAP \(aq
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now when we try to open the file, an exception is raised:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Opening an invalid file raises an exception:
>>> mrc = mrcfile.open(\(aqinvalid.mrc\(aq)
Traceback (most recent call last):
  ...
ValueError: Map ID string not found \- not an MRC file, or file is corrupt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If we use permissive mode, we can open the file, and we\(aqll see a warning about
the problem (except that here, we have to catch the warning and print the
message manually, because warnings don\(aqt play nicely with doctests!):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Opening in permissive mode succeeds, with a warning:
>>> with warnings.catch_warnings(record=True) as w:
\&...     mrc = mrcfile.open(\(aqinvalid.mrc\(aq, permissive=True)
\&...     print(w[0].message)
\&...
Map ID string not found \- not an MRC file, or file is corrupt
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now let\(aqs fix the file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Fix the invalid file by correcting the header
>>> with mrcfile.open(\(aqinvalid.mrc\(aq, mode=\(aqr+\(aq, permissive=True) as mrc:
\&...     mrc.header.map = mrcfile.constants.MAP_ID
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
And now we should be able to open the file again normally:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Now we don\(aqt need permissive mode to open the file any more:
>>> mrc = mrcfile.open(\(aqinvalid.mrc\(aq)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The problems that can cause an exception when opening an MRC file are:
.INDENT 0.0
.IP 1. 3
The header\(aqs \fBmap\fP field is not set correctly to confirm the file type. If
the file is otherwise correct, permissive mode should be able to read the
file normally.
.IP 2. 3
The machine stamp is invalid and so the file\(aqs byte order cannot be
determined. In this case, permissive mode assumes that the byte order is
little\-endian and continues trying to read the file. If the file is actually
big\-endian, the mode and data size checks will also fail because these
values depend on the endianness and will be nonsensical.
.IP 3. 3
The mode number is not recognised. Currently accepted modes are 0, 1, 2, 4
and 6.
.IP 4. 3
The data block is not large enough for the specified data type and
dimensions.
.UNINDENT
.sp
In the last two cases, the data block will not be read and the
\fI\%data\fP attribute will be set to
\fI\%None\fP\&.
.sp
Fixing invalid files can be quite complicated! This usage guide might be
expanded in future to explain how to analyse and fix problems, or the library
itself might be improved to fix certain problems automatically. For now, if
you have trouble with an invalid file, inspecting the code in this library
might help you to work out how to approach the problem (start with
\fI\%MrcInterpreter._read_header()\fP), or you could try asking on the
\fI\%CCP\-EM mailing list\fP for advice.
.SS A note on axis ordering
.sp
\fBmrcfile\fP follows the Python / C\-style convention for axis
ordering. This means that the first index is the slowest axis (typically Z for
volume data or Y for images) and the last index is the fastest axis (typically
X), and the numpy arrays are C\-contiguous:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> data = mrcfile.read(\(aqtmp.mrc\(aq)
>>> data
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]], dtype=int8)

>>> data[1, 0]  # x = 0, y = 1
4
>>> data[2, 3]  # x = 3, y = 2
11

>>> data.flags.c_contiguous
True
>>> data.flags.f_contiguous
False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that this axis order is the opposite of the FORTRAN\-style convention that
is used by some other software in structural biology. This can cause confusing
errors!
.SS Using MrcFile objects
.SS Accessing the header and data
.sp
The header and data arrays can be accessed using the
\fI\%header\fP,
\fI\%extended_header\fP and
\fI\%data\fP attributes:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq)
>>> mrc.header
rec.array((4, 3, 1, ...),
          dtype=[(\(aqnx\(aq, ...)])
>>> mrc.extended_header
array([],
      dtype=\(aq|V1\(aq)
>>> mrc.data
array([[ 0,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]], dtype=int8)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
These attributes are read\-only and cannot be assigned to directly, but (unless
the file mode is \fBr\fP) the arrays can be modified in\-place:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> # A new data array cannot be assigned directly to the data attribute
>>> mrc.data = np.ones_like(example_data)
Traceback (most recent call last):
  ...
AttributeError: can\(aqt set attribute
>>> # But the data can be modified by assigning to a slice or index
>>> mrc.data[0, 0] = 10
>>> mrc.data
array([[10,  1,  2,  3],
       [ 4,  5,  6,  7],
       [ 8,  9, 10, 11]], dtype=int8)
>>> # All of the data values can be replaced this way, as long as the data
>>> # size, shape and type are not changed
>>> mrc.data[:] = np.ones_like(example_data)
>>> mrc.data
array([[1, 1, 1, 1],
       [1, 1, 1, 1],
       [1, 1, 1, 1]], dtype=int8)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To replace the data or extended header completely, call the
\fI\%set_data()\fP and
\fI\%set_extended_header()\fP methods:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> data_3d = np.linspace(\-1000, 1000, 20, dtype=np.int16).reshape(2, 2, 5)
>>> mrc.set_data(data_3d)
>>> mrc.data
array([[[\-1000,  \-894,  \-789,  \-684,  \-578],
        [ \-473,  \-368,  \-263,  \-157,   \-52]],
       [[   52,   157,   263,   368,   473],
        [  578,   684,   789,   894,  1000]]], dtype=int16)
>>> # Setting a new data array updates the header dimensions to match
>>> mrc.header.nx
array(5, dtype=int32)
>>> mrc.header.ny
array(2, dtype=int32)
>>> mrc.header.nz
array(2, dtype=int32)
>>> # We can also set the extended header in the same way
>>> string_array = np.fromstring(b\(aqThe extended header can hold any kind of numpy array\(aq, dtype=\(aqS52\(aq)
>>> mrc.set_extended_header(string_array)
>>> mrc.extended_header
array([b\(aqThe extended header can hold any kind of numpy array\(aq],
      dtype=\(aq|S52\(aq)
>>> # Setting the extended header updates the header\(aqs nsymbt field to match
>>> mrc.header.nsymbt
array(52, dtype=int32)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that setting an extended header does not automatically set or change the
header\(aqs \fBexttyp\fP field. You should set this yourself to identify the type
of extended header you are using.
.sp
For a quick overview of the contents of a file\(aqs header, call
\fI\%print_header()\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> with mrcfile.open(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc.print_header()
\&...
nx              : 5
ny              : 2
nz              : 2
mode            : 1
nxstart ...
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Voxel size
.sp
The voxel (or pixel) size in the file can be accessed using the
\fI\%voxel_size\fP attribute, which returns a
\fI\%numpy record array\fP with three fields, \fBx\fP, \fBy\fP
and \fBz\fP, for the voxel size in each dimension:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> with mrcfile.open(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc.voxel_size
\&...
rec.array((0.,  0.,  0.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In a new file, the voxel size is zero by default. To set the voxel size, you
can assign to the \fI\%voxel_size\fP attribute,
using a single number (for an isotropic voxel size), a 3\-tuple or a single\-item
record array with \fBx\fP, \fBy\fP and \fBz\fP fields (which must be in that order):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # Set a new isotropic voxel size:
>>> mrc.voxel_size = 1.0
>>> mrc.voxel_size
rec.array((1.,  1.,  1.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])

>>> # Set an anisotropic voxel size using a tuple:
>>> mrc.voxel_size = (1.0, 2.0, 3.0)
>>> mrc.voxel_size
rec.array((1.,  2.,  3.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])

>>> # And set a different anisotropic voxel size using a record array:
>>> mrc.voxel_size = np.rec.array(( 4.,  5.,  6.), dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])
>>> mrc.voxel_size
rec.array((4.,  5.,  6.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The sizes are not stored directly in the MRC header, but are calculated when
required from the header\(aqs cell and grid size fields. The voxel size can
therefore be changed by altering the cell size:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # Check the current voxel size in X:
>>> mrc.voxel_size.x
array(4., dtype=float32)

>>> # And check the current cell dimensions:
>>> mrc.header.cella
rec.array((20.,  10.,  6.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])

>>> # Now change the cell\(aqs X length:
>>> mrc.header.cella.x = 10

>>> # And we see the voxel size has also changed:
>>> mrc.voxel_size.x
array(2., dtype=float32)

>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Equivalently, the cell size will be changed if a new voxel size is given:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # Check the current cell dimensions:
>>> mrc.header.cella
rec.array((10.,  10.,  6.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])

>>> # Set a new voxel size:
>>> mrc.voxel_size = 1.0

>>> # And our cell size has been updated:
>>> mrc.header.cella
rec.array((5.,  2.,  1.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])

>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Because the voxel size array is calculated on demand, assigning back to it
wouldn\(aqt work so it\(aqs flagged as read\-only:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # This doesn\(aqt work
>>> mrc.voxel_size.x = 2.0
Traceback (most recent call last):
  ...
ValueError: assignment destination is read\-only

>>> # But you can do this
>>> vsize = mrc.voxel_size.copy()
>>> vsize.x = 2.0
>>> mrc.voxel_size = vsize
>>> mrc.voxel_size
rec.array((2.,  1.,  1.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the calculated voxel size will change if the grid size is changed by
replacing the data array:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # Check the current voxel size:
>>> mrc.voxel_size
rec.array((2.,  1.,  1.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])
>>> # And the current data dimensions:
>>> mrc.data.shape
(2, 2, 5)

>>> # Replace the data with an array with a different shape:
>>> mrc.set_data(example_data)
>>> mrc.data.shape
(3, 4)

>>> # ...and the voxel size has changed:
>>> mrc.voxel_size
rec.array((2.5, 0.6666667, 1.),
          dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])

>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Keeping the header and data in sync
.sp
When a new data array is given (using
\fI\%set_data()\fP or the \fBdata\fP argument to
\fI\%mrcfile.new()\fP), the header is automatically updated to ensure the file is
is valid:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # Check the current data shape and header dimensions match
>>> mrc.data.shape
(3, 4)
>>> mrc.header.nx
array(4, dtype=int32)
>>> mrc.header.nx == mrc.data.shape[\-1]  # X axis is always the last in shape
True

>>> # Let\(aqs also check the maximum value recorded in the header
>>> mrc.header.dmax
array(11., dtype=float32)
>>> mrc.header.dmax == mrc.data.max()
True

>>> # Now set a data array with a different shape, and check the header again
>>> mrc.set_data(data_3d)
>>> mrc.data.shape
(2, 2, 5)
>>> mrc.header.nx
array(5, dtype=int32)
>>> mrc.header.nx == mrc.data.shape[\-1]
True

>>> # The data statistics are updated as well
>>> mrc.header.dmax
array(1000., dtype=float32)
>>> mrc.header.dmax == mrc.data.max()
True
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If the data array is modified in place, for example by editing values
or changing the shape or dtype attributes, the header will no longer be
correct:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> mrc.data.shape
(2, 2, 5)

>>> # Change the data shape in\-place and check the header
>>> mrc.data.shape = (5, 4)
>>> mrc.header.nx == mrc.data.shape[\-1]
False

>>> # We\(aqll also change some values and check the data statistics
>>> mrc.data[2:] = 0
>>> mrc.data.max()
0
>>> mrc.header.dmax == mrc.data.max()
False
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the header is deliberately not updated automatically except when
\fI\%set_data()\fP is called, so if you need to
override any of the automatic header values you can do.
.sp
To keep the header in sync with the data, three methods can be used to update
the header:
.INDENT 0.0
.IP \(bu 2
\fI\%update_header_from_data()\fP: This updates
the   header\(aqs dimension fields, mode, space group and machine stamp to be
consistent with the data array. Because it only inspects the data array\(aqs
attributes, this method is fast even for very large arrays.
.IP \(bu 2
\fI\%update_header_stats()\fP: This updates the
data statistics fields in the header (dmin, dmax, dmean and rms). This method
can be slow with large data arrays because it has to access the full contents
of the array.
.IP \(bu 2
\fI\%reset_header_stats()\fP: If the data values
have changed and the statistics fields are invalid, but the data array is
very large and you do not want to wait for \fBupdate_header_stats()\fP to run,
you can call this method to reset the header\(aqs statistics fields to indicate
that the values are undetermined.
.UNINDENT
.sp
The file we just saved had an invalid header, but of course, that\(aqs what\(aqs used
by \fBmrcfile\fP to work out how to read the file from disk! When we open the
file again, our change to the shape has disappeared:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)
>>> mrc.data.shape
(2, 2, 5)

>>> # Let\(aqs change the shape again, as we did before
>>> mrc.data.shape = (5, 4)
>>> mrc.header.nx == mrc.data.shape[\-1]
False

>>> # Now let\(aqs update the dimensions:
>>> mrc.update_header_from_data()
>>> mrc.header.nx
array(4, dtype=int32)
>>> mrc.header.nx == mrc.data.shape[\-1]
True

>>> # The data statistics are still incorrect:
>>> mrc.header.dmax
array(1000., dtype=float32)
>>> mrc.header.dmax == mrc.data.max()
False

>>> # So let\(aqs update those as well:
>>> mrc.update_header_stats()
>>> mrc.header.dmax
array(0., dtype=float32)
>>> mrc.header.dmax == mrc.data.max()
True
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
In general, if you\(aqre changing the shape, type or endianness of the data, it\(aqs
easiest to use \fI\%set_data()\fP and the header
will be kept up to date for you. If you start changing values in the data,
remember that the statistics in the header will be out of date until you call
\fI\%update_header_stats()\fP or
\fI\%reset_header_stats()\fP\&.
.SS Data dimensionality
.sp
MRC files can be used to store several types of data: single images, image
stacks, volumes and volume stacks. These are distinguished by the
dimensionality of the data array and the space group number (the header\(aqs
\fBispg\fP field):
.TS
center;
|l|l|l|.
_
T{
Data type
T}	T{
Dimensions
T}	T{
Space group
T}
_
T{
Single image
T}	T{
2
T}	T{
0
T}
_
T{
Image stack
T}	T{
3
T}	T{
0
T}
_
T{
Volume
T}	T{
3
T}	T{
1\-\-230 (1 for normal EM data)
T}
_
T{
Volume stack
T}	T{
4
T}	T{
401\-\-630 (401 for normal EM data)
T}
_
.TE
.sp
\fI\%MrcFile\fP objects have methods to allow easy
identification of the data type:
\fI\%is_single_image()\fP,
\fI\%is_image_stack()\fP,
\fI\%is_volume()\fP and
\fI\%is_volume_stack()\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq)

>>> # The file currently contains two\-dimensional data
>>> mrc.data.shape
(5, 4)
>>> len(mrc.data.shape)
2

>>> # This is intepreted as a single image
>>> mrc.is_single_image()
True
>>> mrc.is_image_stack()
False
>>> mrc.is_volume()
False
>>> mrc.is_volume_stack()
False

>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a file already contains image or image stack data, new three\-dimensional
data is treated as an image stack; otherwise, 3D data is treated as a volume by
default:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # New 3D data in an existing image file is treated as an image stack:
>>> mrc.set_data(data_3d)
>>> len(mrc.data.shape)
3
>>> mrc.is_volume()
False
>>> mrc.is_image_stack()
True
>>> int(mrc.header.ispg)
0
>>> mrc.close()

>>> # But normally, 3D data is treated as a volume:
>>> mrc = mrcfile.new(\(aqtmp.mrc\(aq, overwrite=True)
>>> mrc.set_data(data_3d)
>>> mrc.is_volume()
True
>>> mrc.is_image_stack()
False
>>> int(mrc.header.ispg)
1
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Call \fI\%set_image_stack()\fP and
\fI\%set_volume()\fP to change the interpretation of
3D data. (Note: as well as changing \fBispg\fP, these methods also change \fBmz\fP
to be 1 for image stacks and equal to \fBnz\fP for volumes.)
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # Change the file to represent an image stack:
>>> mrc.set_image_stack()
>>> mrc.is_volume()
False
>>> mrc.is_image_stack()
True
>>> int(mrc.header.ispg)
0

>>> # And now change it back to representing a volume:
>>> mrc.set_volume()
>>> mrc.is_volume()
True
>>> mrc.is_image_stack()
False
>>> int(mrc.header.ispg)
1

>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the \fI\%MRC format\fP allows the data axes to be swapped using the
header\(aqs \fBmapc\fP, \fBmapr\fP and \fBmaps\fP fields. This library does not attempt
to swap the axes and simply assigns the columns to X, rows to Y and sections to
Z. (The data array is indexed in C style, so data values can be accessed using
\fBmrc.data[z][y][x]\fP\&.) In general, EM data is written using the default
axes, but crystallographic data files might use swapped axes in certain space
groups \-\- if this might matter to you, you should check the \fBmapc\fP, \fBmapr\fP
and \fBmaps\fP fields after opening the file and consider transposing the data
array if necessary.
.SS Data types
.sp
Various numpy \fI\%data types\fP can be used for MRC data arrays. The conversions to
MRC mode numbers are:
.TS
center;
|l|l|.
_
T{
Data type
T}	T{
MRC mode
T}
_
T{
float16
T}	T{
12 (see note below)
T}
_
T{
float32
T}	T{
2
T}
_
T{
int8
T}	T{
0
T}
_
T{
int16
T}	T{
1
T}
_
T{
uint8
T}	T{
6 (note that data will be widened to 16 bits in the file)
T}
_
T{
uint16
T}	T{
6
T}
_
T{
complex64
T}	T{
4
T}
_
.TE
.sp
(Mode 3 and the proposed 4\-bit mode 101 are not supported since there are no
corresponding numpy dtypes.)
.sp
Note that mode 12 is a proposed extension to the MRC2014 format and is not yet
widely supported by other software. If you need to write float16 data to MRC
files in a compatible way, you should cast to float32 first and use mode 2.
.sp
No other data types are accepted, including integer types of more than 16 bits,
or float types of more than 32 bits. Many numpy array creation routines use
int64 or float64 dtypes by default, which means you will need to give a
\fBdtype\fP argument to ensure the array can be used in an MRC file:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrc = mrcfile.open(\(aqtmp.mrc\(aq, mode=\(aqr+\(aq)

>>> # This does not work
>>> mrc.set_data(np.zeros((4, 5)))
Traceback (most recent call last):
  ...
ValueError: dtype \(aqfloat64\(aq cannot be converted to an MRC file mode
>>> # But this does
>>> mrc.set_data(np.zeros((4, 5), dtype=np.int16))
>>> mrc.data
array([[0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0]], dtype=int16)

>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Warning: be careful if you have an existing numpy array in float64, int64 or
int32 data types. If they try to convert them into one of the narrower types
supported by \fBmrcfile\fP and they contain values outside the range of the
target type, the values will silently overflow. For floating point formats
this can lead to \fBinf\fP values, and with integers it can lead to entirely
meaningless values. A full discussion of this issue is outside the scope of
this guide; see the numpy documentation for more information.
.SS Dealing with large files
.sp
\fBmrcfile\fP provides two ways of improving performance when handling large
files: memory mapping and asynchronous (background) opening. \fI\%Memory mapping\fP
treats the file\(aqs data on disk as if it is already in memory, and only actually
loads the data in small chunks when it is needed. \fI\%Asynchronous opening\fP uses
a separate thread to open the file, allowing the main thread to carry on with
other work while the file is loaded from disk in parallel.
.sp
Which technique is better depends on what you intend to do with the file and
the characteristics of your computer, and it\(aqs usually worth testing both
approaches and seeing what works best for your particular task. In general,
memory mapping gives better performance when dealing with a single file,
particularly if the file is very large. If you need to process several files,
asynchronous opening can be faster because you can work on one file while
loading the next one.
.SS Memory\-mapped files
.sp
With very large files, it might be helpful to use the \fI\%mrcfile.mmap()\fP
function to open the file, which will open the data as a
\fI\%memory\-mapped numpy array\fP\&. The contents of the array
are only read from disk as needed, so this allows large files to be opened very
quickly. Parts of the data can then be read and written by slicing the array:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Let\(aqs make a new file to work with (only small for this example!)
>>> mrcfile.write(\(aqmaybe_large.mrc\(aq, example_data)

>>> # Open the file in memory\-mapped mode
>>> mrc = mrcfile.mmap(\(aqmaybe_large.mrc\(aq, mode=\(aqr+\(aq)
>>> # Now read part of the data by slicing
>>> mrc.data[1:3]
memmap([[ 4,  5,  6,  7],
        [ 8,  9, 10, 11]], dtype=int8)

>>> # Set some values by assigning to a slice
>>> mrc.data[1:3,1:3] = 0

>>> # Read the entire array \- with large files this might take a while!
>>> mrc.data[:]
memmap([[ 0,  1,  2,  3],
        [ 4,  0,  0,  7],
        [ 8,  0,  0, 11]], dtype=int8)
>>> mrc.close()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
To create new large, empty files quickly, use the \fI\%mrcfile.new_mmap()\fP
function. This creates an empty file with a given shape and data mode. An
optional fill value can be provided but filling a very large mmap array can
take a long time, so it\(aqs best to use this only when needed. If you plan to
fill the array with other data anyway, it\(aqs better to leave the fill value as
\fI\%None\fP\&. A typical use case would be to create a new file and then fill
it slice by slice:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Make a new, empty memory\-mapped MRC file
>>> mrc = mrcfile.new_mmap(\(aqmmap.mrc\(aq, shape=(3, 3, 4), mrc_mode=0)
>>> # Fill each slice with a different value
>>> for val in range(len(mrc.data)):
\&...     mrc.data[val] = val
\&...
>>> mrc.data[:]
memmap([[[0, 0, 0, 0],
         [0, 0, 0, 0],
         [0, 0, 0, 0]],

        [[1, 1, 1, 1],
         [1, 1, 1, 1],
         [1, 1, 1, 1]],

        [[2, 2, 2, 2],
         [2, 2, 2, 2],
         [2, 2, 2, 2]]], dtype=int8)
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Asynchronous opening
.sp
When processing several files in a row, asynchronous (background) opening can
improve performance by allowing you to open multiple files in parallel. The
\fI\%mrcfile.open_async()\fP function starts a background thread to open a file,
and returns a \fI\%FutureMrcFile\fP object which you
can call later to get the file after it\(aqs been opened:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Open the first example file
>>> mrc1 = mrcfile.open(\(aqmaybe_large.mrc\(aq)
>>> # Start opening the second example file before we process the first
>>> future_mrc2 = mrcfile.open_async(\(aqtmp.mrc.gz\(aq)
>>> # Now we\(aqll do some calculations with the first file
>>> mrc1.data.sum()
36
>>> # Get the second file from its \(dqFuture\(dq container (\(aqresult()\(aq will wait
>>> # until the file is ready)
>>> mrc2 = future_mrc2.result()
>>> # Before we process the second file, we\(aqll start the third one opening
>>> future_mrc3 = mrcfile.open_async(\(aqtmp.mrc.bz2\(aq)
>>> mrc2.data.max()
22
>>> # Finally, we\(aqll get the third file and process it
>>> mrc3 = future_mrc3.result()
>>> mrc3.data
array([[ 0,  3,  6,  9],
       [12, 15, 18, 21],
       [24, 27, 30, 33]], dtype=int8)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
As we saw in that example, calling
\fI\%result()\fP will give us the
\fI\%MrcFile\fP from the file opening operation. If the file
hasn\(aqt been fully opened yet,
\fI\%result()\fP will simply wait until
it\(aqs ready. To avoid waiting, call
\fI\%done()\fP to check if it\(aqs finished.
.SS Validating MRC files
.sp
MRC files can be validated with \fI\%mrcfile.validate()\fP, which prints an
explanation of what is happening and also returns \fI\%True\fP if the file is
valid or \fI\%False\fP otherwise:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrcfile.validate(\(aqtmp.mrc\(aq)
Checking if tmp.mrc is a valid MRC2014 file...
File appears to be valid.
True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This works equally well for gzip\- or bzip2\-compressed files:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> mrcfile.validate(\(aqtmp.mrc.gz\(aq)
Checking if tmp.mrc.gz is a valid MRC2014 file...
File appears to be valid.
True

>>> mrcfile.validate(\(aqtmp.mrc.bz2\(aq)
Checking if tmp.mrc.bz2 is a valid MRC2014 file...
File appears to be valid.
True
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Errors will cause messages to be printed to the console, and
\fI\%validate()\fP will return \fBFalse\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Let\(aqs make a file which is valid except for the header\(aqs mz value
>>> with mrcfile.new(\(aqtmp.mrc\(aq, overwrite=True) as mrc:
\&...     mrc.set_data(example_data)
\&...     mrc.header.mz = \-1
\&...

>>> # Now it should fail validation and print a helpful message
>>> mrcfile.validate(\(aqtmp.mrc\(aq)
Checking if tmp.mrc is a valid MRC2014 file...
Header field \(aqmz\(aq is negative
False
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
(More serious errors might also cause warnings to be printed to
\fI\%sys.stderr\fP\&.)
.sp
Normally, messages are printed to \fI\%sys.stdout\fP (as normal for Python
\fI\%print()\fP calls). \fI\%validate()\fP has an optional \fBprint_file\fP
argument which allows any text stream to be used for the output instead:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
>>> # Create a text stream to capture the output
>>> import io
>>> output = io.StringIO()

>>> # Now validate the file...
>>> mrcfile.validate(\(aqtmp.mrc\(aq, print_file=output)
False

>>> # ...and check the output separately
>>> print(output.getvalue().strip())
Checking if tmp.mrc is a valid MRC2014 file...
Header field \(aqmz\(aq is negative
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Behind the scenes, \fI\%mrcfile.validate()\fP opens the file in \fI\%permissive mode\fP
using \fI\%mrcfile.open()\fP and then calls
\fI\%MrcFile.validate()\fP\&. If you already
have an \fI\%MrcFile\fP open, you can call its
\fI\%validate()\fP method directly
to check the file \-\- but note that the file size test might be inaccurate
unless you call \fI\%flush()\fP first. To
ensure the file is completely valid, it\(aqs best to flush or close the file and
then validate it from scratch using \fI\%mrcfile.validate()\fP\&.
.sp
If you find that a file created with this library is invalid, and you haven\(aqt
altered anything in the header in a way that might cause problems, please file
a bug report on the \fI\%issue tracker\fP!
.SS Command line usage
.sp
Some \fBmrcfile\fP functionality is available directly from the command line,
via scripts that are installed along with the package, or in some cases by
running modules with \fBpython \-m\fP\&.
.sp
(If you\(aqve downloaded the source code instead of installing via \fBpip\fP, run
\fBpip install <path\-to\-mrcfile>\fP or \fBpython setup.py install\fP to make the
command line scripts available.)
.SS Validation
.sp
MRC files can be validated with the \fBmrcfile\-validate\fP script:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ mrcfile\-validate tests/test_data/EMD\-3197.map
Checking if tests/test_data/EMD\-3197.map is a valid MRC2014 file...
File does not declare MRC format version 20140 or 20141: nversion = 0

$ # Exit status is 1 if file is invalid
$ echo $?
1
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This script wraps the \fI\%mrcfile.validator\fP module, which can also be called
directly:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ python \-m mrcfile.validator valid_file.mrc
Checking if valid_file.mrc is a valid MRC2014 file...
File appears to be valid.
$ echo $?
0
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Multiple file names can be passed to either form of the command, and because
these commands call \fI\%mrcfile.validate()\fP behind the scenes, gzip\- and
bzip2\-compressed files can be validated as well:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ mrcfile\-validate valid_file_1.mrc valid_file_2.mrc.gz valid_file_3.mrc.bz2
Checking if valid_file_1.mrc is a valid MRC2014 file...
File appears to be valid.
Checking if valid_file_2.mrc is a valid MRC2014 file...
File appears to be valid.
Checking if valid_file_3.mrc is a valid MRC2014 file...
File appears to be valid.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Examining MRC headers
.sp
MRC file headers can be printed to the console with the \fBmrcfile\-header\fP
script:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ mrcfile\-header tests/test_data/EMD\-3197.map
MRC header for tests/test_data/EMD\-3197.map:
nx              : 20
ny              : 20
nz              : 20
mode            : 2
nxstart         : \-2
nystart         : 0
nzstart         : 0
mx              : 20
my              : 20
mz              : 20
cella           : (228.0, 228.0, 228.0)
cellb           : (90.0, 90.0, 90.0)
\&...
\&...
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Like \fBmrcfile\-validate\fP, this also works for multiple files. If you want to
access the same functionality from within Python, call
\fI\%print_header()\fP on an open
\fI\%MrcFile\fP object, or
\fI\%mrcfile.command_line.print_headers()\fP with a list of file names.
.SS API overview
.SS Class hierarchy
.sp
The following classes are provided by the mrcfile.py library:
.INDENT 0.0
.IP \(bu 2
\fI\%MrcObject\fP: Represents a generic MRC\-like data
object in memory, and provides header, extended header and data arrays and
methods for operating on them.
.IP \(bu 2
\fI\%MrcInterpreter\fP: Subclass of MrcObject that
can read and/or write its MRC data from arbitrary byte I/O streams
(including Python file objects).
.IP \(bu 2
\fI\%MrcFile\fP: Subclass of MrcInterpreter that opens a
file from disk to use as its I/O stream. This is the normal class used for
most interactions with MRC files.
.IP \(bu 2
\fI\%GzipMrcFile\fP: Reads and writes MRC data using
compressed gzip files.
.IP \(bu 2
\fI\%Bzip2MrcFile\fP: Reads and writes MRC data using
compressed bzip2 files.
.IP \(bu 2
\fI\%MrcMemmap\fP: Uses a memory\-mapped data array, for
fast random access to very large data files. MrcMemmap overrides various
parts of the MrcFile implementation to ensure that the memory\-mapped data
array is opened, closed and moved correctly when the data or extended header
array sizes are changed.
.UNINDENT
.SS MrcFile attributes and methods
.sp
Attributes:
.INDENT 0.0
.IP \(bu 2
\fI\%header\fP
.IP \(bu 2
\fI\%extended_header\fP
.IP \(bu 2
\fI\%data\fP
.IP \(bu 2
\fI\%voxel_size\fP
.UNINDENT
.sp
Methods:
.INDENT 0.0
.IP \(bu 2
\fI\%set_extended_header()\fP
.IP \(bu 2
\fI\%set_data()\fP
.IP \(bu 2
\fI\%is_single_image()\fP
.IP \(bu 2
\fI\%is_image_stack()\fP
.IP \(bu 2
\fI\%is_volume()\fP
.IP \(bu 2
\fI\%is_volume_stack()\fP
.IP \(bu 2
\fI\%set_image_stack()\fP
.IP \(bu 2
\fI\%set_volume()\fP
.IP \(bu 2
\fI\%update_header_from_data()\fP
.IP \(bu 2
\fI\%update_header_stats()\fP
.IP \(bu 2
\fI\%reset_header_stats()\fP
.IP \(bu 2
\fI\%print_header()\fP
.IP \(bu 2
\fI\%validate()\fP
.IP \(bu 2
\fI\%flush()\fP
.IP \(bu 2
\fI\%close()\fP
.UNINDENT
.SH SOURCE DOCUMENTATION
.SS mrcfile \-\- Main package
.SS mrcfile
.sp
A pure Python implementation of the MRC2014 file format.
.sp
For a full introduction and documentation, see \fI\%http://mrcfile.readthedocs.io/\fP
.SS Functions
.INDENT 0.0
.IP \(bu 2
\fI\%new()\fP: Create a new MRC file.
.IP \(bu 2
\fI\%open()\fP: Open an MRC file.
.IP \(bu 2
\fI\%open_async()\fP: Open an MRC file asynchronously.
.IP \(bu 2
\fI\%mmap()\fP: Open a memory\-mapped MRC file (fast for large files).
.IP \(bu 2
\fI\%new_mmap()\fP: Create a new empty memory\-mapped MRC file (fast for large files).
.IP \(bu 2
\fI\%validate()\fP: Validate an MRC file
.UNINDENT
.SS Basic usage
.sp
Examples assume that this package has been imported as \fBmrcfile\fP and numpy
has been imported as \fBnp\fP\&.
.sp
To open an MRC file and read a slice of data:
.sp
.nf
.ft C
>>> with mrcfile.open(\(aqtests/test_data/EMD\-3197.map\(aq) as mrc:
\&...     mrc.data[10,10]
\&...
array([ 2.58179283,  3.1406002 ,  3.64495397,  3.63812137,  3.61837363,
        4.0115056 ,  3.66981959,  2.07317996,  0.1251585 , \-0.87975615,
        0.12517013,  2.07319379,  3.66982722,  4.0115037 ,  3.61837196,
        3.6381247 ,  3.64495087,  3.14059472,  2.58178973,  1.92690361], dtype=float32)
.ft P
.fi
.sp
To create a new file with a 2D data array, and change some values:
.sp
.nf
.ft C
>>> with mrcfile.new(\(aqtmp.mrc\(aq) as mrc:
\&...     mrc.set_data(np.zeros((5, 5), dtype=np.int8))
\&...     mrc.data[1:4,1:4] = 10
\&...     mrc.data
\&...
array([[ 0,  0,  0,  0,  0],
       [ 0, 10, 10, 10,  0],
       [ 0, 10, 10, 10,  0],
       [ 0, 10, 10, 10,  0],
       [ 0,  0,  0,  0,  0]], dtype=int8)
.ft P
.fi
.SS Background
.sp
The MRC2014 format was described in the Journal of Structural Biology:
\fI\%http://dx.doi.org/10.1016/j.jsb.2015.04.002\fP
.sp
The format specification is available on the CCP\-EM website:
\fI\%http://www.ccpem.ac.uk/mrc_format/mrc2014.php\fP
.SS Members
.INDENT 0.0
.TP
.B mrcfile.new(name, data=None, compression=None, overwrite=False)
Create a new MRC file.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to use, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBdata\fP \-\- Data to put in the file, as a \fI\%numpy array\fP\&. The default is \fI\%None\fP, to create an empty
file.
.IP \(bu 2
\fBcompression\fP \-\- The compression format to use. Acceptable values are:
\fI\%None\fP (the default; for no compression), \fB\(aqgzip\(aq\fP or
\fB\(aqbzip2\(aq\fP\&.
It\(aqs good practice to name compressed files with an appropriate
extension (for example, \fB\&.mrc.gz\fP for gzip) but this is not
enforced.
.IP \(bu 2
\fBoverwrite\fP \-\- Flag to force overwriting of an existing file. If
\fI\%False\fP and a file of the same name already exists, the file
is not overwritten and an exception is raised.
.UNINDENT
.TP
.B Returns
An \fI\%MrcFile\fP object (or a
subclass of it if \fBcompression\fP is specified).
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the file already exists and overwrite is
    \fI\%False\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the compression format is not recognised.
.UNINDENT
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data array contains Inf or NaN values.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.open(name, mode=\(aqr\(aq, permissive=False, header_only=False)
Open an MRC file.
.sp
This function opens both normal and compressed MRC files. Supported
compression formats are: gzip, bzip2.
.sp
It is possible to use this function to create new MRC files (using mode
\fBw+\fP) but the \fI\%new()\fP function is more flexible.
.sp
This function offers a permissive read mode for attempting to open corrupt
or invalid files. In permissive mode, \fI\%warnings\fP are issued instead of
exceptions if problems with the file are encountered. See
\fI\%MrcInterpreter\fP or the
\fI\%usage guide\fP for more information.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBmode\fP \-\- The file mode to use. This should be one of the following: \fBr\fP
for read\-only, \fBr+\fP for read and write, or \fBw+\fP for a new empty
file. The default is \fBr\fP\&.
.IP \(bu 2
\fBpermissive\fP \-\- Read the file in permissive mode. The default is
\fI\%False\fP\&.
.IP \(bu 2
\fBheader_only\fP \-\- Only read the header (and extended header) from the file.
The default is \fI\%False\fP\&.
.UNINDENT
.TP
.B Returns
An \fI\%MrcFile\fP object (or a
\fI\%GzipMrcFile\fP object if the file is
gzipped).
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the mode is not one of \fBr\fP, \fBr+\fP or \fBw+\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the file is not a valid MRC file and
    \fBpermissive\fP is \fI\%False\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the mode is \fBw+\fP and the file already exists.
    (Call \fI\%new()\fP with \fBoverwrite=True\fP to deliberately overwrite
    an existing file.)
.IP \(bu 2
\fI\%OSError\fP \-\- If the mode is \fBr\fP or \fBr+\fP and the file does not
    exist.
.UNINDENT
.TP
.B Warns
.INDENT 7.0
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the file appears to be a valid MRC file but the data
block is longer than expected from the dimensions in the header.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the file is not a valid MRC file and \fBpermissive\fP
is \fI\%True\fP\&.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the header\(aqs \fBexttyp\fP field is set to a known
value but the extended header\(aqs size is not a multiple of the
number of bytes in the corresponding dtype.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.read(name)
Read an MRC file\(aqs data into a numpy array.
.sp
This is a convenience function to read the data from an MRC file when there is no
need for the file\(aqs header information. To read the headers as well, or if you need
access to an \fI\%MrcFile\fP object representing the file, use
\fI\%mrcfile.open()\fP instead.
.INDENT 7.0
.TP
.B Parameters
\fBname\fP \-\- The file name to read, as a string or \fI\%Path\fP\&.
.TP
.B Returns
A \fI\%numpy array\fP containing the data from the file.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.write(name, data=None, overwrite=False, voxel_size=None)
Write a new MRC file.
.sp
This is a convenience function to allow data to be quickly written to a file (with
optional compression) using just a single function call. However, there is no
control over the file\(aqs metadata except for optionally setting the voxel size. For
more control, or if you need access to an \fI\%MrcFile\fP object
representing the new file, use \fI\%mrcfile.new()\fP instead.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to use, as a string or \fI\%Path\fP\&. If the name
ends with \fB\&.gz\fP or \fB\&.bz2\fP, the file will be compressed using gzip or
bzip2 respectively.
.IP \(bu 2
\fBdata\fP \-\- Data to put in the file, as a \fI\%numpy array\fP\&. The default is \fI\%None\fP, to create an empty
file.
.IP \(bu 2
\fBoverwrite\fP \-\- Flag to force overwriting of an existing file. If
\fI\%False\fP and a file of the same name already exists, the file
is not overwritten and an exception is raised.
.IP \(bu 2
\fBvoxel_size\fP \-\- float | 3\-tuple
The voxel size to be written in the file header.
.UNINDENT
.TP
.B Raises
\fI\%ValueError\fP \-\- If the file already exists and overwrite is
    \fI\%False\fP\&.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data array contains Inf or NaN values.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.open_async(name, mode=\(aqr\(aq, permissive=False)
Open an MRC file asynchronously in a separate thread.
.sp
This allows a file to be opened in the background while the main thread
continues with other work. This can be a good way to improve performance if
the main thread is busy with intensive computation, but will be less
effective if the main thread is itself busy with disk I/O.
.sp
Multiple files can be opened in the background simultaneously. However,
this implementation is relatively crude; each call to this function will
start a new thread and immediately use it to start opening a file. If you
try to open many large files at the same time, performance will decrease as
all of the threads attempt to access the disk at once. You\(aqll also risk
running out of memory to store the data from all the files.
.sp
This function returns a \fI\%FutureMrcFile\fP
object, which deliberately mimics the API of the
\fI\%Future\fP object from Python 3\(aqs
\fI\%concurrent.futures\fP module. (Future versions of this library might
return genuine \fI\%Future\fP objects instead.)
.sp
To get the real \fI\%MrcFile\fP object from a
\fI\%FutureMrcFile\fP, call
\fI\%result()\fP\&. This will block until
the file has been read and the \fI\%MrcFile\fP object is
ready. To check if the \fI\%MrcFile\fP is ready without
blocking, call \fI\%running()\fP or
\fI\%done()\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBmode\fP \-\- The file mode (one of \fBr\fP, \fBr+\fP or \fBw+\fP).
.IP \(bu 2
\fBpermissive\fP \-\- Read the file in permissive mode. The default is
\fI\%False\fP\&.
.UNINDENT
.TP
.B Returns
A \fI\%FutureMrcFile\fP object.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.mmap(name, mode=\(aqr\(aq, permissive=False)
Open a memory\-mapped MRC file.
.sp
This allows much faster opening of large files, because the data is only
accessed on disk when a slice is read or written from the data array. See
the \fI\%MrcMemmap\fP class documentation for more
information.
.sp
Because the memory\-mapped data array accesses the disk directly, compressed
files cannot be opened with this function. In all other ways, \fI\%mmap()\fP
behaves in exactly the same way as \fI\%open()\fP\&. The
\fI\%MrcMemmap\fP object returned by this function can
be used in exactly the same way as a normal
\fI\%MrcFile\fP object.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBmode\fP \-\- The file mode (one of \fBr\fP, \fBr+\fP or \fBw+\fP).
.IP \(bu 2
\fBpermissive\fP \-\- Read the file in permissive mode. The default is
\fI\%False\fP\&.
.UNINDENT
.TP
.B Returns
An \fI\%MrcMemmap\fP object.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.new_mmap(name, shape, mrc_mode=0, fill=None, overwrite=False, extended_header=None, exttyp=None)
Create a new, empty memory\-mapped MRC file.
.sp
This function is useful for creating very large files. The initial contents
of the data array can be set with the \fBfill\fP parameter if needed, but be
aware that filling a large array can take a long time.
.sp
If \fBfill\fP is not set, the new data array\(aqs contents are unspecified and
system\-dependent. (Some systems fill a new empty mmap with zeros, others
fill it with the bytes from the disk at the newly\-mapped location.) If you
are definitely going to fill the entire array with new data anyway you can
safely leave \fBfill\fP as \fI\%None\fP, otherwise it is advised to use a
sensible fill value (or ensure you are on a system that fills new mmaps
with a reasonable default value).
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to use, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBshape\fP \-\- The shape of the data array to open, as a 2\-, 3\- or 4\-tuple of
ints. For example, \fB(nz, ny, nx)\fP for a new 3D volume, or
\fB(ny, nx)\fP for a new 2D image.
.IP \(bu 2
\fBmrc_mode\fP \-\- 
.sp
The MRC mode to use for the new file. One of 0, 1, 2, 4 or 6,
which correspond to numpy dtypes as follows:
.INDENT 2.0
.IP \(bu 2
mode 0 \-> int8
.IP \(bu 2
mode 1 \-> int16
.IP \(bu 2
mode 2 \-> float32
.IP \(bu 2
mode 4 \-> complex64
.IP \(bu 2
mode 6 \-> uint16
.UNINDENT
.sp
The default is 0.

.IP \(bu 2
\fBfill\fP \-\- An optional value to use to fill the new data array. If
\fI\%None\fP, the data array will not be filled and its contents
are unspecified. Numpy\(aqs usual rules for rounding or rejecting
values apply, according to the dtype of the array.
.IP \(bu 2
\fBoverwrite\fP \-\- Flag to force overwriting of an existing file. If
\fI\%False\fP and a file of the same name already exists, the file
is not overwritten and an exception is raised.
.IP \(bu 2
\fBextended_header\fP \-\- The extended header object
.IP \(bu 2
\fBexttyp\fP \-\- The extended header type
.UNINDENT
.TP
.B Returns
A new \fI\%MrcMemmap\fP object.
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the MRC mode is invalid.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the file already exists and overwrite is
    \fI\%False\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.validate(name, print_file=None)
Validate an MRC file.
.sp
This function first opens the file by calling \fI\%open()\fP (with
\fBpermissive=True\fP), then calls \fI\%validate()\fP,
which runs a series of tests to check whether the file complies with the
MRC2014 format specification.
.sp
If the file is completely valid, this function returns \fI\%True\fP,
otherwise it returns \fI\%False\fP\&. Messages explaining the validation
result will be printed to \fI\%sys.stdout\fP by default, but if a text
stream is given (using the \fBprint_file\fP argument) output will be printed
to that instead.
.sp
Badly invalid files will also cause \fI\%warning\fP messages to
be issued, which will be written to \fI\%sys.stderr\fP by default. See the
documentation of the \fI\%warnings\fP module for information on how to
suppress or capture warning output.
.sp
Because the file is opened by calling \fI\%open()\fP, gzip\- and
bzip2\-compressed MRC files can be validated easily using this function.
.sp
After the file has been opened, it is checked for problems. The tests are:
.INDENT 7.0
.IP 1. 4
MRC format ID string: The \fBmap\fP field in the header should contain
\(dqMAP \(dq.
.IP 2. 4
Machine stamp: The machine stamp should contain one of
\fB0x44 0x44 0x00 0x00\fP, \fB0x44 0x41 0x00 0x00\fP or
\fB0x11 0x11 0x00 0x00\fP\&.
.IP 3. 4
MRC mode: the \fBmode\fP field should be one of the supported mode
numbers: 0, 1, 2, 4, 6 or 12. (Note that MRC modes 3 and 101 are also
valid according to the MRC 2014 specification but are not supported by
mrcfile.)
.IP 4. 4
Map and cell dimensions: The header fields \fBnx\fP, \fBny\fP, \fBnz\fP,
\fBmx\fP, \fBmy\fP, \fBmz\fP, \fBcella.x\fP, \fBcella.y\fP and \fBcella.z\fP must
all be positive numbers.
.IP 5. 4
Axis mapping: Header fields \fBmapc\fP, \fBmapr\fP and \fBmaps\fP must contain
the values 1, 2, and 3 (in any order).
.IP 6. 4
Volume stack dimensions: If the spacegroup is in the range 401\-\-630,
representing a volume stack, the \fBnz\fP field should be exactly
divisible by \fBmz\fP to represent the number of volumes in the stack.
.IP 7. 4
Header labels: The \fBnlabl\fP field should be set to indicate the number
of labels in use, and the labels in use should appear first in the label
array.
.IP 8. 4
MRC format version: The \fBnversion\fP field should be 20140 or 20141 for
compliance with the MRC2014 standard.
.IP 9. 4
Extended header type: If an extended header is present, the \fBexttyp\fP
field should be set to indicate the type of extended header.
.IP 10. 4
Data statistics: The statistics in the header should be correct for the
actual data in the file, or marked as undetermined.
.IP 11. 4
File size: The size of the file on disk should match the expected size
calculated from the MRC header.
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open and validate.
.IP \(bu 2
\fBprint_file\fP \-\- The output text stream to use for printing messages about
the validation. This is passed directly to the \fBfile\fP argument of
Python\(aqs \fI\%print()\fP function. The default is \fI\%None\fP, which
means output will be printed to \fI\%sys.stdout\fP\&.
.UNINDENT
.TP
.B Returns
\fI\%True\fP if the file is valid, or \fI\%False\fP if the file does
not meet the MRC format specification in any way.
.TP
.B Raises
\fI\%OSError\fP \-\- If the file does not exist or cannot be opened.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the file is seriously invalid because it has no map
ID string, an incorrect machine stamp, an unknown mode number, or
is not the same size as expected from the header.
.UNINDENT
.UNINDENT
.SS Submodules
.SS mrcfile.bzip2mrcfile module
.SS bzip2mrcfile
.sp
Module which exports the \fI\%Bzip2MrcFile\fP class.
.INDENT 0.0
.TP
.B Classes:
\fI\%Bzip2MrcFile\fP: An object which represents a bzip2\-compressed MRC
file.
.UNINDENT
.INDENT 0.0
.TP
.B class  mrcfile.bzip2mrcfile.Bzip2MrcFile(name, mode=\(aqr\(aq, overwrite=False, permissive=False, header_only=False, **kwargs)
Bases: \fI\%MrcFile\fP
.sp
\fI\%MrcFile\fP subclass for handling bzip2\-compressed
files.
.sp
Usage is the same as for \fI\%MrcFile\fP\&.
.INDENT 7.0
.TP
.B _open_file(name)
Override _open_file() to open a bzip2 file.
.UNINDENT
.INDENT 7.0
.TP
.B _read(header_only=False)
Override _read() to ensure bzip2 file is in read mode.
.UNINDENT
.INDENT 7.0
.TP
.B _ensure_readable_bzip2_stream()
Make sure _iostream is a bzip2 stream that can be read.
.UNINDENT
.INDENT 7.0
.TP
.B _get_file_size()
Override _get_file_size() to ensure stream is readable first.
.UNINDENT
.INDENT 7.0
.TP
.B _read_bytearray_from_stream(number_of_bytes)
Override because BZ2File in Python 2 does not support
\fI\%readinto()\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B flush()
Override \fI\%flush()\fP since
BZ2File objects need special handling.
.UNINDENT
.UNINDENT
.SS mrcfile.command_line module
.SS command_line
.sp
Module for functions used as command line entry points.
.sp
The names of the corresponding command line scripts can be found in the
\fBentry_points\fP section of \fBsetup.py\fP\&.
.INDENT 0.0
.TP
.B mrcfile.command_line.print_headers(names=None, print_file=None)
Print the MRC header contents from a list of files.
.sp
This function opens files in permissive mode to allow headers of invalid
files to be examined.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBnames\fP \-\- A list of file names. If not given or \fI\%None\fP, the names
are taken from the command line arguments.
.IP \(bu 2
\fBprint_file\fP \-\- The output text stream to use for printing the headers.
This is passed directly to the \fBprint_file\fP argument of
\fI\%print_header()\fP\&. The default is
\fI\%None\fP, which means output will be printed to
\fI\%sys.stdout\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS mrcfile.constants module
.SS constants
.sp
Constants used by the \fBmrcfile.py\fP library.
.SS mrcfile.dtypes module
.SS dtypes
.sp
numpy dtypes used by the \fBmrcfile.py\fP library.
.sp
The dtypes are defined in a separate module because they do not interact nicely
with the \fBfrom __future__ import unicode_literals\fP feature used in the rest
of the package.
.INDENT 0.0
.TP
.B mrcfile.dtypes.get_ext_header_dtype(exttyp, byte_order=\(aq=\(aq)
Get a dtype for an extended header.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBexttyp\fP \-\- One of \fBb\(aqFEI1\(aq\fP or \fBb\(aqFEI2\(aq\fP, which are currently the only
supported extended header types.
.IP \(bu 2
\fBbyte_order\fP \-\- One of \fB=\fP, \fB<\fP or \fB>\fP\&.
.UNINDENT
.TP
.B Returns
A \fI\%numpy dtype\fP object for the extended header, or
\fI\%None\fP
.TP
.B Raises
\fI\%ValueError\fP \-\- If \fBbyte_order\fP is not one of \fB=\fP, \fB<\fP or \fB>\fP\&.
.UNINDENT
.UNINDENT
.SS mrcfile.future_mrcfile module
.SS future_mrcfile
.sp
Module which exports the \fI\%FutureMrcFile\fP class.
.INDENT 0.0
.TP
.B Classes:
.INDENT 7.0
.TP
.B \fI\%FutureMrcFile\fP: An object which represents an MRC file being
opened asynchronously.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B class  mrcfile.future_mrcfile.FutureMrcFile(open_function, args=(), kwargs={})
Bases: \fI\%object\fP
.sp
Object representing an MRC file being opened asynchronously.
.sp
This API deliberately mimics a \fI\%Future\fP object
from the \fI\%concurrent.futures\fP module in Python 3.2+ (which we do
not use directly because this code still needs to run in Python 2.7).
.INDENT 7.0
.TP
.B __init__(open_function, args=(), kwargs={})
Initialise a new \fI\%FutureMrcFile\fP object.
.sp
This constructor starts a new thread which will invoke the callable
given in \fBopen_function\fP with the given arguments.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBopen_function\fP \-\- The callable to use to open the MRC file. (This will
normally be \fI\%mrcfile.open()\fP, but could also be
\fI\%MrcFile\fP or any of its subclasses.)
.IP \(bu 2
\fBargs\fP \-\- A tuple of positional arguments to use when \fBopen_function\fP
is called. (Normally a 1\-tuple containing the name of the file
to open.)
.IP \(bu 2
\fBkwargs\fP \-\- A dictionary of keyword arguments to use when
\fBopen_function\fP is called.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _run(*args, **kwargs)
Call the open function and store the result in the holder list.
.sp
(For internal use only.)
.UNINDENT
.INDENT 7.0
.TP
.B cancel()
Return \fI\%False\fP\&.
.sp
(See \fI\%concurrent.futures.Future.cancel()\fP for more details. This
implementation does not allow jobs to be cancelled.)
.UNINDENT
.INDENT 7.0
.TP
.B cancelled()
Return \fI\%False\fP\&.
.sp
(See \fI\%concurrent.futures.Future.cancelled()\fP for more details.
This implementation does not allow jobs to be cancelled.)
.UNINDENT
.INDENT 7.0
.TP
.B running()
Return \fI\%True\fP if the \fI\%MrcFile\fP is
currently being opened.
.sp
(See \fI\%concurrent.futures.Future.running()\fP for more details.)
.UNINDENT
.INDENT 7.0
.TP
.B done()
Return \fI\%True\fP if the file opening has finished.
.sp
(See \fI\%concurrent.futures.Future.done()\fP for more details.)
.UNINDENT
.INDENT 7.0
.TP
.B result(timeout=None)
Return the \fI\%MrcFile\fP that has been opened.
.sp
(See \fI\%concurrent.futures.Future.result()\fP for more details.)
.INDENT 7.0
.TP
.B Parameters
\fBtimeout\fP \-\- Time to wait (in seconds) for the file opening to finish.
If \fBtimeout\fP is not specified or is \fI\%None\fP, there is no
limit to the wait time.
.TP
.B Returns
An \fI\%MrcFile\fP object (or one of its
subclasses).
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%RuntimeError\fP \-\- If the operation has not finished within the
    time limit set by \fBtimeout\fP\&. (Note that the type of this
    exception will change in future if this class is replaced by
    \fI\%concurrent.futures.Future\fP\&.)
.IP \(bu 2
\fI\%Exception\fP \-\- Any exception raised by the
    \fI\%MrcFile\fP opening operation will be
    re\-raised here.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B exception(timeout=None)
Return the exception raised by the file opening operation.
.sp
(See \fI\%concurrent.futures.Future.exception()\fP for more details.)
.INDENT 7.0
.TP
.B Parameters
\fBtimeout\fP \-\- Time to wait (in seconds) for the operation to finish. If
\fBtimeout\fP is not specified or is \fI\%None\fP, there is no
limit to the wait time.
.TP
.B Returns
An \fI\%Exception\fP, if one was raised by the file opening
operation, or \fI\%None\fP if no exception was raised.
.TP
.B Raises
\fI\%RuntimeError\fP \-\- If the operation has not finished within the
    time limit set by \fBtimeout\fP\&. (Note that the type of this
    exception will change in future if this class is replaced by
    \fI\%concurrent.futures.Future\fP\&.)
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _get_result(timeout)
Return the result or exception from the file opening operation.
.sp
(For internal use only.)
.UNINDENT
.INDENT 7.0
.TP
.B add_done_callback(fn)
Not implemented.
.sp
(See \fI\%concurrent.futures.Future.add_done_callback()\fP for more details.)
.UNINDENT
.UNINDENT
.SS mrcfile.gzipmrcfile module
.SS gzipmrcfile
.sp
Module which exports the \fI\%GzipMrcFile\fP class.
.INDENT 0.0
.TP
.B Classes:
\fI\%GzipMrcFile\fP: An object which represents a gzipped MRC file.
.UNINDENT
.INDENT 0.0
.TP
.B class  mrcfile.gzipmrcfile.GzipMrcFile(name, mode=\(aqr\(aq, overwrite=False, permissive=False, header_only=False, **kwargs)
Bases: \fI\%MrcFile\fP
.sp
\fI\%MrcFile\fP subclass for handling gzipped files.
.sp
Usage is the same as for \fI\%MrcFile\fP\&.
.INDENT 7.0
.TP
.B _open_file(name)
Override _open_file() to open both normal and gzip files.
.UNINDENT
.INDENT 7.0
.TP
.B _close_file()
Override _close_file() to close both normal and gzip files.
.UNINDENT
.INDENT 7.0
.TP
.B _read(header_only=False)
Override _read() to ensure gzip file is in read mode.
.UNINDENT
.INDENT 7.0
.TP
.B _ensure_readable_gzip_stream()
Make sure _iostream is a gzip stream that can be read.
.UNINDENT
.INDENT 7.0
.TP
.B _get_file_size()
Override _get_file_size() to avoid seeking from end.
.UNINDENT
.INDENT 7.0
.TP
.B flush()
Override \fI\%flush()\fP since
GzipFile objects need special handling.
.UNINDENT
.UNINDENT
.SS mrcfile.load_functions module
.SS load_functions
.sp
Module for top\-level functions that open MRC files and form the main API of
the package.
.INDENT 0.0
.TP
.B mrcfile.load_functions.new(name, data=None, compression=None, overwrite=False)
Create a new MRC file.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to use, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBdata\fP \-\- Data to put in the file, as a \fI\%numpy array\fP\&. The default is \fI\%None\fP, to create an empty
file.
.IP \(bu 2
\fBcompression\fP \-\- The compression format to use. Acceptable values are:
\fI\%None\fP (the default; for no compression), \fB\(aqgzip\(aq\fP or
\fB\(aqbzip2\(aq\fP\&.
It\(aqs good practice to name compressed files with an appropriate
extension (for example, \fB\&.mrc.gz\fP for gzip) but this is not
enforced.
.IP \(bu 2
\fBoverwrite\fP \-\- Flag to force overwriting of an existing file. If
\fI\%False\fP and a file of the same name already exists, the file
is not overwritten and an exception is raised.
.UNINDENT
.TP
.B Returns
An \fI\%MrcFile\fP object (or a
subclass of it if \fBcompression\fP is specified).
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the file already exists and overwrite is
    \fI\%False\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the compression format is not recognised.
.UNINDENT
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data array contains Inf or NaN values.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.load_functions.open(name, mode=\(aqr\(aq, permissive=False, header_only=False)
Open an MRC file.
.sp
This function opens both normal and compressed MRC files. Supported
compression formats are: gzip, bzip2.
.sp
It is possible to use this function to create new MRC files (using mode
\fBw+\fP) but the \fI\%new()\fP function is more flexible.
.sp
This function offers a permissive read mode for attempting to open corrupt
or invalid files. In permissive mode, \fI\%warnings\fP are issued instead of
exceptions if problems with the file are encountered. See
\fI\%MrcInterpreter\fP or the
\fI\%usage guide\fP for more information.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBmode\fP \-\- The file mode to use. This should be one of the following: \fBr\fP
for read\-only, \fBr+\fP for read and write, or \fBw+\fP for a new empty
file. The default is \fBr\fP\&.
.IP \(bu 2
\fBpermissive\fP \-\- Read the file in permissive mode. The default is
\fI\%False\fP\&.
.IP \(bu 2
\fBheader_only\fP \-\- Only read the header (and extended header) from the file.
The default is \fI\%False\fP\&.
.UNINDENT
.TP
.B Returns
An \fI\%MrcFile\fP object (or a
\fI\%GzipMrcFile\fP object if the file is
gzipped).
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the mode is not one of \fBr\fP, \fBr+\fP or \fBw+\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the file is not a valid MRC file and
    \fBpermissive\fP is \fI\%False\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the mode is \fBw+\fP and the file already exists.
    (Call \fI\%new()\fP with \fBoverwrite=True\fP to deliberately overwrite
    an existing file.)
.IP \(bu 2
\fI\%OSError\fP \-\- If the mode is \fBr\fP or \fBr+\fP and the file does not
    exist.
.UNINDENT
.TP
.B Warns
.INDENT 7.0
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the file appears to be a valid MRC file but the data
block is longer than expected from the dimensions in the header.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the file is not a valid MRC file and \fBpermissive\fP
is \fI\%True\fP\&.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the header\(aqs \fBexttyp\fP field is set to a known
value but the extended header\(aqs size is not a multiple of the
number of bytes in the corresponding dtype.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.load_functions.read(name)
Read an MRC file\(aqs data into a numpy array.
.sp
This is a convenience function to read the data from an MRC file when there is no
need for the file\(aqs header information. To read the headers as well, or if you need
access to an \fI\%MrcFile\fP object representing the file, use
\fI\%mrcfile.open()\fP instead.
.INDENT 7.0
.TP
.B Parameters
\fBname\fP \-\- The file name to read, as a string or \fI\%Path\fP\&.
.TP
.B Returns
A \fI\%numpy array\fP containing the data from the file.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.load_functions.write(name, data=None, overwrite=False, voxel_size=None)
Write a new MRC file.
.sp
This is a convenience function to allow data to be quickly written to a file (with
optional compression) using just a single function call. However, there is no
control over the file\(aqs metadata except for optionally setting the voxel size. For
more control, or if you need access to an \fI\%MrcFile\fP object
representing the new file, use \fI\%mrcfile.new()\fP instead.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to use, as a string or \fI\%Path\fP\&. If the name
ends with \fB\&.gz\fP or \fB\&.bz2\fP, the file will be compressed using gzip or
bzip2 respectively.
.IP \(bu 2
\fBdata\fP \-\- Data to put in the file, as a \fI\%numpy array\fP\&. The default is \fI\%None\fP, to create an empty
file.
.IP \(bu 2
\fBoverwrite\fP \-\- Flag to force overwriting of an existing file. If
\fI\%False\fP and a file of the same name already exists, the file
is not overwritten and an exception is raised.
.IP \(bu 2
\fBvoxel_size\fP \-\- float | 3\-tuple
The voxel size to be written in the file header.
.UNINDENT
.TP
.B Raises
\fI\%ValueError\fP \-\- If the file already exists and overwrite is
    \fI\%False\fP\&.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data array contains Inf or NaN values.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.load_functions.open_async(name, mode=\(aqr\(aq, permissive=False)
Open an MRC file asynchronously in a separate thread.
.sp
This allows a file to be opened in the background while the main thread
continues with other work. This can be a good way to improve performance if
the main thread is busy with intensive computation, but will be less
effective if the main thread is itself busy with disk I/O.
.sp
Multiple files can be opened in the background simultaneously. However,
this implementation is relatively crude; each call to this function will
start a new thread and immediately use it to start opening a file. If you
try to open many large files at the same time, performance will decrease as
all of the threads attempt to access the disk at once. You\(aqll also risk
running out of memory to store the data from all the files.
.sp
This function returns a \fI\%FutureMrcFile\fP
object, which deliberately mimics the API of the
\fI\%Future\fP object from Python 3\(aqs
\fI\%concurrent.futures\fP module. (Future versions of this library might
return genuine \fI\%Future\fP objects instead.)
.sp
To get the real \fI\%MrcFile\fP object from a
\fI\%FutureMrcFile\fP, call
\fI\%result()\fP\&. This will block until
the file has been read and the \fI\%MrcFile\fP object is
ready. To check if the \fI\%MrcFile\fP is ready without
blocking, call \fI\%running()\fP or
\fI\%done()\fP\&.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBmode\fP \-\- The file mode (one of \fBr\fP, \fBr+\fP or \fBw+\fP).
.IP \(bu 2
\fBpermissive\fP \-\- Read the file in permissive mode. The default is
\fI\%False\fP\&.
.UNINDENT
.TP
.B Returns
A \fI\%FutureMrcFile\fP object.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.load_functions.mmap(name, mode=\(aqr\(aq, permissive=False)
Open a memory\-mapped MRC file.
.sp
This allows much faster opening of large files, because the data is only
accessed on disk when a slice is read or written from the data array. See
the \fI\%MrcMemmap\fP class documentation for more
information.
.sp
Because the memory\-mapped data array accesses the disk directly, compressed
files cannot be opened with this function. In all other ways, \fI\%mmap()\fP
behaves in exactly the same way as \fI\%open()\fP\&. The
\fI\%MrcMemmap\fP object returned by this function can
be used in exactly the same way as a normal
\fI\%MrcFile\fP object.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBmode\fP \-\- The file mode (one of \fBr\fP, \fBr+\fP or \fBw+\fP).
.IP \(bu 2
\fBpermissive\fP \-\- Read the file in permissive mode. The default is
\fI\%False\fP\&.
.UNINDENT
.TP
.B Returns
An \fI\%MrcMemmap\fP object.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.load_functions.new_mmap(name, shape, mrc_mode=0, fill=None, overwrite=False, extended_header=None, exttyp=None)
Create a new, empty memory\-mapped MRC file.
.sp
This function is useful for creating very large files. The initial contents
of the data array can be set with the \fBfill\fP parameter if needed, but be
aware that filling a large array can take a long time.
.sp
If \fBfill\fP is not set, the new data array\(aqs contents are unspecified and
system\-dependent. (Some systems fill a new empty mmap with zeros, others
fill it with the bytes from the disk at the newly\-mapped location.) If you
are definitely going to fill the entire array with new data anyway you can
safely leave \fBfill\fP as \fI\%None\fP, otherwise it is advised to use a
sensible fill value (or ensure you are on a system that fills new mmaps
with a reasonable default value).
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to use, as a string or \fI\%Path\fP\&.
.IP \(bu 2
\fBshape\fP \-\- The shape of the data array to open, as a 2\-, 3\- or 4\-tuple of
ints. For example, \fB(nz, ny, nx)\fP for a new 3D volume, or
\fB(ny, nx)\fP for a new 2D image.
.IP \(bu 2
\fBmrc_mode\fP \-\- 
.sp
The MRC mode to use for the new file. One of 0, 1, 2, 4 or 6,
which correspond to numpy dtypes as follows:
.INDENT 2.0
.IP \(bu 2
mode 0 \-> int8
.IP \(bu 2
mode 1 \-> int16
.IP \(bu 2
mode 2 \-> float32
.IP \(bu 2
mode 4 \-> complex64
.IP \(bu 2
mode 6 \-> uint16
.UNINDENT
.sp
The default is 0.

.IP \(bu 2
\fBfill\fP \-\- An optional value to use to fill the new data array. If
\fI\%None\fP, the data array will not be filled and its contents
are unspecified. Numpy\(aqs usual rules for rounding or rejecting
values apply, according to the dtype of the array.
.IP \(bu 2
\fBoverwrite\fP \-\- Flag to force overwriting of an existing file. If
\fI\%False\fP and a file of the same name already exists, the file
is not overwritten and an exception is raised.
.IP \(bu 2
\fBextended_header\fP \-\- The extended header object
.IP \(bu 2
\fBexttyp\fP \-\- The extended header type
.UNINDENT
.TP
.B Returns
A new \fI\%MrcMemmap\fP object.
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the MRC mode is invalid.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the file already exists and overwrite is
    \fI\%False\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.SS mrcfile.mrcfile module
.SS mrcfile
.sp
Module which exports the \fI\%MrcFile\fP class.
.INDENT 0.0
.TP
.B Classes:
\fI\%MrcFile\fP: An object which represents an MRC file.
.UNINDENT
.INDENT 0.0
.TP
.B class  mrcfile.mrcfile.MrcFile(name, mode=\(aqr\(aq, overwrite=False, permissive=False, header_only=False, **kwargs)
Bases: \fI\%MrcInterpreter\fP
.sp
An object which represents an MRC file.
.sp
The header and data are handled as numpy arrays \- see
\fI\%MrcObject\fP for details.
.sp
\fI\%MrcFile\fP supports a permissive read mode for attempting to open
corrupt or invalid files. See
\fI\%mrcfile.mrcinterpreter.MrcInterpreter\fP or the \fI\%usage guide\fP for more information.
.INDENT 7.0
.TP
.B Usage:
To create a new MrcFile object, pass a file name and optional mode. To
ensure the file is written to disk and closed correctly, it\(aqs best to
use the \fI\%with\fP statement:
.sp
.nf
.ft C
>>> with MrcFile(\(aqtmp.mrc\(aq, \(aqw+\(aq) as mrc:
\&...     mrc.set_data(np.zeros((10, 10), dtype=np.int8))
.ft P
.fi
.sp
In mode \fBr\fP or \fBr+\fP, the named file is opened from disk and read.
In mode \fBw+\fP a new empty file is created and will be written to disk
at the end of the \fI\%with\fP block (or when
\fI\%flush()\fP or \fI\%close()\fP is called).
.UNINDENT
.INDENT 7.0
.TP
.B __init__(name, mode=\(aqr\(aq, overwrite=False, permissive=False, header_only=False, **kwargs)
Initialise a new \fI\%MrcFile\fP object.
.sp
The given file name is opened in the given mode. For mode \fBr\fP or
\fBr+\fP the header, extended header and data are read from the file. For
mode \fBw+\fP a new file is created with a default header and empty
extended header and data arrays.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open, as a string or pathlib Path.
.IP \(bu 2
\fBmode\fP \-\- The file mode to use. This should be one of the following:
\fBr\fP for read\-only, \fBr+\fP for read and write, or \fBw+\fP for a
new empty file. The default is \fBr\fP\&.
.IP \(bu 2
\fBoverwrite\fP \-\- Flag to force overwriting of an existing file if the
mode is \fBw+\fP\&. If \fI\%False\fP and a file of the same name
already exists, the file is not overwritten and an exception is
raised. The default is \fI\%False\fP\&.
.IP \(bu 2
\fBpermissive\fP \-\- Read the file in permissive mode. (See
\fI\%mrcfile.mrcinterpreter.MrcInterpreter\fP for details.)
The default is \fI\%False\fP\&.
.IP \(bu 2
\fBheader_only\fP \-\- Only read the header (and extended header) from the
file. The default is \fI\%False\fP\&.
.UNINDENT
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the mode is not one of \fBr\fP, \fBr+\fP or
    \fBw+\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the file is not a valid MRC file and
    \fBpermissive\fP is \fI\%False\fP\&.
.IP \(bu 2
\fI\%ValueError\fP \-\- If the mode is \fBw+\fP, the file already exists
    and overwrite is \fI\%False\fP\&.
.IP \(bu 2
\fI\%OSError\fP \-\- If the mode is \fBr\fP or \fBr+\fP and the file does
    not exist.
.UNINDENT
.TP
.B Warns
.INDENT 7.0
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the file appears to be a valid MRC file but the
data block is longer than expected from the dimensions in the
header.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the file is not a valid MRC file and
\fBpermissive\fP is \fI\%True\fP\&.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the header\(aqs \fBexttyp\fP field is set to a known
value but the extended header\(aqs size is not a multiple of the
number of bytes in the corresponding dtype.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _open_file(name)
Open a file object to use as the I/O stream.
.UNINDENT
.INDENT 7.0
.TP
.B _read(header_only=False)
Override _read() to move back to start of file first.
.UNINDENT
.INDENT 7.0
.TP
.B _read_data()
Override _read_data() to check file size matches data block size.
.UNINDENT
.INDENT 7.0
.TP
.B _get_file_size()
Return the size of the underlying file object, in bytes.
.UNINDENT
.INDENT 7.0
.TP
.B close()
Flush any changes to disk and close the file.
.sp
This override calls \fI\%MrcInterpreter.close()\fP to ensure the stream
is flushed and closed, then closes the file object.
.UNINDENT
.INDENT 7.0
.TP
.B _close_file()
Close the file object.
.UNINDENT
.INDENT 7.0
.TP
.B validate(print_file=None)
Validate this MRC file.
.sp
The tests are:
.INDENT 7.0
.IP 1. 4
MRC format ID string: The \fBmap\fP field in the header should
contain \(dqMAP \(dq.
.IP 2. 4
Machine stamp: The machine stamp should contain one of
\fB0x44 0x44 0x00 0x00\fP, \fB0x44 0x41 0x00 0x00\fP or
\fB0x11 0x11 0x00 0x00\fP\&.
.IP 3. 4
MRC mode: the \fBmode\fP field should be one of the supported mode
numbers: 0, 1, 2, 4, 6 or 12. (Note that MRC modes 3 and 101 are
also valid according to the MRC 2014 specification but are not
supported by mrcfile.)
.IP 4. 4
Map and cell dimensions: The header fields \fBnx\fP, \fBny\fP, \fBnz\fP,
\fBmx\fP, \fBmy\fP, \fBmz\fP, \fBcella.x\fP, \fBcella.y\fP and \fBcella.z\fP
must all be positive numbers.
.IP 5. 4
Axis mapping: Header fields \fBmapc\fP, \fBmapr\fP and \fBmaps\fP must
contain the values 1, 2, and 3 (in any order).
.IP 6. 4
Volume stack dimensions: If the spacegroup is in the range 401\-\-630,
representing a volume stack, the \fBnz\fP field should be exactly
divisible by \fBmz\fP to represent the number of volumes in the stack.
.IP 7. 4
Header labels: The \fBnlabl\fP field should be set to indicate the
number of labels in use, and the labels in use should appear first
in the label array.
.IP 8. 4
MRC format version: The \fBnversion\fP field should be 20140 or 20141
for compliance with the MRC2014 standard.
.IP 9. 4
Extended header type: If an extended header is present, the
\fBexttyp\fP field should be set to indicate the type of extended
header.
.IP 10. 4
Data statistics: The statistics in the header should be correct for
the actual data in the file, or marked as undetermined.
.IP 11. 4
File size: The size of the file on disk should match the expected
size calculated from the MRC header.
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBprint_file\fP \-\- The output text stream to use for printing messages
about the validation. This is passed directly to the \fBfile\fP
argument of Python\(aqs \fI\%print()\fP function. The default is
\fI\%None\fP, which means output will be printed to
\fI\%sys.stdout\fP\&.
.TP
.B Returns
\fI\%True\fP if the file is valid, or \fI\%False\fP if the file
does not meet the MRC format specification in any way.
.UNINDENT
.UNINDENT
.UNINDENT
.SS mrcfile.mrcinterpreter module
.SS mrcinterpreter
.sp
Module which exports the \fI\%MrcInterpreter\fP class.
.INDENT 0.0
.TP
.B Classes:
\fI\%MrcInterpreter\fP: An object which can interpret an I/O stream as MRC
data.
.UNINDENT
.INDENT 0.0
.TP
.B class  mrcfile.mrcinterpreter.MrcInterpreter(iostream=None, permissive=False, header_only=False, **kwargs)
Bases: \fI\%MrcObject\fP
.sp
An object which interprets an I/O stream as MRC / CCP4 map data.
.sp
The header and data are handled as numpy arrays \- see
\fI\%MrcObject\fP for details.
.sp
\fI\%MrcInterpreter\fP can be used directly, but it is mostly intended as
a superclass to provide common stream\-handling functionality. This can be
used by subclasses which will handle opening and closing the stream.
.sp
This class implements the \fI\%__enter__()\fP and
\fI\%__exit__()\fP special methods which allow it to be used by the
Python context manager in a \fI\%with\fP block. This ensures that
\fI\%close()\fP is called after the object is finished with.
.sp
When reading the I/O stream, a \fI\%ValueError\fP is raised if the data is
invalid in one of the following ways:
.INDENT 7.0
.IP 1. 3
The header\(aqs \fBmap\fP field is not set correctly to confirm the file
type.
.IP 2. 3
The machine stamp is invalid and so the data\(aqs byte order cannot be
determined.
.IP 3. 3
The mode number is not recognised. Currently accepted modes are 0, 1, 2,
4 and 6.
.IP 4. 3
The file is not large enough for the specified extended header size.
.IP 5. 3
The data block is not large enough for the specified data type and
dimensions.
.UNINDENT
.sp
\fI\%MrcInterpreter\fP offers a permissive read mode for handling
problematic files. If \fBpermissive\fP is set to \fI\%True\fP and any of the
validity checks fails, a \fI\%warning\fP is issued instead of an
exception, and file interpretation continues. If the mode number is invalid
or the data block is too small, the
\fI\%data\fP attribute will be set to
\fI\%None\fP\&. In this case, it might be possible to inspect and correct the
header, and then call \fI\%_read()\fP again to read the data correctly. See
the \fI\%usage guide\fP for more details.
.sp
Methods:
.INDENT 7.0
.IP \(bu 2
\fI\%flush()\fP
.IP \(bu 2
\fI\%close()\fP
.UNINDENT
.sp
Methods relevant to subclasses:
.INDENT 7.0
.IP \(bu 2
\fI\%_read()\fP
.IP \(bu 2
\fI\%_read_data()\fP
.IP \(bu 2
\fI\%_read_bytearray_from_stream()\fP
.UNINDENT
.INDENT 7.0
.TP
.B __init__(iostream=None, permissive=False, header_only=False, **kwargs)
Initialise a new MrcInterpreter object.
.sp
This initialiser reads the stream if it is given. In general,
subclasses should call \fI\%__init__()\fP without giving an \fBiostream\fP
argument, then set the \fB_iostream\fP attribute themselves and call
\fI\%_read()\fP when ready.
.sp
To use the MrcInterpreter class directly, pass a stream when creating
the object (or for a write\-only stream, create an MrcInterpreter with
no stream, call \fI\%_create_default_attributes()\fP and set the
\fB_iostream\fP attribute directly).
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBiostream\fP \-\- The I/O stream to use to read and write MRC data. The
default is \fI\%None\fP\&.
.IP \(bu 2
\fBpermissive\fP \-\- Read the stream in permissive mode. The default is
\fI\%False\fP\&.
.IP \(bu 2
\fBheader_only\fP \-\- Only read the header (and extended header) from the
file. The default is \fI\%False\fP\&.
.UNINDENT
.TP
.B Raises
\fI\%ValueError\fP \-\- If \fBiostream\fP is given, the data it contains
    cannot be interpreted as a valid MRC file and \fBpermissive\fP
    is \fI\%False\fP\&.
.TP
.B Warns
.INDENT 7.0
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If \fBiostream\fP is given, the data it contains
cannot be interpreted as a valid MRC file and \fBpermissive\fP
is \fI\%True\fP\&.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the header\(aqs \fBexttyp\fP field is set to a known
value but the extended header\(aqs size is not a multiple of the
number of bytes in the corresponding dtype.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _read(header_only=False)
Read the header, extended header and data from the I/O stream.
.sp
Before calling this method, the stream should be open and positioned at
the start of the header. This method will advance the stream to the end
of the data block (or the end of the extended header if \fBheader_only\fP
is \fI\%True\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBheader_only\fP \-\- Only read the header and extended header from the
stream. The default is \fI\%False\fP\&.
.TP
.B Raises
\fI\%ValueError\fP \-\- If the data in the stream cannot be interpreted
    as a valid MRC file and \fBpermissive\fP is \fI\%False\fP\&.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data in the stream cannot be interpreted
as a valid MRC file and \fBpermissive\fP is \fI\%True\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _read_header()
Read the MRC header from the I/O stream.
.sp
The header will be read from the current stream position, and the
stream will be advanced by 1024 bytes.
.INDENT 7.0
.TP
.B Raises
\fI\%ValueError\fP \-\- If the data in the stream cannot be interpreted
    as a valid MRC file and \fBpermissive\fP is \fI\%False\fP\&.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data in the stream cannot be interpreted
as a valid MRC file and \fBpermissive\fP is \fI\%True\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _read_extended_header()
Read the extended header from the stream.
.sp
If there is no extended header, a zero\-length array is assigned to the
extended_header attribute.
.sp
If the extended header is recognised as FEI microscope metadata (by
\(aqFEI1\(aq or \(aqFEI2\(aq in the header\(aqs \fBexttyp\fP field), its dtype is set
appropriately. Otherwise, the dtype is set as void (\fB\(aqV1\(aq\fP).
.INDENT 7.0
.TP
.B Raises
\fI\%ValueError\fP \-\- If the stream is not long enough to contain the
    extended header indicated by the header and \fBpermissive\fP
    is \fI\%False\fP\&.
.TP
.B Warns
.INDENT 7.0
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the header\(aqs \fBexttyp\fP field is set to \(aqFEI1\(aq
or \(aqFEI2\(aq but the extended header\(aqs size is not a multiple of
the number of bytes in the FEI metadata dtype.
.IP \(bu 2
\fBRuntimeWarning\fP \-\- If the stream is not long enough to contain the
extended header indicated by the header and \fBpermissive\fP
is \fI\%True\fP\&.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _read_data(max_bytes=0)
Read the data array from the stream.
.sp
This method uses information from the header to set the data array\(aqs
shape and dtype.
.INDENT 7.0
.TP
.B Parameters
\fBmax_bytes\fP \-\- Read at most this many bytes from the stream. If zero or
negative, the full size of the data block as defined in the header
will be read, even if this is very large.
.TP
.B Raises
\fI\%ValueError\fP \-\- If the stream is not long enough to contain the
    data indicated by the header and \fBpermissive\fP is
    \fI\%False\fP\&.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the stream is not long enough to contain the
data indicated by the header and \fBpermissive\fP is
\fI\%True\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _read_bytearray_from_stream(number_of_bytes)
Read a \fI\%bytearray\fP from the stream.
.sp
This default implementation relies on the stream implementing the
\fI\%readinto()\fP method to avoid copying the new
array while creating the mutable \fI\%bytearray\fP\&. Subclasses
should override this if their stream does not support
\fI\%readinto()\fP\&.
.INDENT 7.0
.TP
.B Returns
A 2\-tuple of the \fI\%bytearray\fP and the number of bytes that
were read from the stream.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B close()
Flush to the stream and clear the header and data attributes.
.UNINDENT
.INDENT 7.0
.TP
.B flush()
Flush the header and data arrays to the I/O stream.
.sp
This implementation seeks to the start of the stream, writes the
header, extended header and data arrays, and then truncates the stream.
.sp
Subclasses should override this implementation for streams which do not
support \fI\%seek()\fP or \fI\%truncate()\fP\&.
.UNINDENT
.UNINDENT
.SS mrcfile.mrcmemmap module
.SS mrcmemmap
.sp
Module which exports the \fI\%MrcMemmap\fP class.
.INDENT 0.0
.TP
.B Classes:
\fI\%MrcMemmap\fP: An MrcFile subclass that uses a memory\-mapped data
array.
.UNINDENT
.INDENT 0.0
.TP
.B class  mrcfile.mrcmemmap.MrcMemmap(name, mode=\(aqr\(aq, overwrite=False, permissive=False, header_only=False, **kwargs)
Bases: \fI\%MrcFile\fP
.sp
MrcFile subclass that uses a \fI\%numpy memmap array\fP
for the data.
.sp
Using a memmap means that the disk access is done lazily: the data array
will only be read or written in small chunks when required. To access the
contents of the array, use the array slice operator.
.sp
Usage is the same as for \fI\%MrcFile\fP\&.
.sp
Note that memmap arrays use a fairly small chunk size and so performance
could be poor on file systems that are optimised for infrequent large I/O
operations.
.sp
If required, it is possible to create a very large empty file by creating a
new MrcMemmap and then calling \fI\%_open_memmap()\fP to create the memmap
array, which can then be filled slice\-by\-slice. Be aware that the contents
of a new, empty memmap array depend on your platform: the data values
could be garbage or zeros.
.INDENT 7.0
.TP
.B set_extended_header(extended_header)
Replace the file\(aqs extended header.
.sp
Note that the file\(aqs entire data block must be moved if the extended
header size changes. Setting a new extended header can therefore be
very time consuming with large files, if the new extended header
occupies a different number of bytes than the previous one.
.UNINDENT
.INDENT 7.0
.TP
.B flush()
Flush the header and data arrays to the file buffer.
.UNINDENT
.INDENT 7.0
.TP
.B _read_data()
Read the data block from the file.
.sp
This method first calculates the parameters needed to read the data
(block start position, endian\-ness, file mode, array shape) and then
opens the data as a numpy memmap array.
.UNINDENT
.INDENT 7.0
.TP
.B _open_memmap(dtype, shape)
Open a new memmap array pointing at the file\(aqs data block.
.UNINDENT
.INDENT 7.0
.TP
.B _close_data()
Delete the existing memmap array, if it exists.
.sp
The array is flagged as read\-only before deletion, so if a reference to
it has been kept elsewhere, changes to it should no longer be able to
change the file contents.
.UNINDENT
.INDENT 7.0
.TP
.B _set_new_data(data)
Override of \fI\%_set_new_data()\fP to handle opening a new memmap and
copying data into it.
.UNINDENT
.UNINDENT
.SS mrcfile.mrcobject module
.SS mrcobject
.sp
Module which exports the \fI\%MrcObject\fP class.
.INDENT 0.0
.TP
.B Classes:
\fI\%MrcObject\fP: An object representing image or volume data in the MRC
format.
.UNINDENT
.INDENT 0.0
.TP
.B class  mrcfile.mrcobject.MrcObject(**kwargs)
Bases: \fI\%object\fP
.sp
An object representing image or volume data in the MRC format.
.sp
The header, extended header and data are stored as numpy arrays and
exposed as read\-only attributes. To replace the data or extended header,
call \fI\%set_data()\fP or \fI\%set_extended_header()\fP\&. The header cannot be
replaced but can be modified in place.
.sp
Voxel size is exposed as a writeable attribute, but is calculated
on\-the\-fly from the header\(aqs \fBcella\fP and \fBmx\fP/\fBmy\fP/\fBmz\fP fields.
.sp
Three\-dimensional data can represent either a stack of 2D images, or a 3D
volume. This is indicated by the header\(aqs \fBispg\fP (space group) field,
which is set to 0 for image data and >= 1 for volume data. The
\fI\%is_single_image()\fP, \fI\%is_image_stack()\fP, \fI\%is_volume()\fP and
\fI\%is_volume_stack()\fP methods can be used to identify the type of
information stored in the data array. For 3D data, the
\fI\%set_image_stack()\fP and \fI\%set_volume()\fP methods can be used to
switch between image stack and volume interpretations of the data.
.sp
If the data contents have been changed, you can use the
\fI\%update_header_from_data()\fP and \fI\%update_header_stats()\fP methods to
make the header consistent with the data. These methods are called
automatically if the data array is replaced by calling \fI\%set_data()\fP\&.
\fI\%update_header_from_data()\fP is fast, even with very large data arrays,
because it only examines the shape and type of the data array.
\fI\%update_header_stats()\fP calculates statistics from all items in the
data array and so can be slow for very large arrays. If necessary, the
\fI\%reset_header_stats()\fP method can be called to set the header fields to
indicate that the statistics are undetermined.
.sp
Attributes:
.INDENT 7.0
.IP \(bu 2
\fI\%header\fP
.IP \(bu 2
\fI\%extended_header\fP
.IP \(bu 2
\fI\%data\fP
.IP \(bu 2
\fI\%voxel_size\fP
.IP \(bu 2
\fI\%nstart\fP
.UNINDENT
.sp
Methods:
.INDENT 7.0
.IP \(bu 2
\fI\%set_extended_header()\fP
.IP \(bu 2
\fI\%set_data()\fP
.IP \(bu 2
\fI\%is_single_image()\fP
.IP \(bu 2
\fI\%is_image_stack()\fP
.IP \(bu 2
\fI\%is_volume()\fP
.IP \(bu 2
\fI\%is_volume_stack()\fP
.IP \(bu 2
\fI\%set_image_stack()\fP
.IP \(bu 2
\fI\%set_volume()\fP
.IP \(bu 2
\fI\%update_header_from_data()\fP
.IP \(bu 2
\fI\%update_header_stats()\fP
.IP \(bu 2
\fI\%reset_header_stats()\fP
.IP \(bu 2
\fI\%print_header()\fP
.IP \(bu 2
\fI\%get_labels()\fP
.IP \(bu 2
\fI\%add_label()\fP
.UNINDENT
.sp
Attributes and methods relevant to subclasses:
.INDENT 7.0
.IP \(bu 2
\fB_read_only\fP
.IP \(bu 2
\fI\%_check_writeable()\fP
.IP \(bu 2
\fI\%_create_default_attributes()\fP
.IP \(bu 2
\fI\%_close_data()\fP
.IP \(bu 2
\fI\%_set_new_data()\fP
.UNINDENT
.INDENT 7.0
.TP
.B __init__(**kwargs)
Initialise a new \fI\%MrcObject\fP\&.
.sp
This initialiser deliberately avoids creating any arrays and simply
sets the header, extended header and data attributes to \fI\%None\fP\&.
This allows subclasses to call \fI\%__init__()\fP at the start of their
initialisers and then set the attributes themselves, probably by
reading from a file, or by calling \fI\%_create_default_attributes()\fP
for a new empty object.
.sp
Note that this behaviour might change in future: this initialiser could
take optional arguments to allow the header and data to be provided
by the caller, or might create the standard empty defaults rather than
setting the attributes to \fI\%None\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B _check_writeable()
Check that this MRC object is writeable.
.INDENT 7.0
.TP
.B Raises
\fI\%ValueError\fP \-\- If this object is read\-only.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _create_default_attributes()
Set valid default values for the header and data attributes.
.UNINDENT
.INDENT 7.0
.TP
.B _create_default_header()
Create a default MRC file header.
.sp
The header is initialised with standard file type and version
information, default values for some essential fields, and zeros
elsewhere. The first text label is also set to indicate the file was
created by this module.
.UNINDENT
.INDENT 7.0
.TP
.B property  header
Get the header as a \fI\%numpy record array\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B property  extended_header
Get the extended header as a \fI\%numpy array\fP\&.
.sp
If this \fI\%MrcObject\fP was read from a file and the extended header
type was recognised, its dtype will be set appropriately. (Currently
the only supported types are \fB\(aqFEI1\(aq\fP and \fB\(aqFEI2\(aq\fP\&.) Otherwise, the
dtype will be void (raw data, dtype \fB\(aqV\(aq\fP). If the actual data type
of the extended header is known, the dtype of the array can be changed
to match.
.sp
The extended header may be modified in place. To replace it completely,
call \fI\%set_extended_header()\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B set_extended_header(extended_header)
Replace the extended header.
.sp
If you set the extended header you should also set the
\fBheader.exttyp\fP field to indicate the type of extended header.
.UNINDENT
.INDENT 7.0
.TP
.B property  data
Get the data as a \fI\%numpy array\fP\&.
.UNINDENT
.INDENT 7.0
.TP
.B set_data(data)
Replace the data array.
.sp
This replaces the current data with the given array (or a copy of it),
and updates the header to match the new data dimensions. The data
statistics (min, max, mean and rms) stored in the header will also be
updated.
.INDENT 7.0
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data array contains Inf or NaN values.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B _close_data()
Close the data array.
.UNINDENT
.INDENT 7.0
.TP
.B _set_new_data(data)
Replace the data array with a new one.
.sp
The new data array is not checked \- it must already be valid for use in
an MRC file.
.UNINDENT
.INDENT 7.0
.TP
.B property  voxel_size
Get or set the voxel size in angstroms.
.sp
The voxel size is returned as a structured NumPy \fI\%record array\fP with three fields (x, y and z). For example:
.sp
.nf
.ft C
>>> mrc.voxel_size
rec.array((0.44825, 0.3925, 0.45874998),
  dtype=[(\(aqx\(aq, \(aq<f4\(aq), (\(aqy\(aq, \(aq<f4\(aq), (\(aqz\(aq, \(aq<f4\(aq)])
>>> mrc.voxel_size.x
array(0.44825, dtype=float32)
.ft P
.fi
.sp
Note that changing the voxel_size array in\-place will \fInot\fP change the
voxel size in the file \-\- to prevent this being overlooked
accidentally, the writeable flag is set to \fI\%False\fP on the
voxel_size array.
.sp
To set the voxel size, assign a new value to the voxel_size attribute.
You may give a single number, a 3\-tuple \fB(x, y ,z)\fP or a modified
version of the voxel_size array. The following examples are all
equivalent:
.sp
.nf
.ft C
>>> mrc.voxel_size = 1.0
.ft P
.fi
.sp
.nf
.ft C
>>> mrc.voxel_size = (1.0, 1.0, 1.0)
.ft P
.fi
.sp
.nf
.ft C
>>> vox_sizes = mrc.voxel_size
>>> vox_sizes.flags.writeable = True
>>> vox_sizes.x = 1.0
>>> vox_sizes.y = 1.0
>>> vox_sizes.z = 1.0
>>> mrc.voxel_size = vox_sizes
.ft P
.fi
.UNINDENT
.INDENT 7.0
.TP
.B _set_voxel_size(x_size, y_size, z_size)
Set the voxel size.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBx_size\fP \-\- The voxel size in the X direction, in angstroms
.IP \(bu 2
\fBy_size\fP \-\- The voxel size in the Y direction, in angstroms
.IP \(bu 2
\fBz_size\fP \-\- The voxel size in the Z direction, in angstroms
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B property  nstart
Get or set the grid start locations.
.sp
This provides a convenient way to get and set the values of the
header\(aqs \fBnxstart\fP, \fBnystart\fP and \fBnzstart\fP fields. Note that
these fields are integers and are measured in voxels, not angstroms.
The start locations are returned as a structured NumPy \fI\%record
array\fP with three fields (x, y and z). For example:
.sp
.nf
.ft C
>>> mrc.header.nxstart
array(0, dtype=int32)
>>> mrc.header.nystart
array(\-21, dtype=int32)
>>> mrc.header.nzstart
array(\-12, dtype=int32)
>>> mrc.nstart
rec.array((0, \-21, \-12),
  dtype=[(\(aqx\(aq, \(aq<i4\(aq), (\(aqy\(aq, \(aq<i4\(aq), (\(aqz\(aq, \(aq<i4\(aq)])
>>> mrc.nstart.y
array(\-21, dtype=int32)
.ft P
.fi
.sp
Note that changing the nstart array in\-place will \fInot\fP change the
values in the file \-\- to prevent this being overlooked accidentally,
the writeable flag is set to \fI\%False\fP on the nstart array.
.sp
To set the start locations, assign a new value to the nstart
attribute. You may give a single number, a 3\-tuple \fB(x, y ,z)\fP or a
modified version of the nstart array. The following examples are all
equivalent:
.sp
.nf
.ft C
>>> mrc.nstart = \-150
.ft P
.fi
.sp
.nf
.ft C
>>> mrc.nstart = (\-150, \-150, \-150)
.ft P
.fi
.sp
.nf
.ft C
>>> starts = mrc.nstart
>>> starts.flags.writeable = True
>>> starts.x = \-150
>>> starts.y = \-150
>>> starts.z = \-150
>>> mrc.nstart = starts
.ft P
.fi
.UNINDENT
.INDENT 7.0
.TP
.B _set_nstart(nxstart, nystart, nzstart)
Set the grid start locations.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBnxstart\fP \-\- The location of the first column in the unit cell
.IP \(bu 2
\fBnystart\fP \-\- The location of the first row in the unit cell
.IP \(bu 2
\fBnzstart\fP \-\- The location of the first section in the unit cell
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B is_single_image()
Identify whether the file represents a single image.
.INDENT 7.0
.TP
.B Returns
\fI\%True\fP if the data array is two\-dimensional.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B is_image_stack()
Identify whether the file represents a stack of images.
.INDENT 7.0
.TP
.B Returns
\fI\%True\fP if the data array is three\-dimensional and the space group
is zero.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B is_volume()
Identify whether the file represents a volume.
.INDENT 7.0
.TP
.B Returns
\fI\%True\fP if the data array is three\-dimensional and the space
group is not zero.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B is_volume_stack()
Identify whether the file represents a stack of volumes.
.INDENT 7.0
.TP
.B Returns
\fI\%True\fP if the data array is four\-dimensional.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B set_image_stack()
Change three\-dimensional data to represent an image stack.
.sp
This method changes the space group number (\fBheader.ispg\fP) to zero.
.INDENT 7.0
.TP
.B Raises
\fI\%ValueError\fP \-\- If the data array is not three\-dimensional.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B set_volume()
Change three\-dimensional data to represent a volume.
.sp
If the space group was previously zero (representing an image stack),
this method sets it to one. Otherwise the space group is not changed.
.INDENT 7.0
.TP
.B Raises
\fI\%ValueError\fP \-\- If the data array is not three\-dimensional.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B update_header_from_data()
Update the header from the data array.
.sp
This function updates the header byte order and machine stamp to match
the byte order of the data. It also updates the file mode, space group
and the dimension fields \fBnx\fP, \fBny\fP, \fBnz\fP, \fBmx\fP, \fBmy\fP and
\fBmz\fP\&.
.sp
If the data is 2D, the space group is set to 0 (image stack). For 3D
data the space group is not changed, and for 4D data the space group is
set to 401 (simple P1 volume stack) unless it is already in the volume
stack range (401\-\-630).
.sp
This means that new 3D data will be treated as an image stack if the
previous data was a single image or image stack, or as a volume if the
previous data was a volume or volume stack.
.sp
Note that this function does \fInot\fP update the data statistics fields in
the header (\fBdmin\fP, \fBdmax\fP, \fBdmean\fP and \fBrms\fP). Use the
\fI\%update_header_stats()\fP function to update the statistics.
(This is for performance reasons \-\- updating the statistics can take a
long time for large data sets, but updating the other header
information is always fast because only the type and shape of the data
array need to be inspected.)
.UNINDENT
.INDENT 7.0
.TP
.B update_header_stats()
Update the header\(aqs \fBdmin\fP, \fBdmax\fP, \fBdmean\fP and \fBrms\fP fields
from the data.
.sp
Note that this can take some time with large files, particularly with
files larger than the currently available memory.
.INDENT 7.0
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the data array contains Inf or NaN values.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B reset_header_stats()
Set the header statistics to indicate that the values are unknown.
.UNINDENT
.INDENT 7.0
.TP
.B print_header(print_file=None)
Print the contents of all header fields.
.INDENT 7.0
.TP
.B Parameters
\fBprint_file\fP \-\- The output text stream to use for printing the header.
This is passed directly to the \fBfile\fP argument of Python\(aqs
\fI\%print()\fP function. The default is \fI\%None\fP, which
means output will be printed to \fI\%sys.stdout\fP\&.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B get_labels()
Get the labels from the MRC header.
.sp
Up to ten labels are stored in the header as arrays of 80 bytes. This method
returns the labels as Python strings, filtered to remove non\-printable
characters. To access the raw bytes (including any non\-printable characters) use
the \fBheader.label\fP attribute (and note that \fBheader.nlabl\fP stores the number
of labels currently set).
.INDENT 7.0
.TP
.B Returns
The labels, as a list of strings. The list will contain between 0 and 10
items, each containing up to 80 characters.
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B add_label(label)
Add a label to the MRC header.
.sp
The new label will be stored after any labels already in the header. If all ten
labels are already in use, an exception will be raised.
.sp
Future versions of this method might add checks to ensure that labels containing
valid text are not overwritten even if the \fBnlabl\fP value is incorrect.
.INDENT 7.0
.TP
.B Parameters
\fBlabel\fP \-\- The label value to store, as a string containing only printable
ASCII characters.
.TP
.B Raises
.INDENT 7.0
.IP \(bu 2
\fI\%ValueError\fP \-\- If the label is longer than 80 bytes or contains
    non\-printable or non\-ASCII characters.
.IP \(bu 2
\fI\%IndexError\fP \-\- If the file already contains 10 labels and so an
    additional label cannot be stored.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.B validate(print_file=None)
Validate this MrcObject.
.sp
This method runs a series of tests to check whether this object
complies strictly with the MRC2014 format specification:
.INDENT 7.0
.IP 1. 4
MRC format ID string: The header\(aqs \fBmap\fP field must contain
\(dqMAP \(dq.
.IP 2. 4
Machine stamp: The machine stamp should contain one of
\fB0x44 0x44 0x00 0x00\fP, \fB0x44 0x41 0x00 0x00\fP or
\fB0x11 0x11 0x00 0x00\fP\&.
.IP 3. 4
MRC mode: the \fBmode\fP field should be one of the supported mode
numbers: 0, 1, 2, 4, 6 or 12. (Note that MRC modes 3 and 101 are
also valid according to the MRC 2014 specification but are not
supported by mrcfile.)
.IP 4. 4
Map and cell dimensions: The header fields \fBnx\fP, \fBny\fP, \fBnz\fP,
\fBmx\fP, \fBmy\fP, \fBmz\fP, \fBcella.x\fP, \fBcella.y\fP and \fBcella.z\fP
must all be positive numbers.
.IP 5. 4
Axis mapping: Header fields \fBmapc\fP, \fBmapr\fP and \fBmaps\fP must
contain the values 1, 2, and 3 (in any order).
.IP 6. 4
Volume stack dimensions: If the spacegroup is in the range 401\-\-630,
representing a volume stack, the \fBnz\fP field should be exactly
divisible by \fBmz\fP to represent the number of volumes in the stack.
.IP 7. 4
Header labels: The \fBnlabl\fP field should be set to indicate the
number of labels in use, and the labels in use should appear first
in the label array (that is, there should be no blank labels between
text\-filled ones).
.IP 8. 4
MRC format version: The \fBnversion\fP field should be 20140 or 20141
for compliance with the MRC2014 standard.
.IP 9. 4
Extended header type: If an extended header is present, the
\fBexttyp\fP field should be set to indicate the type of extended
header.
.IP 10. 4
Data statistics: The statistics in the header should be correct for
the actual data, or marked as undetermined.
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
\fBprint_file\fP \-\- The output text stream to use for printing messages
about the validation. This is passed directly to the \fBfile\fP
argument of Python\(aqs \fI\%print()\fP function. The default is
\fI\%None\fP, which means output will be printed to
\fI\%sys.stdout\fP\&.
.TP
.B Returns
\fI\%True\fP if this MrcObject  is valid, or \fI\%False\fP if it
does not meet the MRC format specification in any way.
.UNINDENT
.UNINDENT
.UNINDENT
.SS mrcfile.utils module
.SS utils
.sp
Utility functions used by the other modules in the mrcfile package.
.SS Functions
.INDENT 0.0
.IP \(bu 2
\fI\%data_dtype_from_header()\fP: Work out the data \fI\%dtype\fP from an MRC header.
.IP \(bu 2
\fI\%data_shape_from_header()\fP: Work out the data array shape from an MRC
header
.IP \(bu 2
\fI\%mode_from_dtype()\fP: Convert a \fI\%numpy dtype\fP to an
MRC mode number.
.IP \(bu 2
\fI\%dtype_from_mode()\fP: Convert an MRC mode number to a \fI\%numpy dtype\fP\&.
.IP \(bu 2
\fI\%pretty_machine_stamp()\fP: Get a nicely\-formatted string from a machine
stamp.
.IP \(bu 2
\fI\%machine_stamp_from_byte_order()\fP: Get a machine stamp from a byte order
indicator.
.IP \(bu 2
\fI\%byte_orders_equal()\fP: Compare two byte order indicators for equal
endianness.
.IP \(bu 2
\fI\%normalise_byte_order()\fP: Convert a byte order indicator to \fB<\fP or
\fB>\fP\&.
.IP \(bu 2
\fI\%spacegroup_is_volume_stack()\fP: Identify if a space group number
represents a volume stack.
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.data_dtype_from_header(header)
Return the data dtype indicated by the given header.
.sp
This function calls \fI\%dtype_from_mode()\fP to get the basic dtype, and
then makes sure that the byte order of the new dtype matches the byte order
of the header\(aqs \fBmode\fP field.
.INDENT 7.0
.TP
.B Parameters
\fBheader\fP \-\- An MRC header as a \fI\%numpy record array\fP\&.
.TP
.B Returns
The \fI\%numpy dtype\fP object for the data array
corresponding to the given header.
.TP
.B Raises
\fI\%ValueError\fP \-\- If there is no corresponding dtype for the given
    mode.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.data_shape_from_header(header)
Return the data shape indicated by the given header.
.INDENT 7.0
.TP
.B Parameters
\fBheader\fP \-\- An MRC header as a \fI\%numpy record array\fP\&.
.TP
.B Returns
The shape tuple for the data array corresponding to the given header.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.mode_from_dtype(dtype)
Return the MRC mode number corresponding to the given \fI\%numpy
dtype\fP\&.
.sp
The conversion is as follows:
.INDENT 7.0
.IP \(bu 2
float16   \-> mode 12
.IP \(bu 2
float32   \-> mode 2
.IP \(bu 2
int8      \-> mode 0
.IP \(bu 2
int16     \-> mode 1
.IP \(bu 2
uint8     \-> mode 6 (data will be widened to 16 bits in the file)
.IP \(bu 2
uint16    \-> mode 6
.IP \(bu 2
complex64 \-> mode 4
.UNINDENT
.sp
Note that there is no numpy dtype which corresponds to MRC mode 3.
.INDENT 7.0
.TP
.B Parameters
\fBdtype\fP \-\- A \fI\%numpy dtype\fP object.
.TP
.B Returns
The MRC mode number.
.TP
.B Raises
\fI\%ValueError\fP \-\- If there is no corresponding MRC mode for the given
    dtype.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.dtype_from_mode(mode)
Return the \fI\%numpy dtype\fP corresponding to the given
MRC mode number.
.sp
The mode parameter may be given as a Python scalar, numpy scalar or
single\-item numpy array.
.sp
The conversion is as follows:
.INDENT 7.0
.IP \(bu 2
mode 0 \-> int8
.IP \(bu 2
mode 1 \-> int16
.IP \(bu 2
mode 2 \-> float32
.IP \(bu 2
mode 4 \-> complex64
.IP \(bu 2
mode 6 \-> uint16
.IP \(bu 2
mode 12 \-> float16
.UNINDENT
.sp
Note that modes 3 and 101 are not supported as there is no matching numpy dtype.
.INDENT 7.0
.TP
.B Parameters
\fBmode\fP \-\- The MRC mode number. This may be given as any type which can be
converted to an int, for example a Python scalar (\fBint\fP or
\fBfloat\fP), a numpy scalar or a single\-item numpy array.
.TP
.B Returns
The \fI\%numpy dtype\fP object corresponding to the
given mode.
.TP
.B Raises
\fI\%ValueError\fP \-\- If there is no corresponding dtype for the given
    mode.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.pretty_machine_stamp(machst)
Return a human\-readable hex string for a machine stamp.
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.byte_order_from_machine_stamp(machst)
Return the byte order corresponding to the given machine stamp.
.INDENT 7.0
.TP
.B Parameters
\fBmachst\fP \-\- The machine stamp, as a \fI\%bytearray\fP or a \fI\%numpy
array\fP of bytes.
.TP
.B Returns
\fB<\fP if the machine stamp represents little\-endian data, or \fB>\fP if
it represents big\-endian.
.TP
.B Raises
\fI\%ValueError\fP \-\- If the machine stamp is invalid.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.machine_stamp_from_byte_order(byte_order=\(aq=\(aq)
Return the machine stamp corresponding to the given byte order
indicator.
.INDENT 7.0
.TP
.B Parameters
\fBbyte_order\fP \-\- The byte order indicator: one of \fB=\fP, \fB<\fP or \fB>\fP, as
defined and used by numpy dtype objects.
.TP
.B Returns
The machine stamp which corresponds to the given byte order, as a
\fI\%bytearray\fP\&. This will be either \fB(0x44, 0x44, 0, 0)\fP for
little\-endian or \fB(0x11, 0x11, 0, 0)\fP for big\-endian. If the given
byte order indicator is \fB=\fP, the native byte order is used.
.TP
.B Raises
\fI\%ValueError\fP \-\- If the byte order indicator is unrecognised.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.byte_orders_equal(a, b)
Work out if the byte order indicators represent the same endianness.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBa\fP \-\- The first byte order indicator: one of \fB=\fP, \fB<\fP or \fB>\fP, as
defined and used by \fI\%numpy dtype\fP objects.
.IP \(bu 2
\fBb\fP \-\- The second byte order indicator.
.UNINDENT
.TP
.B Returns
\fI\%True\fP if the byte order indicators represent the same
endianness.
.TP
.B Raises
\fI\%ValueError\fP \-\- If the byte order indicator is not recognised.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.normalise_byte_order(byte_order)
Convert a numpy byte order indicator to one of \fB<\fP or \fB>\fP\&.
.INDENT 7.0
.TP
.B Parameters
\fBbyte_order\fP \-\- One of \fB=\fP, \fB<\fP or \fB>\fP\&.
.TP
.B Returns
\fB<\fP if the byte order indicator represents little\-endian data, or
\fB>\fP if it represents big\-endian. Therefore on a little\-endian
machine, \fB=\fP will be converted to \fB<\fP, but on a big\-endian machine
it will be converted to \fB>\fP\&.
.TP
.B Raises
\fI\%ValueError\fP \-\- If \fBbyte_order\fP is not one of \fB=\fP, \fB<\fP or
    \fB>\fP\&.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.spacegroup_is_volume_stack(ispg)
Identify if the given space group number represents a volume stack.
.INDENT 7.0
.TP
.B Parameters
\fBispg\fP \-\- The space group number, as an integer, numpy scalar or single\-
element numpy array.
.TP
.B Returns
\fI\%True\fP if the space group number is in the range 401\-\-630.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.is_printable_ascii(string_)
Check if a string is entirely composed of printable ASCII characters.
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.printable_string_from_bytes(bytes_)
Convert bytes into a printable ASCII string by removing non\-printable characters.
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.utils.bytes_from_string(string_)
Convert a string to bytes.
.sp
Even though this is a one\-liner, the details are tricky to get right so things work
properly in both Python 2 and 3. It\(aqs broken out as a separate function so it can be
thoroughly tested.
.INDENT 7.0
.TP
.B Raises
\fI\%UnicodeError\fP \-\- If the input contains non\-ASCII characters.
.UNINDENT
.UNINDENT
.SS mrcfile.validator module
.SS validator
.sp
Module for top\-level functions that validate MRC files.
.sp
This module is runnable to allow files to be validated easily from the command
line.
.INDENT 0.0
.TP
.B mrcfile.validator.main(args=None)
Validate a list of MRC files given as command arguments.
.sp
The return value is used as the process exit code when this function is
called by running this module or from the corresponding \fBconsole_scripts\fP
entry point.
.INDENT 7.0
.TP
.B Returns
\fB0\fP if all command arguments are names of valid MRC files. \fB1\fP if
no file names are given or any of the files is not a valid MRC file.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.validator.validate_all(names, print_file=None)
Validate a list of MRC files.
.sp
This function calls \fI\%validate()\fP for each file name in the given list.
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBnames\fP \-\- A sequence of file names to open and validate.
.IP \(bu 2
\fBprint_file\fP \-\- The output text stream to use for printing messages about
the validation. This is passed directly to the \fBprint_file\fP
argument of the \fI\%validate()\fP function. The default is
\fI\%None\fP, which means output will be printed to
\fI\%sys.stdout\fP\&.
.UNINDENT
.TP
.B Returns
\fI\%True\fP if all of the files are valid, or \fI\%False\fP if any of
the files do not meet the MRC format specification in any way.
.TP
.B Raises
\fI\%OSError\fP \-\- If one of the files does not exist or cannot be opened.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If one of the files is seriously invalid because it has
no map ID string, an incorrect machine stamp, an unknown mode
number, or is not the same size as expected from the header.
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B mrcfile.validator.validate(name, print_file=None)
Validate an MRC file.
.sp
This function first opens the file by calling \fI\%open()\fP (with
\fBpermissive=True\fP), then calls \fI\%validate()\fP,
which runs a series of tests to check whether the file complies with the
MRC2014 format specification.
.sp
If the file is completely valid, this function returns \fI\%True\fP,
otherwise it returns \fI\%False\fP\&. Messages explaining the validation
result will be printed to \fI\%sys.stdout\fP by default, but if a text
stream is given (using the \fBprint_file\fP argument) output will be printed
to that instead.
.sp
Badly invalid files will also cause \fI\%warning\fP messages to
be issued, which will be written to \fI\%sys.stderr\fP by default. See the
documentation of the \fI\%warnings\fP module for information on how to
suppress or capture warning output.
.sp
Because the file is opened by calling \fI\%open()\fP, gzip\- and
bzip2\-compressed MRC files can be validated easily using this function.
.sp
After the file has been opened, it is checked for problems. The tests are:
.INDENT 7.0
.IP 1. 4
MRC format ID string: The \fBmap\fP field in the header should contain
\(dqMAP \(dq.
.IP 2. 4
Machine stamp: The machine stamp should contain one of
\fB0x44 0x44 0x00 0x00\fP, \fB0x44 0x41 0x00 0x00\fP or
\fB0x11 0x11 0x00 0x00\fP\&.
.IP 3. 4
MRC mode: the \fBmode\fP field should be one of the supported mode
numbers: 0, 1, 2, 4, 6 or 12. (Note that MRC modes 3 and 101 are also
valid according to the MRC 2014 specification but are not supported by
mrcfile.)
.IP 4. 4
Map and cell dimensions: The header fields \fBnx\fP, \fBny\fP, \fBnz\fP,
\fBmx\fP, \fBmy\fP, \fBmz\fP, \fBcella.x\fP, \fBcella.y\fP and \fBcella.z\fP must
all be positive numbers.
.IP 5. 4
Axis mapping: Header fields \fBmapc\fP, \fBmapr\fP and \fBmaps\fP must contain
the values 1, 2, and 3 (in any order).
.IP 6. 4
Volume stack dimensions: If the spacegroup is in the range 401\-\-630,
representing a volume stack, the \fBnz\fP field should be exactly
divisible by \fBmz\fP to represent the number of volumes in the stack.
.IP 7. 4
Header labels: The \fBnlabl\fP field should be set to indicate the number
of labels in use, and the labels in use should appear first in the label
array.
.IP 8. 4
MRC format version: The \fBnversion\fP field should be 20140 or 20141 for
compliance with the MRC2014 standard.
.IP 9. 4
Extended header type: If an extended header is present, the \fBexttyp\fP
field should be set to indicate the type of extended header.
.IP 10. 4
Data statistics: The statistics in the header should be correct for the
actual data in the file, or marked as undetermined.
.IP 11. 4
File size: The size of the file on disk should match the expected size
calculated from the MRC header.
.UNINDENT
.INDENT 7.0
.TP
.B Parameters
.INDENT 7.0
.IP \(bu 2
\fBname\fP \-\- The file name to open and validate.
.IP \(bu 2
\fBprint_file\fP \-\- The output text stream to use for printing messages about
the validation. This is passed directly to the \fBfile\fP argument of
Python\(aqs \fI\%print()\fP function. The default is \fI\%None\fP, which
means output will be printed to \fI\%sys.stdout\fP\&.
.UNINDENT
.TP
.B Returns
\fI\%True\fP if the file is valid, or \fI\%False\fP if the file does
not meet the MRC format specification in any way.
.TP
.B Raises
\fI\%OSError\fP \-\- If the file does not exist or cannot be opened.
.TP
.B Warns
\fBRuntimeWarning\fP \-\- If the file is seriously invalid because it has no map
ID string, an incorrect machine stamp, an unknown mode number, or
is not the same size as expected from the header.
.UNINDENT
.UNINDENT
.SH AUTHOR
Colin Palmer
.SH COPYRIGHT
2023, Science and Technology Facilities Council
.\" Generated by docutils manpage writer.
.