MRC File I/O Library

Warnings

• breaking In v1.5.0, the `indexed_extended_header` attribute was introduced. Code that previously accessed items in FEI1- and FEI2-type extended headers directly via `extended_header` will now need to use `indexed_extended_header` instead.
  Fix: 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.
• breaking Starting with v1.3.0, `float16` (NumPy `float16`) arrays are now saved in MRC mode 12. Previously, they were widened to `float32` and saved in mode 2. This change can lead to incompatibility with other software that does not yet support MRC mode 12.
  Fix: 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.
• gotcha Header statistics calculation was changed in v1.4.3 to use `float32` instead of `float64` for performance. While faster and less memory-intensive, this can lead to slightly less accurate statistics and potential overflow (to 'inf') if data arrays contain very large values (e.g., larger than 1e19).
  Fix: 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.
• gotcha If you modify the data array directly after opening an `MrcFile` object, the header statistics (min, max, mean, etc.) will become out of date. These are not automatically recalculated.
  Fix: 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.
• gotcha Failure to use a `with` statement or explicitly call `.close()` on `MrcFile` objects can lead to changes not being written to disk and file handles remaining open, potentially causing data loss or resource leaks.
  Fix: 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.
• gotcha MRC files with invalid header fields (e.g., incorrect `map` ID or machine stamp) may raise exceptions by default. This can be problematic when trying to repair corrupt files.
  Fix: 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.

Install

• pip install mrcfile Install with pip
• conda install --channel conda-forge mrcfile Install with conda

Imports

• mrcfile

  import mrcfile

• numpy

  import numpy as np

  NumPy is essential for interacting with the data arrays exposed by mrcfile.

Quickstart

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.

import mrcfile
import numpy as np
import os

# Define a filename for the MRC file
filename = 'example.mrc'

# Create a new MRC file with some dummy data
data = np.random.rand(10, 20, 30).astype(np.float32)
with mrcfile.new(filename, data=data) as mrc:
    mrc.voxel_size = 1.5 # Set a custom voxel size
    print(f"Created {filename} with shape {mrc.data.shape} and voxel size {mrc.voxel_size}")

# Open an existing MRC file in read mode
with mrcfile.open(filename) as mrc:
    print(f"Opened {filename}. Data shape: {mrc.data.shape}, dtype: {mrc.data.dtype}")
    print(f"Header map ID: {mrc.header.map.decode('ascii')}")
    # Accessing a slice of data
    first_slice = mrc.data[0, :, :]
    print(f"First slice min/max: {first_slice.min()}/{first_slice.max()}")

# Clean up the created file
os.remove(filename)