Theoretical profiles and fitting from models – PDB2SAS (DENSS) in RAW
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. _denss_pdb2sas_tutorial:

RAW has a built-in method to calculate theoretical scattering profiles from atomic
models and fit them to experimental data. This method is based on the DENSS PDB2SAS
calculator (corresponding to the DENSS command line tool called denss.pdb2mrc.py).
The purpose and output of PDB2SAS is similar to that of CRYSOL, but uses a fundamentally
different algorithm. PDB2SAS calculates a theoretical scattering profile from an atomic
model by first calculating a real space electron density map for the atoms in vacuo, the
excluded solvent, and the hydration shell, and then performs a Fourier transform and
spherical averaging of intensities to generate the 1D SAXS profile. PDB2SAS allows you
to fit the excluded solvent and hydration shell to best match experimental data.

If you use RAW to run PDB2SAS, in addition to citing the RAW paper, please
cite the paper given `here. <https://www.cell.com/biophysj/abstract/S0006-3495(23)00670-7>`_

The written version of the tutorial follows.

#.  The easiest way to generate a theoretical profile in RAW using PDB2SAS
    is simply to plot a **.pdb** file. In the Files Control
    Panel go to the **theory_data** folder, select the **1XIB_4mer.pdb**
    and click the plot button.

    *   *Note:* **.cif** files are not currently supported in PDB2SAS.

    *   *Note:* PDB2SAS is the default calculator in RAW. However,
        it is possible that it has been changed to CRYSOL by a user.
        If so, you can reset the default calculator to PDB2MRC by going to
        Options->Advanced Options->General Settings and selecting PDB2SAS
        in the "Default structure calculator" drop down menu.

#.  After the calculation is done, RAW will plot the theoretical profile
    from PDB2SAS on the profiles plot. You should see one profile,
    **1XIB_4mer.dat**

    |theory_pdb2sas_load_model_png|

#.  You can also generate a theoretical profile using the PDB2SAS window in RAW.
    This gives you more control over the parameters used to generate the profile,
    using the plot button simply uses the default parameters. Select the
    "Tools->DENSS->PDB2SAS" menu option to open the PDB2SAS window.

    |theory_pdb2sas_menu_png|

#.  In the PDB2SAS window, in the models section use the Add button to add
    the **1XIB_4mer.pdb** file to the list of models to calculate a theoretical
    profile from.

    |theory_pdb2sas_model_add_png|

#.  Click the "Start" button to calculate the theoretical scattering profile
    for the model.

    *   *Note:* The Status will change to "Running calculation" while running
        and then to "Finished calculation" when finished.

    |theory_pdb2sas_start_png|

#.  After the calculation finishes, the theoretical profile will display in the
    plot on the right side of the window, and parameters from the profile will
    be shown in the list at the bottom right of the window.

    *   *Note:* Not all parameters will display. The Data and Chi^2
        fields are only calculated if the model is fit to data.

    |theory_pdb2sas_results1_png|

#.  The PDB2SAS window can also be used to fit the model against experimental
    data. Go back to the Files Control Panel and load in the **glucose_isomerase.dat**
    data. Return to the PDB2SAS window. In the Experimental data section use the
    Add button, check the **glucose_isomerase.dat** item in the dialog that
    appears, and then click OK to add the **glucose_isomerase.dat** experimental data to the
    list of data you can fit a model against.

    *   *Note:* Only data that is loaded into RAW can be added to the PDB2SAS
        experimental data list.

    |theory_pdb2sas_data_add_png|

#.  Click the Start button to calculate the theoretical scattering profile and
    fit it to the data. After the calculation finishes you'll see both the
    theoretical profile, the data, and the uncertainty normalized residual
    plotted in the right plot, as well as the parameters from the theoretical
    profile in the list at the bottom right.

    *   *Note:* This will now have all parameters, including the Data and Chi^2
        fields that were missing when you calculated a theoretical profile
        without fitting.

    |theory_pdb2sas_results2_png|

