Skip to main content

MRC file I/O library

Project description

Build Status Documentation Python Versions Python Package Index conda-forge

mrcfile is a Python implementation of the MRC2014 file format, which is used in structural biology to store image and volume data.

It allows MRC files to be created and opened easily using a very simple API, which exposes the file’s header and data as numpy arrays. The code runs in Python 2 and 3 and is fully unit-tested.

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 numpy. 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.

Key Features

  • Clean, simple API for access to MRC files

  • Easy to install and use

  • Validation of files according to the MRC2014 format

  • Seamless support for gzip and bzip2 files

  • Memory-mapped file option for fast random access to very large files

  • Asynchronous opening option for background loading of multiple files

  • Runs in Python 2 & 3, on Linux, Mac OS X and Windows

Installation

The mrcfile library is available from the Python package index:

pip install mrcfile

Or from conda-forge:

conda install --channel conda-forge mrcfile

It is also included in the ccpem-python environment in the CCP-EM software suite.

The source code (including the full test suite) can be found on GitHub.

Basic usage

The easiest way to open a file is with the mrcfile.open and mrcfile.new functions. These return an MrcFile object which represents an MRC file on disk.

To open an MRC file and read a slice of data:

>>> import mrcfile
>>> with mrcfile.open('tests/test_data/EMD-3197.map') 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)

To create a new file with a 2D data array, and change some values:

>>> array = np.zeros((5, 5), dtype=np.int8)
>>> with mrcfile.new('tmp.mrc') 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)

The data will be saved to disk when the file is closed, either automatically at the end of the with block (like a normal Python file object) or manually by calling close(). You can also call flush() to write any changes to disk and keep the file open.

To validate an MRC file:

>>> mrcfile.validate('tests/test_data/EMD-3197.map')
File does not declare MRC format version 20140 or 20141: nversion = 0
False

>>> mrcfile.validate('tmp.mrc')
True

Documentation

Full documentation is available on Read the Docs.

Citing mrcfile

If you find mrcfile useful in your work, please cite:

Burnley T, Palmer C & Winn M (2017) Recent developments in the CCP-EM software suite. Acta Cryst. D73:469–477. doi: 10.1107/S2059798317007859

Contributing

Please use the GitHub issue tracker for bug reports and feature requests, or email CCP-EM.

Code contributions are also welcome, please submit pull requests to the GitHub repository.

To run the test suite, go to the top-level project directory (which contains the mrcfile and tests packages) and run python -m unittest tests. (Or, if you have tox installed, run tox.)

Licence

The project is released under the BSD licence.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mrcfile-1.4.1.tar.gz (34.6 kB view details)

Uploaded Source

Built Distribution

mrcfile-1.4.1-py2.py3-none-any.whl (42.8 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file mrcfile-1.4.1.tar.gz.

File metadata

  • Download URL: mrcfile-1.4.1.tar.gz
  • Upload date:
  • Size: 34.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.13

File hashes

Hashes for mrcfile-1.4.1.tar.gz
Algorithm Hash digest
SHA256 6ce300a4a56fc421ccc28d36c822a284b7bb5a78e2b3eaa6b8c49eba96868c3d
MD5 656c44cc47a22caf88f093de6d741300
BLAKE2b-256 57c55c0909a3fd408b5a07ec39afa900962a15baf2f282001947cddcb57374f2

See more details on using hashes here.

Provenance

File details

Details for the file mrcfile-1.4.1-py2.py3-none-any.whl.

File metadata

  • Download URL: mrcfile-1.4.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 42.8 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.1 CPython/3.9.13

File hashes

Hashes for mrcfile-1.4.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 b15600d43c5844794602a5abfcae75a9c7b7e788791293d379dcf99a66bc26ec
MD5 f19f299a362ee89a9c31fdbb598d7455
BLAKE2b-256 ed54990e000e3478d5788c02c56486fced5a7f198f7ba692f2e359581fe77584

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page