.. Doppio Tomography Tutorial documentation master file, created by sphinx-quickstart on Tue Feb 18 13:09:38 2025. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Align tilt-series ==================== In Doppio, there are two wrappers around IMOD and AreTomo2 for tilt-series alignement. Unlike in RELION tomography pipeline, those wrappers are separate tools and are located under **Tilt Series Alignment** section in the :purple:`NEW JOB` tab in Doppio GUI. .. note:: Both IMOD and AreTomo2 executables are required to be on your PATH to use these tools. Tilt-series alignement with IMOD ----------------------------------- IMOD offers two ways to align tilt-series, fiducial-based and patch-tracking based. In Doppio, we have wrappers for both. To run fiducial-based alignment, go to :purple:`NEW JOB` tab in Doppio GUI and find the **Tilt Series Alignment** section and choose **IMOD fiducial** job. For tutorial data, we use fiducial-based alignment. The job parameters are as follows: .. image:: ../_static/images/STA/imod-fiducials-job-params.png :alt: Example image :width: 100% :align: center -------------------- If you do not have fiducials in your tilt-series, then you can use patch-tracking based alignment. To run patch-tracking based alignment, go to :purple:`NEW JOB` tab in Doppio GUI and find the **Tilt Series Alignment** section and choose **IMOD patch-tracking** job. .. warning:: Tutorial data has fiducials. This is just for demonstration. It is recommended to use fiducials whenever possible. The job parameters are shown in the image below. .. image:: ../_static/images/STA/imod-patchtract-job-params.png :alt: Example image :width: 100% :align: center -------------------------------- Manual improvement of the IMOD alignment [patch-tracking] ------------------------------------------------------------ Sometimes, the automatic alignment may not be perfect. In such cases, you can manually improve the alignment using IMOD's 3dmod tool. To do this, first run the IMOD fiducial or patch-tracking job as described above. The output of this job is in the ``AlignTiltSeries/job005/`` directory. The file ``aligned_tilt_series.star`` is the umbrella star file that contains the alignment information for all tilt-series. Inside this directory, there is a sub-directory called ``external`` which contains sub directories for each tilt-series, e.g., ``external/TS_01/``. Inside this directory, there are files required to open the tilt-series in etomo. To improve the alignment manually, open the etomo GUI by running the following command in the terminal, e.g. ``etomo TS_01.edf``. In the etomo GUI, you can now improve the alignment by modifying the fiducial model etc. (Obviously, this step will require some knowledge of IMOD, which is outside the scope of this tutorial). Once you are satisfied with the alignment, make sure to finish all the steps you started in etomo GUI, and exit. Next, go back to your alignment job in Doppio GUI and click on the :purple:`Continue` button. That will update the ``aligned_tilt_series.star`` file and all the associated metadata files with the new alignment information. Tilt-series alignement with AreTomo2 --------------------------------------- AreTomo2 is a GPU-accelerated tilt-series alignment tool. It can do fiducial-less alignment and dose-weighting. To run AreTomo2 alignment, go to :purple:`NEW JOB` tab in Doppio GUI and find the **Tilt Series Alignment** section and choose **AreTomo2** job. The job parameters are as follows: .. image:: ../_static/images/STA/aretomo2-job-params.png :alt: Example image :width: 100% :align: center Mandatory parameters are the `Input tilt series` and `Estimated tomogram thickness (nm)`. The first parameter is the ``selected_tilt_series.star`` file from the previous step. The second parameter is a proxy to `-AlignZ` parameter in AreTomo2, and is important for alignment accuracy. It is the z-height for alignment and should be close to the actual sample thickness. If the sample is FIB-milled, most of the time you know the lamella thickness. You can feed it in here. If you don't know the thickness or cannot make any educational guesses about it, you can do a global only alignment and 3D reconstruction in AreTomo2 (outside of Relion) with a large binning factor. Then measure the thickness of the sample in the reconstruction (look at the XZ slice and locate the signal region only) and re-run the AreTomo2 job inside Relion with that thickness. Note that the thickness should be converted to nm from pixels using the pixel size of the reconstruction. .. math:: thickness = \frac{AlignZ}{pixel~size} Inspecting the alignment results ------------------------------------ You can inspect the aligned tilt series in the :purple:`RESULTS` tab in Doppio GUI. Use the slider to navigate through the tilt series. To move to the next tilt series, click on the right arrow. The tilt series is down sampled by factor 6 for visualization purposes. A good alignment will guarantee a good tomogram in the next step. At the moment , Doppio only allows you to you to judge the quality of the alignment by visually, but in future releases, we plan to add more quantitative tools to assess the alignment quality. However, those metrics are already available in IMOD and AreTomo2 standalone packages. .. image:: ../_static/images/STA/imod-fiducial-aligned-view.png :alt: Example image :width: 100% :align: center More information about IMOD and AreTomo2 tilt-series alignment jobs can be found in the RELION documentation below. `Relion IMOD Tilt Series Alignment job documentation `_.