#.  Click the OK button to close the PDB2SAS window and send the calculated
    theoretical scattering profile to the Profiles plot. It will appear as
    **1XIB_4mer_glucose_isomerase_FIT** in the Profiles Control Panel.

#.  You can also load more than one model and/or profile into the PDB2SAS window
    to calculate multiple profiles at once. Load the **polymerase.dat**
    experimental data into RAW. Select both the polymerase and GI profiles in the
    Profiles Control Panel, right click on the **polymerase.dat** profile and select
    "Other Analysis->Fit Model (DENSS PDB2SAS)". This will open the PDB2SAS window with
    the selected profiles already loaded in the Experimental Data section.

    |theory_pdb2sas_right_click_png|

#.  Add the **1XIB_4mer.pdb** (GI) and **2pol.pdb** (polymerase) models to the
    PDB2MRC model section.

#.  Uncheck the **2pol.pdb** model in the Models list. Only items that are checked
    are used for calculation, so this will let you fit just the **1XIB_4mer.pdb**
    model.

    |theory_pdb2sas_model_select_png|

#.  Click the Start button to fit the **1XIB_4mer.cif** model against both experimental
    profiles. After the calculation finishes you'll see both experimental profiles and the
    theoretical profile fit to both measured profiles.

    *   *Question:* Which dataset does the model fit better?

    *   *Try:* Turn off the 1XIB_4mer model and turn on the 2pol model and see
        how that fits both profiles.

    |theory_pdb2sas_results3_png|

#.  You can also fit multiple models against a single profile. Check both
    the **1XIB_4mer.pdb** and **2pol.pdb** entries in the models list
    and uncheck the **glucose_isomerase.dat** experimental data.

    |theory_pdb2sas_data_select_png|

#.  Click the Start button to fit both models against the polymerase data.

    *   *Question:* Which model fits the profile better?

    *   *Try:*  Turn off the polymerase profile and turn on the GI profile
        and see how each model fits that data.

    *   *Tip:* You can also calculate the theoretical scattering profile from
        multiple models without fitting against data. To do this, uncheck all the
        data items and calculate the 'minimal' theoretical profiles.

    |theory_pdb2sas_results4_png|

#.  You can fit multiple models against multiple profiles. Check both models
    and both experimental profiles. Click the start button to fit both models
    against both experimental profiles.

#.  You can export the values in the results table to a csv file. Right click
    on the table and select Export Data. Save the .csv file in the **theory_data**
    folder.

    *   *Try:* Open the .csv file in Excel or another spreadsheet program.

    |theory_pdb2sas_export_data_png|

#.  Click OK to close the PDB2SAS window and send all the fits to the Profiles
    plot and control panel.

#.  You can also adjust the settings for running PDB2SAS from the PDB2SAS
    window. We'll do that using some example data. Load the **SASDP43.dat**
    experimental data into RAW.

    *   *Note:* This dataset is from the `SASDP43 entry in the SASBDB
        <https://www.sasbdb.org/data/SASDP43/>`_

#.  Open a PDB2SAS window and add the **Brpt55_M_Zn.pdb** model and the
    **SASDP43.dat** data.

#.  Run the PDB2SAS fitting with the default settings.

    *   *Note:* Notice that the maximum q value for the theoretical fit does
        not extend all the way to the experimental maximum. This is because
        the default number of samples (128) is too small. This protein is elongated
        causing the real space voxel size to be quite large, which results
        in the maximum q value to be too small.

#.  Open a second PDB2MRC window and add the same model and data to it.
    Set the N samples (real space) option to 256. Run the PDB2SAS fitting
    with these updated settings.

    |theory_pdb2sas_nsamples_png|

#.  You should see that the result using 256 samples extends to the full q range
    of the experimental data.

    *   *Note:* Setting the N samples to a power of 2 (64, 128, 256, etc.) is best
        for calculation speed, though any even number can be used.

    *   *Note:* You can explicitly set the voxel size in the Advanced Settings,
        which will override N samples.

    |theory_pdb2sas_results5_png|

