DCA Frustratometer examples
=============================

Loading Protein Structures
~~~~~~~~~~~~~~~~~~~~~~~~~~

The Frustratometer package includes a prody-based Structure class to load the structure and calculate the properties needed for the AWSEM and DCA Frustratometers.

.. code-block:: python

    import frustratometer

    # Define the path to your PDB file
    pdb_path = Path('data/my_protein.pdb')
    # Load the structure
    structure = frustratometer.Structure.full_pdb(pdb_path)
    structure.sequence #The sequence of the structure

Creating a DCA Model Instance
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

After loading the structure, create a DCA model instance with the desired parameters. When creating a DCA model instance, you can provide an existing Potts model or a Potts model file (in Matlab format). Additionally, the Frustratometer can generate a Potts model for a given protein via the pydca package.

When using Potts Model files generated by the mfDCA algorithm, make sure to set the "reformat_potts_model" to True.

.. code-block:: python
    potts_model_file=Path('data/my_potts_model.mat')

    ## Using existing potts model file
    model_dca = frustratometer.DCA.from_potts_model_file(structure,potts_model_file,distance_cutoff=4,
                                                        sequence_cutoff=0)


Check the Accuracy of the Potts Model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to check the accuracy of the contacts predicted by the Potts model and true contacts from the protein's contact map, the receiver operator curve (ROC) can be generated. If the Potts model has high accuracy, the Area Under the Curve (AUC) of the ROC will be 1.

.. code-block:: python
    ## Generate the ROC curve
    model_dca.plot_roc()

    ##Calculate AUC of ROC curve
    print(model_dca.auc())


Calculating Frustration Indices
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Frustration indices can be calculated for single residues or mutationally. This measurement helps identify energetically favorable or unfavorable interactions within the protein structure.

Single Residue Frustration
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    # Calculate single residue frustration
    single_residue_frustration = model_dca.frustration(kind='singleresidue')
    print(single_residue_frustration)

Single Residue Decoy Fluctuation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The frustratometer package also allows the quick calculation of the energies of all single residue and mutational decoys.

.. code-block:: python

    # Calculate mutational frustration
    mutational_frustration = model_dca.decoy_fluctuation(kind='singleresidue')
    print(mutational_frustration)

Mutational Frustration
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    # Calculate mutational frustration
    mutational_frustration = model_dca.frustration(kind='mutational')
    print(mutational_frustration)

Energy Calculations
~~~~~~~~~~~~~~~~~~~

You can calculate different energy contributions, including fields energy (pseudo one-body terms like burial), couplings energy (pseudo two-body terms like contact and electrostatics), and their combination to determine the native energy of the protein structure. The fields, couplings, and native energies of other threaded sequences can be calculated like below by simply changing the "sequence" variable in the functions' arguments.

Fields Energy
~~~~~~~~~~~~~

.. code-block:: python

    fields_energy = model_dca.fields_energy()
    print(fields_energy)

Couplings Energy
~~~~~~~~~~~~~~~~

.. code-block:: python

    couplings_energy = model_dca.couplings_energy()
    print(couplings_energy)

Native Energy
~~~~~~~~~~~~~

Native energy can be considered as a combination of fields and couplings energy contributions.

.. code-block:: python

    native_energy = model_dca.native_energy()
    print(native_energy)