mrcfile.py
==========
|build-status| |readthedocs| |python-versions| |pypi-version| |conda-forge-version|
.. |build-status| image:: https://app.travis-ci.com/ccpem/mrcfile.svg?branch=master
:target: https://app.travis-ci.com/github/ccpem/mrcfile
:alt: Build Status
.. |readthedocs| image:: https://readthedocs.org/projects/mrcfile/badge/
:target: http://mrcfile.readthedocs.org
:alt: Documentation
.. |python-versions| image:: https://img.shields.io/pypi/pyversions/mrcfile.svg
:target: https://pypi.python.org/pypi/mrcfile
:alt: Python Versions
.. |pypi-version| image:: https://img.shields.io/pypi/v/mrcfile.svg
:target: https://pypi.python.org/pypi/mrcfile
:alt: Python Package Index
.. |conda-forge-version| image:: https://img.shields.io/conda/vn/conda-forge/mrcfile.svg
:target: https://anaconda.org/conda-forge/mrcfile
:alt: conda-forge
.. start_of_main_text
``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.
.. _MRC2014 file format: http://www.ccpem.ac.uk/mrc_format/mrc2014.php
.. _numpy: http://www.numpy.org/
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.
.. _CCP-EM: http://www.ccpem.ac.uk
The source code (including the full test suite) can be found `on GitHub`_.
.. _Python package index: https://pypi.org/project/mrcfile
.. _conda-forge: https://anaconda.org/conda-forge/mrcfile
.. _on GitHub: https://github.com/ccpem/mrcfile
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.
.. _mrcfile.open: http://mrcfile.readthedocs.io/en/latest/source/mrcfile.html#mrcfile.open
.. _mrcfile.new: http://mrcfile.readthedocs.io/en/latest/source/mrcfile.html#mrcfile.new
.. _MrcFile: http://mrcfile.readthedocs.io/en/latest/usage_guide.html#using-mrcfile-objects
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`_.
.. _Read the Docs: http://mrcfile.readthedocs.org
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.* D\ **73**:469--477.
`doi: 10.1107/S2059798317007859`_
.. _`doi: 10.1107/S2059798317007859`: https://doi.org/10.1107/S2059798317007859
Contributing
------------
Please use the `GitHub issue tracker`_ for bug reports and feature requests, or
`email CCP-EM`_.
.. _GitHub issue tracker: https://github.com/ccpem/mrcfile/issues
.. _email CCP-EM: ccpem@stfc.ac.uk
Code contributions are also welcome, please submit pull requests to the
`GitHub repository`_.
.. _GitHub repository: https://github.com/ccpem/mrcfile
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``.)
.. _tox: http://tox.readthedocs.org
Licence
-------
The project is released under the BSD licence.
Raw data
{
"_id": null,
"home_page": "https://github.com/ccpem/mrcfile",
"name": "mrcfile",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Colin Palmer",
"author_email": "colin.palmer@stfc.ac.uk",
"download_url": "https://files.pythonhosted.org/packages/20/95/aeb11b58ed514961d52de76e936741ff5774a9cfdacbf9c4671285fb2ace/mrcfile-1.5.0.tar.gz",
"platform": null,
"description": "mrcfile.py\n==========\n\n|build-status| |readthedocs| |python-versions| |pypi-version| |conda-forge-version|\n\n.. |build-status| image:: https://app.travis-ci.com/ccpem/mrcfile.svg?branch=master\n :target: https://app.travis-ci.com/github/ccpem/mrcfile\n :alt: Build Status\n\n.. |readthedocs| image:: https://readthedocs.org/projects/mrcfile/badge/\n :target: http://mrcfile.readthedocs.org\n :alt: Documentation\n \n.. |python-versions| image:: https://img.shields.io/pypi/pyversions/mrcfile.svg\n :target: https://pypi.python.org/pypi/mrcfile\n :alt: Python Versions\n\n.. |pypi-version| image:: https://img.shields.io/pypi/v/mrcfile.svg\n :target: https://pypi.python.org/pypi/mrcfile\n :alt: Python Package Index\n\n.. |conda-forge-version| image:: https://img.shields.io/conda/vn/conda-forge/mrcfile.svg\n :target: https://anaconda.org/conda-forge/mrcfile\n :alt: conda-forge\n\n.. start_of_main_text\n\n``mrcfile`` is a Python implementation of the `MRC2014 file format`_, which\nis used in structural biology to store image and volume data.\n\nIt allows MRC files to be created and opened easily using a very simple API,\nwhich exposes the file's header and data as `numpy`_ arrays. The code runs in\nPython 2 and 3 and is fully unit-tested.\n\n.. _MRC2014 file format: http://www.ccpem.ac.uk/mrc_format/mrc2014.php\n.. _numpy: http://www.numpy.org/\n\nThis library aims to allow users and developers to read and write\nstandard-compliant MRC files in Python as easily as possible, and with no\ndependencies on any compiled libraries except `numpy`_. You can use it\ninteractively to inspect files, correct headers and so on, or in scripts and\nlarger software packages to provide basic MRC file I/O functions.\n\nKey Features\n------------\n\n* Clean, simple API for access to MRC files\n* Easy to install and use\n* Validation of files according to the MRC2014 format\n* Seamless support for gzip and bzip2 files\n* Memory-mapped file option for fast random access to very large files\n* Asynchronous opening option for background loading of multiple files\n* Runs in Python 2 & 3, on Linux, Mac OS X and Windows\n\nInstallation\n------------\n\nThe ``mrcfile`` library is available from the `Python package index`_::\n\n pip install mrcfile\n\nOr from `conda-forge`_::\n\n conda install --channel conda-forge mrcfile\n\nIt is also included in the ``ccpem-python`` environment in the `CCP-EM`_\nsoftware suite.\n\n.. _CCP-EM: http://www.ccpem.ac.uk\n\nThe source code (including the full test suite) can be found `on GitHub`_.\n\n.. _Python package index: https://pypi.org/project/mrcfile\n.. _conda-forge: https://anaconda.org/conda-forge/mrcfile\n.. _on GitHub: https://github.com/ccpem/mrcfile\n\nBasic usage\n-----------\n\nThe easiest way to open a file is with the `mrcfile.open`_ and `mrcfile.new`_\nfunctions. These return an `MrcFile`_ object which represents an MRC file on\ndisk.\n\n.. _mrcfile.open: http://mrcfile.readthedocs.io/en/latest/source/mrcfile.html#mrcfile.open\n.. _mrcfile.new: http://mrcfile.readthedocs.io/en/latest/source/mrcfile.html#mrcfile.new\n.. _MrcFile: http://mrcfile.readthedocs.io/en/latest/usage_guide.html#using-mrcfile-objects\n\nTo open an MRC file and read a slice of data::\n\n >>> import mrcfile\n >>> with mrcfile.open('tests/test_data/EMD-3197.map') as mrc:\n ... mrc.data[10,10]\n ... \n array([ 2.58179283, 3.1406002 , 3.64495397, 3.63812137, 3.61837363,\n 4.0115056 , 3.66981959, 2.07317996, 0.1251585 , -0.87975615,\n 0.12517013, 2.07319379, 3.66982722, 4.0115037 , 3.61837196,\n 3.6381247 , 3.64495087, 3.14059472, 2.58178973, 1.92690361], dtype=float32)\n\nTo create a new file with a 2D data array, and change some values::\n\n >>> array = np.zeros((5, 5), dtype=np.int8)\n >>> with mrcfile.new('tmp.mrc') as mrc:\n ... mrc.set_data(array)\n ... mrc.data[1:4,1:4] = 10\n ... mrc.data\n ... \n array([[ 0, 0, 0, 0, 0],\n [ 0, 10, 10, 10, 0],\n [ 0, 10, 10, 10, 0],\n [ 0, 10, 10, 10, 0],\n [ 0, 0, 0, 0, 0]], dtype=int8)\n\nThe data will be saved to disk when the file is closed, either automatically at\nthe end of the ``with`` block (like a normal Python file object) or manually by\ncalling ``close()``. You can also call ``flush()`` to write any changes to disk\nand keep the file open.\n\nTo validate an MRC file::\n\n >>> mrcfile.validate('tests/test_data/EMD-3197.map')\n File does not declare MRC format version 20140 or 20141: nversion = 0\n False\n\n >>> mrcfile.validate('tmp.mrc')\n True\n\nDocumentation\n-------------\n\nFull documentation is available on `Read the Docs`_.\n\n.. _Read the Docs: http://mrcfile.readthedocs.org\n\nCiting mrcfile\n--------------\n\nIf you find ``mrcfile`` useful in your work, please cite:\n\nBurnley T, Palmer C & Winn M (2017) Recent developments in the CCP-EM\nsoftware suite. *Acta Cryst.* D\\ **73**:469--477.\n`doi: 10.1107/S2059798317007859`_\n\n.. _`doi: 10.1107/S2059798317007859`: https://doi.org/10.1107/S2059798317007859\n\nContributing\n------------\n\nPlease use the `GitHub issue tracker`_ for bug reports and feature requests, or\n`email CCP-EM`_.\n\n.. _GitHub issue tracker: https://github.com/ccpem/mrcfile/issues\n.. _email CCP-EM: ccpem@stfc.ac.uk\n\nCode contributions are also welcome, please submit pull requests to the\n`GitHub repository`_.\n\n.. _GitHub repository: https://github.com/ccpem/mrcfile\n\nTo run the test suite, go to the top-level project directory (which contains\nthe ``mrcfile`` and ``tests`` packages) and run ``python -m unittest tests``.\n(Or, if you have `tox`_ installed, run ``tox``.)\n\n.. _tox: http://tox.readthedocs.org\n\nLicence\n-------\n\nThe project is released under the BSD licence.\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "MRC file I/O library",
"version": "1.5.0",
"project_urls": {
"Download": "https://github.com/ccpem/mrcfile/releases",
"Homepage": "https://github.com/ccpem/mrcfile"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a4b42bceabec5a7349831ee5dac446ca0cea5f7808374588e6eded625a6d1dc1",
"md5": "485b3ee2821da340eca2f0d502ede347",
"sha256": "9c3af796b35d84dd2ddc357b8427d2034212ad58de0a8f0201c2a724b9e59ad1"
},
"downloads": -1,
"filename": "mrcfile-1.5.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "485b3ee2821da340eca2f0d502ede347",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 44119,
"upload_time": "2024-01-10T15:35:51",
"upload_time_iso_8601": "2024-01-10T15:35:51.806723Z",
"url": "https://files.pythonhosted.org/packages/a4/b4/2bceabec5a7349831ee5dac446ca0cea5f7808374588e6eded625a6d1dc1/mrcfile-1.5.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2095aeb11b58ed514961d52de76e936741ff5774a9cfdacbf9c4671285fb2ace",
"md5": "77dbe3db34c2703982201e9c2491d3eb",
"sha256": "9e8196b8a33aa5b5237b43336cb9d08b6058b8127ea668d63b84d58bca795ec1"
},
"downloads": -1,
"filename": "mrcfile-1.5.0.tar.gz",
"has_sig": false,
"md5_digest": "77dbe3db34c2703982201e9c2491d3eb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 55843,
"upload_time": "2024-01-10T15:35:53",
"upload_time_iso_8601": "2024-01-10T15:35:53.248486Z",
"url": "https://files.pythonhosted.org/packages/20/95/aeb11b58ed514961d52de76e936741ff5774a9cfdacbf9c4671285fb2ace/mrcfile-1.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-10 15:35:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ccpem",
"github_project": "mrcfile",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "mrcfile"
}
JSON
