Hardware requirements

The following hardware components with the recommended minimal specifications are needed:

• a computer or workstation;
• sufficient disk storage (>3 TB) and random access memory (RAM, >64 GB);
• access to multiple graphic processing units (GPUs) for subtomogram alignment. We suggest a minimum of 2 state-of-the-art GPUs (e.g., NVIDIA GeForce RTX 2080 Ti) but recommend at least 6, since subvolume alignment is the most computationally intensive step in the processing; and
• access to a multicore computing environment for the averaging of subtomograms (>12 processing cores).

Software requirements

Operating system

• Linux (recommended) or macOS. Windows was not tested, and extra steps may be necessary to ensure compatibility.

Preprocessing

• MotionCor2 [22] for drift correction;
• CTFFIND4 [23] for defocus estimation; and
• IMOD [24] for tilt series alignment and tomogram reconstruction.

Subtomogram averaging

• MATLAB (Mathworks) version R2019a or newer. For users unfamiliar with MATLAB or similar coding languages, we highly recommend to learn some of its basics. Users should ideally be familiar with terms such as arrays, loops, and functions.
• Dynamo software for STA (version 1.1.520 or newer). A stand-alone version of Dynamo exists that works independently of MATLAB. For this protocol, however, we recommend to use the MATLAB version. The download links, extensive documentation, and guides can be found online (www.dynamo-em.org).
• Chimera UCSF [25] for subtomogram annotations.

Postprocessing

• RELION 3 [26] for resolution estimation and sharpening; and
• Bsoft [27] for local resolution estimation (function blocres).

Dataset

From the EMPIAR entry 10164 (download here: www.ebi.ac.uk/pdbe/emdb/empiar/entry/10164), the frames of the 5 tilt series according to Table 1 are used.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Table 1. Dataset.

Tomogram name and dose rate of the 5 tomograms from the EMPIAR-10164 dataset that are used in the processing.

https://doi.org/10.1371/journal.pbio.3001318.t001

The frames were recorded on a FEI Titan Krios transmission electron microscope (spherical aberration: 2.7 mm) operated at 300 keV equipped with a Gatan K2 direct electron detector using the dose-symmetric tilt scheme [28]. The calibrated 4K pixel size is 1.35 angstrom. More details about data acquisition is found in the Supporting information of the corresponding publication [20].

Preprocessing

Drift correction of the frames and Fourier binning [29] to 3710×3838 pixels is done using MotionCor2. The used parameters are listed in Table 2. This step can be done using the Dynamo wrapper dpcomp.motioncor.wrapper. The Dynamo tool dpktut.hiv.preprocess can be used to create mrc stacks from the individual micrographs.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Table 2. Preprocessing parameters.

Parameters used in MotionCor2 and CTFFIND4.

https://doi.org/10.1371/journal.pbio.3001318.t002

Defocus estimation is done using CTFFIND4 on each tilt. For defocus estimation, we consider only the micrograph area that corresponds to the projection of the tilted micrograph from 0° tilt. This angle-dependent cropping leads to a more robust defocus estimation. The parameters used in CTFFIND4 are listed in Table 2. This step can be done using the wrapper dpcomp.ctffind.wrapper.

Dose weighting is done after defocus estimation on each tilt using a MATLAB implementation of the algorithm introduced in Unblur [30] and using the accumulated dose corresponding to the last frame of each tilt (reduced by 20% to be more conservative). This step can be done using the Dynamo wrapper dpktilt.filters.exposure. Alternatively, the option for dose weighting implemented in IMOD can be used.