#.  There are also a number of advanced settings you can set. Expand the
    Advanced Setting section and (if necessary) scroll down to see the
    different options. The settings are explained in detail in the PDB2SAS
    manual.

    *   *Note:* Common settings to change are the solvent density and hydration
        shell contrast (requires turning off the "Fit solvent" and "Fit hydration
        shell" options).

    *   *Tip:* If you need all the PDB2SAS outputs (such as the .dat and .fit files)
        you can check the "Save all outputs to folder" option and provide
        a folder to save to by clicking the "..." button after the "Save to" field.

    |theory_pdb2sas_settings_png|

#.  Close the PDB2SAS windows with the OK button to save the fit results to
    the Profiles plot and control panel.

#.  You can save information from a theoretical profile generated by PDB2SAS in RAW
    as part of a pdf report. Right click on the **1XIB_4mer_glucose_isomerase_FIT**
    item in the Profiles control panel and select "Save report". In the window
    that opens click "Save Report" and save the pdf report. If you open the
    report you will see the usually summary pots and a table with a summary of
    theoretical profile parameters.

    |theory_pdb2sas_report_png|

.. |theory_pdb2sas_load_model_png| image:: images/theory_pdb2sas_load_model.png
    :target: ../_images/theory_pdb2sas_load_model.png

.. |theory_pdb2sas_menu_png| image:: images/theory_pdb2sas_menu.png
    :target: ../_images/theory_pdb2sas_menu.png
    :width: 400 px

.. |theory_pdb2sas_model_add_png| image:: images/theory_pdb2sas_model_add.png
    :target: ../_images/theory_pdb2sas_model_add.png

.. |theory_pdb2sas_start_png| image:: images/theory_pdb2sas_start.png
    :target: ../_images/theory_pdb2sas_start.png
    :width: 300 px

.. |theory_pdb2sas_results1_png| image:: images/theory_pdb2sas_results1.png
    :target: ../_images/theory_pdb2sas_results1.png

.. |theory_pdb2sas_data_add_png| image:: images/theory_pdb2sas_data_add.png
    :target: ../_images/theory_pdb2sas_data_add.png

.. |theory_pdb2sas_results2_png| image:: images/theory_pdb2sas_results2.png
    :target: ../_images/theory_pdb2sas_results2.png

.. |theory_pdb2sas_right_click_png| image:: images/theory_pdb2sas_right_click.png
    :target: ../_images/theory_pdb2sas_right_click.png
    :width: 400 px

.. |theory_pdb2sas_model_select_png| image:: images/theory_pdb2sas_model_select.png
    :target: ../_images/theory_pdb2sas_model_select.png
    :width: 300 px

.. |theory_pdb2sas_results3_png| image:: images/theory_pdb2sas_results3.png
    :target: ../_images/theory_pdb2sas_results3.png

.. |theory_pdb2sas_data_select_png| image:: images/theory_pdb2sas_data_select.png
    :target: ../_images/theory_pdb2sas_data_select.png
    :width: 300 px

.. |theory_pdb2sas_results4_png| image:: images/theory_pdb2sas_results4.png
    :target: ../_images/theory_pdb2sas_results4.png

.. |theory_pdb2sas_export_data_png| image:: images/theory_pdb2sas_export_data.png
    :target: ../_images/theory_pdb2sas_export_data.png

.. |theory_pdb2sas_nsamples_png| image:: images/theory_pdb2sas_nsamples.png
    :target: ../_images/theory_pdb2sas_nsamples.png
    :width: 300 px

.. |theory_pdb2sas_results5_png| image:: images/theory_pdb2sas_results5.png
    :target: ../_images/theory_pdb2sas_results5.png

.. |theory_pdb2sas_settings_png| image:: images/theory_pdb2sas_settings.png
    :target: ../_images/theory_pdb2sas_settings.png
    :width: 300 px

.. |theory_pdb2sas_report_png| image:: images/theory_pdb2sas_report.png
    :target: ../_images/theory_pdb2sas_report.png
    :width: 450 px