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