servalcat 0.4.72__tar.gz → 0.4.88__tar.gz

{servalcat-0.4.72 → servalcat-0.4.88}/CMakeLists.txt

@@ -41,7 +41,7 @@ string(STRIP "${pybind11_DIR}" pybind11_DIR)
 find_package(pybind11 2.6 CONFIG REQUIRED)
 message(STATUS "Found pybind11 ${pybind11_VERSION}: ${pybind11_INCLUDE_DIRS}")
 
-pybind11_add_module(ext src/ext.cpp src/intensity.cpp src/amplitude.cpp src/refine.cpp)
+pybind11_add_module(ext src/ext.cpp src/intensity.cpp src/amplitude.cpp src/refine.cpp src/twin.cpp)
 
 if (EXISTS "${CMAKE_HOME_DIRECTORY}/eigen/Eigen")
   include_directories("${CMAKE_CURRENT_SOURCE_DIR}/eigen")
@@ -58,7 +58,7 @@ if (DEFINED SKBUILD)
     # For now, locate it relatively to pybind11.
     get_filename_component(gemmi_ROOT "${pybind11_INCLUDE_DIR}/../../../.." ABSOLUTE)
   endif()
-  find_package(gemmi 0.6.6 CONFIG REQUIRED)
+  find_package(gemmi 0.6.7 CONFIG REQUIRED)
 else()
   set(USE_PYTHON ON CACHE BOOL "" FORCE)
   message(STATUS "")
@@ -71,7 +71,7 @@ else()
     FetchContent_Declare(
       gemmi
       GIT_REPOSITORY https://github.com/project-gemmi/gemmi.git
-      GIT_TAG        v0.6.6
+      GIT_TAG        v0.6.7
     )
     FetchContent_GetProperties(gemmi)
     if (NOT gemmi_POPULATED)

{servalcat-0.4.72 → servalcat-0.4.88}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: servalcat
-Version: 0.4.72
+Version: 0.4.88
 Summary: Structure refinement and validation for crystallography and single particle analysis
 Author: Keitaro Yamashita, Garib N. Murshudov
 License: MPL-2.0
@@ -10,7 +10,7 @@ Requires-Dist: packaging
 Requires-Dist: numpy>=1.15
 Requires-Dist: scipy
 Requires-Dist: pandas>=1.1.0
-Requires-Dist: gemmi==0.6.6
+Requires-Dist: gemmi==0.6.7
 Description-Content-Type: text/markdown
 
 # Servalcat
@@ -40,7 +40,7 @@ pip install servalcat
 ```
 will install the stable version.
 
-The required GEMMI version is now [v0.6.6](https://github.com/project-gemmi/gemmi/releases/tag/v0.6.6). It may not work with the latest gemmi code from the github. The policy is in the main branch I only push the code that works with the latest package of GEMMI.
+The required GEMMI version is now [v0.6.7](https://github.com/project-gemmi/gemmi/releases/tag/v0.6.7). It may not work with the latest gemmi code from the github. The policy is in the main branch I only push the code that works with the latest package of GEMMI.
 
 To use the Refmac5 related commands, you also need to install [CCP4](https://www.ccp4.ac.uk/). For "No Refmac5" commands, you may just need [the monomer library](https://github.com/MonomerLibrary/monomers) if CCP4 is not installed.
 

{servalcat-0.4.72 → servalcat-0.4.88}/README.md

@@ -25,7 +25,7 @@ pip install servalcat
 ```
 will install the stable version.
 
