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