diff --git a/docs/conf.py b/docs/conf.py index 28a89fcee..f06c3c7c0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -195,7 +195,7 @@ else: repo = git.Repo.clone_from( "https://github.com/OpenFreeEnergy/ExampleNotebooks.git", - branch="rename-cinnabar-howto", + branch="prep-analysis-for-howto", to_path=example_notebooks_path, ) except Exception as e: diff --git a/docs/guide/protocols/absolutebinding.rst b/docs/guide/protocols/absolutebinding.rst index c9986f433..acb5d380b 100644 --- a/docs/guide/protocols/absolutebinding.rst +++ b/docs/guide/protocols/absolutebinding.rst @@ -129,10 +129,22 @@ Because the ligand is held in place by orientational restraints in the complex leg, also check that the restraint geometry stays well defined; see the `Boresch restraint analysis tutorial `_. -The multistate trajectory (``simulation.nc``) and its topology -(``alchemical_system.pdb``) can be analysed further using `openfe_analysis`_. -.. TODO: Link to the trajectory visualisation how_to_guide when published. +.. _abfe_trajectory_output: + +Trajectory output +""""""""""""""""" + +Each leg writes a multistate trajectory (``complex.nc`` and ``solvent.nc``) with its topology +(``alchemical_system.pdb``). The trajectory stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_indices`` are saved, which by default excludes water. +Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also -------- diff --git a/docs/guide/protocols/absolutesolvation.rst b/docs/guide/protocols/absolutesolvation.rst index bdd10fc5e..1e89be702 100644 --- a/docs/guide/protocols/absolutesolvation.rst +++ b/docs/guide/protocols/absolutesolvation.rst @@ -111,11 +111,24 @@ The frame stride can be set through ``analysis_settings.skip`` in :class:`.AbsoluteSolvationSettings` (by default, about 500 frames are analysed per state). The ligand atoms must be included in the trajectory output, through ``output_indices`` in ``solvent_output_settings``; otherwise -the structural analysis is skipped. The multistate trajectories -(``solvent.nc`` and ``vacuum.nc``) can be analysed further using -`openfe_analysis`_. - -.. TODO: Link to the trajectory visualisation how_to_guide when published. +the structural analysis is skipped. + +.. _ahfe_trajectory_output: + +Trajectory output +""""""""""""""""" + +Each leg writes a multistate trajectory (``solvent.nc`` and ``vacuum.nc``) with its topology +(``hybrid_system.pdb``). The trajectory stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_indices`` are saved, which by default excludes water. +Both files can be loaded with `openfe_analysis`_ to visualize +the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also diff --git a/docs/guide/protocols/relativehybridtopology.rst b/docs/guide/protocols/relativehybridtopology.rst index b8dee3515..6a384ffb2 100644 --- a/docs/guide/protocols/relativehybridtopology.rst +++ b/docs/guide/protocols/relativehybridtopology.rst @@ -198,10 +198,31 @@ the interacting part of the ligand remains in its binding pose. Inspect the trajectory before interpreting a high RMSD as evidence of ligand displacement. -The multistate trajectory (``simulation.nc``) and the hybrid topology -(``hybrid_system.pdb``) can be analysed further using `openfe_analysis`_. - -.. TODO: Link to the trajectory visualisation how_to_guide when published. +.. _rbfe_trajectory_output: + +Trajectory output +""""""""""""""""" + +The multistate trajectory (``simulation.nc``) stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_settings.output_indices`` are saved, which by default excludes water. + +The accompanying topology (``hybrid_system.pdb``) contains the hybrid ligand, in which the core atoms are shared +between both end states. Its temperature factors record which end state each atom belongs to: + +* ``0.0``: environment atoms (protein, ions and any saved solvent) +* ``0.25``: atoms unique to ligand A +* ``0.5``: core atoms, present in both end states +* ``0.75``: atoms unique to ligand B + +The atoms of end state A are therefore those with a temperature factor of ``0.5`` or lower, +and the atoms of end state B are those with ``0.0``, ``0.5`` or ``0.75``. +Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also diff --git a/docs/guide/protocols/septop.rst b/docs/guide/protocols/septop.rst index de10a567b..2a14130eb 100644 --- a/docs/guide/protocols/septop.rst +++ b/docs/guide/protocols/septop.rst @@ -141,10 +141,27 @@ Because both ligands are held in place by orientational restraints in the complex leg, also check that the restraint geometry stays well defined; see the `Boresch restraint analysis tutorial `_. -The multistate trajectory (``simulation.nc``) and its topology -(``alchemical_system.pdb``) can be analysed further using `openfe_analysis`_. -.. TODO: Link to the trajectory visualisation how_to_guide when published. +.. _septop_trajectory_output: + +Trajectory output +""""""""""""""""" + +Each leg writes a multistate trajectory (``complex.nc`` and ``solvent.nc``) with its topology +(``alchemical_system.pdb``). The trajectory stores the positions of every replica, together with the λ state each +replica was in at each iteration. A trajectory can therefore be read in two ways: at a fixed λ **state**, combining +frames from whichever replica occupied that state, or along a single **replica** as it moves between λ states. +This applies to the default replica exchange sampler (``sampler_method = "repex"``). +With ``"independent"`` sampling, replicas never change state, so both give the same trajectory; +with ``"sams"``, a λ state is not necessarily occupied at every iteration, so reading by state may not be possible. +Only the atoms selected by ``output_indices`` are saved, which by default excludes water. + +Unlike the hybrid topology, both ligands are present with their own atoms in every λ state; what changes along +the λ schedule is how strongly each ligand interacts with its environment. In the first λ state, ligand A is fully +interacting and ligand B is decoupled; in the last λ state, the reverse is true. The atoms of each end state are +therefore the environment atoms together with the atoms of the respective ligand. +Both files can be loaded with `openfe_analysis`_ to visualize the simulation, extract the trajectories of the end states, +or analyse them further; see :doc:`/how_to_guides/simulation_visualization`. See Also -------- diff --git a/docs/guide/results/index.rst b/docs/guide/results/index.rst index ce3d80905..115a26795 100644 --- a/docs/guide/results/index.rst +++ b/docs/guide/results/index.rst @@ -18,6 +18,5 @@ and entire networks of results analysed. * :doc:`/how_to_guides/gather_results` * :doc:`/how_to_guides/plotting_with_cinnabar` * :doc:`/how_to_guides/load_results` + * :doc:`/how_to_guides/simulation_visualization` * :doc:`/how_to_guides/jq_inspection` - -.. TODO: add openfe_analysis how-to. diff --git a/docs/guide/results/working_with_results.rst b/docs/guide/results/working_with_results.rst index a608f680a..109b7c835 100644 --- a/docs/guide/results/working_with_results.rst +++ b/docs/guide/results/working_with_results.rst @@ -57,6 +57,7 @@ and the uncertainty is their standard deviation. .. admonition:: How-to guides * :doc:`/how_to_guides/load_results` + * :doc:`/how_to_guides/simulation_visualization` * :doc:`/how_to_guides/jq_inspection` See Also diff --git a/docs/how_to_guides/index.rst b/docs/how_to_guides/index.rst index b9834a625..41af51270 100644 --- a/docs/how_to_guides/index.rst +++ b/docs/how_to_guides/index.rst @@ -62,10 +62,9 @@ For the concepts behind each step, see the :doc:`User Guide `. gather_results plotting_with_cinnabar load_results + simulation_visualization jq_inspection -.. TODO: Add Analyze an RBFE network with cinnabar" (from - guide/results/working_with_networks) and "Visualize trajectories with openfe_analysis". .. TODO: merge dumping_transformation and jq_inspection into a single "Save and inspect OpenFE JSON files" how-to. diff --git a/docs/how_to_guides/simulation_visualization.nblink b/docs/how_to_guides/simulation_visualization.nblink new file mode 100644 index 000000000..195a78ab5 --- /dev/null +++ b/docs/how_to_guides/simulation_visualization.nblink @@ -0,0 +1,3 @@ +{ + "path": "../ExampleNotebooks/cookbook/simulation_visualization.ipynb" +} diff --git a/docs/tutorials/showcase_notebook.nblink b/docs/tutorials/showcase_notebook.nblink index b4b180ee5..50ebe5cc3 100644 --- a/docs/tutorials/showcase_notebook.nblink +++ b/docs/tutorials/showcase_notebook.nblink @@ -1,8 +1,7 @@ { "path": "../ExampleNotebooks/showcase/openfe_showcase.ipynb", "extra-media": [ - "../ExampleNotebooks/showcase/tyk2.png", - "../ExampleNotebooks/showcase/OFE-color-horizontal.png", + "../ExampleNotebooks/showcase/images", "../ExampleNotebooks/showcase/inputs" ] }