add docs for gathering septop and abfe

docs/conf.py

@@ -102,6 +102,7 @@
 ]
 
 autodoc_mock_imports = [
+    "cinnabar",
     "MDAnalysis",
     "matplotlib",
     "mdtraj",
@@ -113,6 +114,7 @@
     "openmmforcefields",
     "psutil",
     "py3Dmol",
+    "zstandard",
 ]
 
 # Extensions for the myst parser

docs/mambaf9t4jj8g5ei

@@ -0,0 +1,5 @@
+git+https://github.com/OpenFreeEnergy/gufe@main
+git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@v0.3.1
+git+https://github.com/OpenFreeEnergy/kartograf@main
+git+https://github.com/OpenFreeEnergy/konnektor@main
+git+https://github.com/OpenFreeEnergy/lomap@main

docs/reference/cli/gather.rst

@@ -3,5 +3,21 @@
 ``gather`` command
 ====================
 
+Currently, ``openfe gather`` is only able to gather results from Relative Binding Free Energy (RBFE) calculations.
+
+To gather results from ABFE or SepTop protocols, you may use the experimental :ref:`openfe gather-abfe <gather-abfe>` and  :ref:`openfe gather-septop <gather-septop>` CLI commands, but please note that these commands are still under development and liable to change in future releases, and meant to be used only for exploratory work.
+
 .. click:: openfecli.commands.gather:gather
    :prog: openfe gather
+
+
+.. _gather-abfe:
+
+.. click:: openfecli.commands.gather_abfe:gather_abfe
+   :prog: openfe gather-abfe
+
+
+.. _gather-septop:
+
+.. click:: openfecli.commands.gather_septop:gather_septop
+   :prog: openfe gather-septop

openfecli/commands/gather.py

@@ -697,7 +697,7 @@ def rich_print_to_stdout(df: pd.DataFrame) -> None:
 
 @click.command(
     "gather",
-    short_help="Gather result jsons for network of RFE results into a TSV file",
+    short_help="Gather result JSONs for network of RBFE results into a TSV file.",
 )
 @click.argument(
     "results",
@@ -712,11 +712,17 @@ def rich_print_to_stdout(df: pd.DataFrame) -> None:
     show_default=True,
     help=(
         "What data to report. 'dg' gives maximum-likelihood estimate of "
-        "absolute deltaG,  'ddg' gives delta-delta-G, and 'raw' gives "
+        "absolute deltaG, 'ddg' gives delta-delta-G, and 'raw' gives "
         "the raw result of the deltaG for a leg."
     ),
 )
