Merge pull request #736 from OpenFreeEnergy/document_cli_settings

Document cli settings

openfecli/commands/gather.py

@@ -311,7 +311,9 @@ def gather(rootdir, output, report, allow_partial):
     \b
     * 'dg' (default) reports the ligand, its absolute free energy, and
       the associated uncertainty as the maximum likelihood estimate obtained
-      from DDG replica averages and standard deviations.
+      from DDG replica averages and standard deviations.  These MLE estimates
+      are centred around 0.0, and when plotted can be shifted to match
+      experimental values.
     * 'ddg' reports pairs of ligand_i and ligand_j, the calculated
       relative free energy DDG(i->j) = DG(j) - DG(i) and its uncertainty.
     * 'raw' reports the raw results, which each repeat simulation given

openfecli/commands/plan_rbfe_network.py

@@ -2,11 +2,10 @@
 # For details, see https://github.com/OpenFreeEnergy/openfe
 
 import click
-from typing import List
 from openfecli.utils import write, print_duration
 from openfecli import OFECommandPlugin
 from openfecli.parameters import (
-    MOL_DIR, PROTEIN, MAPPER, OUTPUT_DIR, COFACTORS, YAML_OPTIONS,
+    MOL_DIR, PROTEIN, OUTPUT_DIR, COFACTORS, YAML_OPTIONS,
 )
 from openfecli.plan_alchemical_networks_utils import plan_alchemical_network_output
 
@@ -88,7 +87,7 @@ def plan_rbfe_network_main(
 )
 @print_duration
 def plan_rbfe_network(
-        molecules: List[str], protein: str, cofactors: tuple[str],
+        molecules: list[str], protein: str, cofactors: tuple[str],
         yaml_settings: str,
         output_dir: str,
 ):
@@ -98,22 +97,24 @@ def plan_rbfe_network(
 
     This tool is an easy way to set up a RBFE calculation campaign.
     The JSON files this outputs can be used to run each leg of the campaign.
-    For customized setups, please consider using the Python layer of
-    openfe. This tool makes the following choices:
+    openfe.
+    The generated Network will be stored in a folder containing for each
+    transformation a JSON file, that can be run with quickrun.
+
+    By default, this tool makes the following choices:
 
     * Atom mappings performed by LOMAP, with settings max3d=1.0 and
       element_change=False
-
     * Minimal spanning network as the network planner, with LOMAP default
       score as the weight function
-
-    * Water as solvent, with NaCl at 0.15 M.
-
+    * Water as solvent, with NaCl counter ions at 0.15 M concentration.
     * Protocol is the OpenMM-based relative hybrid topology protocol, with
       default settings.
 
-    The generated Network will be stored in a folder containing for each
-    transformation a JSON file, that can be run with quickrun.
+    These choices can be customized by creating a settings yaml file,
+    which is passed in via the ``-s settings.yaml`` option,
+    which is detailed in the Options section.
+    For more advanced setups, please consider using the Python layer of openfe.
     """
     write("RBFE-NETWORK PLANNER")
     write("______________________")

openfecli/commands/quickrun.py

@@ -40,14 +40,21 @@ def _format_exception(exception) -> str:
 )
 @print_duration
 def quickrun(transformation, work_dir, output):
-    """Run the transformation (edge) in the given JSON file in serial.
+    """Run the transformation (edge) in the given JSON file.
 
-    A transformation can be saved as JSON using from Python using its dump
+    Simulation JSON files can be created with the
+    :ref:`cli_plan-rbfe-network`
+    or from Python a :class:`.Transformation` can be saved using its dump
     method::
 
         transformation.dump("filename.json")
 
     That will save a JSON file suitable to be input for this command.
+
+    Running this command will execute the simulation defined in the JSON file,
+    creating a directory for each individual task (``Unit``) in the workflow.
+    For example, when running the OpenMM HREX Protocol a directory will be created
+    for each repeat of the sampling process (by default 3).
     """
     import gufe
     import os

openfecli/parameters/plan_network_options.py

@@ -174,9 +174,39 @@ def load_yaml_planner_options(path: Optional[str], context) -> PlanNetworkOption
     )
 
 
+_yaml_help = """\
+Path to planning settings yaml file
+
+Currently it can contain sections for customising the
+atom mapper and network planning algorithm,
+these are addressed using a `mapper:` or `network:` key in the yaml file.
+The algorithm to be used for these sections is then specified by the `method:` key. 
+For choosing mappers, either the LomapAtomMapper or KartografAtomMapper are allowed choices,
+while for the network planning algorithm either the generate_minimal_spanning_tree or
+generate_minimal_redundant_network options are allowed.
+Finally, a `settings:` key can be given to customise the algorithm,
+with allowable options corresponding to the keyword arguments of the Python API for these algorithms.
+
+For example, this is a valid settings yaml file to specify that
+the Lomap atom mapper should be used forbidding element changes,
+while the generate_minimal_redundant_network function used to plan the network
+::
+
+  mapper:
+    method: LomapAtomMapper
+    settings:
+      element_change: false
+
+  network:
+    method: generate_minimal_redundant_network
+    settings:
+      mst_num: 3
+"""
+
+
 YAML_OPTIONS = Option(
     '-s', "--settings", "yaml_settings",
     type=click.Path(exists=True, dir_okay=False),
-    help="Path to planning settings yaml file.",
+    help=_yaml_help,
     getter=load_yaml_planner_options,
 )