{"id":6006,"library":"mrcfile","title":"MRC File I/O Library","description":"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.","status":"active","version":"1.5.4","language":"en","source_language":"en","source_url":"https://github.com/ccpem/mrcfile","tags":["MRC","electron microscopy","structural biology","file I/O","numpy","cryo-EM"],"install":[{"cmd":"pip install mrcfile","lang":"bash","label":"Install with pip"},{"cmd":"conda install --channel conda-forge mrcfile","lang":"bash","label":"Install with conda"}],"dependencies":[{"reason":"mrcfile exposes file headers and data as NumPy arrays and has no other compiled library dependencies.","package":"numpy","optional":false}],"imports":[{"symbol":"mrcfile","correct":"import mrcfile"},{"note":"NumPy is essential for interacting with the data arrays exposed by mrcfile.","symbol":"numpy","correct":"import numpy as np"}],"quickstart":{"code":"import mrcfile\nimport numpy as np\nimport os\n\n# Define a filename for the MRC file\nfilename = 'example.mrc'\n\n# Create a new MRC file with some dummy data\ndata = np.random.rand(10, 20, 30).astype(np.float32)\nwith mrcfile.new(filename, data=data) as mrc:\n    mrc.voxel_size = 1.5 # Set a custom voxel size\n    print(f\"Created {filename} with shape {mrc.data.shape} and voxel size {mrc.voxel_size}\")\n\n# Open an existing MRC file in read mode\nwith mrcfile.open(filename) as mrc:\n    print(f\"Opened {filename}. Data shape: {mrc.data.shape}, dtype: {mrc.data.dtype}\")\n    print(f\"Header map ID: {mrc.header.map.decode('ascii')}\")\n    # Accessing a slice of data\n    first_slice = mrc.data[0, :, :]\n    print(f\"First slice min/max: {first_slice.min()}/{first_slice.max()}\")\n\n# Clean up the created file\nos.remove(filename)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.5.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.3.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.4.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}