Merge pull request #783 from OpenFreeEnergy/issue_745_results_docs

docs: working with individual results page

docs/guide/results/index.rst

@@ -1,8 +1,12 @@
 .. _userguide_results:
 
 Working with Results
-====================
+=====================
 
-This section is still under construction. In the meantime, please
-contact us on our `issue tracker <https://github.com/OpenFreeEnergy/openfe/issues>`_
-if you have any questions about analysing your results!
+With simulations completed,
+the results of individual simulations can be inspected,
+and entire networks of results analysed.
+
+.. toctree::
+   working_with_results
+   working_with_networks

docs/guide/results/working_with_networks.rst

@@ -0,0 +1,10 @@
+.. _userguide_result_networks:
+
+Working with networks of results
+================================
+
+issue #803
+
+
+The :ref:`openfe gather <cli_gather>` command offers a way to collate information across many different individual
+simulations and prepare a table of results.

docs/guide/results/working_with_results.rst

@@ -0,0 +1,57 @@
+.. _userguide_individual_results:
+
+Working with individual results
+===============================
+
+With :ref:`execution of your calculations <userguide_execution>` completed,
+we can now start looking at what has been produced.
+The majority of Protocols will produce estimates of free energy differences between two or more ``ChemicalSystem`` \s
+(the current exception being the :class:`.PlainMDProtocol` which just simulates the dynamics of a single system).
+Beyond this, the exact data produced by a given Protocol can vary significantly,
+for example the :class:`.RelativeHybridTopologyProtocol` protocol will produce graphs to assess the quality of the simulation, alongside trajectory data files.
+By comparison, the :class:`.PlainMDProtocol` will only produce the latter.
+For exact details on what is produced consult the :ref:`pages for each Protocol<userguide_protocols>`.
+
+.. todo crossref to HREX and MD Protocol docs from issue 743
+
+How you can inspect these results depends on whether you have executed your simulations
+from the command line or a Python script.
+
+From command line execution
+---------------------------
+
+If you had executed your calculation using the :ref:`quickrun <cli_quickrun>` command,
+then a ``.json`` results log file as well as a directory of files will have been produced.
+This directory will have various plots and results of analysis, the exact details of which are described
+in the :ref:`pages for each Protocol<userguide_protocols>`.
+
+Most importantly, the ``.json`` results file has ``estimate`` and ``uncertainty`` keys,
+which serve the same purpose as the ``get_estimate()`` and ``get_uncertainty()`` methods described below.
+The full ``json`` results file can be reloaded into a Python session as::
+
+  >>> import gufe
+  >>> import json
+  >>>
+  >>> with open('././Transformation-97d7223f918bbdb0570edc2a49bbc43e_results.json', 'r') as f:
+  ...     results = json.load(f, cls=gufe.tokenization.JSON_HANDLER.decoder)
+  >>> results['estimate']
+  -19.889719513104342 <Unit('kilocalorie_per_mole')>
+  >>> results['uncertainty']
+  0.574685524681712 <Unit('kilocalorie_per_mole')>
+
+
+From Python execution
+---------------------
+
+Executing a :class:`.ProtocolDAG` using :func:`openfe.execute_DAG` will produce a :class:`.ProtocolDAGResult`,
+representing a single iteration of estimating the free energy difference.
+One or more of these can be put into the ``.gather()`` method of the ``Protocol`` to form a :class:`.ProtocolResult`,
+this class takes care of the averaging and concatenation of different iterations of the estimation process.
+This ``ProtocolResult`` class has ``.get_estimate()`` and ``.get_uncertainty()`` methods which return the estimates
+of free energy difference along with its uncertainty.
+
+See Also
+--------
+
+For how to deal with multiple results forming a network consult the :ref:`working with networks<userguide_result_networks>`
+page.