-The required GEMMI version is now [v0.6.6](https://github.com/project-gemmi/gemmi/releases/tag/v0.6.6). It may not work with the latest gemmi code from the github. The policy is in the main branch I only push the code that works with the latest package of GEMMI.
+The required GEMMI version is now [v0.6.7](https://github.com/project-gemmi/gemmi/releases/tag/v0.6.7). It may not work with the latest gemmi code from the github. The policy is in the main branch I only push the code that works with the latest package of GEMMI.
 
 To use the Refmac5 related commands, you also need to install [CCP4](https://www.ccp4.ac.uk/). For "No Refmac5" commands, you may just need [the monomer library](https://github.com/MonomerLibrary/monomers) if CCP4 is not installed.
 

{servalcat-0.4.72 → servalcat-0.4.88}/docs/commands.rst

@@ -4,10 +4,10 @@ Servalcat commands
 SPA
 ---
 
-refine_spa
-~~~~~~~~~~
+refine_spa_norefmac
+~~~~~~~~~~~~~~~~~~~
 
-REFMAC5 pipeline for SPA. The weighted and sharpened Fo-Fc map is calculated after the refinement. For details please see the reference.
+Refinement pipeline for SPA. The weighted and sharpened Fo-Fc map is calculated after the refinement. For details please see the reference.
 
 .. literalinclude:: help/refine_spa.txt
    :language: console

{servalcat-0.4.72 → servalcat-0.4.88}/docs/conf.py

@@ -19,7 +19,7 @@ import os
 # -- Project information -----------------------------------------------------
 
 project = 'Servalcat'
-copyright = '2021-2022, MRC Laboratory of Molecular Biology'
+copyright = '2021-2024, Keitaro Yamashita'
 author = 'Keitaro Yamashita, Garib Murshudov'
 
 

{servalcat-0.4.72 → servalcat-0.4.88}/docs/help/fofc.txt

@@ -1,15 +1,16 @@
 $ servalcat fofc -h
 usage: servalcat fofc [-h] [--halfmaps HALFMAPS HALFMAPS | --map MAP]
                       [--pixel_size PIXEL_SIZE] --model MODEL -d RESOLUTION
-                      [-m MASK] [-r MASK_RADIUS] [-B B] [--half1_only]
-                      [--normalized_map] [--no_fsc_weights]
-                      [--sharpening_b SHARPENING_B] [--trim] [--trim_mtz]
-                      [--monlib MONLIB] [--omit_proton] [--omit_h_electron]
-                      [-o OUTPUT_PREFIX]
+                      [-m MASK] [-r MASK_RADIUS] [--no_check_mask_with_model]
+                      [-B B] [--half1_only] [--normalized_map]
+                      [--no_fsc_weights] [--sharpening_b SHARPENING_B]
+                      [--trim] [--trim_mtz] [--monlib MONLIB] [--omit_proton]
+                      [--omit_h_electron] [--source {electron,xray,neutron}]
+                      [-o OUTPUT_PREFIX] [--keep_charges]
 
 Fo-Fc map calculation based on model and data errors
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   --halfmaps HALFMAPS HALFMAPS
   --map MAP             Use only if you really do not have half maps.
@@ -20,10 +21,13 @@ optional arguments:
   -m MASK, --mask MASK  mask file
   -r MASK_RADIUS, --mask_radius MASK_RADIUS
                         mask radius (not used if --mask is given)
+  --no_check_mask_with_model
+                        Disable mask test using model
   -B B                  Estimated blurring
   --half1_only          Only use half 1 for map calculation (use half 2 only
                         for noise estimation)
-  --normalized_map      Write normalized map in the masked region
+  --normalized_map      Write normalized map in the masked region. Now this is
+                        on by default.
   --no_fsc_weights      Just for debugging purpose: turn off FSC-based
                         weighting
   --sharpening_b SHARPENING_B
@@ -34,4 +38,8 @@ optional arguments:
   --monlib MONLIB       Monomer library path. Default: $CLIBD_MON
   --omit_proton         Omit proton from model in map calculation
   --omit_h_electron     Omit hydrogen electrons from model in map calculation
+  --source {electron,xray,neutron}
   -o OUTPUT_PREFIX, --output_prefix OUTPUT_PREFIX
+                        output file name prefix (default: diffmap)
+  --keep_charges        Use scattering factor for charged atoms. Use it with
+                        care.

servalcat-0.4.88/docs/help/refine_spa.txt

@@ -0,0 +1,126 @@
+$ servalcat refine_spa_norefmac -h
+usage: servalcat refine_spa_norefmac [-h] (--halfmaps HALFMAPS HALFMAPS | --map MAP | --hklin HKLIN)
+                                     [--pixel_size PIXEL_SIZE] [--labin LABIN] --model MODEL -d
+                                     RESOLUTION [-r MASK_RADIUS] [--padding PADDING] [--no_mask]
+                                     [--no_trim] [--mask_soft_edge MASK_SOFT_EDGE]
+                                     [--no_sharpen_before_mask] [--b_before_mask B_BEFORE_MASK]
+                                     [--blur BLUR] [--monlib MONLIB] [--ligand [LIGAND ...]]
+                                     [--newligand_continue] [--hydrogen {all,yes,no}] [--hout]
+                                     [--jellybody] [--jellybody_params sigma dmax] [--jellyonly]
+                                     [--pg PG] [--twist TWIST] [--rise RISE]
+                                     [--center CENTER CENTER CENTER] [--axis1 AXIS1 AXIS1 AXIS1]
+                                     [--axis2 AXIS2 AXIS2 AXIS2] [--contacting_only]
+                                     [--ignore_symmetry IGNORE_SYMMETRY] [--find_links]
+                                     [--no_check_ncs_overlaps] [--no_check_ncs_map]
+                                     [--no_check_mask_with_model] [--keywords KEYWORDS [KEYWORDS ...]]
+                                     [--keyword_file KEYWORD_FILE [KEYWORD_FILE ...]]
+                                     [--randomize RANDOMIZE] [--ncycle NCYCLE] [--weight WEIGHT]
+                                     [--no_weight_adjust]
+                                     [--target_bond_rmsz_range TARGET_BOND_RMSZ_RANGE TARGET_BOND_RMSZ_RANGE]
+                                     [--adpr_weight ADPR_WEIGHT] [--ncsr] [--bfactor BFACTOR]
+                                     [--fix_xyz] [--adp {fix,iso,aniso}] [--refine_all_occ]
+                                     [--max_dist_for_adp_restraint MAX_DIST_FOR_ADP_RESTRAINT]
+                                     [--adp_restraint_power ADP_RESTRAINT_POWER]
+                                     [--adp_restraint_exp_fac ADP_RESTRAINT_EXP_FAC]
+                                     [--adp_restraint_no_long_range]
+                                     [--adp_restraint_mode {diff,kldiv}] [--refine_h]
+                                     [--source {electron,xray,neutron}] [-o OUTPUT_PREFIX]
+                                     [--cross_validation]
+                                     [--mask_for_fofc MASK_FOR_FOFC | --mask_radius_for_fofc MASK_RADIUS_FOR_FOFC]
+                                     [--fsc_resolution FSC_RESOLUTION] [--keep_charges]
+                                     [--keep_entities] [--write_trajectory]
+
+EXPERIMENTAL program to refine cryo-EM SPA structures
+
+options:
+  -h, --help            show this help message and exit
+  --halfmaps HALFMAPS HALFMAPS
+                        Input half map files
+  --map MAP             Use this only if you really do not have half maps.
+  --hklin HKLIN         Use mtz file. With limited functionality.
+  --pixel_size PIXEL_SIZE
+                        Override pixel size (A)
+  --labin LABIN         F,PHI for hklin
+  --model MODEL         Input atomic model file
+  -d RESOLUTION, --resolution RESOLUTION
+  -r MASK_RADIUS, --mask_radius MASK_RADIUS
+                        mask radius
+  --padding PADDING     Default: 2*mask_radius
+  --no_mask
+  --no_trim             Keep original box (not recommended)
+  --mask_soft_edge MASK_SOFT_EDGE
+                        Add soft edge to model mask. Should use with --no_sharpen_before_mask?
+  --no_sharpen_before_mask
+                        By default half maps are sharpened before masking by std of signal and
+                        unsharpened after masking. This option disables it.
+  --b_before_mask B_BEFORE_MASK
+                        sharpening B value for sharpen-mask-unsharpen procedure. By default it is
+                        determined automatically.
+  --blur BLUR           Sharpening or blurring B
+  --monlib MONLIB       Monomer library path. Default: $CLIBD_MON
+  --ligand [LIGAND ...]
+                        restraint dictionary cif file(s)
+  --newligand_continue  Make ad-hoc restraints for unknown ligands (not recommended)
+  --hydrogen {all,yes,no}
+                        all: (re)generate hydrogen atoms, yes: use hydrogen atoms if present, no:
+                        remove hydrogen atoms in input. Default: all
+  --hout                write hydrogen atoms in the output model
+  --jellybody           Use jelly body restraints
+  --jellybody_params sigma dmax
+                        Jelly body sigma and dmax (default: [0.01, 4.2])
+  --jellyonly           Jelly body only (experimental, may not be useful)
+  --pg PG               Point group symbol
+  --twist TWIST         Helical twist (degree)
+  --rise RISE           Helical rise (Angstrom)
+  --center CENTER CENTER CENTER
+                        Origin of symmetry. Default: center of the box
+  --axis1 AXIS1 AXIS1 AXIS1
+                        Axis1 (if I: 5-fold, O: 4-fold, T: 3-fold)
+  --axis2 AXIS2 AXIS2 AXIS2
+                        Axis2 (if I: 5-fold, O: 4-fold, T: 3-fold, Dn: 2-fold)
+  --contacting_only     Filter out non-contacting strict NCS copies
+  --ignore_symmetry IGNORE_SYMMETRY
+                        Ignore symmetry information (MTRIX/_struct_ncs_oper) in the model file
+  --find_links          Automatically add links
+  --no_check_ncs_overlaps
+                        Disable model overlap test due to strict NCS
+  --no_check_ncs_map    Disable map symmetry test due to strict NCS
+  --no_check_mask_with_model
+                        Disable mask test using model
+  --keywords KEYWORDS [KEYWORDS ...]
+                        refmac keyword(s)
+  --keyword_file KEYWORD_FILE [KEYWORD_FILE ...]
+                        refmac keyword file(s)
+  --randomize RANDOMIZE
+                        Shake coordinates with the specified rmsd value
+  --ncycle NCYCLE       number of CG cycles (default: 10)
+  --weight WEIGHT       refinement weight. default: automatic
+  --no_weight_adjust    Do not adjust weight during refinement
+  --target_bond_rmsz_range TARGET_BOND_RMSZ_RANGE TARGET_BOND_RMSZ_RANGE
+                        Bond rmsz range for weight adjustment (default: [0.5, 1.0])
+  --adpr_weight ADPR_WEIGHT
+                        ADP restraint weight (default: 1.000000)
+  --ncsr                Use local NCS restraints
+  --bfactor BFACTOR     reset all atomic B values to the specified value
+  --fix_xyz             Fix atomic coordinates
+  --adp {fix,iso,aniso}
+                        ADP parameterization
+  --refine_all_occ
+  --max_dist_for_adp_restraint MAX_DIST_FOR_ADP_RESTRAINT
+  --adp_restraint_power ADP_RESTRAINT_POWER
+  --adp_restraint_exp_fac ADP_RESTRAINT_EXP_FAC
+  --adp_restraint_no_long_range
+  --adp_restraint_mode {diff,kldiv}
+  --refine_h            Refine hydrogen against data (default: only restraints apply)
+  --source {electron,xray,neutron}
+  -o OUTPUT_PREFIX, --output_prefix OUTPUT_PREFIX
+  --cross_validation    Run cross validation. Only "throughout" mode is available (no "shake" mode)
+  --mask_for_fofc MASK_FOR_FOFC
+                        Mask file for Fo-Fc map calculation
+  --mask_radius_for_fofc MASK_RADIUS_FOR_FOFC
+                        Mask radius for Fo-Fc map calculation
+  --fsc_resolution FSC_RESOLUTION
+                        High resolution limit for FSC calculation. Default: Nyquist
+  --keep_charges        Use scattering factor for charged atoms. Use it with care.
+  --keep_entities       Do not override entities
+  --write_trajectory    Write all output from cycles

{servalcat-0.4.72 → servalcat-0.4.88}/docs/index.rst

@@ -7,15 +7,17 @@ Servalcat - refinement and map calculation
 ==========================================
 
 Servalcat (for **S**\ tructur\ **e** **r**\ efinement and **val**\ idation for **c**\ rystallography and single p\ **a**\ r\ **t**\ icle analysis) is a software package for atomic model refinement and map calculation.
-We currently focus on cryo-EM single particle analysis (SPA).
-
 
 Source code repository: https://github.com/keitaroyam/servalcat
 
-.. note::
+References
+----------
+
+| Cryo-EM SPA refinement:
+| `Yamashita, K., Palmer, C. M., Burnley, T., Murshudov, G. N. (2021) "Cryo-EM single particle structure refinement and map calculation using Servalcat" Acta Cryst. D77, 1282-1291 <https://doi.org/10.1107/S2059798321009475>`_
 
-   If Servalcat is useful for your research, please cite:
-   Yamashita, K., Palmer, C. M., Burnley, T., Murshudov, G. N. (2021) "Cryo-EM single particle structure refinement and map calculation using Servalcat" *Acta Cryst. D*\ **77**, 1282-1291 doi: `10.1107/S2059798321009475 <https://doi.org/10.1107/S2059798321009475>`_
+| Refmacat and restraint generation using GEMMI:
+| `Yamashita, K., Wojdyr, M., Long, F., Nicholls, R. A., Murshudov, G. N. (2023) "GEMMI and Servalcat restrain REFMAC5" Acta Cryst. D79, 368-373 <https://doi.org/10.1107/S2059798323002413>`_
 
 Table of Contents
 -----------------

servalcat-0.4.88/docs/overview.rst

@@ -0,0 +1,94 @@
+Overview
+========
+
+Servalcat offers various functionalities for refinement and map calculations in crystallography and single particle analysis (SPA).
+
+* SPA
+   * refinement (refine_spa_norefmac)
+   * sharpened and weighted map calculation (Fo and Fo-Fc)
+   * map trimming tool
+* crystallography
+   * amplitude or intensity based refinement (refine_xtal_norefmac)
+   * map calculation from ML parameter estimation (sigmaa)
+* others/general
+   * REFMAC5 wrapper ("refmacat")
+   * geometry optimisation 
+
+The basic usage is:
+
+.. code-block:: console
+
+    $ servalcat <command> <args>
+
+The most common commands are listed below. To see all arguments for a specific command, run:
+
+.. code-block:: console
+
+    $ servalcat <command> -h
+
+
+Command examples for cryo-EM SPA
+--------------------------------
+
+refinement
+~~~~~~~~~~
+Servalcat performs reciprocal space refinement for single particle analysis. The weighted and sharpened Fo-Fc map is calculated after the refinement. For details please see the reference.
+Make a new directory and run:
+
+.. code-block:: console
+
+    $ servalcat refine_spa_norefmac \
+     --model input.pdb --resolution 2.5 \
+     --halfmaps ../half_map_1.mrc ../half_map_2.mrc \
+     --ncycle 10 [--pg C2] \
+     [--mask_for_fofc mask.mrc] [-o output_prefix]
+
+Provide unsharpened and unweighted half maps (e.g., from RELION's Refine3D) after ``--halfmaps``.
+
+If map has been symmetrised with a point group, use ``--pg`` to specify the point group symbol along with the asymmetric unit model.
+The centre of the box is assumed to be the origin of symmetry. The axis convention follows `RELION <https://relion.readthedocs.io/en/latest/Reference/Conventions.html#symmetry>`_.
+
+Other useful options:
+   * ``--ligand lig.cif`` : specify restraint dictionary (.cif) file(s)
+   * ``--mask_for_fofc mask.mrc`` : specify mask file for Fo-Fc map calculation
+   * ``--jellybody`` : turn on jelly body refinement
+   * ``--weight value`` : specify the weight. By default Servalcat determines it from resolution and mask/box ratio
+   * ``--keyword_file file`` : specify any refmac keyword file(s) (e.g. prosmart restraint file) Note that not all refmac keywords are supported
+   * ``--pixel_size value`` : override pixel size of map
+
+Output files:
+   * ``prefix.pdb``: refined model
+   * ``prefix_expanded.pdb``: symmetry-expanded version
+   * ``prefix_diffmap.mtz``: can be auto-opened with coot. sharpened and weighted Fo map and Fo-Fc map
+   * ``prefix_diffmap_normalized_fofc.mrc``: Fo-Fc map normalised within a mask. Look at raw values
+
+Fo-Fc map calculation
+~~~~~~~~~~~~~~~~~~~~~
+It is crucial to refine individual atomic B values with electron scattering factors for a meaningful Fo-Fc map.
+While the ``refine_spa_norefmac`` command calculates the Fo-Fc map (explained above), you can use the fofc command to calculate specific maps, like omit maps.
+
+.. code-block:: console
+
+    $ servalcat fofc \
+      --model input.pdb --resolution 2.5 \
+      --halfmaps ../half_map_1.mrc ../half_map_2.mrc \
+      [--mask mask.mrc] [-o output_prefix] [-B B value]
+
+
+``-B`` is to calculate weighted maps based on local B estimate. It may be useful for model building in noisy region.
+
+Map trimming
+~~~~~~~~~~~~
+Maps from single particle analysis are often large due to unnecessary regions outside the molecule. Use trim to save disk space by removing these regions.
+
+.. code-block:: console
+
+    $ servalcat trim \
+      --maps postprocess.mrc halfmap1.mrc halfmap2.mrc \
+      [--mask mask.mrc] [--model model.pdb] [--padding 10]
+
+Maps specified with ``--maps`` are trimmed. The boundary is decided by ``--mask`` or ``--model`` if mask is not available.
+Model(s) are shifted into a new box.
+By default new boundary is centred on the original map and cubic, but they can be turned off with ``--noncentered`` and ``--noncubic``.
+If you do not want to shift maps and models, specify ``--no_shift`` to keep origin.
+

servalcat-0.4.88/docs/spa_examples/ab42.rst

@@ -0,0 +1,202 @@
+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://ftp.wwpdb.org/pub/emdb/structures/EMD-13809/other/emd_13809_half_map_1.map.gz
+    wget https://ftp.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.