7. Picking in tomograms

Doppio supports the Napari picker implemented in RELION. This picker has individual particle picking, sphere annotation and filament picking modes. Since Napari is graphics intensive and does not scale for port forwarding, we strongly recommend to use Napari picker locally for slower connections. A separate section on how to run Napari picker locally is provided below (Section 7.2). If you have a fast connection, or you work on a workstation, run Napari picker directly on the server as per instruction below.

7.1. Running Napari picker on the server in Doppio

To run Napari picker in Doppio, got to NEW JOB tab in Doppio GUI and find the Manual Particle Picking section and choose Napari Manual Particle Picking job. In the job parameters, choose the Tomograms/job006/tomograms.star as Input tomograms. Picking mode should be set to Spheres with Particle spacing of 60 Angstroms. Next hit RUN button. This will open Napari picker in a new window, and automatically load the first tomogram in the GUI.

Why we choose sphere annotation mode for picking?

Tutorial data - HIV-VPLs- are more or less spherical in shape. Hence, we use sphere annotation mode for picking. By doing this, we can annotate the spheres in the tomograms and then sample the annotated spheres with the given particle spacing to generate particle coordinates assuming that the particles are distributed uniformly on the surface of the spheres. This is a good approximation for HIV-VPLs. Besides that, the sphere annotation allows us to define each particle’s orientation with respect to the sphere surface. Choosing tilt angle = 90 degrees will give us the particle orientation normal to the sphere surface (i.e. along Z-axis).

Napari picker controls

  • rotate the scene: left-mouse button + drag

  • zoom in/out: mouse wheel

  • navigate through tomogram slices (z-axis): Shift + left-mouse button + drag

How to do sphere annotation in Napari picker?

  1. When Napari first opens, you’ll see the first tomogram in the GUI. On the left - tomogram layer (highlighted means active) and n3d spheres layer.

  2. While the tomogram layer is active, zoom in to the tomogram to fit it in the GUI window. Then, go to contrast limits (in the GUI) and change the contrast by sliding two buttons so that you can clearly see features you intend to annotate. You may even choose a different colour.

  3. To capture a HIV capside in a sphere, one must locate its centroid. To do that, (visually) choose a capside and navigate through the tomogram slices until you find the maximum diameter of that capside.

  4. To mark its centroid, use Alt + left-mouse click on the centroid of the capside. This will create a small sphere at that location. If you found your placement is not accurate, you can move the sphere by dragging. To do that, activate the n3d spheres layer, go to layer controls and choose Select points. Then click on the centroid and drag it where it needs to be. Make sure your centroid is correct in top and side views in the tomogram.

  5. Next, you need to resize the sphere to match the HIV capside. To do that, place the cursor roguhly on the middle layer of the capside (in the XY plane) and press the letter r on the keyboard. A bigger sphere will be drawn around the centroid. You can move the sphere by dragging (from its center) to match the capside.

  6. To pick the next capside, press the letter n on the keyboard. Now you’ll be able to pick the next capside by repeating steps 4-6.

  7. Once you have annotated all the spheres in the tomogram, click on the save spheres button on the lower left of the GUI. This will save the annotations in a file called TS_01_spheres.star in the Picks/job007/annotations folder.

  8. Move on to the next tomogram by selecting its name under tomograms on the bottom left of the GUI and repeat steps 3-7.

Example image

Once you finished annotating all the tomograms, close the Napari picker window. If everything is successful you’ll see TS_01_spheres.star TS_03_spheres.star files in the Picks/job007/annotations folder. A combined particle star file will be generated at Picks/job007/particles.star. This file will be used for the next step of particle extraction.

For a complete account on particle picking in Napari Picker can be found in the RELION STA tutorial, Picking in Napari picker.

7.2. How to run Napari picker locally?

For this, you’ll need to install the Napari picker in your local system (aka laptop). As far as our experience goes, local installation of RELON will bring all the necessary tools into your local system.

7.3. Local installation of Napari

We’ll install Napari in a new conda environmenet in the local system.

git clone https://github.com/3dem/relion.git  # Clone RELION repository
git checkout ver5.0                           # Checkout to ver5.0 branch

conda create -n relion-picker python=3.10     # Create relion-picker conda env
conda activate relion-picker                  # activate the conda env

pip install '.[.vis]'                         # Install python modules listed in pyproject.toml
                                              # including Napari components
conda deactivate
conda activate relion-picker

7.4. Running Napari locally

Navigate to the project folder where you have copied the Tomograms folder. Then

mkdir -p Picks/job007                         # Make Picks/job007 dir for picking
relion_tomo_pick spheres --tilt-series-star-file Tomograms/job006/tomograms.star --output-directory Picks/job007

This will open Napari picker in your local system. Do the sphare annotation as explained in the Relion tutorial [link below]. Once you’ve annotated all the spheres in one tomograms click Save spheres button on the lower left and move on to next tomograms. At the end of annotation of all tomograms, close Napari-picker window. If everything is successful you’ll see TS_01_spheres.star TS_03_spheres.star files in the Picks/job007/annotations folder.

Once you have annotations, the next step is to do the sampling on the spheres to generate particle coordinates. To do that,

mkdir -p Picks/job008                         # Make Picks/job008 dir for particles
relion_tomo_get_particle_poses spheres --tilt-series-star-file Tomograms/job006/tomograms.star --annotations-directory Picks/job007/annotations --output-directory Picks/job008/ --spacing-angstroms 60

This will generate and write out particles into Picks/job008/particles.star. This is the particle.star file you’ll use for next steps. Copy this file to your Doppio project folder and use it for particle extraction.

In this example, we use sphere annotation of the locally installed Napari-picker, but you’ll be able to use its other picking modes as explained in the Relion tutorial below:

Relion Particle Picking job documentation.

7.5. EulerMate Particle Picking

TODO