servalcat 0.4.39__tar.gz → 0.4.72__tar.gz

servalcat-0.4.72/CMakeLists.txt

@@ -0,0 +1,93 @@
+cmake_minimum_required(VERSION 3.15...3.22)
+
+# get version string from servalcat/__init__.py
+file(STRINGS "${CMAKE_CURRENT_SOURCE_DIR}/servalcat/__init__.py"
+     serval_version_line REGEX "__version__ = '")
+string(REGEX REPLACE "__version__ = '(.+)'" "\\1" serval_version_str ${serval_version_line})
+
+project(servalcat LANGUAGES C CXX VERSION ${serval_version_str})
+message(STATUS "Servalcat version ${PROJECT_VERSION}")
+
+include(GNUInstallDirs)
+
+if (DEFINED SKBUILD)  # building with scikit-build-core (pip install)
+  set(PYTHON_INSTALL_DIR "${SKBUILD_PLATLIB_DIR}")
+  set(CMAKE_INSTALL_BINDIR "${SKBUILD_SCRIPTS_DIR}")
+endif()
+
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+# Set default build mode to Release, unless we got CXXFLAGS=...
+if (DEFINED ENV{CXXFLAGS})
+  set(USING_ENV_CXXFLAGS ON CACHE BOOL "" FORCE)
+endif()
+if (NOT CMAKE_BUILD_TYPE AND NOT USING_ENV_CXXFLAGS)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING
+      "Choose the type of build, options are: None Debug Release RelWithDebInfo MinSizeRel."
+      FORCE)
+endif()
+
+# CMake >=3.18 has subcomponent Development.Module, scikit-build-core also has it
+if (${CMAKE_VERSION} VERSION_LESS 3.18 AND NOT SKBUILD)
+  find_package(Python ${PYTHON_VERSION} REQUIRED COMPONENTS Interpreter Development)
+else()
+  find_package(Python ${PYTHON_VERSION} REQUIRED COMPONENTS Interpreter Development.Module)
+endif()
+
+# use pybind11-config (if available) to determine pybind11_DIR
+execute_process(COMMAND pybind11-config --cmakedir OUTPUT_VARIABLE pybind11_DIR)
+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)
+
+if (EXISTS "${CMAKE_HOME_DIRECTORY}/eigen/Eigen")
+  include_directories("${CMAKE_CURRENT_SOURCE_DIR}/eigen")
+  message(STATUS "Using ${CMAKE_HOME_DIRECTORY}/eigen (internal copy).")
+else()
+  find_package (Eigen3 3.4 CONFIG REQUIRED)
+  message(STATUS "Found Eigen3 version ${EIGEN3_VERSION_STRING}")
+  target_link_libraries(ext PRIVATE Eigen3::Eigen)
+endif()
+
+if (DEFINED SKBUILD)
+  if (WIN32)
+    # Gemmi is installed in an overlay directory in virtualenv.
+    # 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)
+else()
+  set(USE_PYTHON ON CACHE BOOL "" FORCE)
+  message(STATUS "")
+  message(STATUS "Configuring GEMMI...")
+  if (EXISTS "${CMAKE_HOME_DIRECTORY}/gemmi/include/gemmi")
+    message(STATUS "Using ${CMAKE_HOME_DIRECTORY}/gemmi (internal copy).")
+    add_subdirectory(gemmi EXCLUDE_FROM_ALL)
+  else()
+    include(FetchContent)
+    FetchContent_Declare(
+      gemmi
+      GIT_REPOSITORY https://github.com/project-gemmi/gemmi.git
+      GIT_TAG        v0.6.6
+    )
+    FetchContent_GetProperties(gemmi)
+    if (NOT gemmi_POPULATED)
+      FetchContent_Populate(gemmi)
+      add_subdirectory(${gemmi_SOURCE_DIR} ${gemmi_BINARY_DIR} EXCLUDE_FROM_ALL)
+    endif()
+  endif()
+  add_dependencies(ext gemmi_py)
+endif()
+target_link_libraries(ext PRIVATE gemmi::gemmi_cpp)
+
+if (DEFINED PYTHON_INSTALL_DIR)
+  message(STATUS "Install directory for Python module: ${PYTHON_INSTALL_DIR}")
+  set(Python_SITEARCH "${PYTHON_INSTALL_DIR}")
+endif()
+file(TO_CMAKE_PATH "${Python_SITEARCH}" Python_SITEARCH)
+install(DIRECTORY servalcat/ DESTINATION "${Python_SITEARCH}/servalcat"
+        FILES_MATCHING PATTERN "*.py")
+install(TARGETS ext DESTINATION "${Python_SITEARCH}/servalcat")