Tilt series alignment and tomogram reconstruction are done in IMOD. The seed model for the gold fiducials is first generated automatically and then completed manually in order to obtain about 8 to 16 bead tracks per tilt series. Fiducials are tracked automatically, and gaps are fixed manually. Fine alignment is done by estimating only 1 rotation and keeping all other parameters fixed. Residuals are minimized according to our online guide (http://www.dynamo-em.org/w/index.php/Considerations_for_tilt_series_alignment_in_IMOD). Residuals should be optimized until a root mean square (RMS) of below 2 pixels is achieved. Defocus estimation in IMOD is skipped, and the results from CTFFIND4 are used instead. The CTFFIND4 output file can be transformed into an IMOD compatible defocus file using the tool dpcomp.ctffind.forImod. CTF correction is done using phase flipping. During tomogram positioning, make sure the tomogram is thick enough to include the whole sample. Also, the x-axis tilt and angle offset should remain at zero. This ensures that the z-axis of the tomogram coincides with the electron beam direction, facilitating the interpretation of the volumes (e.g., geometry of the missing wedge). Finally, only 1 full-sized tomogram is generated for each tilt series using weighted backprojection (WBP). Any necessary binning will be done later on the fly directly on the subvolumes themselves during their alignment.

The final tomograms should be named after the Dynamo file naming convention (www.dynamo-em.org/w/index.php/Practical_Suggestions_for_Tomographic_Reconstruction). Here, we expect to have the 5 following tomograms at the end of the processing:

b001ts001.rec

b001ts003.rec

b001ts043.rec

b001ts045.rec

b001ts054.rec

For users that want to skip the preprocessing, these tomograms can be found on EMPIAR (EMPIAR-10702).

Preparing data structure for processing scripts

Before running the processing scripts, a consistent data structure needs to be set up. This is best done by following the Dynamo convention as explained in the next paragraphs.

First, the 3 following directories should be created within the main project directory:

• catalogues: contains files related to the Dynamo catalogue including the doc and vll files;
• particles: contains the various particle folders that will be created during the processing; and
• projects: contains the processing script itself, all alignment projects, and individual files (e.g., masks) that are generated during processing.

Next, a volume list or vll file that contains the path (absolute or relative) to the tomograms needs to be created and stored in the catalogues folder (it will be used to load all tomograms into the Dynamo catalogue at once). Create a text file named tomograms.vll with the following content:

Then, a doc file that also contains the path (absolute or relative) to the tomograms and their volume ID needs to be created and also stored in the catalogues folder. This file will be used to extract subvolumes from the tomograms. Create a text file named tomograms.doc with the following content:

The processing scripts (setup.m, oversample.m, locate.m and refine.m) need to be saved into the folder projects. The scripts can be found in the Supporting information S1 Appendix, or they can be retrieved directly from Dynamo (where they are maintained and updated with every new version) using the commands dpktut.hiv.setup, dpktut.hiv.oversample, dpktut.hiv.locate, and dpktut.hiv.refine.

Finally, the Dynamo catalogue has to be set up by first opening MATLAB and then loading Dynamo. After navigating to the catalogue folder, the catalogue manager can be loaded with the command dcm. Details on how to use the catalogue can be found in our online guide (www.dynamo-em.org/w/index.php/Dcm_GUI). A new catalogue should be created and named c001. The tomograms can then be imported by loading the previously created file tomograms.vll. Afterwards, the tomograms need to be binned by first selecting all volumes and then clicking create binned version from the menu (use factor 2). This binned volumes are only used for Dynamo internal purposes and not for the actual processing.

Description of processing script

The 4 processing scripts form the core of this protocol. They include all processing steps starting from particle picking to generating the 2 gold standard half-maps of the structure. They are completely written in MATLAB and Dynamo. The scripts are fully automated and are run in a sequential order, either by typing their filename (without extension) in the MATLAB command line and pressing the enter key or by opening them in the MATLAB editor and clicking the button run. User interaction is minimized, and it is only required between the execution of the scripts for tomogram and subtomogram annotations.

The scripts are structured in a total of 9 main processing steps that are further divided into so-called blocks (see flowchart in Fig 1). In this report, the functionality of each step is explained in a dedicated section. Each section contains in the beginning a general description of the corresponding step, followed by a detailed explanation of each block. Details about single commands are further commented directly in the code of the scripts themselves. More information about the used commands can also be found using the command help for MATLAB functions or dhelp for Dynamo functions.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 1. Flowchart of processing scripts.

Overview of all steps and blocks from the corresponding processing scripts. All steps are automated apart from the tomogram and subtomogram annotations (marked with the hand symbol) that are required between the execution of the individual scripts. The 2 main processing categories (particle picking and gold standard refinement) are highlighted. CC, cross-correlation; VLP, virus-like particle.

https://doi.org/10.1371/journal.pbio.3001318.g001

The scripts are designed in a way that allows to pause and resume processing after every step. Only setup.m that loads the global inputs has to be run once every time MATLAB is restarted.

The scripts are designed to set up and run alignment projects locally in the directory projects. To run the alignment projects in another location (e.g., on a cluster), users should use the dvtar command instead of dvrun and follow the corresponding online guidelines for transferring of alignment projects (www.dynamo-em.org/w/index.php/Tarring_projects).

Before starting with the first step of the processing, it should be verified that all processing scripts are located in the folder projects. To be able to run the scripts, the current folder in MATLAB should be the projects folder as well.

An overview of the approximate processing times is given in S1 Table. An overview of all intermediate files used during processing is given in S2 Table. The listed files (including the tomograms) are also available on EMPIAR (EMPIAR-10702) and can be used to skip individual processing steps. The data and code to reproduce all shown figures are as well provided.

Step 1: Set up inputs

Step 2: Oversampling of VLP hexameric lattice

Block B: Process dipole models.

Each dipole is processed by running the so-called model workflow to create a regular lattice of coordinates (about 800 to 1,000 per tomogram) on the surface (see Fig 2A). These coordinates, or crop points, will be the center of the extracted (or cropped) subvolumes. The oversampling is achieved by setting the spacing (or separation) between the crop points to 120 pixels, which is a bit less than half the side length (or box size) of the cropped subvolumes (256 pixels). This side length is large enough to fit multiple unit cells of the lattice. Coordinates of the individual unit cells will be identified later. For each tomogram, the subvolumes are extracted and stored in a tomogram-specific directory named pa_ts???_s256, where the question marks are replaced by the tomogram number. A simple average without alignment should already reveal the curvature of the surface (see Fig 2B).

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 2. Oversampling of VLPs and average.

(A) Crop points of tomogram ts001 (z-view) visualized with the Dynamo command dtplot. The crop points are located with a regular spacing on the surface of spheres. (B) Average of cropped particles (projected in x-view). The curvature of the VLP surface is visible. The data and commands to exactly reproduce this figure are available on EMPIAR (EMPIAR-10702). EMPIAR, Electron Microscopy Public Image Archive; VLP, virus-like particle.

https://doi.org/10.1371/journal.pbio.3001318.g002

Step 3: Create initial reference

Block B: Define particle center.

The previously saved average with the filename result_pr_ts001_0_INVERTED.em is opened in Chimera USCF. Using the volume tracer tool, the center of the most central unit is marked as shown in Fig 3. The coordinate is then stored by saving the current marker set with the filename reference_center.cmm.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 3. Center of unit cell defined in Chimera UCSF.

The center of a unit cell (yellow dot) was marked by first rotating the average upside down and then marking the tip of the CA-N terminal domain using the volume tracer tool.

https://doi.org/10.1371/journal.pbio.3001318.g003

Step 4: First alignment project

Block A: First alignment project.

Using a loop over all tomograms, the particles of each tomogram are aligned to the previously created reference. The azimuth of the subvolumes is randomized again to minimize potential missing wedge artifacts. The alignment parameters are identical to the previous reference project, with the only difference that from now on a C6 symmetry is imposed. The resulting coordinates (see Fig 4) are expected to have moved away from their initial positions (compare Fig 2) and to have adapted to the shape of the VLPs, which is not strictly spherical.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 4. Results of first alignment.

The left plot shows the coordinates of tomogram ts001 (z-view) visualized with the Dynamo command dtplot using the resulting table from the first alignment. The coordinates moved from their initial positions (compare Fig 2) and adapted to the shape of the VLPs. The cropped subvolumes are large enough to cover all the empty spaces between the coordinates. This is visualized in the plot on the right where disks with a diameter matching the side length of the subvolumes (256 pixels) are placed at each coordinate and successfully cover the whole surface of the VLPs (visualized using the Dynamo command dpktbl.plots.disks). The data and commands to exactly reproduce this figure are available on EMPIAR (EMPIAR-10702). EMPIAR, Electron Microscopy Public Image Archive; VLP, virus-like particle.

https://doi.org/10.1371/journal.pbio.3001318.g004

Step 5: Determine candidate particles

Description.

The aim of particle picking is to determine the coordinate of every unit cell of the hexameric lattice (or every 18-meric assembly of the capsid protein p24). In this step, the first part of particle picking is done, in which all candidate coordinates are determined (false coordinates will be excluded in the following step). Using the results from the previous alignment projects, the candidate coordinates will be determined using a 2-step subboxing procedure (in subboxing, coordinates of a specific structural feature are first defined in an average. Since the average is composed by multiple subvolumes with individual orientations, these coordinates can then be translated (or mapped) onto each of those subvolumes, and, finally, also onto the tomograms themselves. With this method, positions of features only visible in an average can be annotated in the full tomograms. See also the online guide: www.dynamo-em.org/w/index.php/Advanced_starters_guide#Subboxing). In principle, one subboxing step would suffice, in which all unit cells in each tomogram average are marked and mapped back into the corresponding tomogram. However, this would have to be done for each tomogram individually. To avoid the extra labor, an additional subboxing step is introduced, in which all tomogram averages are first aligned to each other to form an “average of averages.” All unit cells visible in this “average of averages” are marked only once and then mapped back to the tomogram averages in a first step. In the second step, they are then mapped from the averages onto the tomograms, leading to a new set of coordinates. The process is illustrated in Fig 5. Using these new coordinates, new subvolumes are extracted and aligned.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 5. Illustration of 2-step subboxing for particle picking.

After the tomogram averages have been aligned and the “average of averages” has been computed, the coordinates (yellow dots) of all unit cells are manually marked in the “average of averages.” The coordinates are then first mapped onto the tomogram averages, and, finally, onto the corresponding tomograms themselves, resulting in a coordinate grid with the expected hexameric geometry fully covering the surface of the VLPs. On the right of the illustrated “average of averages,” all marked centers of the unit cells on the actual “average of averages” produced with this protocol are shown. The coordinates were marked in Chimera UCSF using the volume tracer tool. With this procedure, candidate coordinates of all unit cells can be determined for the full dataset by manually labeling only 1 single density map. VLP, virus-like particle.

https://doi.org/10.1371/journal.pbio.3001318.g005

Block D: Map coordinates back to the tomograms.

The second step of subboxing is performed here, where the coordinates are mapped from the averages to the tomograms. First, for every tomogram, the previously computed coordinates and the table from the first alignment project are loaded and used in the dynamo_subboxing_table function for subboxing. For each coordinate, a table is then generated that contains the transformed coordinate relative to every subvolumes origin. The tables from all coordinates are merged, resulting in a final table that contains the candidate positions of all lattice units in the tomogram. Due to the previous oversampling, we expect many coordinates to overlap. The table can be corrected for this effect by using the Dynamo function dpktbl.exclusionPerVolume that reduces coordinates within a user specified radius to a single coordinate. Coordinates that incidentally describe defect or nonexisting particles will be removed in the next step. The final coordinates are visualized in Fig 6. About 5,000 to 9,000 coordinates per tomogram should be defined. We use those to extract a new set of subvolumes with a side length of 192 pixels, which generously fit a full unit cell of the hexameric lattice. The raw average of these subvolumes (without alignment) will contain some artifacts, since the z-axis orientation of the subboxed subvolumes is inherited from the previous average in which they were picked. This new z-axis does not always coincide with the normal vector of the VLP surface due to its curvature. This effect will disappear in the second alignment project.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 6. Resulting coordinates from particle picking.

Particle coordinates on the surface of one VLP from tomogram ts001 are shown using the Dynamo command dtplot to demonstrate the results from the particle picking. The hexagonal lattice structure inherent to the immature HIV-1 CA-SP1 is clearly visible. A slight deviation from a perfect sphere is also notable. The data and commands to exactly reproduce this figure are available on EMPIAR (EMPIAR-10702). EMPIAR, Electron Microscopy Public Image Archive.

https://doi.org/10.1371/journal.pbio.3001318.g006

Step 6: Cross-correlation classification

Block A: CC threshold.

The CC between each aligned subvolume and the final average is stored in the last generated table. A histogram of the CC score shows 2 populations. The population with the lower CC score is assumed to be the “bad” class that needs to be excluded from the processing. It contains mainly particles with particularly bad quality (e.g., stemming from defects) or subvolumes that contain just noise. To automate the exclusion process, a Gaussian mixture model (GMM) is fitted to the CC score distribution. GMMs are commonly used for classification, and the specific one used here describes the combination of 2 Gaussian distributions. Using the MATLAB function fitgmdist, the GMM is fitted to the CC score distribution. The threshold is then defined by taking the minimum between the 2 Gaussian peaks and by adding an empirically defined constant of 0.01. An example of the threshold determination for one tomogram is shown in Fig 7A, and the resulting particle exclusion is visualized in Fig 7B. Coordinates that describe the same particle are again fixed, and a new average for each tomogram is computed.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 7. Particle exclusion through CC classification.

(A) GMM fit to the CC score distribution of the particles from tomogram ts001 and the automatically defined threshold for particle exclusion. (B) Example of excluded particle coordinates (red) of some VLPs from tomogram ts001. Particles that do not fit in the expected lattice geometry are excluded. Visualized using the Dynamo command dtplot. The data and commands to exactly reproduce this figure are available on EMPIAR (EMPIAR-10702). CC, cross-correlation; EMPIAR, Electron Microscopy Public Image Archive; GMM, Gaussian mixture model; VLP, virus-like particle.

https://doi.org/10.1371/journal.pbio.3001318.g007

Block C: Re-crop.

The particle picking is completed, and using the coordinates from the last table, all subvolumes are re-extracted one last time (using the previous side length of 192 pixels). About 2,000 to 5,000 particles per tomogram are expected. This dataset now consists of subvolumes that all contain one centered unit cell. The quality of the particles and their initial orientation are good enough to serve as basis for the following gold standard alignment. Fig 8 shows a compilation of all tomogram averages. Note the structural differences caused by the different defoci of the tomograms.

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 8. Results of per-tomogram subtomogram averages.

Overview of all subtomogram averages from all tomograms (low-pass filtered and cut through center). Structural differences caused by the different D of the tomograms are visible (subscripts refer to tomogram number as stated in Table 1). D, defoci.

https://doi.org/10.1371/journal.pbio.3001318.g008

Step 7: Gold standard alignment

Step 8: Refinement

Step 9: Prepare half-maps

Postprocessing

The resolution estimation is done in RELION by computing the mask-corrected FSC curve between the 2 half-maps and using the cutoff criterion of 0.143. The half-maps created in the end are already named in the RELION convention and can therefore directly be loaded into the software. A tight and soft mask is used for the FSC computation. This mask is created by Gaussian filtering and binarizing the final average in an iterative manner until the full central unit cell is included inside the mask and the Gaussian falloff of the mask does not overlap with the structure. Our resolution estimate is 4.5 Å (see FSC curve in S1A Fig). This resolution is identical to the resolution estimated in [21] using the same dataset and 2D CTF correction (Fig 9).

Download:

• PPT
  PowerPoint slide
• PNG
  larger image
• TIFF
  original image

Fig 9. Electron density map after postprocessing.

(A) A CA-SP1 monomer is shown with highlighted CA-N-terminal domain (orange) and CA-C-terminal domain (green). For an easy comparison of the structures, a similar view to the one shown in [21] is displayed. (B) A rigid fit of the corresponding PDB entry 5l93 shows the quality of the map. PDB, Protein Data Bank.

https://doi.org/10.1371/journal.pbio.3001318.g009

Local resolution is estimated using the blocres function from the Bsoft software package. A box size of 23 pixels can be used with an FSC cutoff criterion of 0.5 and C6 symmetry. The results of local resolution estimation are shown in S1B Fig.

The final density map is generated with the RELION command relion_image_handler using a B-factor of -270, which is slightly stronger compared to the Guinier plot estimate (−240 in our case). The low-pass filter is set to the estimated resolution of 4.5 Å. Finally, the hand of the map is adjusted using the command clip flipyz from IMOD. Details of the final density map including a fit of the molecular structure are shown in S1 Fig. Orthogonal sections of the final average are shown in S1C Fig.