Cache Subtomograms

Loading subtomograms from a tomogram is a computationally expensive operation; The proper regions of the tomogram must be read from disk, and will be shifted/rotated to the proper position/orientation.

Nevertheless, sometimes you’ll have to load subtomograms from the same places many times. A typical example is when you want to create a template image by subtomogram averaging, and use the template to align molecules.

from acryo import SubtomogramLoader, Molecules
loader = SubtomogramLoader.imread(
    "/path/to/tomogram.mrc",
    molecules=Molecules.from_csv("/path/to/molecules.csv"),
    output_shape=(50, 50, 50),
)

template = loader.average()  # create template
aligned = loader.align(template)  # align molecules to template

Note

Of course, this simple example is what align_no_template() does in more efficient way.

In this example, same set of subtomograms is loaded twice.

Create Cache of Loading Tasks

Subtomogram loaders have cached() context manager. Within this context, subtomograms of the given shape will temporarily be saved in a file, and will be loaded from there if possible.

with loader.cached():  # take a while to create cache
    template = loader.average()  # much faster
    aligned = loader.align(template)  # much faster

Cache Inheritance

filter() and groupby() inherits the cache of the parent loader. For instance, if you want to create a template from the well-aligned molecules, you can do the following:

with loader.cached():  # take a while to create cache
    loader_filt = loader.filter(pl.col("score") > 0.7)
    template = loader_filt.average()  # much faster
    aligned = loader.align(template)  # much faster

Here, loader_filt.average() requires a subset of subtomograms that are already cached by loader.cached(), which is also available from loader_filt.average().