Data

Tools

Indexes

Applications

Experiments

Open Source Science

mrcfile

A Python implementation of the MRC2014 file format

https://github.com/ccpem/mrcfile

Science Score: 57.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 4 DOI reference(s) in README
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    2 of 9 committers (22.2%) from academic institutions
  • ✓
    Institutional organization owner
    Organization ccpem has institutional domain (www.ccpem.ac.uk)
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (17.7%) to scientific vocabulary

Keywords from Contributors

cctbx cryo-em crystallography phenix
Last synced: 6 months ago · JSON representation

Repository

A Python implementation of the MRC2014 file format

Basic Info
Statistics
  • Stars: 84
  • Watchers: 2
  • Forks: 23
  • Open Issues: 9
  • Releases: 17
Created over 9 years ago · Last pushed 9 months ago
Metadata Files
Readme Changelog License

README.rst 

mrcfile.py
==========

|build-status| |readthedocs| |python-versions| |pypi-version| |conda-forge-version|

.. |build-status| image:: https://github.com/ccpem/mrcfile/actions/workflows/python-test.yml/badge.svg?branch=master
    :target: https://github.com/ccpem/mrcfile/actions/workflows/python-test.yml
    :alt: Build Status

.. |readthedocs| image:: https://readthedocs.org/projects/mrcfile/badge/
    :target: https://mrcfile.readthedocs.io/
    :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 3 and is fully unit-tested.

.. _MRC2014 file format: https://www.ccpem.ac.uk/mrc-format/mrc2014/
.. _numpy: https://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 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: https://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, install ``mrcfile`` with ``dev`` dependencies (probably in a new
virtual environment in editable mode, for example ``python -m pip install .[dev]``
from the top-level project directory), then run ``python -m pytest``.
(Or, if you have `tox`_ installed, run ``tox``.)

.. _tox: http://tox.readthedocs.org

Licence
-------

The project is released under the BSD licence.

Owner

  • Name: CCP-EM
  • Login: ccpem
  • Kind: organization

Collaborative Computational Project for Electron cryo-Microscopy

GitHub Events

Total
  • Create event: 2
  • Release event: 2
  • Issues event: 9
  • Watch event: 4
  • Delete event: 1
  • Issue comment event: 18
  • Push event: 30
Last Year
  • Create event: 2
  • Release event: 2
  • Issues event: 9
  • Watch event: 4
  • Delete event: 1
  • Issue comment event: 18
  • Push event: 30

Committers

Last synced: over 2 years ago

All Time
  • Total Commits: 280
  • Total Committers: 9
  • Avg Commits per committer: 31.111
  • Development Distribution Score (DDS): 0.061
Past Year
  • Commits: 11
  • Committers: 3
  • Avg Commits per committer: 3.667
  • Development Distribution Score (DDS): 0.545
Top Committers
Name Email Commits
Colin Palmer c****r@s****k 263
David Waterman d****n@g****m 5
James Parkhurst j****t@d****k 2
Alister Burt a****t@g****m 2
David Waterman d****a 2
kevinpetersavage k****e@g****m 2
Michael Saur m****r@w****e 2
Colin Palmer c****r@c****t 1
Holger Kohr h****r@z****m 1
Committer Domains (Top 20 + Academic)
zoho.com: 1 cantab.net: 1 github.com: 1 diamond.ac.uk: 1 stfc.ac.uk: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 58
  • Total pull requests: 13
  • Average time to close issues: 2 months
  • Average time to close pull requests: 3 months
  • Total issue authors: 40
  • Total pull request authors: 11
  • Average comments per issue: 3.22
  • Average comments per pull request: 2.0
  • Merged pull requests: 6
  • Bot issues: 0
  • Bot pull requests: 1
Past Year
  • Issues: 7
  • Pull requests: 0
  • Average time to close issues: 13 days
  • Average time to close pull requests: N/A
  • Issue authors: 7
  • Pull request authors: 0
  • Average comments per issue: 1.29
  • Average comments per pull request: 0
  • Merged pull requests: 0
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • alisterburt (5)
  • jmp1985 (4)
  • colinpalmer (4)
  • aliaksei-chareshneu (3)
  • pconesa (2)
  • mgorny (2)
  • paulkorir (2)
  • martinschorb (2)
  • ssscj (2)
  • markbasham (1)
  • MohamadHarastani (1)
  • eisfabian (1)
  • rathann (1)
  • kimdn (1)
  • luke-c-sargent (1)
Pull Request Authors
  • hanjinliu (2)
  • jmp1985 (2)
  • sroet (2)
  • alisterburt (2)
  • milliams (1)
  • dagewa (1)
  • dependabot[bot] (1)
  • kohr-h (1)
  • kevinpetersavage (1)
  • luke-c-sargent (1)
  • biohaznerd (1)
Top Labels
Issue Labels
Pull Request Labels
dependencies (1)

Packages

  • Total packages: 3
  • Total downloads:
    • pypi 153,871 last-month
  • Total docker downloads: 5,325
  • Total dependent packages: 89
    (may contain duplicates)
  • Total dependent repositories: 205
    (may contain duplicates)
  • Total versions: 58
  • Total maintainers: 1
pypi.org: mrcfile

MRC file I/O library

  • Versions: 31
  • Dependent Packages: 76
  • Dependent Repositories: 196
  • Downloads: 153,871 Last month
  • Docker Downloads: 5,325
Rankings
Dependent packages count: 0.2%
Dependent repos count: 1.1%
Downloads: 1.4%
Docker downloads count: 1.6%
Average: 3.4%
Forks count: 8.1%
Stargazers count: 8.2%
Maintainers (1)
colinpalmer
Last synced: 6 months ago
proxy.golang.org: github.com/ccpem/mrcfile
  • Versions: 19
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Forks count: 4.7%
Stargazers count: 5.2%
Average: 7.6%
Dependent packages count: 9.6%
Dependent repos count: 10.8%
Last synced: 6 months ago
conda-forge.org: mrcfile

mrcfile is a Python implementation of the MRC2014 file format (http://www.ccpem.ac.uk/mrc_format/mrc2014.php), 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.

  • Versions: 8
  • Dependent Packages: 13
  • Dependent Repositories: 9
Rankings
Dependent packages count: 4.8%
Dependent repos count: 11.6%
Average: 23.3%
Stargazers count: 37.9%
Forks count: 38.8%
Last synced: 6 months ago