-@click.option("output", "-o", type=click.File(mode="w"), default="-")
+@click.option(
+    "output",
+    "-o",
+    type=click.File(mode="w"),
+    default="-",
+    help="Filepath at which to write the tsv report.",
+)
 @click.option(
     "--tsv",
     is_flag=True,
@@ -743,28 +749,28 @@ def gather(
     tsv: bool,
     allow_partial: bool,
 ):
-    """Gather simulation result JSON files of relative calculations to a tsv file.
+    """Gather simulation result JSON files from RBFE simulations and generate a report.
+
+    RESULTS is the path(s) to JSON files or directories of JSON files containing RBFE protocol results as generated by ``openfe quickrun``.
 
-    This walks RESULTS recursively and finds all result JSON files from the
-    quickrun command (these files must end in .json). Each of these contains
-    the results of a separate leg from a relative free energy thermodynamic
-    cycle.
+    All directories will be walked recursively and any valid JSON results files will be gathered.
+    Files must end in .json to be collected, and invalid files will be ignored.
 
-    The results reported depend on ``--report`` flag:
+    The results reported depends on ``--report`` flag:
 
     \b
-    * 'dg' (default) reports the ligand, its absolute free energy, and
+    * ``--report=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.  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
+    * ``--report=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
+    * ``--report=raw`` reports the raw results, which each repeat simulation given
       separately (i.e. no combining of redundant simulations is performed)
 
     The output is a table of **tab** separated values. By default, this
-    outputs to stdout, use the -o option to choose an output file.
+    outputs to stdout, use the -o option to specify an output filepath.
     """
     # find and filter result jsons
     result_fns = _collect_result_jsons(results)

openfecli/commands/gather_abfe.py

@@ -224,7 +224,9 @@ def _generate_dg_raw(results_dict: dict[str, dict[str, list]], allow_partial: bo
     return df_out
 
 
-@click.command("gather-abfe")
+@click.command(
+    "gather-abfe", short_help="Gather result JSONs for network of ABFE results into a TSV file."
+)
 @click.argument(
     "results",
     nargs=-1,  # accept any number of results
@@ -241,7 +243,13 @@ def _generate_dg_raw(results_dict: dict[str, dict[str, list]], allow_partial: bo
         "'raw' outputs the raw dG values for each individual leg in the ABFE transformation cycles."
     ),
 )
-@click.option("output", "-o", type=click.File(mode="w"), default="-")
+@click.option(
+    "output",
+    "-o",
+    type=click.File(mode="w"),
+    default="-",
+    help="Filepath at which to write the tsv report.",
+)
 @click.option(
     "--tsv",
     is_flag=True,
@@ -268,6 +276,34 @@ def gather_abfe(
     tsv: bool,
     allow_partial: bool,
 ):
+    """
+    .. warning::
+
+        Gathering of ABFE results with ``openfe gather-abfe`` is an experimental feature
+        and is subject to change in a future release of openfe!
+
+    Gather simulation result JSON files from ABFE simulations and generate a report.
+
+    RESULTS is the path(s) to JSON files or directories of JSON files containing ABFE protocol results as generated by ``openfe quickrun``.
+
+    All directories will be walked recursively and any valid JSON results files will be gathered.
+    Files must end in .json to be collected, and invalid files will be ignored.
+
+    Each JSON contains the results of a separate leg from an Absolute Binding Free Energy calculation.
+    See https://docs.openfree.energy/en/latest/tutorials/abfe_tutorial.html for details on running ABFE calculations.
+
+    The results reported depends on the ``--report`` flag:
+
+    \b
+    * ``--report=dg`` (default) reports the ligand, its absolute free energy, and
+      the associated uncertainty obtained from DG replica averages and
+      standard deviations.
+    * ``--report=raw`` reports the raw results, which each repeat simulation given
+      separately (i.e. no combining of redundant simulations is performed)
+
+    The output is a table of **tab** separated values. By default, this
+    outputs to stdout, use the -o option to specify an output filepath.
+    """
     msg = "WARNING! Gathering of ABFE results with `openfe gather-abfe` is an experimental feature and is subject to change in a future release of openfe."
     click.secho(msg, err=True, fg="yellow")  # fmt: skip
 

openfecli/commands/gather_septop.py

@@ -307,7 +307,10 @@ def _generate_raw(
     return df_out
 
 
-@click.command("gather-septop")
+@click.command(
+    "gather-septop",
+    short_help="Gather result JSONs for a network of SepTop results into a TSV file.",
+)
 @click.argument(
     "results",
     nargs=-1,  # accept any number of results
@@ -325,7 +328,13 @@ def _generate_raw(
         "the raw result of the deltaG for a leg."
     ),
 )
-@click.option("output", "-o", type=click.File(mode="w"), default="-")
+@click.option(
+    "output",
+    "-o",
+    type=click.File(mode="w"),
+    default="-",
+    help="Filepath at which to write the tsv report.",
+)
 @click.option(
     "--tsv",
     is_flag=True,
@@ -352,6 +361,39 @@ def gather_septop(
     tsv: bool,
     allow_partial: bool,
 ):
+    """
+    .. warning::
+
+        Gathering of SepTop results with ``openfe gather-septop`` is an experimental feature
+        and is subject to change in a future release of openfe!
+
+    Gather simulation result JSON files from SepTop simulations and generate a report.
+
+    RESULTS is the path(s) to JSON files or directories of JSON files containing SepTop protocol results as generated by ``openfe quickrun``.
+
+    All directories will be walked recursively and any valid JSON results files will be gathered.
+    Files must end in .json to be collected, and invalid files will be ignored.
+
+    Each JSON contains the results of a separate leg from a Separated Topologies calculation.
+    See https://docs.openfree.energy/en/latest/tutorials/septop_tutorial.html for details on running SepTop calculations.
+
+    The results reported depends on ``--report`` flag:
+
+    \b
+    * ``--report=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.  These MLE estimates
+      are centred around 0.0, and when plotted can be shifted to match
+      experimental values.
+    * ``--report=ddg`` reports pairs of ligand_i and ligand_j, the calculated
+      relative free energy DDG(i->j) = DG(j) - DG(i) and its uncertainty.
+    * ``--report=raw`` reports the raw results, which each repeat simulation given
+      separately (i.e. no combining of redundant simulations is performed)
+
+    The output is a table of **tab** separated values. By default, this
+    outputs to stdout, use the -o option to specify an output filepath.
+    """
+
     msg = "WARNING! Gathering of SepTop results with `openfe gather-septop` is an experimental feature and is subject to change in a future release of openfe."
     click.secho(msg, err=True, fg="yellow")  # fmt: skip
     # find and filter result jsons