From bd44f4589900510bad9d4cfc0fbcea4312f53a29 Mon Sep 17 00:00:00 2001 From: aviralgarg05 Date: Tue, 10 Nov 2026 18:36:21 +0530 Subject: [PATCH] Allow creating a Grid from a native mrcfile object Grid(grid=...) now also accepts the native objects of the mrcfile library, i.e., anything derived from mrcfile.mrcobject.MrcObject, which covers MrcFile, MrcInterpreter and subclasses such as MrcMemmap and GzipMrcFile: with mrcfile.open("density.mrc") as mrcobj: g = Grid(mrcobj) Pulling the data, header, origin and grid spacing out of an mrcfile object is exactly what reading a file already did, so that part was split out of MRC.read() into MRC._populate() and is now shared with the new classmethod MRC.from_mrcfile(). The grid data are a view of the data of the native object and are not copied, so a grid built this way needs the native object to keep its data around. The API interoperability docs still said that loading from a native object was not implemented; they now describe it for both MRC and OpenVDB. Fixes #172 --- AUTHORS | 1 + CHANGELOG | 5 +- doc/source/gridData/interoperability.rst | 24 +++- gridData/core.py | 36 ++++- gridData/mrc.py | 164 +++++++++++++++++------ gridData/tests/test_mrc.py | 101 ++++++++++++++ 6 files changed, 277 insertions(+), 54 deletions(-) diff --git a/AUTHORS b/AUTHORS index 91eabb3..6f3f62b 100644 --- a/AUTHORS +++ b/AUTHORS @@ -30,3 +30,4 @@ Contributors: * Rich Waldo * Pradyumn Prasad * Shreejan Dolai +* Aviral Garg diff --git a/CHANGELOG b/CHANGELOG index 2eae8d5..a9a9b97 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -13,7 +13,7 @@ The rules for this file: * accompany each entry with github issue/PR number (Issue #xyz) ------------------------------------------------------------------------------- -MM/DD/2026 orbeckst, spyke7 +MM/DD/2026 orbeckst, spyke7, aviralgarg05 * 1.3.0 @@ -26,6 +26,9 @@ MM/DD/2026 orbeckst, spyke7 * Implemented loading of a Grid from a native object for OpenVDB (Issue #162, PR #170) + * Implemented loading of a Grid from a native mrcfile object such as + mrcfile.mrcfile.MrcFile or mrcfile.mrcinterpreter.MrcInterpreter; the + data are used as a view and not copied (Issue #162, Issue #172) Fixes diff --git a/doc/source/gridData/interoperability.rst b/doc/source/gridData/interoperability.rst index ecd9a4d..2385940 100644 --- a/doc/source/gridData/interoperability.rst +++ b/doc/source/gridData/interoperability.rst @@ -62,15 +62,27 @@ native objects are produced:: Creating a Grid from a native object ------------------------------------ -.. note:: **Not implemented yet.** See issue `#162`_ for details. - -:class:`~gridData.core.Grid` should be able to consume *native objects* in place of files. +.. versionadded:: 1.3.0 +:class:`~gridData.core.Grid` also consumes *native objects* in place of files: +the object is passed as the *grid* argument and the data together with the +origin and the grid spacings are taken from it. For example, a :class:`mrcfile.mrcfile.MrcFile` instance can be used to instantiate the :class:`Grid` instance:: - mrc = mrcfile.mrcfile.MrcFile("density.ccp4") - g = Grid(mrc) + mrc = mrcfile.open("density.ccp4") + g = Grid(mrc) - +and in the same manner for an OpenVDB grid:: + + grids, _ = vdb.readAll("density.vdb") + g = Grid(grids[0]) + +The data are extracted by the *adapter class* of the format, namely with the +*classmethod* :meth:`gridData.mrc.MRC.from_mrcfile` for MRC data. For MRC, the +data are used as a *view* of the data of the native object and are not copied, +so the native object has to keep the data available for as long as the +:class:`Grid` is used. + +(See issue `#162`_ for additional background.) diff --git a/gridData/core.py b/gridData/core.py index fcc90bd..e0731ee 100644 --- a/gridData/core.py +++ b/gridData/core.py @@ -38,6 +38,7 @@ import pickle import numpy +import mrcfile # For interpolated grids: need scipy.ndimage but we import it only when needed: # import scipy @@ -190,6 +191,12 @@ class Grid(object): g = Grid() g.load(filename) + From a native object of one of the supported libraries, e.g., a + :class:`mrcfile.mrcfile.MrcFile`:: + + with mrcfile.open("density.mrc") as mrcobj: + g = Grid(mrcobj) + Notes ----- @@ -209,6 +216,13 @@ class Grid(object): CCP4 files are now read with :class:`gridData.mrc.MRC` and not anymore with the deprecated/buggy `ccp4.CCP4` + .. versionchanged:: 1.3.0 + *grid* can be a native mrcfile object, i.e., an instance of + :class:`mrcfile.mrcobject.MrcObject` such as + :class:`mrcfile.mrcfile.MrcFile` or + :class:`mrcfile.mrcinterpreter.MrcInterpreter`. The data of the grid + are a view of the data of the mrcfile object. + """ #: Default format for exporting with :meth:`export`. @@ -264,6 +278,10 @@ def __init__(self, grid=None, edges=None, origin=None, delta=None, return except ImportError: pass + if isinstance(grid, mrcfile.mrcobject.MrcObject): + # if a native mrcfile object is passed + self._load_mrcfile(grid, assume_volumetric=assume_volumetric) + return if isinstance(grid, str): # can probably safely try to load() it... filename = grid @@ -637,12 +655,24 @@ def _load_python(self, filename, **kwargs): def _load_mrc(self, filename, assume_volumetric=False, **kwargs): """Initializes Grid from a MRC/CCP4 file.""" - mrcfile = mrc.MRC(filename, assume_volumetric=assume_volumetric) - grid, edges = mrcfile.histogramdd() + mrcdata = mrc.MRC(filename, assume_volumetric=assume_volumetric) + self._populate_from_mrc(mrcdata) + + def _load_mrcfile(self, mrcobj, assume_volumetric=False): + """Initializes Grid from a native mrcfile object. + + The grid data are a view of the data of `mrcobj`. + """ + mrcdata = mrc.MRC.from_mrcfile(mrcobj, assume_volumetric=assume_volumetric) + self._populate_from_mrc(mrcdata) + + def _populate_from_mrc(self, mrcdata): + """Initializes Grid from a :class:`gridData.mrc.MRC` instance.""" + grid, edges = mrcdata.histogramdd() self._load(grid=grid, edges=edges, metadata=self.metadata) # Store header for access from Grid object (undocumented) # https://github.com/MDAnalysis/GridDataFormats/pull/100#discussion_r782604833 - self._mrc_header = mrcfile.header.copy() + self._mrc_header = mrcdata.header.copy() def _load_dx(self, filename, **kwargs): """Initializes Grid from a OpenDX file.""" diff --git a/gridData/mrc.py b/gridData/mrc.py index bf41d61..9c2625d 100644 --- a/gridData/mrc.py +++ b/gridData/mrc.py @@ -14,6 +14,25 @@ .. _mrcfile: https://mrcfile.readthedocs.io/ .. _`MRC2014 file format`: http://www.ccpem.ac.uk/mrc_format/mrc2014.php +A :class:`~gridData.core.Grid` can be built either from a file or directly +from one of the native objects of the mrcfile_ library, namely +:class:`~mrcfile.mrcfile.MrcFile`, +:class:`~mrcfile.mrcinterpreter.MrcInterpreter`, and their subclasses:: + + import mrcfile + from gridData import Grid + + g = Grid("density.mrc") # from a file + + with mrcfile.open("density.mrc") as mrcobj: + g = Grid(mrcobj) # from a native object + +The data of such a grid are a view of the data of the native object and are +not copied; see :meth:`MRC.from_mrcfile`. + +.. versionchanged:: 1.3.0 + Grids can be created from native mrcfile objects. + References ---------- @@ -136,6 +155,55 @@ def from_grid(cls, grid, **kwargs): return mrc_obj + @classmethod + def from_mrcfile(cls, mrcobj, assume_volumetric=False): + """Create a MRC object from a native mrcfile object. + + Parameters + ---------- + mrcobj : mrcfile.mrcobject.MrcObject + Native object of the mrcfile_ library that holds the data and the + header, such as :class:`~mrcfile.mrcfile.MrcFile` or + :class:`~mrcfile.mrcinterpreter.MrcInterpreter`. + assume_volumetric : bool (optional) + If ``False`` (default), check the header to determine whether the + data in `mrcobj` are a 3D volume. If ``True``, assume that they + are volumetric. + + Returns + ------- + MRC + MRC wrapper object + + Raises + ------ + TypeError + If `mrcobj` is not a native mrcfile object. + ValueError + If the unit cell is not orthorhombic or if the data are not + volumetric. + + Notes + ----- + The :attr:`array` is a view of the data of `mrcobj`, i.e., the data + are not copied and changes to `mrcobj` are also seen here. The data of + a memory-mapped object (from :func:`mrcfile.mmap`) become unavailable + once that object is closed. + + + .. versionadded:: 1.3.0 + """ + if not isinstance(mrcobj, mrcfile.mrcobject.MrcObject): + raise TypeError( + "mrcobj must be a native mrcfile object (an instance of " + "mrcfile.mrcobject.MrcObject) but is a {}".format(type(mrcobj)) + ) + + mrc_obj = cls() + mrc_obj._populate(mrcobj, assume_volumetric=assume_volumetric) + + return mrc_obj + @property def native(self): """Return a native :class:`~mrcfile.mrcinterpreter.MrcInterpreter` object. @@ -264,52 +332,60 @@ def read(self, filename, assume_volumetric=False): if filename is not None: self.filename = filename with mrcfile.open(filename) as mrc: - if assume_volumetric: - # non 3D volumes should always fail, regardless of assume_volumetric value - is_volume = mrc.data is not None and len(mrc.data.shape) == 3 - else: - is_volume = mrc.is_volume() - - if not is_volume: - raise ValueError( - "MRC file {} is not a volumetric density.".format(filename) - ) - self.header = h = mrc.header.copy() - # check for being orthorhombic - if not np.allclose( - [h.cellb.alpha, h.cellb.beta, h.cellb.gamma], [90, 90, 90] - ): - raise ValueError( - "Only orthorhombic unitcells are currently " - "supported, not " - "alpha={0}, beta={1}, gamma={2}".format( - h.cellb.alpha, h.cellb.beta, h.cellb.gamma - ) + self._populate(mrc, assume_volumetric=assume_volumetric) + + def _populate(self, mrc, assume_volumetric=False): + """Populate the instance from the native mrcfile object *mrc*. + + The :attr:`array` is a view of the data of *mrc*. + """ + if assume_volumetric: + # non 3D volumes should always fail, regardless of assume_volumetric value + is_volume = mrc.data is not None and len(mrc.data.shape) == 3 + else: + is_volume = mrc.data is not None and mrc.is_volume() + + if not is_volume: + source = ( + "MRC file {}".format(self.filename) + if self.filename is not None + else "{} object".format(type(mrc).__name__) + ) + raise ValueError("{} is not a volumetric density.".format(source)) + self.header = h = mrc.header.copy() + # check for being orthorhombic + if not np.allclose([h.cellb.alpha, h.cellb.beta, h.cellb.gamma], [90, 90, 90]): + raise ValueError( + "Only orthorhombic unitcells are currently " + "supported, not " + "alpha={0}, beta={1}, gamma={2}".format( + h.cellb.alpha, h.cellb.beta, h.cellb.gamma ) - # mrc.data[z, y, x] indexed: convert to x,y,z as used in GridDataFormats - # together with the axes orientation information in mapc/mapr/maps. - # mapc, mapr, maps = 1, 2, 3 for Fortran-ordering and 3, 2, 1 for C-ordering. - # Other combinations are possible. We reorder the data for the general case - # by sorting mapc, mapr, maps in ascending order, i.e., to obtain x,y,z. - # mrcfile provides the data in zyx shape (without regard to map*) so we first - # transpose it to xyz and then reorient with axes_c_order. - # - # All other "xyz" quantitities are also reordered. - axes_order = np.hstack([h.mapc, h.mapr, h.maps]) - axes_c_order = np.argsort(axes_order) - transpose_order = np.argsort(axes_order[::-1]) - self.array = np.transpose(mrc.data, axes=transpose_order) - self.delta = np.diag( - np.array([mrc.voxel_size.x, mrc.voxel_size.y, mrc.voxel_size.z]) ) - # the grid is shifted to the MRC origin by offset - # (assume orthorhombic) - offsets = np.hstack([h.nxstart, h.nystart, h.nzstart])[ - axes_c_order - ] * np.diag(self.delta) - # GridData origin is centre of cell at x=col=0, y=row=0 z=seg=0 - self.origin = np.hstack([h.origin.x, h.origin.y, h.origin.z]) + offsets - self.rank = 3 + # mrc.data[z, y, x] indexed: convert to x,y,z as used in GridDataFormats + # together with the axes orientation information in mapc/mapr/maps. + # mapc, mapr, maps = 1, 2, 3 for Fortran-ordering and 3, 2, 1 for C-ordering. + # Other combinations are possible. We reorder the data for the general case + # by sorting mapc, mapr, maps in ascending order, i.e., to obtain x,y,z. + # mrcfile provides the data in zyx shape (without regard to map*) so we first + # transpose it to xyz and then reorient with axes_c_order. + # + # All other "xyz" quantitities are also reordered. + axes_order = np.hstack([h.mapc, h.mapr, h.maps]) + axes_c_order = np.argsort(axes_order) + transpose_order = np.argsort(axes_order[::-1]) + self.array = np.transpose(mrc.data, axes=transpose_order) + self.delta = np.diag( + np.array([mrc.voxel_size.x, mrc.voxel_size.y, mrc.voxel_size.z]) + ) + # the grid is shifted to the MRC origin by offset + # (assume orthorhombic) + offsets = np.hstack([h.nxstart, h.nystart, h.nzstart])[axes_c_order] * np.diag( + self.delta + ) + # GridData origin is centre of cell at x=col=0, y=row=0 z=seg=0 + self.origin = np.hstack([h.origin.x, h.origin.y, h.origin.z]) + offsets + self.rank = 3 @property def shape(self): diff --git a/gridData/tests/test_mrc.py b/gridData/tests/test_mrc.py index cec54e0..8565ef5 100644 --- a/gridData/tests/test_mrc.py +++ b/gridData/tests/test_mrc.py @@ -1,3 +1,5 @@ +import shutil + import pytest import numpy as np @@ -43,6 +45,11 @@ def ccp4data(): return mrc.MRC(datafiles.CCP4_1JZV) +@pytest.fixture(scope="module") +def ccp4grid(): + return Grid(datafiles.CCP4_1JZV) + + @pytest.mark.parametrize( "name,value", [ @@ -378,3 +385,97 @@ def test_mrc_write_4x4x4_without_header(self, tmpdir): assert_allclose(m_read.array, data) assert_allclose(np.diag(m_read.delta), [1.0, 1.0, 1.0]) assert_allclose(m_read.origin, [0.0, 0.0, 0.0], rtol=1e-4, atol=1.0) + + +class TestGridFromMrcfile: + """Tests for building a Grid from a native mrcfile object""" + + def test_from_mrcfile(self, ccp4grid): + with mrcfile.open(datafiles.CCP4_1JZV) as mrcobj: + g = Grid(mrcobj) + + assert_equal(g.grid.shape, ccp4grid.grid.shape) + assert_allclose(g.grid, ccp4grid.grid) + assert_allclose(g.origin, ccp4grid.origin) + assert_allclose(g.delta, ccp4grid.delta) + + def test_from_mrcfile_keyword(self, ccp4grid): + with mrcfile.open(datafiles.CCP4_1JZV) as mrcobj: + g = Grid(grid=mrcobj) + + assert_allclose(g.grid, ccp4grid.grid) + + def test_from_mrcfile_header(self, ccp4grid): + with mrcfile.open(datafiles.CCP4_1JZV) as mrcobj: + g = Grid(mrcobj) + + # undocumented MRC header in Grid + assert g._mrc_header == ccp4grid._mrc_header + + def test_from_mrcmemmap(self, ccp4grid): + # subclasses of MrcFile must work, too + with mrcfile.mmap(datafiles.CCP4_1JZV) as mrcobj: + assert isinstance(mrcobj, mrcfile.mrcmemmap.MrcMemmap) + g = Grid(mrcobj) + assert_allclose(g.grid, ccp4grid.grid) + + def test_from_mrcinterpreter(self, ccp4grid): + mrcobj = mrc.MRC(datafiles.CCP4_1JZV).native + + assert isinstance(mrcobj, mrcfile.mrcinterpreter.MrcInterpreter) + + g = Grid(mrcobj) + assert_allclose(g.grid, ccp4grid.grid) + assert_allclose(g.origin, ccp4grid.origin, rtol=1e-5, atol=1e-3) + assert_allclose(g.delta, ccp4grid.delta) + + def test_data_is_view(self, tmpdir): + # the data must not be copied (Issue #172) + mrcfile_copy = str(tmpdir / "writable.ccp4") + shutil.copy(datafiles.CCP4_1JZV, mrcfile_copy) + + with mrcfile.mmap(mrcfile_copy, mode="r+") as mrcobj: + g = Grid(mrcobj) + + assert np.shares_memory(g.grid, mrcobj.data) + + # changing the native object also changes the grid + mrcobj.data[0, 0, 0] += 1 + assert_equal(g.grid[0, 0, 0], mrcobj.data[0, 0, 0]) + + def test_convert_to_roundtrip(self, ccp4grid): + g = Grid(ccp4grid.convert_to("mrc")) + + assert_allclose(g.grid, ccp4grid.grid) + assert_allclose(g.origin, ccp4grid.origin, rtol=1e-5, atol=1e-3) + assert_allclose(g.delta, ccp4grid.delta, rtol=1e-5) + + def test_volume_check(self): + with mrcfile.open(datafiles.ISPG_0) as mrcobj: + with pytest.raises(ValueError, match="is not a volumetric density"): + Grid(mrcobj) + + def test_volume_force(self): + with mrcfile.open(datafiles.ISPG_0) as mrcobj: + g = Grid(mrcobj, assume_volumetric=True) + + assert_allclose(np.sum(g.grid), 829.925) + + def test_empty_data_ValueError(self): + mrcobj = mrcfile.mrcinterpreter.MrcInterpreter() + mrcobj._create_default_attributes() + + with pytest.raises(ValueError, match="is not a volumetric density"): + Grid(mrcobj) + + def test_triclinic_ValueError(self): + with mrcfile.open(datafiles.MRC_EMD3001) as mrcobj: + with pytest.raises( + ValueError, + match="Only orthorhombic unitcells are currently supported, not", + ): + Grid(mrcobj) + + def test_not_mrcfile_TypeError(self): + with pytest.raises(TypeError, match="must be a native mrcfile object"): + mrc.MRC.from_mrcfile(np.ones((2, 3, 4)))