Prebinned tomograms
Prebinned tomograms are files that contained binned versions of a tomogram. The filename of a prebinned tomogram must be derived from the original tomogram following a specific convention.
Prebinning the tomograms in a catalogue before starting to annotate them in dtmslice is strongly adviced.
Contents
Motivation
Quick access in viewers
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.
Better depiction
Full resolution tomograms are quite noise. Binning them makes the navigation through a tomogram much easier, making structures more distinguishable for the bare eye. Skipping the prebinning of your tomograms and viewing them in full resolution will not only give you a rather painful experience with dtmslice, it will also most probably not give you any advantage and you will have to bin the tomograms anyway.
Storage considerations
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.
The GUI allows to change the parameters used for the binning:
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.
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'.
Use
In tmslice
Prebinned tomograms are mostly used inside to feed dtmslice. In fact, using non-binned full resolution tomograms normally overwhelms this browser, forcing to use dpreview for on-the-fly binning or feeding only blocks into dtmslice. We however recommend to use prebinned tomograms. As they are computed only once (and incur not noticeable disk storage cost), they keep the workflow swift. Slices of 1000x1000 or real memory are comfortably moved by dtmslice in a MacBook Pro of a Linux workstation.
When you open a file by invoking one prebinned version, the models will be annotated with the right size (i.e., in voxel coordinates of the original tomogram).
Through the catalogue
You need to secondary click on the index field of the tomogram inside the dcm GUI. If prebinned versions are avaialable, they will show. You can then click on the open with tmslice option for the binning factor that you wish.
From the command line
You can open the tomograms using the flag 'pb' or 'prebinned' to detail that you want the prebinned version. If not available, it will be computed on the fly:
dtmslice myTomogram.mrc -pb 2
