mrcfile is a pure Python library designed for reading and writing MRC2014 file format data, commonly used in structural biology for image and volume data. It provides a simple API to expose file headers and data as NumPy arrays. The library is actively maintained, with frequent updates to support new Python and NumPy versions, and to enhance features like large file handling and validation.
pip install mrcfileVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to create a new MRC file with random data and then open it to inspect its header and data. It uses `mrcfile.new()` for creation and `mrcfile.open()` for reading, both utilizing Python's `with` statement for proper file handling. NumPy is used for data generation and manipulation.
Update direct access to `extended_header` for indexed types to use `mrc.indexed_extended_header` for `mrcfile` objects opened from v1.5.0 onwards. Consider feature-checking with `hasattr(mrc, 'indexed_extended_header')` for backward compatibility.
Be aware that `float16` data may not be readable by older software. If compatibility is critical, explicitly convert `float16` arrays to `float32` before passing them to `mrcfile` functions for saving.
Be aware of potential precision loss or overflow for extreme data values when relying on header statistics. If maximum precision is required for statistics, calculate them manually using `float64` on the data array.
Call `mrc.update_header_stats()` or `mrc.reset_header_stats()` after modifying `mrc.data` to ensure the header reflects the current data statistics. Alternatively, use `mrc.set_data()` which updates statistics automatically.
Always use `with mrcfile.open(...) as mrc:` or `with mrcfile.new(...) as mrc:` when interacting with MRC files. If using `mrc = mrcfile.open(...)` outside a `with` block (e.g., in an interactive session), remember to call `mrc.close()` explicitly when finished.
When opening potentially corrupt or non-standard files, use `mrcfile.open(filename, permissive=True)`. This will issue warnings instead of exceptions and attempt to interpret the file as far as possible.
Try opening the file using `mrcfile.open('filename.mrc', permissive=True)` to ignore non-critical header errors and attempt to read the file. You can also use `mrcfile.validate('filename.mrc')` to get details on header issues without raising an exception. If the file is opened permissively with write access (`mode='r+'`), you might be able to correct specific header fields, e.g., `mrc.header.map = mrcfile.constants.MAP_ID`.To replace the entire data array, use the `mrc.set_data(new_array)` method. To modify individual fields within the header, access and assign to them directly, for example, `mrc.header.nx = new_value` or `mrc.header.cella = (100.0, 90.0, 80.0)`.
Ensure that the NumPy arrays involved in the operation have compatible shapes. This often requires explicitly reshaping one or both arrays using methods like `.reshape()`, `np.newaxis` (or `array[:, None]` for adding a new axis), `.transpose()`, or careful slicing to align their dimensions for the intended operation.
Ensure that the user account running the Python script has write permissions for the directory where the MRC file is being created or saved. This may involve changing directory permissions, running the script with elevated privileges (e.g., 'Run as administrator' on Windows, or `sudo python script.py` on Linux/macOS), or choosing a different output directory (e.g., your user's home or documents folder). Also, confirm that no other program is currently accessing the file.