diff --git a/actions/ost-compare-ligand-structures b/actions/ost-compare-ligand-structures
index cf87c1c13353d98b7c7256cc525af303331de26a..a8e314ed659c88ea6923cc7739ec00b77e3d0383 100644
--- a/actions/ost-compare-ligand-structures
+++ b/actions/ost-compare-ligand-structures
@@ -1,7 +1,7 @@
"""
-Evaluate model with non-polymer/small molecule ligands against reference
+Evaluate model with non-polymer/small molecule ligands against reference.
-Example: ost compare-structures-new \\
+Example: ost compare-ligand-structures \\
-m model.pdb \\
-ml ligand.sdf \\
-r reference.cif \\
@@ -14,8 +14,15 @@ Ligands can be given as path to SDF files containing the ligand for both model
(--model-ligands/-ml) and reference (--reference-ligands/-rl). If omitted,
ligands will be detected in the model and reference structures. For structures
given in mmCIF format, this is based on the annotation as "non polymer entity"
-and works reliably. For structures given in PDB format, this is based on the
-HET records and is normally not what you want.
+(i.e. ligands in the _pdbx_entity_nonpoly mmCIF category) and works reliably.
+For structures given in PDB format, this is based on the HET records and is
+normally not what you want. You should always give ligands as SDF for
+structures in PDB format.
+
+Ligands in mmCIF and PDB files must comply with the PDB component dictionary
+definition, and have properly named residues and atoms, in order for
+ligand connectivity to be loaded correctly. Ligands loaded from SDF files
+are exempt from this restriction, meaning any arbitrary ligand can be assessed.
Output is written in JSON format (default: out.json). In case of no additional
options, this is a dictionary with three keys:
@@ -32,18 +39,15 @@ options, this is a dictionary with three keys:
content of the JSON output will be \"status\" set to FAILURE and an
additional key: "traceback".
-Each score is opt-in and can be enabled with optional arguments and is added
-to the output. Keys correspond to the values in `"model_ligands"` above.
+Each score is opt-in and, be enabled with optional arguments and is added
+to the output. Keys correspond to the values in "model_ligands" above.
Only mapped ligands are reported.
-
-
"""
import argparse
import json
import os
import traceback
-import warnings
import ost
from ost import conop
@@ -171,19 +175,21 @@ def _ParseArgs():
"--radius",
dest="radius",
default=4.0,
- help=("."))
+ help=("Inclusion radius for the binding site. Any residue with atoms "
+ "within this distance of the ligand will be included in the "
+ "binding site."))
parser.add_argument(
"--lddt-pli-radius",
dest="lddt_pli_radius",
default=6.0,
- help=("."))
+ help=("lDDT inclusion radius for lDDT-PLI."))
parser.add_argument(
"--lddt-bs-radius",
dest="lddt_bs_radius",
default=4.0,
- help=("."))
+ help=("lDDT inclusion radius for lDDT-BS."))
parser.add_argument(
'-v',
diff --git a/modules/doc/actions.rst b/modules/doc/actions.rst
index 6afdbe6ce7dc8bfcc804077ff8bd81bf186ad1f7..c10f942e809bcbdfa3aec0da85ccb1e6f401ac08 100644
--- a/modules/doc/actions.rst
+++ b/modules/doc/actions.rst
@@ -224,3 +224,102 @@ Details on the usage (output of ``ost compare-structures --help``):
Residues are represented as string in form
<num><inscode>. The respective scores are available as
keys "patch_qs" and "patch_dockq"
+
+
+.. _ost compare ligand structures:
+
+Comparing two structures with ligands
+--------------------------------------------------------------------------------
+
+You can compare two structures with non-polymer/small molecule ligands from the
+command line with the ``ost compare-ligand-structures`` action.
+
+Details on the usage (output of ``ost compare-ligand-structures --help``):
+
+.. code-block:: console
+
+ usage: ost compare-ligand-structures [-h] -m MODEL [-ml [MODEL_LIGANDS ...]] -r REFERENCE [-rl [REFERENCE_LIGANDS ...]] [-o OUTPUT] [-mf {pdb,mmcif}]
+ [-rf {cif,mmcif}] [-ft] [-rna] [-cr] [-sm] [--lddt-pli] [--rmsd] [--radius RADIUS] [--lddt-pli-radius LDDT_PLI_RADIUS]
+ [--lddt-bs-radius LDDT_BS_RADIUS] [-v VERBOSITY]
+
+ Evaluate model with non-polymer/small molecule ligands against reference.
+
+ Example: ost compare-ligand-structures \
+ -m model.pdb \
+ -ml ligand.sdf \
+ -r reference.cif \
+ --lddt-pli --rmsd
+
+ Only minimal cleanup steps are performed (remove hydrogens, and for structures
+ only, remove unknown atoms and cleanup element column).
+
+ Ligands can be given as path to SDF files containing the ligand for both model
+ (--model-ligands/-ml) and reference (--reference-ligands/-rl). If omitted,
+ ligands will be detected in the model and reference structures. For structures
+ given in mmCIF format, this is based on the annotation as "non polymer entity"
+ (i.e. ligands in the _pdbx_entity_nonpoly mmCIF category) and works reliably.
+ For structures given in PDB format, this is based on the HET records and is
+ normally not what you want. You should always give ligands as SDF for
+ structures in PDB format.
+
+ Ligands in mmCIF and PDB files must comply with the PDB component dictionary
+ definition, and have properly named residues and atoms, in order for
+ ligand connectivity to be loaded correctly. Ligands loaded from SDF files
+ are exempt from this restriction, meaning any arbitrary ligand can be assessed.
+
+ Output is written in JSON format (default: out.json). In case of no additional
+ options, this is a dictionary with three keys:
+
+ * "model_ligands": A list of ligands in the model. If ligands were provided
+ explicitly with --model-ligands, elements of the list will be the paths to
+ the ligand SDF file(s). Otherwise, they will be the chain name and residue
+ number of the ligand, separated by a dot.
+ * "reference_ligands": A list of ligands in the reference. If ligands were
+ provided explicitly with --reference-ligands, elements of the list will be
+ the paths to the ligand SDF file(s). Otherwise, they will be the chain name
+ and residue number of the ligand, separated by a dot.
+ * "status": SUCCESS if everything ran through. In case of failure, the only
+ content of the JSON output will be "status" set to FAILURE and an
+ additional key: "traceback".
+
+ Each score is opt-in and, be enabled with optional arguments and is added
+ to the output. Keys correspond to the values in "model_ligands" above.
+ Only mapped ligands are reported.
+
+ options:
+ -h, --help show this help message and exit
+ -m MODEL, --mdl MODEL, --model MODEL
+ Path to model file.
+ -ml [MODEL_LIGANDS ...], --mdl-ligands [MODEL_LIGANDS ...], --model-ligands [MODEL_LIGANDS ...]
+ Path to model ligand files.
+ -r REFERENCE, --ref REFERENCE, --reference REFERENCE
+ Path to reference file.
+ -rl [REFERENCE_LIGANDS ...], --ref-ligands [REFERENCE_LIGANDS ...], --reference-ligands [REFERENCE_LIGANDS ...]
+ Path to reference ligand files.
+ -o OUTPUT, --out OUTPUT, --output OUTPUT
+ Output file name. The output will be saved as a JSON file. default: out.json
+ -mf {pdb,mmcif}, --mdl-format {pdb,mmcif}, --model-format {pdb,mmcif}
+ Format of model file. Inferred from path if not given.
+ -rf {cif,mmcif}, --reference-format {cif,mmcif}, --ref-format {cif,mmcif}
+ Format of reference file. Inferred from path if not given.
+ -ft, --fault-tolerant
+ Fault tolerant parsing.
+ -rna, --residue-number-alignment
+ Make alignment based on residue number instead of using a global BLOSUM62-based alignment (NUC44 for nucleotides).
+ -cr, --check-resnames
+ Enforce residue name matches between mapped model and targetresidues.
+ -sm, --substructure-match
+ Allow incomplete target ligands.
+ --lddt-pli Compute lDDT-PLI score and store as key "lddt-pli".
+ --rmsd Compute RMSD score and store as key "lddt-pli".
+ --radius RADIUS Inclusion radius for the binding site. Any residue with atoms within this distance of the ligand will be included in the binding site.
+ --lddt-pli-radius LDDT_PLI_RADIUS
+ lDDT inclusion radius for lDDT-PLI.
+ --lddt-bs-radius LDDT_BS_RADIUS
+ lDDT inclusion radius for lDDT-BS.
+ -v VERBOSITY, --verbosity VERBOSITY
+ Set verbosity level. Defaults to 3 (INFO).
+
+Additional information about the scores and output values is available in
+:meth:`rmsd_details <ost.mol.alg.ligand_scoring.LigandScorer.rmsd_details>` and
+:meth:`lddt_pli_details <ost.mol.alg.ligand_scoring.LigandScorer.lddt_pli_details>`.
\ No newline at end of file