Volume list file
Volume list files are text files with extension .vll. They are used as an easy interface to describe sets of tomograms and attached models.
A volume list file just lists tomogram files, letting the user attach under each line representing a tomogram some information about it. A comment is represented by a # symbol. A text file as:
myTomogram1.mrc myTomogram2.mrc myTomogram3.mrc # tomogram 4 was awful!, we exclude it! myTomogram5.mrc
is already a perfectly formatted volume list file that can be used for instance to create a catalogue
Depending on the final use of the volumen file (possibly creating a catalogue from anew or cropping particles), there are several special characters that introduce different operations:
- # Comment
- * Parameter assignation (ftype,ytilt, etc)
- * label = testCatalogue_2
- * index = 2
- * ftype = 1
- * xtilt = -60 60
- * ytilt = -60 60
- * ztilt = -60 60
- * apix = 1.20
- * defocus = 2.40
- * cropFromElsewhere = 1
- * cropFromFile = /path/to/cropping_volume.mrc
- > Crop particles from this source
- ! Import models from this source
dtcrop <vll file> reorder sidelength datafolder
Here, myList.vll is a file text that lists tomogram files. Below each tomogram, one can insert one or several files models or tables preceded with the symbol >. For instance, if we write the file example.vll as
myTomogram1.mrc > myTable1.tbl myTomogram2.mrc > myModel_imported.omd > myTable2.tbl # we can mix models and tables myTomogram5.mrc # a volume may have no sources
and use it as first argument of dtcrop, as in:
dtcrop example.vll reorder mydata 64;
Dynamo will use myTable1.tbl to crop particles (with a sidelength of 64) from myTomogram1.mrc. For the next volume myTomogram2.mrcIt will generate internally a table out of model myModel_imported.omd and use those positions and angles together with the ones in myTable2.tbl. The particles will land in a data folder called mydata, which will include a single cropping table that will represent positions and angles merged from myTable1.tbl, myModel_imported.omd and myTable2.tbl.
It is convenient to make certain that particles from different tomograms remember from which tomogram they were cropped. This happens automatically when particles are cropped through the catalogue GUI or when the source files indicated with > are model files (with .omd extension). When the sources are table files, if volume information is not available one needs to enforce the tomogram number manually.
myTomogram1.mrc * index = 1 > myTable1.tbl myTomogram2.mrc * index = 2 > myTable2.tbl
The reason is that models are naturally bound to catalogues, and can remember the number that the respective tomogram had in the indexing of a particular catalogue. With tables, it is a frequent scenario that the the user created them independently from the catalogue. Thus, the column 20 (which represents a volume number) in a general table does not necessarily contain a catalogue-aware indexing. In such a case, the user does not need to manually edit the 20th column on each table of interest, but can impose independently a tomogram number with the syntax * index = 1 like in example above.
Through the catalogue
Volume list files are automatically generated when extracting particles using the catalogue.
You can create a catalogue from anew with
dcm -create newCatalogue -fromvll somelist.vll
You can also add a set of new files to a catalogue through the flag addvll.:
dcm -c oldCatalogue -addvll somelist.vll
Here -c simply stands for the name of the catalogue into which you want to add new tomograms. Do not use the .ctlg of the catalogue file.
Creating volume list files
Volume lists are automatically created when cropping particles through the regular GUI.
However as text files, they can be created with any regular editor. Otherwise, there are some Dynamo tools to ease the creation of volume list files in habitual scenarios.
From lists of models
Each (catalogued) model contains a key that allows it to find the volume and the catalogue it is assigned to. Thus, if you have a cell array of model files (or a cell array of models), those contain already all the information needed to extract particles from them. You can dig the information individually, or use the tools detailed below for automatted formatting of vll files.
The basic order is 'dvll' passing a cell array of models:
After this operation, you can crop particles from the tomograms referred by the models through the command:
dtcrop myList.vll reorder 64 myDataFolder
By the GUIs
A vll is automatically created when cropping particles using the catalogue
The volume that a model is linked to is depicted in screen through the method 'fullFileName' of the property 'cvolume' in the volume.
Thus, you can access the tomogram name of model myModel through:
tomogramFile = myModel.cvolume.fullFileName();