Prebinned tomograms

Big tomograms are difficult to fit in memory. Even if they fit, their visualization can be difficult inside browsers as dtmsice, which load volumetric data in memory. For this reason, it is frequently necessary to keep one or several binned versions of the same tomogram in disk. Some programs in Dynamo can use a prebinned tomogram as a proxy for the full defined tomogram, keeping track of all the coordinate coventions. The most used one is dtmslice. A tomogram with original sidelengths of 4000 x 4000 x 800 pixels will probably make the interaction with dtmslicesluggish and inconvenient. It's more convenient to send to dtmslice a 2 times binned tomogram, with a sidelength of 1000x1000x200 pixels, which can be comfortably navigated. Annotations will be automatically kept in the scale of the original tomogram.

Storage of prebinned tomograms is normally not problematic in terms of disk space: a 2x binned tomogram has 64 times less voxels than the original one.

Convention

Naming

The file that represents a prebinend version of another one has to be named:

originalFileName_CatBinnedX.originalFileExtension

where X is the number of times that a binning with bin size 2x2x2 voxels has been applied.

For instance, the 2 times binned version of

tomogram.mrc
needs to be called 
tomogram_CatBinned2.mrc 

Both tomograms need to reside in the same directory in order to let Dynamo find the prebinned version of the respective tomogram file.

Binning factor

The binning factor expresses the number of single binnings operated on one tomogram consecutively. Each binning represents the collapse of a cube of 2x2x2 voxels of the original file into a single voxel of the prebinned file. If the original tomogram had a sidelength of L voxels along one dimension, the 1x binned tomogram will have L/2 voxels, the 2x binned one will have L/4, etc.

Creation

Binning tomograms can be a time intensive procedure. The attempt of reading a full resolution tomogram into memory in one step can easily block the computer. Binning programs in Dynamo will proceed by loading into memory only small slabs (i.e., sets of correlative z-slices) of the original volume, binning the slab and then writing the slab into a file representing the binned file. If the slab size is too small, the process can be rather long. If the slab size is too large, you risk crowding the memory. If the binning procedure is performed with many processors, each one will read a different slab in parallel, so that you need to take into account the total memory use in a given time.

We default slab size is 50, which uses to work reasonably in most occasions. The different methods to prebin the tomograms will provide different levels of control on the way the binning is computed.

Through the catalogue

The catalogue GUI allows to select a binning factor that will be applied to all the tomograms in the catalogue. If you add new tomograms and then use this option later, by default the tomograms that were already prebinned won't be processed again.

Binning options in the dcm GUI

The GUI allows to change the parameters used for the binning:

BOpening the binning options

Your most important options are the slab size and the number of processors acting in parallel (called matlab workers). If the slab size is set to zero, then the size will be determined in runtime so as not to exceed the maximum number of Mb in memory. This number is indicated per processor.

editing the binning options

Through dtmslice

When you open a tomogram with dtmslice, you can ask to open the prebinned version:

dtmslice myTomogram.mrc -pb 2 -c myCatalogue

will open a prebinned version of the tomogram myTomogram.mrc. If the file myTomogram_CatBinned2.mrc does not exist, it will be created on the fly. The other flag, -c myCatalogue is merely to declare in which catalogue we are opening the tomogram, i.e., where the models that we create during this session will be created.

During the creation of prebinned tomograms, a slabsize of 50 is used by default.

Command line

Dedicated tools

The easiest way is dpktomo.prebin.create where you just feed the filename of the high resolution file.

dpktomo.prebin.create(filename,2);

which will use a default slab size of 50 pixels and store the file with the right naming convention.

Generic tools

The generic binning tool dpktomo.tools.bin allows for more flexibility in the input of options

dpktomo.tools.bin('tomogram.mrc','tomogram_CatBinned2.mrc',2,'ss',100)

dpktomo.tools.bin('tomogram.mrc','tomogram_CatBinned2.mrc',2,'ss',16,'mw',10)

In this case, you need to pass the correct name of the target file. In the example, for a file called 'tomogram.mrc', we need to use convention for prebinned tomograms and specifiy the output as 'tomogram_CatBinned2.mrc'.