Debian Codegraph @

docs/source/tutorial/s2_pdb2sas.rst

raw
1 Theoretical profiles and fitting from models – PDB2SAS (DENSS) in RAW
2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3 .. _denss_pdb2sas_tutorial:
4
5 RAW has a built-in method to calculate theoretical scattering profiles from atomic
6 models and fit them to experimental data. This method is based on the DENSS PDB2SAS
7 calculator (corresponding to the DENSS command line tool called denss.pdb2mrc.py).
8 The purpose and output of PDB2SAS is similar to that of CRYSOL, but uses a fundamentally
9 different algorithm. PDB2SAS calculates a theoretical scattering profile from an atomic
10 model by first calculating a real space electron density map for the atoms in vacuo, the
11 excluded solvent, and the hydration shell, and then performs a Fourier transform and
12 spherical averaging of intensities to generate the 1D SAXS profile. PDB2SAS allows you
13 to fit the excluded solvent and hydration shell to best match experimental data.
14
15 If you use RAW to run PDB2SAS, in addition to citing the RAW paper, please
16 cite the paper given `here. <https://www.cell.com/biophysj/abstract/S0006-3495(23)00670-7>`_
17
18 The written version of the tutorial follows.
19
20 #. The easiest way to generate a theoretical profile in RAW using PDB2SAS
21 is simply to plot a **.pdb** file. In the Files Control
22 Panel go to the **theory_data** folder, select the **1XIB_4mer.pdb**
23 and click the plot button.
24
25 * *Note:* **.cif** files are not currently supported in PDB2SAS.
26
27 * *Note:* PDB2SAS is the default calculator in RAW. However,
28 it is possible that it has been changed to CRYSOL by a user.
29 If so, you can reset the default calculator to PDB2MRC by going to
30 Options->Advanced Options->General Settings and selecting PDB2SAS
31 in the "Default structure calculator" drop down menu.
32
33 #. After the calculation is done, RAW will plot the theoretical profile
34 from PDB2SAS on the profiles plot. You should see one profile,
35 **1XIB_4mer.dat**
36
37 |theory_pdb2sas_load_model_png|
38
39 #. You can also generate a theoretical profile using the PDB2SAS window in RAW.
40 This gives you more control over the parameters used to generate the profile,
41 using the plot button simply uses the default parameters. Select the
42 "Tools->DENSS->PDB2SAS" menu option to open the PDB2SAS window.
43
44 |theory_pdb2sas_menu_png|
45
46 #. In the PDB2SAS window, in the models section use the Add button to add
47 the **1XIB_4mer.pdb** file to the list of models to calculate a theoretical
48 profile from.
49
50 |theory_pdb2sas_model_add_png|
51
52 #. Click the "Start" button to calculate the theoretical scattering profile
53 for the model.
54
55 * *Note:* The Status will change to "Running calculation" while running
56 and then to "Finished calculation" when finished.
57
58 |theory_pdb2sas_start_png|
59
60 #. After the calculation finishes, the theoretical profile will display in the
61 plot on the right side of the window, and parameters from the profile will
62 be shown in the list at the bottom right of the window.
63
64 * *Note:* Not all parameters will display. The Data and Chi^2
65 fields are only calculated if the model is fit to data.
66
67 |theory_pdb2sas_results1_png|
68
69 #. The PDB2SAS window can also be used to fit the model against experimental
70 data. Go back to the Files Control Panel and load in the **glucose_isomerase.dat**
71 data. Return to the PDB2SAS window. In the Experimental data section use the
72 Add button, check the **glucose_isomerase.dat** item in the dialog that
73 appears, and then click OK to add the **glucose_isomerase.dat** experimental data to the
74 list of data you can fit a model against.
75
76 * *Note:* Only data that is loaded into RAW can be added to the PDB2SAS
77 experimental data list.
78
79 |theory_pdb2sas_data_add_png|
80
81 #. Click the Start button to calculate the theoretical scattering profile and
82 fit it to the data. After the calculation finishes you'll see both the
83 theoretical profile, the data, and the uncertainty normalized residual
84 plotted in the right plot, as well as the parameters from the theoretical
85 profile in the list at the bottom right.
86
87 * *Note:* This will now have all parameters, including the Data and Chi^2
88 fields that were missing when you calculated a theoretical profile
89 without fitting.
90
91 |theory_pdb2sas_results2_png|
92
93 #. Click the OK button to close the PDB2SAS window and send the calculated
94 theoretical scattering profile to the Profiles plot. It will appear as
95 **1XIB_4mer_glucose_isomerase_FIT** in the Profiles Control Panel.
96
97 #. You can also load more than one model and/or profile into the PDB2SAS window
98 to calculate multiple profiles at once. Load the **polymerase.dat**
99 experimental data into RAW. Select both the polymerase and GI profiles in the
100 Profiles Control Panel, right click on the **polymerase.dat** profile and select
101 "Other Analysis->Fit Model (DENSS PDB2SAS)". This will open the PDB2SAS window with
102 the selected profiles already loaded in the Experimental Data section.
103
104 |theory_pdb2sas_right_click_png|
105
106 #. Add the **1XIB_4mer.pdb** (GI) and **2pol.pdb** (polymerase) models to the
107 PDB2MRC model section.
108
109 #. Uncheck the **2pol.pdb** model in the Models list. Only items that are checked
110 are used for calculation, so this will let you fit just the **1XIB_4mer.pdb**
111 model.
112
113 |theory_pdb2sas_model_select_png|
114
115 #. Click the Start button to fit the **1XIB_4mer.cif** model against both experimental
116 profiles. After the calculation finishes you'll see both experimental profiles and the
117 theoretical profile fit to both measured profiles.
118
119 * *Question:* Which dataset does the model fit better?
120
121 * *Try:* Turn off the 1XIB_4mer model and turn on the 2pol model and see
122 how that fits both profiles.
123
124 |theory_pdb2sas_results3_png|
125
126 #. You can also fit multiple models against a single profile. Check both
127 the **1XIB_4mer.pdb** and **2pol.pdb** entries in the models list
128 and uncheck the **glucose_isomerase.dat** experimental data.
129
130 |theory_pdb2sas_data_select_png|
131
132 #. Click the Start button to fit both models against the polymerase data.
133
134 * *Question:* Which model fits the profile better?
135
136 * *Try:* Turn off the polymerase profile and turn on the GI profile
137 and see how each model fits that data.
138
139 * *Tip:* You can also calculate the theoretical scattering profile from
140 multiple models without fitting against data. To do this, uncheck all the
141 data items and calculate the 'minimal' theoretical profiles.
142
143 |theory_pdb2sas_results4_png|
144
145 #. You can fit multiple models against multiple profiles. Check both models
146 and both experimental profiles. Click the start button to fit both models
147 against both experimental profiles.
148
149 #. You can export the values in the results table to a csv file. Right click
150 on the table and select Export Data. Save the .csv file in the **theory_data**
151 folder.
152
153 * *Try:* Open the .csv file in Excel or another spreadsheet program.
154
155 |theory_pdb2sas_export_data_png|
156
157 #. Click OK to close the PDB2SAS window and send all the fits to the Profiles
158 plot and control panel.
159
160 #. You can also adjust the settings for running PDB2SAS from the PDB2SAS
161 window. We'll do that using some example data. Load the **SASDP43.dat**
162 experimental data into RAW.
163
164 * *Note:* This dataset is from the `SASDP43 entry in the SASBDB
165 <https://www.sasbdb.org/data/SASDP43/>`_
166
167 #. Open a PDB2SAS window and add the **Brpt55_M_Zn.pdb** model and the
168 **SASDP43.dat** data.
169
170 #. Run the PDB2SAS fitting with the default settings.
171
172 * *Note:* Notice that the maximum q value for the theoretical fit does
173 not extend all the way to the experimental maximum. This is because
174 the default number of samples (128) is too small. This protein is elongated
175 causing the real space voxel size to be quite large, which results
176 in the maximum q value to be too small.
177
178 #. Open a second PDB2MRC window and add the same model and data to it.
179 Set the N samples (real space) option to 256. Run the PDB2SAS fitting
180 with these updated settings.
181
182 |theory_pdb2sas_nsamples_png|
183
184 #. You should see that the result using 256 samples extends to the full q range
185 of the experimental data.
186
187 * *Note:* Setting the N samples to a power of 2 (64, 128, 256, etc.) is best
188 for calculation speed, though any even number can be used.
189
190 * *Note:* You can explicitly set the voxel size in the Advanced Settings,
191 which will override N samples.
192
193 |theory_pdb2sas_results5_png|
194
195 #. There are also a number of advanced settings you can set. Expand the
196 Advanced Setting section and (if necessary) scroll down to see the
197 different options. The settings are explained in detail in the PDB2SAS
198 manual.
199
200 * *Note:* Common settings to change are the solvent density and hydration
201 shell contrast (requires turning off the "Fit solvent" and "Fit hydration
202 shell" options).
203
204 * *Tip:* If you need all the PDB2SAS outputs (such as the .dat and .fit files)
205 you can check the "Save all outputs to folder" option and provide
206 a folder to save to by clicking the "..." button after the "Save to" field.
207
208 |theory_pdb2sas_settings_png|
209
210 #. Close the PDB2SAS windows with the OK button to save the fit results to
211 the Profiles plot and control panel.
212
213 #. You can save information from a theoretical profile generated by PDB2SAS in RAW
214 as part of a pdf report. Right click on the **1XIB_4mer_glucose_isomerase_FIT**
215 item in the Profiles control panel and select "Save report". In the window
216 that opens click "Save Report" and save the pdf report. If you open the
217 report you will see the usually summary pots and a table with a summary of
218 theoretical profile parameters.
219
220 |theory_pdb2sas_report_png|
221
222 .. |theory_pdb2sas_load_model_png| image:: images/theory_pdb2sas_load_model.png
223 :target: ../_images/theory_pdb2sas_load_model.png
224
225 .. |theory_pdb2sas_menu_png| image:: images/theory_pdb2sas_menu.png
226 :target: ../_images/theory_pdb2sas_menu.png
227 :width: 400 px
228
229 .. |theory_pdb2sas_model_add_png| image:: images/theory_pdb2sas_model_add.png
230 :target: ../_images/theory_pdb2sas_model_add.png
231
232 .. |theory_pdb2sas_start_png| image:: images/theory_pdb2sas_start.png
233 :target: ../_images/theory_pdb2sas_start.png
234 :width: 300 px
235
236 .. |theory_pdb2sas_results1_png| image:: images/theory_pdb2sas_results1.png
237 :target: ../_images/theory_pdb2sas_results1.png
238
239 .. |theory_pdb2sas_data_add_png| image:: images/theory_pdb2sas_data_add.png
240 :target: ../_images/theory_pdb2sas_data_add.png
241
242 .. |theory_pdb2sas_results2_png| image:: images/theory_pdb2sas_results2.png
243 :target: ../_images/theory_pdb2sas_results2.png
244
245 .. |theory_pdb2sas_right_click_png| image:: images/theory_pdb2sas_right_click.png
246 :target: ../_images/theory_pdb2sas_right_click.png
247 :width: 400 px
248
249 .. |theory_pdb2sas_model_select_png| image:: images/theory_pdb2sas_model_select.png
250 :target: ../_images/theory_pdb2sas_model_select.png
251 :width: 300 px
252
253 .. |theory_pdb2sas_results3_png| image:: images/theory_pdb2sas_results3.png
254 :target: ../_images/theory_pdb2sas_results3.png
255
256 .. |theory_pdb2sas_data_select_png| image:: images/theory_pdb2sas_data_select.png
257 :target: ../_images/theory_pdb2sas_data_select.png
258 :width: 300 px
259
260 .. |theory_pdb2sas_results4_png| image:: images/theory_pdb2sas_results4.png
261 :target: ../_images/theory_pdb2sas_results4.png
262
263 .. |theory_pdb2sas_export_data_png| image:: images/theory_pdb2sas_export_data.png
264 :target: ../_images/theory_pdb2sas_export_data.png
265
266 .. |theory_pdb2sas_nsamples_png| image:: images/theory_pdb2sas_nsamples.png
267 :target: ../_images/theory_pdb2sas_nsamples.png
268 :width: 300 px
269
270 .. |theory_pdb2sas_results5_png| image:: images/theory_pdb2sas_results5.png
271 :target: ../_images/theory_pdb2sas_results5.png
272
273 .. |theory_pdb2sas_settings_png| image:: images/theory_pdb2sas_settings.png
274 :target: ../_images/theory_pdb2sas_settings.png
275 :width: 300 px
276
277 .. |theory_pdb2sas_report_png| image:: images/theory_pdb2sas_report.png
278 :target: ../_images/theory_pdb2sas_report.png
279 :width: 450 px