Cropping table

From Dynamo
Jump to navigation Jump to search

A cropping table is a regular table used in the context of particle extraction.

Using a cropping table

Dynamo uses internally tables to execute all particle extraction operations through the catalogue. If you want to generate data folders of particles extracted from a (series of) tomogram(s) and you have already a set of coordinates

On a single volume

Cropping particles from a single volume is

dtcrop <myVolumeFile> <tableFile> <folderToBeCreated> <sidelength>;

i.e., a typical command would look like:

dtcrop example.mrc crop.tbl data 64;

look at dtcrop for the full syntax.

On several volumes

You need provide a text file that maps the column 20 in the table with a tomogram file. Such a file is generated automatically when using the catalogue tools for cropping particles, but you can generate your own file manually.

Generation of cropping tables

By Dynamo

Whenever you use the catalogue for a particle extraction, or whenever you use a multivolume cropping procedure from the command line, Dynamo will generate an unified table and an volume table index file, which will be stored in the generated data folder, with names crop.tbl and respectively.

Note that the list of tags inside crop.tbl can be smaller that the tags originally in the input table: during the extraction procedure, some particles might be too close to the boundaries of the respective tomograms, and will not be cropped. Thus, it is always useful to use the produced crop.tbl table to initialize an alignment project, as it contains the identities of the particles actually on the data folder.

By the user

If you have the coordinates of your N particles in a variable called, say, p of size Nx3, you can generate a table variable:

cropTable=dynamo_table_blank(N,'r',p);

This will becorrectly formatted, and will contain the spacial coordinates on the columns 24:26. Angles, if known, might be written onto columns 7 to 9.

From models

Generating tables is the very reason models exist. If you want to generate the table corresponding to a single model m, you should

  1. Make sure that the model has finished its computing stage and is ready to deliver a table, i.e.
    m.updateCrop
  2. Extract the table
    t = m.grepTable();

Scaling cropping tables

A typical situation is the reuse of cropping tables generated for binned versions of tomograms to recrop particles on full sized (or less binned tomograms). For such a task, one needs to

  • first scale the coordinates. This includes the cropping positions in columns 24 to 26, but also the shifts in positions 4 to 6. Including the shifts is crucial if the table expresses the result of an alignment project, as the final xyz position of the particles will be the addition of columns 24:26 to columns 4:6
  • then, balance the final positions of the centers, so that positions 24 to 26 contain semintegers positions.

Both steps can be performed with simple matlab operations, or using the commands dynamo_table_rescale and dpktbl.centerCropPoints.

Example

Let's imagine you have a variable tBin2 representing the results of a subtomogram averaging experiment performed on a tomogram called vBin2.mrc. This tomogram is the two-times binned version of the full resolution tomogram vFull.mrc. Now, you want to crop particles from vFull.mrc using the information in tBin2.

First, you rescale the table to the correct size. If vBin2.mrc is the result of binning vFull.mrc twice, it means that the physical sidelength of the voxels in vFull.mrc if four times smaller. Coordinates in tBin2 must then be multiplied by four.

tFullRaw = dynamo_table_rescale(tBin2,'factor',2); 

This command creates a variable tFullRaw in the workspace, with the same entries as tBin2 except for columns 4 to 6 (shifts) and 24 to 26 (positions in tomogram).

Then, we redefine the positions in columns 24:26 to point to semiintegers coordinates, so that they point at the physical centers of voxels.

 tFullCentered = dpktbl.centerCropPoints(tFullRaw); 

For each row in tFullCentered and tFullRaw, the total xyz position should be exactly the same. It means that the Nx3 matrices (N being the number of particles) tFullCentered(:,4:6)+ tFullCentered(:24:26) and tFullRaw(:,4:6)+ tFullRaw(:24:26), which express the 3d position of the particles, will be the same. The difference is that columns 24:26 in tFullCentered have been set to the semiinteger value closest to the xyz position of the particle. Notice that, in consequence, the shifts in columns 4:6 in tFullCentered will have values between -0.5 and 0.5;