Refinement of amyloid-β 42 structure
====================================

This guide demonstrates how to refine an atomic model of amyloid-β 42 type II from the helical reconstruction. We will utilise data from `Yang et al. 2022 <http://dx.doi.org/10.1126/science.abm7285>`_: `PDB 7q4m <https://www.rcsb.org/structure/7q4m>`_ and `EMD-13809 <https://www.emdataresource.org/EMD-13809>`_).
We need the pdb (or mmcif) file and half maps:
::

    wget https://files.rcsb.org/download/7q4m.pdb
    wget https://files.rcsb.org/download/7q4m.cif
    wget https://files.wwpdb.org/pub/emdb/structures/EMD-13809/other/emd_13809_half_map_1.map.gz
    wget https://files.wwpdb.org/pub/emdb/structures/EMD-13809/other/emd_13809_half_map_2.map.gz

**In this example please use at least CCP4 9.0 and Servalcat from it (Servalcat 0.4.72 or newer).**

Obtaining ASU model
-------------------
The helical symmetry information for this entry can be found in the mmCIF file. We will generate the ASU model from chain A of the PDB file and apply the specified helical symmetry.

.. code-block:: console

    $ grep _em_helical_entity 7q4m.cif
    _em_helical_entity.id                             1
    _em_helical_entity.image_processing_id            1
    _em_helical_entity.angular_rotation_per_subunit   -2.9
    _em_helical_entity.axial_rise_per_subunit         4.9
    _em_helical_entity.axial_symmetry                 C2
    _em_helical_entity.details                        ?

This has axial symmetry of C2, twist of -2.9°, and rise of 4.9 Å.

PDB deposited model contains 10 chains, and only one chain is unique. We check this with the following command.

.. code-block:: console

    $ servalcat util symmodel --model 7q4m.pdb --map emd_13809_half_map_1.map.gz \
                              --pg C2 --twist -2.9 --rise 4.9 --chains A

It tells a program to extract the chain A of 7q4m.pdb, take unit cell parameters (box size) from emd_13809_half_map_1.map.gz, and apply specified helical symmetry. Here you can use 7q4m.cif as well (I just supposed you are more familiar with the PDB format). You will get ``7q4m_asu.pdb`` and ``7q4m_asu_expanded.pdb``, which are asymmetric unit (ASU) model with symmetry operators in the header and the symmetry expanded model, respectively. We use the ASU model in the refinement.

Run refinement from command-line
--------------------------------
Run following command in *a new directory* to avoid overwriting files.

.. code-block:: console

    $ servalcat refine_spa_norefmac \
      --model ../7q4m_asu.pdb \
      --halfmaps ../emd_13809_half_map_1.map.gz ../emd_13809_half_map_2.map.gz \
      --pg C2 --twist -2.9 --rise 4.9 \
      --resolution 2.6 [--cross_validation]

* ``--halfmaps``: Provide unsharpened and unweighted half maps.
* ``--cross_validation`` (optional): Use this option to run cross-validation with half maps. Half map 1 will be used for refinement, and map 2 for validation. Combine this option with ``--randomize 0.3`` to follow the method described in `Brown et al. 2015 <https://doi.org/10.1107/S1399004714021683>`_.
* ``--pg C2 --twist -2.9 --rise 4.9``: Define the helical symmetry parameters.
* ``--resolution``: Specify the resolution for refinement and map calculation (set slightly higher than the global resolution determined by the FSC=0.143 criterion).

Helical symmetry is usually not applied to the map. Therefore, model should be built in the highest resolution region (central part of the box) and Servalcat only considers symmetry copies that contact the ASU model.

Please refer to :doc:`ChRmine example <chrmine>` for the refinement procedure.

Final summary would look like:

.. code-block:: none

    =============================================================================
    * Final Summary *

    Rmsd from ideal
      bond lengths: 0.0056 A
      bond  angles: 1.186 deg

    Map-model FSCaverages (at 2.60 A):
     FSCaverage(full) =  0.6294
    Cross-validated map-model FSCaverages:
     FSCaverage(half1)=  0.6185
     FSCaverage(half2)=  0.6058
     Run loggraph refined_fsc.log to see plots
    
    ADP statistics
     Chain A (461 atoms) min= 13.2 median= 49.8 max=360.6 A^2 
    
    Weight used: 7.874e-01
                 If you want to change the weight, give larger (looser restraints)
                 or smaller (tighter) value to --weight=.
                 
    Open refined model and refined_diffmap.mtz with COOT:
    coot --script refined_coot.py
       
    WARNING: --mask_for_fofc was not given, so the Fo-Fc map was not normalized.
    =============================================================================

Check FSC
~~~~~~~~~
See :ref:`ChRmine example<chrmine-check-fsc>`.

Check maps and model
~~~~~~~~~~~~~~~~~~~~
Let us open the refined model and maps with COOT:

.. code-block:: console

    $ coot --script refined_coot.py

If the maps seem noisy, it might be due to an inappropriate contour level. Increase the level until you see features. In SPA, the sigma-level is not useful because the box size is arbitrary and volumes outside the mask are all zero, leading to an underestimation of the sigma value. In this example a mask file is not available and the normalisation within a mask could not be done.

You only see one chain because this is a unique part and you only need to fix this model. If you want to see the symmetry-expanded model, open ``refined_expanded.pdb``.

