Walkthrough for lattices on vesicles

This walkthrough shows the approach to process proteins that cover spheroidal vesicles following (approximately) a structured lattice. For demonstration, we use a highly binned tomogram with several viral capsides.

Data

The data has been made available by Florian Schur. This single tomogram is part of the data set used for the paper An atomic model of HIV-1 capsid-SP1 reveals structures regulating assembly and maturation by Schur FK, Obr M, Hagen WJ, Wan W, Jakobi AJ, Kirkpatrick JM, Sachse C, Kräusslich HG and Briggs JA. (2016)

Getting the data

You can download the data through the command:

dpkhelp.wiki.downloadExample('hiv');

In case this command files, please try the direct link:

wget to be filled XXX, sorry

Viewing the data

The tomogram is severely binned, so it will probably fit in memory without major problems. We can just use our typical tool to quick check a tomogram.

dtmshow v17.rec

thumb|center|500px| dtmshow on the sample tomogram.

Annotation of a tomogram

We are interested in cropping the particles between the two layers of each one of the viruses.

Structure to average

DipoleSet models

In our approach, we will first use a single model to manually input the approximate centers and radiuses of all the viruses. We will use the model type dipoleSet. This model allows to describe each annotated virus as a dipole: we will mark the (approximate) center of the virus as the center property of a dipole. The radius of the virus will be described by an annotation of the north property of the dipole.

Selecting the dipoleSet model

When the model is active, we use the key c to mark the center of the current dipole, and n to mark the north. It will create a semitransparent sphere enclosing the completed dipole.

Selecting a dipole: click on C for the center, then N for the north

Corrections during picking

Further clicks on c or n will just move the center or the north of the same dipole. In order to click a further dipole, you need to click on enter and "open" the next dipole for clicking. If you forget to click on enter before annotating points on the next vesicle, you'll end up with situation like this:

Wrong input: enter needed to be clicked between vesicles 2 and 3

Here, the user probably clicked on c for vesicle 2 in its real center, then clicked on n for the north point, and then moved to vesicle 3, clicking on c trying to mark the center. As a new dipole was not opened (i.e., the enter key was not pressed) when the vesicle 2 was finished, the center of vesicle 2 got misplaced. When this happens, simply press on h to hide the spheres and click the center of vesicle 2 back in its position. Then, press on enter to start the next vesicle.

Corrections after picking

It is a good idea to observe your annotation from the xor yperspectives (for this, press on keys x or y when the cursor is on the slide). Sometimes you might identify situations like this ne:

Vesicle is too poorly picked

In such cases, you want to remove the dipole and click it again. The easiest way to do so is to:

1. click on 'h' to hide the spheres, and
2. secondary click on the wrongly created dipole (you have to click on the line itself) and select the Remove and prepare for reenter option in the menu that will popup.

Remove dipole and click again

When you are finished, don't forget to save the tomogram into the catalogue, using the disk icon (or the Active Model control)

Save model into catalogue

Cropping the particles

We will describe a protocol to be carried from the command line, explaining each step. In short, we will visit each dipole in the model we just created, define a spherical vesicle centered on the dipole, use it to define a regular distribution of points on each vesicle, define positions pointing outwards and format everything as a table that can be used directly by Dynamo to operate an extraction and a subsequent alignment.

Extracting information from the catalogue

dcmodels hiv -tc dipoleSet -ws o -gm 1

% assumes that you only have one model file 
ds = o.models{1};

Create a table for each vesicle

Now we can loop on each dipole contained in the dipole set ds.

NDipoles = length(ds.dipoles);

for i=1:NDipoles;
   v =dmodels.vesicle();
   
   v.center = ds.dipoles{i}.center;

   % defines the radius in terms of the clicked dipole 
   v.radius = norm( ds.dipoles{i}.north - ds.dipoles{i}.center);
   
   % create a separation distance in the vesicle
   v.separation = 20;

   % sets the cropping point 5 pixels away from the vesicle
   % this  distance in pixels  is measured in the normal direction
   v.crop_points_from_surface =2;
   
   % creates the crop points and respective angles
   v.updateCrop();
   
   % extracts a table
   tv{i} = v.grepTable();
   
   % marks the table assigning in the column 22 (foreseen for arbitrary use)
   % the number of the individual dipole
   tv{i}(:,22) = i;
    
   % provides information on the output
   
   disp(sprintf('Dipole %d will provide %d crop points',i,size(v.crop_points,2)));
end 

Merging the tables

Each dipole with number i generated a table stored as tv{i}, i.e., the entry i inside the cell array t. We want to generate a single table. Concatenating the table matrixes will not work, as it would have several particles with the same particle tags. We thus ask Dynamo to operate the table merging by itself, and renaming the particle tags. With the order:

tAll = dynamo_table_merge(tv,'linear_tags',1);

we concatenate the tables inside the cell array tv and set the particle tags (in column 1) to be named from 1 to the maximal number of particles to be extracted from all the vesicles. You can check the result through

dtinfo(tAll);

or graphically through: dtplot(tAll,'pf','oriented_positions');axis equal

dtplot graphic of merged table

There are several programs to depict tables. In this case we may find dpktbl.plot.disks useful, as it allows to depict the particles in a table with an associated extee can thus check how a given sidelength in pixels covers the vesicles for a given particle distribution.

dpktbl.plots.disks(tAll,'r',10);

dpktbl.plot.disks graphic of merged table

Create a data folder

We can now create our typical data folder with dtcrop with a single command.

targetFolder = 'testData';
sidelength = 40;
check = dtcrop(ds.cvolume.file,tAll,targetFolder,sidelength); 

Note that that dtcrop will create a new file that contains only the particles that were actually cropped from the tomogram. Some particles were probably excluded if they were too close to the boundary of the tomogram. We can read this table file into memory.

finalTable = dread([targetFolder,'/crop.tbl']);

Checking the particles can be done with the interactive browsers ddbrowse or dgallery, but for a quick check we can use the dslices command:

dslices(targetFolder,'projy','*','t',finalTable,'align',1,'tag',1:10:700,'labels','on');

Here, we selected only one every ten tags to get a general idea on what is going on. The flag 'projy','*' creates a projection of the aligned particles along y, projecting all the slides, so that we can check that we are indeed greping the capsides.

dslices on a subset of particles, y projection view

We see that there are different problems: we are not hitting the center of the region of interest in many particles, and in some particles the region is out of scope.

Create a coarse average

In this case, the area of interest is probably too low in the direction 'z'. We want to lift the cropping point of the particles a little bit "downwards", that is, in the negative normal direction.

Recroping the particles

Well, the protocol that we have described step by step in the previous steps can actually be completed with a single command: the method getTableFromEnclosingSpheres

A complete syntax description can be found it: help dmodels.dipoleSet.getTableFromEnclosingSpheres