servalcat-0.4.72/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.1
+Name: servalcat
+Version: 0.4.72
+Summary: Structure refinement and validation for crystallography and single particle analysis
+Author: Keitaro Yamashita, Garib N. Murshudov
+License: MPL-2.0
+Project-URL: Repository, https://github.com/keitaroyam/servalcat
+Requires-Python: >=3.7
+Requires-Dist: packaging
+Requires-Dist: numpy>=1.15
+Requires-Dist: scipy
+Requires-Dist: pandas>=1.1.0
+Requires-Dist: gemmi==0.6.6
+Description-Content-Type: text/markdown
+
+# Servalcat
+[![Build](https://github.com/keitaroyam/servalcat/workflows/CI/badge.svg)](https://github.com/keitaroyam/servalcat/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/servalcat?color=blue)](https://pypi.org/project/servalcat/)
+
+**S**tructur**e** **r**efinement and **val**idation for **c**rystallography and single p**a**r**t**icle analysis
+
+Servalcat implements pipelines that use Refmac5:
+  * `servalcat refine_spa`: cryo-EM SPA refinement pipeline
+  * `servalcat refine_cx`: small molecule crystallography
+
+and a Refmac5 controller
+  * `refmacat`: behaves as Refmac, but uses GEMMI for restraint generation instead of MAKECIF
+
+Now “No Refmac5” refinement programs have been actively developed:
+  * `servalcat refine_geom`: geometry optimization
+  * `servalcat refine_spa_norefmac`: "No Refmac" version of refine\_spa
+  * `servalcat refine_xtal_norefmac`: crystallographic refinement
+
+Also, it has several utility commands: `servalcat util`.
+
+## Installation
+
+```
+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.
+
+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.
+
+**Notice:**
+From ver. 0.4.6, Servalcat is no longer python-only package and has some C++ code. If you build Servalcat by yourself, probably you also need to build GEMMI using the same compiler.
+
+## Usage
+Please read the documentation: https://servalcat.readthedocs.io/en/latest/
+
+## References
+* [Yamashita, K., Wojdyr, M., Long, F., Nicholls, R. A., Murshudov, G. N. (2023) "GEMMI and Servalcat restrain REFMAC5" *Acta Cryst.* D**79**, 368-373](https://doi.org/10.1107/S2059798323002413)
+* [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](https://doi.org/10.1107/S2059798321009475)

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

@@ -25,7 +25,7 @@ pip install servalcat
 ```
 will install the stable version.
 
-The required GEMMI version is now [v0.6.3](https://github.com/project-gemmi/gemmi/releases/tag/v0.6.3). 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.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.
 
 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/commit.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+newv=`python -c 'v={}; exec(open("servalcat/__init__.py").read(), v); v=v["__version__"].split("."); print(".".join(v[:-1])+".{}".format(int(v[-1])+1))'`
+date=`date "+%Y-%m-%d"`
+sed -i "s/__version__.*/__version__ = '$newv'/; s/__date__.*/__date__ = '$date'/" servalcat/__init__.py
+git add servalcat/__init__.py
+git commit

servalcat-0.4.72/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

servalcat-0.4.72/docs/commands.rst

@@ -0,0 +1,31 @@
+Servalcat commands
+==================
+
+SPA
+---
+
+refine_spa
+~~~~~~~~~~
+
+REFMAC5 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
+
+fofc
+~~~~
+
+.. literalinclude:: help/fofc.txt
+   :language: console
+
+trim
+~~~~
+
+.. literalinclude:: help/trim.txt
+   :language: console
+
+
+Utilities
+---------
+
+TBD

servalcat-0.4.72/docs/conf.py

@@ -0,0 +1,54 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+import os
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Servalcat'
+copyright = '2021-2022, MRC Laboratory of Molecular Biology'
+author = 'Keitaro Yamashita, Garib Murshudov'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+if not os.environ.get('READTHEDOCS'):
+    html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']

servalcat-0.4.72/docs/help/fofc.txt

@@ -0,0 +1,37 @@
+$ 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]
+
+Fo-Fc map calculation based on model and data errors
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --halfmaps HALFMAPS HALFMAPS
+  --map MAP             Use only if you really do not have half maps.
+  --pixel_size PIXEL_SIZE
+                        Override pixel size (A)
+  --model MODEL         Input atomic model file
+  -d RESOLUTION, --resolution RESOLUTION
+  -m MASK, --mask MASK  mask file
+  -r MASK_RADIUS, --mask_radius MASK_RADIUS
+                        mask radius (not used if --mask is given)
+  -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
+  --no_fsc_weights      Just for debugging purpose: turn off FSC-based
+                        weighting
+  --sharpening_b SHARPENING_B
+                        Use B value (negative value for sharpening) instead of
+                        standard deviation of the signal
+  --trim                Write trimmed maps
+  --trim_mtz            Write trimmed mtz
+  --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
+  -o OUTPUT_PREFIX, --output_prefix OUTPUT_PREFIX

servalcat-0.4.72/docs/help/refine_spa.txt

@@ -0,0 +1,142 @@
+$ servalcat refine_spa -h
+usage: servalcat refine_spa [-h] [--exe EXE] [--monlib MONLIB]
+                            [--halfmaps HALFMAPS HALFMAPS | --map MAP]
+                            [--mapref MAPREF] [--mask MASK] [--model MODEL]
+                            [--mask_radius MASK_RADIUS] [--padding PADDING]
+                            [--no_mask] [--invert_mask]
+                            [--pixel_size PIXEL_SIZE]
+                            [--resolution RESOLUTION] [--no_trim] [--no_shift]
+                            [--blur BLUR [BLUR ...]] [--pg PG] [--twist TWIST]
+                            [--rise RISE] [--center CENTER CENTER CENTER]
+                            [--axis1 AXIS1 AXIS1 AXIS1]
+                            [--axis2 AXIS2 AXIS2 AXIS2]
+                            [--ignore_symmetry IGNORE_SYMMETRY]
+                            [--keep_multiple_models] [--no_link_check]
+                            [--b_before_mask B_BEFORE_MASK]
+                            [--no_sharpen_before_mask]
+                            [--no_fix_microheterogeneity] [--no_fix_resi9999]
+                            [--no_check_ncs_overlaps]
+                            [--ligand [LIGAND [LIGAND ...]]]
+                            [--bfactor BFACTOR] [--ncsr {local,global}]
+                            [--ncycle NCYCLE] [--tlscycle TLSCYCLE]
+                            [--tlsin TLSIN] [--hydrogen {all,yes,no}]
+                            [--jellybody] [--jellybody_params sigma dmax]
+                            [--hout]
+                            [--weight_auto_scale WEIGHT_AUTO_SCALE | --weight_matrix WEIGHT_MATRIX]
+                            [--keywords KEYWORDS [KEYWORDS ...]]
+                            [--keyword_file KEYWORD_FILE [KEYWORD_FILE ...]]
+                            [--external_restraints_json EXTERNAL_RESTRAINTS_JSON]
+                            [--show_refmac_log]
+                            [--output_prefix OUTPUT_PREFIX]
+                            [--cross_validation]
+                            [--cross_validation_method {throughout,shake}]
+                            [--shake_radius SHAKE_RADIUS]
+                            [--mask_for_fofc MASK_FOR_FOFC | --mask_radius_for_fofc MASK_RADIUS_FOR_FOFC]
+                            [--trim_fofc_mtz]
+                            [--fsc_resolution FSC_RESOLUTION]
+
+Run REFMAC5 for SPA
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --exe EXE             refmac5 binary (default: refmac5)
+  --monlib MONLIB       Monomer library path. Default: $CLIBD_MON
+  --ligand [LIGAND [LIGAND ...]]
+                        restraint dictionary cif file(s)
+  --bfactor BFACTOR     reset all atomic B values to specified value
+  --ncsr {local,global}
+                        local or global NCS restrained (default: local)
+  --ncycle NCYCLE       number of cycles in Refmac (default: 10)
+  --tlscycle TLSCYCLE   number of TLS cycles in Refmac (default: 0)
+  --tlsin TLSIN         TLS parameter input for Refmac
+  --hydrogen {all,yes,no}
+                        all: add riding hydrogen atoms, yes: use hydrogen
+                        atoms if present, no: remove hydrogen atoms in input.
+                        Default: all
+  --jellybody           Use jelly body restraints
+  --jellybody_params sigma dmax
+                        Jelly body sigma and dmax (default: [0.01, 4.2])
+  --hout                write hydrogen atoms in the output model
+  --weight_auto_scale WEIGHT_AUTO_SCALE
+                        'weight auto' scale value. automatically determined
+                        from resolution and mask/box volume ratio if
+                        unspecified
+  --weight_matrix WEIGHT_MATRIX
+                        weight matrix value
+  --keywords KEYWORDS [KEYWORDS ...]
+                        refmac keyword(s)
+  --keyword_file KEYWORD_FILE [KEYWORD_FILE ...]
+                        refmac keyword file(s)
+  --external_restraints_json EXTERNAL_RESTRAINTS_JSON
+  --show_refmac_log     show all Refmac log instead of summary
+  --output_prefix OUTPUT_PREFIX
+                        output file name prefix (default: refined)
+  --cross_validation    Run cross validation
+  --cross_validation_method {throughout,shake}
+                        shake: randomize a model refined against a full map
+                        and then refine it against a half map, throughout: use
+                        only a half map for refinement (another half map is
+                        used for error estimation) Default: shake
+  --shake_radius SHAKE_RADIUS
+                        Shake rmsd in case of --cross_validation_method=shake
+                        (default: 0.3)
+  --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
+  --trim_fofc_mtz       diffmap.mtz will have smaller cell (if --mask_for_fofc
+                        is given)
+  --fsc_resolution FSC_RESOLUTION
+                        High resolution limit for FSC calculation. Default:
+                        Nyquist
+
+sfcalc:
+  --halfmaps HALFMAPS HALFMAPS
+                        Input half map files
+  --map MAP             Use this only if you really do not have half maps.
+  --mapref MAPREF       Reference map file
+  --mask MASK           Mask file
+  --model MODEL         Input atomic model file
+  --mask_radius MASK_RADIUS
+  --padding PADDING     Default: 2*mask_radius
+  --no_mask
+  --invert_mask         not for refinement.
+  --pixel_size PIXEL_SIZE
+                        Override pixel size (A)
+  --resolution RESOLUTION
+  --no_trim             Keep original box (not recommended)
+  --no_shift            Keep map origin so that output maps overlap with the
+                        input maps.
+  --blur BLUR [BLUR ...]
+                        Sharpening or blurring B
+  --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)
+  --ignore_symmetry IGNORE_SYMMETRY
+                        Ignore symmetry information (MTRIX/_struct_ncs_oper)
+                        in the model file
+  --keep_multiple_models
+                        Multi-models will be kept; by default only 1st model
+                        is kept because REFMAC5 does not support it
+  --no_link_check       Do not find and fix link records in input model.
+  --b_before_mask B_BEFORE_MASK
+                        sharpening B value for sharpen-mask-unsharpen
+                        procedure. By default it is determined automatically.
+  --no_sharpen_before_mask
+                        By default half maps are sharpened before masking by
+                        std of signal and unsharpened after masking. This
+                        option disables it.
+  --no_fix_microheterogeneity
+                        By default it will fix microheterogeneity for Refmac
+  --no_fix_resi9999     By default it will split chain if max residue number >
+                        9999 which is not supported by Refmac
+  --no_check_ncs_overlaps
+                        Disable model overlap (e.g. expanded model is used
+                        with --pg) test
+

servalcat-0.4.72/docs/help/trim.txt

@@ -0,0 +1,37 @@
+$ servalcat trim -h
+usage: servalcat trim [-h] [--maps MAPS [MAPS ...]] [--mask MASK]
+                      [--pixel_size PIXEL_SIZE] [--model MODEL [MODEL ...]]
+                      [--no_expand_ncs] [--padding PADDING]
+                      [--mask_cutoff MASK_CUTOFF] [--noncubic] [--noncentered]
+                      [--no_shift] [--no_shift_keep_cell]
+                      [--force_cell FORCE_CELL FORCE_CELL FORCE_CELL FORCE_CELL FORCE_CELL FORCE_CELL]
+                      [--disable_cell_check] [--shifts SHIFTS]
+
+Trim maps and shift models into a small new box.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --maps MAPS [MAPS ...]
+                        Input map file(s)
+  --mask MASK           Mask file
+  --pixel_size PIXEL_SIZE
+                        Override pixel size (A)
+  --model MODEL [MODEL ...]
+                        Input atomic model file(s)
+  --no_expand_ncs       Do not expand strict NCS in MTRIX or _struct_ncs_oper
+  --padding PADDING     padding in angstrom unit (default: 10.0)
+  --mask_cutoff MASK_CUTOFF
+                        Mask value cutoff to define boundary (default: 0.5)
+  --noncubic
+  --noncentered         If specified non-centered trimming is performed. Not
+                        recommended if having some symmetry
+  --no_shift            If specified resultant maps will have shifted origin
+                        and overlap with the input maps.
+  --no_shift_keep_cell  Keep original unit cell when --no_shift is given
+  --force_cell FORCE_CELL FORCE_CELL FORCE_CELL FORCE_CELL FORCE_CELL FORCE_CELL
+                        Use specified unit cell parameter
+  --disable_cell_check  Turn off unit cell consistency test
+  --shifts SHIFTS       Specify shifts.json to use precalculated parameters
+
+If --mask is provided, a boundary is decided using the mask and --padding.
+Otherwise the model is used.

servalcat-0.4.72/docs/index.rst

@@ -0,0 +1,28 @@
+.. servalcat documentation master file, created by
+   sphinx-quickstart on Fri Apr 22 07:49:31 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+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::
+
+   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>`_
+
+Table of Contents
+-----------------
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   spa
+   spa_examples/index
+   commands

servalcat-0.4.72/docs/overview.rst

@@ -0,0 +1,98 @@
+Overview
+========
+
+Servalcat has several functions for refinement and map calculations for crystallography and single particle analysis (SPA).
+
+* SPA
+   * refinement using REFMAC
+   * sharpened and weighted map calculation (Fo and Fo-Fc)
+   * map trimming tool
+   * refinement without REFMAC (experimental)
+* crystallography
+   * refinement of small molecule structures using REFMAC
+   * map calculation from ML parameter estimation
+   * refinement and map calculation using intensity (experimental)
+* others/general
+   * REFMAC5 wrapper ("refmacat")
+   * geometry optimisation 
+
+The basic usage is:
+
+.. code-block:: console
+
+    $ servalcat <command> <args>
+
+The most useful commands are shown below. To see all arguments for each command please run
+
+.. code-block:: console
+
+    $ servalcat <command> -h
+
+
+Command examples for cryo-EM SPA
+--------------------------------
+
+refinement using REFMAC5
+~~~~~~~~~~~~~~~~~~~~~~~~
+Servalcat makes refinement by REFMAC5 easy 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 \
+     --model input.pdb --resolution 2.5 \
+     --halfmaps ../half_map_1.mrc ../half_map_2.mrc \
+     --ncycle 10 [--pg C2] \
+     [--mask_for_fofc mask.mrc]
+
+Specify unsharpened and unweighted half maps (e.g. those after Refine3D of RELION) after ``--halfmaps``.
+
+If map has been symmetrised with a point group, asymmetric unit model should be given together with ``--pg`` to specify a point group symbol.
+It assumes the centre of the box is the origin of the symmetry and 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_auto_scale value`` : specify weight auto scale. 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)
+   * ``--pixel_size value`` : override pixel size of map
+   * ``--exe refmac5`` : specify REFMAC5 binary
+
+Output files:
+   * ``refined.pdb``: refined model
+   * ``refined_expanded.pdb``: symmetry-expanded version
+   * ``diffmap.mtz``: can be auto-opened with coot. sharpened and weighted Fo map and Fo-Fc map
+   * ``diffmap_normalized_fofc.mrc``: Fo-Fc map normalised within a mask. Look at raw values
+   * ``shifted_refined.log``: refmac log file
+
+Fo-Fc map calculation
+~~~~~~~~~~~~~~~~~~~~~
+It is important to refine individual atomic B values with electron scattering factors to calculate meaningful Fo-Fc map.
+Fo-Fc map is calculated in ``refine_spa`` command (explained above) so usually you do not need to run ``fofc`` command manually, but you may want to calculate e.g. 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 often have very large size due to unnecessary region outside the molecule. You can save disk space by trimming the unnecessary region.
+
+.. 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.72/docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx_rtd_theme >= 1.0.0
+sphinx >= 2.4.4