Debian Codegraph @

docs/source/tutorial/s2_crysol.rst

raw
1 Theoretical profiles and fitting from models – CRYSOL in RAW
2 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3 .. _crysol_tutorial:
4
5 One of the most useful things to do with SAXS data is to compare the data
6 against high resolution models (such as crystallography or CryoEM structures or
7 AlphaFold models). You can generate theoretical scattering profiles from
8 high resolution models, such as pdb models, independent of the experimental
9 data. You can also fit these generated theoretical scattering profiles against
10 the experimental SAXS data.
11
12 While it might seem that the most rigorous approach would be to generate a
13 theoretical profile independent of the experimental data, this 'minimal' approach
14 often fails to produce good fits even when the model and solution structure are
15 in good agreement. This is because there are contributions from the solvent,
16 particularly the hydration layer and the excluded volume, that are hard to model
17 and that most theoretical scattering profile calculators treat as fit parameters.
18 So to get the most accurate understanding of whether your model fits the data,
19 you should actually fit the data as part of the process of generating the
20 theoretical profile, rather than generating a 'minimal' theoretical profile
21 and comparing to the data.
22
23 One of the most common programs to generate theoretical scattering profiles
24 is the CRYSOL program in the ATSAS package. We will use RAW to run CRYSOL. Note
25 that you need :ref:`ATSAS installed <atsas>` to do this part of the tutorial.
26
27 If you use RAW to run CRYSOL, in addition to citing the RAW paper, please
28 cite the paper given in the `CRYSOL manual. <https://biosaxs-com.github.io/atsas/4.0.0/manuals/crysol.html>`_
29
30 The written version of the tutorial follows.
31
32 #. The easiest way to generate a theoretical profile in RAW using CRYSOL
33 is simply to plot a **.pdb** or **.cif** file. In the Files Control
34 Panel go to the **theory_data** folder, select the **1XIB_4mer.pdb**
35 and click the plot button.
36
37 #. After the calculation is done, RAW will plot the theoretical profiles
38 from CRYSOL on the profiles plot. You should see two profiles,
39 **1XIB_4mer.abs** and **1XIB_4mer.int**
40
41 * *Note:* The difference between **.abs** and **.int** results from CRYSOL
42 is simply the overall scale factor. The **.abs** is on an absolute
43 scale of 1/(cm*(mg/ml)), while **.int** is on an arbitrary scale.
44 Generally **.abs** is probably more useful, since many beamlines
45 calibrate their experimental data to an absolute scale, so this result
46 will be relatively close in overall scale to what you measure.
47
48 |theory_crysol_load_model_png|
49
50 #. You can also generate a theoretical profile using the CRYSOL window in RAW.
51 This gives you more control over the parameters used to generate the profile,
52 using the plot button simply uses the default parameters. Select the
53 "Tools->ATSAS->CRYSOL" menu option to open the CRYSOL window.
54
55 |theory_crysol_menu_png|
56
57 #. In the CRYSOL window, in the models section use the Add button to add
58 the **1XIB_4mer.pdb** file to the list of models to calculate a theoretical
59 profile from.
60
61 |theory_crysol_model_add_png|
62
63 #. Click the "Start" button to calculate the theoretical scattering profile
64 for the model.
65
66 * *Note:* The Status will change to "Running calculation" while running
67 and then to "Finished calculation" when finished.
68
69
70 |theory_crysol_start_png|
71
72 #. After the calculation finishes, the theoretical profile will display in the
73 plot on the right side of the window, and parameters from the profile will
74 be shown in the list at the bottom right of the window.
75
76 * *Note:* Not all parameters will display. The Data, Chi^2, and Prob.
77 fields are only calculated if the model is fit to data.
78
79 |theory_crysol_results1_png|
80
81 #. The CRYSOL window can also be used to fit the model against experimental
82 data. Go back to the Files Control Panel and load in the **glucose_isomerase.dat**
83 data. Return to the CRYSOL window. In the Experimental data section use the
84 Add button, check the **glocuse_isomerase.dat** item in the dialog that
85 appears, and then click OK to add the **glucose_isomerase.dat** experimental data to the
86 list of data you can fit a model against.
87
88 * *Note:* Only data that is loaded into RAW can be added to the CRYSOL
89 experimental data list.
90
91 |theory_crysol_data_add_png|
92
93 #. Click the Start button to calculate the theoretical scattering profile and
94 fit it to the data. After the calculation finishes you'll see both the
95 theoretical profile, the data, and the uncertainty normalized residual
96 plotted in the right plot, as well as the parameters from the theoretical
97 profile in the list at the bottom right.
98
99 * *Note:* This will now have all parameters, including the Data, Chi^2, and
100 Prob. fields that were missing when you calculated a theoretical profile
101 without fitting.
102
103 |theory_crysol_results2_png|
104
105 #. Click the OK button to close the CRYSOL window and send the calculated
106 theoretical scattering profile to the Profiles plot. It will appear as
107 **1XIB_4mer_glucose_isomerase_FIT** in the Profiles Control Panel.
108
109 #. You can also load more than one model and/or profile into the CRYSOL window
110 to calculate multiple profiles at once. Load the **polymerase.dat**
111 experimental data into RAW. Select both the polymerase and GI profiles in the
112 Profiles Control Panel, right click on the **polymerase.dat** profile and select
113 "Other Analysis->Fit Model (CRYSOL)". This will open the CRYSOL window with
114 the selected profiles already loaded in the Experimental Data section.
115
116 |theory_crysol_right_click_png|
117
118 #. Add the **1XIB_4mer.pdb** (GI) and **2pol.cif** (polymerase) models to the
119 CRYSOL model section.
120
121 #. Uncheck the **2pol.pdb** model in the Models list. Only items that are checked
122 are used for calculation, so this will let you fit just the **1XIB_4mer.cif**
123 model.
124
125 |theory_crysol_model_select_png|
126
127 #. Click the Start button to fit the **1XIB_4mer.cif** model against both experimental
128 profiles. After the calculation finishes you'll see both experimental profiles and the
129 theoretical profile fit to both measured profiles.
130
131 * *Question:* Which dataset does the model fit better?
132
133 * *Try:* Turn off the 1XIB_4mer model and turn on the 2pol model and see
134 how that fits both profiles.
135
136 |theory_crysol_results3_png|
137
138 #. You can also fit multiple models against a single profile. Check both
139 the **1XIB_4mer.pdb** and **2pol.cif** entries in the models list
140 and uncheck the **glucose_isomerase.dat** experimental data.
141
142 |theory_crysol_data_select_png|
143
144 #. Click the Start button to fit both models against the polymerase data.
145
146 * *Question:* Which model fits the profile better?
147
148 * *Try:* Turn off the polymerase profile and turn on the GI profile
149 and see how each model fits that data.
150
151 * *Tip:* You can also calculate the theoretical scattering profile from
152 multiple models without fitting against data. To do this, uncheck all the
153 data items and calculate the 'minimal' theoretical profiles.
154
155 |theory_crysol_results4_png|
156
157 #. You can fit multiple models against multiple profiles. Check both models
158 and both experimental profiles. Click the start button to fit both models
159 against both experimental profiles.
160
161
162 #. You can export the values in the results table to a csv file. Right click
163 on the table and select Export Data. Save the .csv file in the **theory_data**
164 folder.
165
166 * *Try:* Open the .csv file in Excel or another spreadsheet program.
167
168 |theory_crysol_export_data_png|
169
170 #. Click OK to close the CRYSOL window and send all the fits to the Profiles
171 plot and control panel.
172
173 #. You can also adjust the settings for running CRYSOL from the CRYSOL
174 window. We'll do that using some example data. Load the **SASDP43.dat**
175 experimental data into RAW.
176
177 * *Note:* This dataset is from the `SASDP43 entry in the SASBDB
178 <https://www.sasbdb.org/data/SASDP43/>`_
179
180 #. Open a CRYSOL window and add the **Brpt55_M_Zn.pdb** model and the
181 **SASDP43.dat** data.
182
183 #. Run the CRYSOL fitting with the default settings.
184
185 #. Open a second CRYSOL window and add the same model and data to it.
186 Set the harmonics to 100. Run the CRYSOL fitting with these updated settings.
187
188 |theory_crysol_harmonics_png|
189
190 #. You should see that the result using 100 harmonics is a better fit than the
191 result using the default harmonics.
192
193 * *Note:* More harmonics are necessary to get accurate theoretical profiles
194 from high aspect ratio objects. This protein happens to be a long thin
195 rod, so using more harmonics is helpful here. For something globular, like
196 GI, it should make little or no difference. You can test this yourself
197 using the tutorial data.
198
199 |theory_crysol_results5_png|
200
201 #. There are also a number of advanced settings you can set. Expand the
202 Advanced Setting section and (if necessary) scroll down to see the
203 different options. The settings are explained in detail in the CRYSOL
204 manual.
205
206 * *Note:* Common settings to change are the solvent density and contrast
207 (requires turning off the "Fit solvent" option).
208
209 * *Tip:* If you need all the CRYSOL outputs (such as the .log and .alm files)
210 you can check the "Save all outputs to folder" option and provide
211 a folder to save to by clicking the "..." button after the "Save to" field.
212
213 |theory_crysol_settings_png|
214
215 #. Close the CRYSOL windows with the OK button to save the fit results to
216 the Profiles plot and control panel.
217
218 #. You can save information from a theoretical profile generated by CRYSOL in RAW
219 as part of a pdf report. Right click on the **1XIB_4mer_glucose_isomerase_FIT**
220 item in the Profiles control panel and select "Save report". In the window
221 that opens click "Save Report" and save the pdf report. If you open the
222 report you will see the usually summary pots and a table with a summary of
223 theoretical profile parameters.
224
225 |theory_crysol_report_png|
226
227 .. |theory_crysol_load_model_png| image:: images/theory_crysol_load_model.png
228 :target: ../_images/theory_crysol_load_model.png
229
230 .. |theory_crysol_menu_png| image:: images/theory_crysol_menu.png
231 :target: ../_images/theory_crysol_menu.png
232 :width: 400 px
233
234 .. |theory_crysol_model_add_png| image:: images/theory_crysol_model_add.png
235 :target: ../_images/theory_crysol_model_add.png
236
237 .. |theory_crysol_start_png| image:: images/theory_crysol_start.png
238 :target: ../_images/theory_crysol_start.png
239 :width: 300 px
240
241 .. |theory_crysol_results1_png| image:: images/theory_crysol_results1.png
242 :target: ../_images/theory_crysol_results1.png
243
244 .. |theory_crysol_data_add_png| image:: images/theory_crysol_data_add.png
245 :target: ../_images/theory_crysol_data_add.png
246
247 .. |theory_crysol_results2_png| image:: images/theory_crysol_results2.png
248 :target: ../_images/theory_crysol_results2.png
249
250 .. |theory_crysol_right_click_png| image:: images/theory_crysol_right_click.png
251 :target: ../_images/theory_crysol_right_click.png
252 :width: 400 px
253
254 .. |theory_crysol_model_select_png| image:: images/theory_crysol_model_select.png
255 :target: ../_images/theory_crysol_model_select.png
256 :width: 300 px
257
258 .. |theory_crysol_results3_png| image:: images/theory_crysol_results3.png
259 :target: ../_images/theory_crysol_results3.png
260
261 .. |theory_crysol_data_select_png| image:: images/theory_crysol_data_select.png
262 :target: ../_images/theory_crysol_data_select.png
263 :width: 300 px
264
265 .. |theory_crysol_results4_png| image:: images/theory_crysol_results4.png
266 :target: ../_images/theory_crysol_results4.png
267
268 .. |theory_crysol_export_data_png| image:: images/theory_crysol_export_data.png
269 :target: ../_images/theory_crysol_export_data.png
270
271 .. |theory_crysol_harmonics_png| image:: images/theory_crysol_harmonics.png
272 :target: ../_images/theory_crysol_harmonics.png
273 :width: 300 px
274
275 .. |theory_crysol_results5_png| image:: images/theory_crysol_results5.png
276 :target: ../_images/theory_crysol_results5.png
277
278 .. |theory_crysol_settings_png| image:: images/theory_crysol_settings.png
279 :target: ../_images/theory_crysol_settings.png
280 :width: 300 px
281
282 .. |theory_crysol_report_png| image:: images/theory_crysol_report.png
283 :target: ../_images/theory_crysol_report.png
284 :width: 450 px