| 1 |
3D reconstruction with bead models – DAMMIF/N and DAMAVER in RAW |
| 2 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 3 |
.. _dammif: |
| 4 |
|
| 5 |
Shape reconstruction in SAXS is typically done using bead models (also called dummy atom models, |
| 6 |
or DAMs). The most common program used to generate these shapes is DAMMIF (and, to a lesser |
| 7 |
degree, DAMMIN) from the ATSAS package. We will use RAW to run DAMMIF/N. Because the shape |
| 8 |
reconstruction is not unique, a number of distinct reconstructions are generated, and then a |
| 9 |
consensus shape is made from the average of these reconstructions. The program DAMAVER from |
| 10 |
the ATSAS package is the most commonly used program for building consensus shapes. Note that you need |
| 11 |
:ref:`ATSAS installed <atsas>` to do this part of the tutorial. Also, this tutorial |
| 12 |
uses ATSAS 3.1.1, some pieces may be slightly different on older versions of ATSAS, |
| 13 |
please see previous versions of this tutorial in that case. |
| 14 |
|
| 15 |
This is not a tutorial on basic principles and best practices for doing bead |
| 16 |
model reconstructions. For that, please see the :ref:`SAXS tutorial <saxs_bead_models>`. |
| 17 |
|
| 18 |
If you use RAW to run DAMMIF or associated programs, in addition to citing the |
| 19 |
RAW paper, please cite the papers given in the: |
| 20 |
|
| 21 |
* `DAMMIF manual <https://biosaxs-com.github.io/atsas/4.0.0/manuals/dammif.html>`_ |
| 22 |
* `DAMMIN manual <https://biosaxs-com.github.io/atsas/4.0.0/manuals/dammin.html>`_ |
| 23 |
* `DAMAVER manual <https://biosaxs-com.github.io/atsas/4.0.0/manuals/damaver.html>`_ |
| 24 |
* `SASRES manual <https://biosaxs-com.github.io/atsas/4.0.0/manuals/sasres.html>`_ |
| 25 |
* `CIFSUP manual <https://biosaxs-com.github.io/atsas/4.0.0/manuals/cifsup.html>`_ |
| 26 |
|
| 27 |
as appropriate. |
| 28 |
|
| 29 |
A video version of this tutorial is available: |
| 30 |
|
| 31 |
.. raw:: html |
| 32 |
|
| 33 |
<style>.embed-container { position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; max-width: 100%; } .embed-container iframe, .embed-container object, .embed-container embed { position: absolute; top: 0; left: 0; width: 100%; height: 100%; }</style><div class='embed-container'><iframe src='https://www.youtube.com/embed/umxeTsgYg58' frameborder='0' allowfullscreen></iframe></div> |
| 34 |
|
| 35 |
The written version of the tutorial follows. |
| 36 |
|
| 37 |
#. Clear all of the data in RAW. Load the **glucose_isomerase.out** file that you saved in the |
| 38 |
**reconstruction_data** folder in a previous part of the tutorial. |
| 39 |
|
| 40 |
* *Note:* If you haven’t done the previous part of the tutorial, or forgot to save |
| 41 |
the results, you can find the **glucose_isomerase.out** file in the |
| 42 |
**reconstruction_data/gi_complete** folder. |
| 43 |
|
| 44 |
#. Right click on the **glucose_isomerase.out** item in the IFT list. Select the “Bead Model (DAMMIF/N)” option. |
| 45 |
|
| 46 |
#. Running DAMMIF generates a lot of files. Click the “Select” button for the output directory, |
| 47 |
make a new folder in the **reconstruction_data** directory called **gi_dammif** and select |
| 48 |
that folder. |
| 49 |
|
| 50 |
#. Change the number of reconstructions to 5. |
| 51 |
|
| 52 |
* *Note:* It is generally recommended that you do 15-20 reconstructions. However, |
| 53 |
for the purposes of this tutorial, 5 are enough. |
| 54 |
|
| 55 |
* *Note:* For final reconstructions for a paper, DAMMIF should be run in Slow mode. |
| 56 |
For this tutorial, or for obtaining an initial quick look at results, Fast mode is fine. |
| 57 |
|
| 58 |
#. Uncheck the "Refine average with dammin" checkbox. |
| 59 |
|
| 60 |
* *Note:* For final reconstructions for a paper, DAMMIN refinement should be done. However, it |
| 61 |
is quite slow, so for the purposes of this tutorial we won't do it. |
| 62 |
|
| 63 |
|
| 64 |
#. RAW can align the DAMMIF/N output with a PDB/mmCIF structure using CIFSUP from the |
| 65 |
ATSAS package. To do so, check the 'Align output to PDB/mmCIF' box and select |
| 66 |
the **1XIB_4mer.pdb** file in the **reconstruction_data/gi_complete** folder. |
| 67 |
|
| 68 |
* *Tip:* If you're not sure if you selected the correct file, hovering |
| 69 |
your mouse over the filename will show the full path to the file. |
| 70 |
|
| 71 |
|dammif_run_tab_png| |
| 72 |
|
| 73 |
#. Click the “Start” button. |
| 74 |
|
| 75 |
* *Note:* The status panel will show you the overall status of the reconstructions. |
| 76 |
You can look at the detailed status of each run by clicking the appropriate tab in |
| 77 |
the log panel. |
| 78 |
|
| 79 |
#. Note that by default the envelopes are aligned, clustered, and averaged using DAMAVER, |
| 80 |
and then the aligned and averaged profile is refined using DAMMIN. |
| 81 |
|
| 82 |
* Some settings are accessible in the panel, and all settings can be changed in the |
| 83 |
advanced settings panel. |
| 84 |
|
| 85 |
#. Wait for all of the DAMMIF runs, DAMAVER, and alignment to finish. |
| 86 |
Depending on the speed of your computer this could take a bit. |
| 87 |
|
| 88 |
#. Once the reconstructions are finished, the window should automatically switch to the |
| 89 |
results tab. If it doesn't, click on the results tab. |
| 90 |
|
| 91 |
|dammif_results_png| |
| 92 |
|
| 93 |
#. The results panel summarizes the results of the reconstruction run. At the top of the |
| 94 |
panel there is the AMBIMETER evaluation of how ambiguous the reconstructions might be |
| 95 |
(see previous tutorial section). If DAMAVER was run, there are results from the normalized |
| 96 |
spatial discrepancy (NSD), showing the mean and standard deviation of the NSD, as well as |
| 97 |
how many of the reconstructions were included in the average. If DAMAVER was run on 3 or |
| 98 |
more reconstructions, and ATSAS >=2.8.0 is installed, there will be the output of SASRES |
| 99 |
which provides information on the resolution of the reconstruction. If DAMAVER |
| 100 |
found more than one cluster, the number of clusters and information |
| 101 |
on each cluster is shown. Note that DAMCLUST (ATSAS <=3.1.0) provided more information |
| 102 |
about the clusters, so some fields will be blank with ATSAS >=3.1.1. |
| 103 |
|
| 104 |
#. Information on each individual model is shown at the bottom. The summary tab |
| 105 |
gives the model chi squared, |Rg|, |Dmax|, excluded volume, molecular |
| 106 |
weight estimated from the excluded volume, and, if appropriate, mean NSD |
| 107 |
of the model. |
| 108 |
|
| 109 |
* Any models rejected from the average by DAMAVER will be shown in red in |
| 110 |
the summary tab list. |
| 111 |
|
| 112 |
* *Tip:* The model highlighted in blue in the summary tab is the 'most |
| 113 |
probable' model, this can be used as your final bead model instead of |
| 114 |
doing a DAMMIN refinement. |
| 115 |
|
| 116 |
* *Note:* DAMMIN in ATSAS >=3.1.0 doesn't provide the |Dmax| value for |
| 117 |
the model. |
| 118 |
|
| 119 |
#. Also, each individual model has a tab which shows the data, the model fit, |
| 120 |
and the residuals. |
| 121 |
|
| 122 |
|dammif_results_fit_png| |
| 123 |
|
| 124 |
#. The results summary shown in Summary tab is automatically saved as a |
| 125 |
**<prefix>_dammif_results.csv** csv file, e.g. for this data as |
| 126 |
**glucose_isomerase_dammif_results.csv**. All the plots shown on the individual model |
| 127 |
tabs are automatically saved as a multi-page pdf file with the same name. |
| 128 |
|
| 129 |
#. Click on the Viewer tab to open the model viewer. |
| 130 |
|
| 131 |
* *Note:* The model viewer is intended for a fast first look at the results. It is |
| 132 |
not currently up to the standards of a program like pyMOL. |
| 133 |
|
| 134 |
|dammif_viewer_png| |
| 135 |
|
| 136 |
#. Click and drag the model to spin it. |
| 137 |
|
| 138 |
* Note: For glucose isomerase, it should look more or less like a flattened sphere. |
| 139 |
|
| 140 |
#. Right click and drag the model to zoom in and out. |
| 141 |
|
| 142 |
#. Use the “Model to display” menu in the Viewer Controls box to change which |
| 143 |
reconstruction is displayed. |
| 144 |
|
| 145 |
#. Click the “Close” button when you are finished looking at the results and reconstructions. |
| 146 |
|
| 147 |
#. The results from individual DAMMIF runs are saved in the selected output folder |
| 148 |
with the name **<prefix>_xx**, where *xx* is the run number: 01, 02, etc. For |
| 149 |
this tutorial, that would be **glucose_isomerase_01**, **glucose_isomerase_02**, and so on. The |
| 150 |
different files produced are described in the `DAMMIF manual <hhttps://biosaxs-com.github.io/atsas/4.0.0/manuals/dammif.html#dammif-output-files>`_. |
| 151 |
|
| 152 |
* *Note:* Generally, the file of interest is the **-1.cif** file, in this case |
| 153 |
**glucose_isomerase_01-1.cif**, **glucose_isomerase_02-1.cif**, etc. |
| 154 |
|
| 155 |
#. If averaging was done with DAMAVER, the results are saved in the selected output |
| 156 |
folder with the given prefix, in this case **glucose_isomerase**. The output |
| 157 |
files generated are described in the `DAMAVER manual <https://biosaxs-com.github.io/atsas/4.0.0/manuals/damaver.html>`_. |
| 158 |
|
| 159 |
* *Note:* Generally, the file of interest is the generated damfilt mmCIF: |
| 160 |
**<prefix>_damfilt.cif**. For this tutorial, that would be |
| 161 |
**glucose_isomerase_damfilt.cif**. |
| 162 |
|
| 163 |
#. If multiple clusters were found, the results are saved in the selected output |
| 164 |
folder with the given prefix (for this tutorial, **glucose_isomerase**). The files generated |
| 165 |
are described in the `DAMAVER manual <https://www.embl-hamburg.de/biosaxs/manuals/damaver.html#>`_. |
| 166 |
|
| 167 |
#. If refinement was done with DAMMIN, the results are saved in the selected output |
| 168 |
folder as **refine_<prefix>**, e.g. for this tutorial **refine_glucose_isomerase**. The files |
| 169 |
generated are described in the `DAMMIN manual <https://biosaxs-com.github.io/atsas/4.0.0/manuals/dammin.html#dammin-output-files>`_. |
| 170 |
|
| 171 |
* *Note:* Generally, the file of interest is the **-1.cif** file, in this case |
| 172 |
**refine_glucose_isomerase-1.cif**. |
| 173 |
|
| 174 |
#. If alignment to a reference PDB/mmCIF was done with CIFSUP, the files aligned |
| 175 |
depend on what other processing was done. |
| 176 |
|
| 177 |
* If refinement was done, then there will be a single file named |
| 178 |
**refine_<prefix>_-1_aligned.cif**. For this tutorial, |
| 179 |
**refine_glucose_isomerase-1_aligned.cif**. |
| 180 |
|
| 181 |
* If no refinement is done but averaging is done, then the |
| 182 |
damaver and damfilt results are aligned, as well as the most |
| 183 |
probable model (the blue highlighted model in the summary panel). |
| 184 |
The associated filenames would be **<prefix>_damaver_aligned.cif**, |
| 185 |
**<prefix>_damfilt_aligned.cif**, and **<prefix>_##_-1_aligned.cif** |
| 186 |
where ## is the model number of the most probable model. For this tutorial, |
| 187 |
**glucose_isomerase_damaver_aligned.cif**, |
| 188 |
**glucose_isomerase_damfilt_aligned.cif**, and |
| 189 |
**glucose_isomerase_##-1_aligned.cif**. |
| 190 |
|
| 191 |
* If no refinement or averaging is done, then every calculated |
| 192 |
model is aligned. The associated filenames would be |
| 193 |
**<prefix>_##-1_aligned.cif** where ## is the model number of a model. |
| 194 |
For this tutorial, that is **glucose_isomerase_##-1_aligned.cif**. |
| 195 |
|
| 196 |
#. You can save a summary table of the DAMMIF results with the pdf report that |
| 197 |
RAW can make. Close the DAMMIF/N window, right click on the **glucose_isomerase.out** |
| 198 |
item in the IFT control panel and select "Save report". Use the "Add DAMMIF/N results |
| 199 |
.csv" button to add the **glucose_isomerase_dammif_results.csv** to the |
| 200 |
report. Then click "Save Report" and save the pdf report. If you open the |
| 201 |
report you will see a summary of the run parameters and numerical results |
| 202 |
saved as a table. |
| 203 |
|
| 204 |
|dammif_report_png| |
| 205 |
|
| 206 |
.. |dammif_run_tab_png| image:: images/dammif_run_tab.png |
| 207 |
:target: ../_images/dammif_run_tab.png |
| 208 |
|
| 209 |
.. |dammif_results_png| image:: images/dammif_results.png |
| 210 |
:target: ../_images/dammif_results.png |
| 211 |
|
| 212 |
.. |dammif_results_fit_png| image:: images/dammif_results_fit.png |
| 213 |
:target: ../_images/dammif_results_fit.png |
| 214 |
|
| 215 |
.. |dammif_viewer_png| image:: images/dammif_viewer.png |
| 216 |
:target: ../_images/dammif_viewer.png |
| 217 |
|
| 218 |
.. |dammif_report_png| image:: images/dammif_report.png |
| 219 |
:target: ../_images/dammif_report.png |
| 220 |
:width: 300 px |
| 221 |
|
| 222 |
.. |Rg| replace:: R\ :sub:`g` |
| 223 |
|
| 224 |
.. |Dmax| replace:: D\ :sub:`max` |