Debian Codegraph @

docs/source/tutorial/s2_dammif.rst

raw
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`