Using symmetry-related beta-sheet restraints
----------------------------------------------
For the high-resolution structure 7q4m, no extra restraints were needed. However, at lower resolutions, secondary structure restraints may be required to stabilise the refinement. Here, the same structure at 3.7 Å (`PDB 8azt <https://www.rcsb.org/structure/8azt>`_, `EMD-15771 <https://www.emdataresource.org/EMD-15771>`_) is used for demonstration.

Preparing external restraints
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We need a text file describing Refmac external restraint keywords. Here is the actual file used for refinement:

.. code-block:: none

    exte alphall 2
    exte symall y exclude self
    exte sgmx 0.05
    exte dist first chain B resi 12 ins . atom  O   second chain B resi 13 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 13 ins . atom  O   second chain B resi 14 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 14 ins . atom  O   second chain B resi 15 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 17 ins . atom  O   second chain B resi 18 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 18 ins . atom  O   second chain B resi 19 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 20 ins . atom  O   second chain B resi 21 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 24 ins . atom  O   second chain B resi 25 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 27 ins . atom  O   second chain B resi 28 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 29 ins . atom  O   second chain B resi 30 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 31 ins . atom  O   second chain B resi 32 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 32 ins . atom  O   second chain B resi 33 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 38 ins . atom  O   second chain B resi 39 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 39 ins . atom  O   second chain B resi 40 ins . atom  N   value 2.8 sigma 0.1
    exte dist first chain B resi 41 ins . atom  O   second chain B resi 42 ins . atom  N   value 2.8 sigma 0.1

All external restraint keywords start with ``exte``. ``alphall 2`` means least-square type function to be used in restraints. See `Barron (2019) <https://arxiv.org/abs/1701.03077>`_ for the meaning of alpha. ``symall y exclude self`` searches for atoms considering symmetry (helical in this case) excluding ASU. This keyword is essential since we want *symmetry related* beta-sheet restraints. ``sgmx 0.05`` sets the maximum sigma value to 0.05 Å so that this sigma will be actually used. You might need to adjust this value.

``dist`` defines distance restraints. Here, we define bonds between the main chain's O and N atoms with a length of 2.8 Å (ProSmart's default hydrogen bond distance) and sigma of 0.1 Å. However, sigma values are overridden by the ``sgmx`` keyword above.

Manually preparing ``exte dist`` lines is tedious. I actually used the following Python script to generate all bonds between residues i and i+1 from i = 12 to 41, and then manually removed unnecessary lines (or added ``!`` at the beginning of a line) by inspecting the model and density.

.. code-block:: python

    chain = "B"
    for i in range(12, 42):
        print("exte dist first chain {} resi {} ins . atom O second chain {} resi {} ins . atom N value 2.8 sigma 0.1".format(chain, i, chain, i+1))

Using external restraints in refinement
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use the ``--keyword_file`` option to specify the external restraint file name. Here, ``--keywords "vdwr 2"`` is specified together, which increases the weight of non-bonded interactions. At low resolution, this option can greatly reduce clashes.

.. code-block:: console

    $ servalcat refine_spa_norefmac \
      --model ../8azt.pdb \
      --halfmaps ../emd_15771_half_map_1.map.gz ../emd_15771_half_map_2.map.gz \
      --mask_for_fofc ../emd_15771_msk_1.map \
      --pg C2 --twist -2.825 --rise 4.806 \
      --resolution 3.7 \
      --keywords "vdwr 2" \
      --keyword_file exte.txt


Generate symmetry copies
-------------------------------------
You might want to generate a specific number of helical copies for visual inspection or making figures.
As explained above, the ``servalcat util symmodel`` command creates a fully expanded model within a box.

If you want more copies, manually increase the box size along the z-axis (c of unit cell parameter):

.. code-block:: console

    $ servalcat util symmodel --model 7q4m.pdb --chains A \
      --cell 186.88 186.88 600 90 90 90 \
      --pg C2 --twist -2.9 --rise 4.9 

Too many copies may exceed a PDB file limit. Add ``--cif`` to write an mmcif file.
If you prefer PDB format, split the copies into multiple files:

.. code-block:: console

    $ servalcat util expand --model 7q4m_asu.pdb --split

and then you will have 7q4m_asu_ncs\_*.pdb files.


Generate assembly operators for PDB deposition
-----------------------------------------------

A utility command ``servalcat util helical_biomt`` prepares matrices for PDB deposition from servalcat-refined ASU models.
The command requires helical parameters (as usual) and two additional options: ``--start`` and ``--end``. These options specify how many helical copies are needed, starting from the input model.
For example, to generate 3 rungs in the 8azt case, use the following command:

.. code-block:: console

    $ servalcat util helical_biomt --model refined.pdb \
      --pg C2 --twist -2.825 --rise 4.806 --start -1 --end 1

Check the \*_biomt_expanded.pdb (or .mmcif) file with a molecular viewer. This file is *not* intended for deposition, but serves as a quick verification that the command worked as intended.
The standard output and servalcat.log file will contain the matrices for PDB deposition.
The other output file, \*_biomt.pdb (or .mmcif), embeds matrices for biological assemblies and may also be used for PDB deposition. However, the PDB deposition system currently does not support embedded matrices within the coordinate file. While there is a plan to introduce this functionality, the timeline is uncertain.