Adding details about --n-protocol-repeats to CLI tutorial (#213)

* Start adding details about --n-protocol-repeats

* Update rbfe_tutorial/cli_tutorial.md

* Apply suggestions from code review

* update result tree

* update language

* updating output example

* =1 -> 1

---------

Co-authored-by: Alyssa Travitz <31974495+atravitz@users.noreply.github.com>
Co-authored-by: Alyssa Travitz <alyssa.travitz@omsf.io>

Author: IAlibay

rbfe_tutorial/cli_tutorial.md

@@ -38,7 +38,7 @@ running the simulations and gathering the results are the same.
 With the single command:
 
 ```bash
-openfe plan-rbfe-network -M tyk2_ligands.sdf -p tyk2_protein.pdb -o network_setup
+openfe plan-rbfe-network -M tyk2_ligands.sdf -p tyk2_protein.pdb -o network_setup --n-protocol-repeats 1
 ```
 
 we do the following:
@@ -49,6 +49,11 @@ we do the following:
 - Pass a PDB of the protein target (TYK2) with `-p tyk2_protein.pdb`.
 - Instruct `openfe` to output files into a directory called `network_setup`
     with the `-o network_setup` option.
+- Instruct `openfe` to only run one repeat of the alchemical simulation per
+  `quickrun` call using `--n-protocol-repeats 1`.
+  **Note:** `openfe`'s default behaviour is to use three
+  repeats to calculate the uncertainty (i.e. standard deviation) in an estimate. When
+  setting `--n-protocol-repeats 1`, you must execute the transformation multiple times - at minimum 2, but best practie is 3 independent repeats.
 
 Planning the campaign may take some time due to the complex series of tasks involved:
 
@@ -61,7 +66,7 @@ The partial charge generation can take advantage of multiprocessing which offers
 the number of processors available using the `-n` flag:
 
 ```bash
-openfe plan-rbfe-network -M tyk2_ligands.sdf -p tyk2_protein.pdb -o network_setup -n 4
+openfe plan-rbfe-network -M tyk2_ligands.sdf -p tyk2_protein.pdb -o network_setup --n-protocol-repeats 1 -n 4
 ```
 
 This will result in a directory called `network_setup/`, which is structured like this:
@@ -80,7 +85,7 @@ network_setup
     ├── rbfe_lig_ejm_31_complex_lig_ejm_50_complex.json
     ├── rbfe_lig_ejm_31_solvent_lig_ejm_42_solvent.json
     ├── rbfe_lig_ejm_31_solvent_lig_ejm_46_solvent.json
-[continues]
+    ...
 ```
 
 The `ligand_network.graphml` file describes the atom mappings between the
@@ -146,7 +151,7 @@ partial_charge:
 2. Plan your rbfe network with an additional `-s` flag for passing the settings:
 
 ```bash
-openfe plan-rbfe-network -M tyk2_ligands.sdf -p tyk2_protein.pdb -o network_setup -s settings.yaml
+openfe plan-rbfe-network -M tyk2_ligands.sdf -p tyk2_protein.pdb -o network_setup --n-protocol-repeats 1 -s settings.yaml
 ```
 
 3. The output of the CLI program will now reflect the changes made:
@@ -156,17 +161,19 @@ RBFE-NETWORK PLANNER
 ______________________
 
 Parsing in Files: 
-        Got input: 
-                Small Molecules: SmallMoleculeComponent(name=lig_ejm_54) SmallMoleculeComponent(name=lig_jmc_23) SmallMoleculeComponent(name=lig_ejm_47) SmallMoleculeComponent(name=lig_jmc_27) SmallMoleculeComponent(name=lig_ejm_46) SmallMoleculeComponent(name=lig_ejm_31) SmallMoleculeComponent(name=lig_ejm_42) SmallMoleculeComponent(name=lig_ejm_50) SmallMoleculeComponent(name=lig_ejm_45) SmallMoleculeComponent(name=lig_jmc_28) SmallMoleculeComponent(name=lig_ejm_55) SmallMoleculeComponent(name=lig_ejm_43) SmallMoleculeComponent(name=lig_ejm_48)
-                Protein: ProteinComponent(name=)
-                Cofactors: []
-                Solvent: SolventComponent(name=O, Na+, Cl-)
+	Got input:
+		Small Molecules: SmallMoleculeComponent(name=lig_ejm_31) SmallMoleculeComponent(name=lig_ejm_42) SmallMoleculeComponent(name=lig_ejm_43) SmallMoleculeComponent(name=lig_ejm_46) SmallMoleculeComponent(name=lig_ejm_47) SmallMoleculeComponent(name=lig_ejm_48) SmallMoleculeComponent(name=lig_ejm_50) SmallMoleculeComponent(name=lig_jmc_23) SmallMoleculeComponent(name=lig_jmc_27) SmallMoleculeComponent(name=lig_jmc_28)
+		Protein: ProteinComponent(name=)
+		Cofactors: []
+		Solvent: SolventComponent(name=O, Na+, Cl-)
 
 Using Options:
-        Mapper: <kartograf.atom_mapper.KartografAtomMapper object at 0x7fea079de790>
-        Mapping Scorer: <function default_lomap_score at 0x7fea1b423d80>
-        Networker: functools.partial(<function generate_maximal_network at 0x7fea18371260>)
-        Partial Charge Generation: am1bccelf10
+	Mapper: <LomapAtomMapper (time=20, threed=True, max3d=1.0, element_change=True, seed='', shift=False)>
+	Mapping Scorer: <function default_lomap_score at 0x166bc5300>
+	Network Generation: <function generate_minimal_spanning_network at 0x16a413e20>
+	Partial Charge Generation: am1bcc
+
+	n_protocol_repeats=1 (1 simulation repeat(s) per transformation)
 ```
 
 That concludes the straightforward process of tailoring your OpenFE setup to your specifications.
@@ -214,7 +221,7 @@ where `path/to/transformation.json` is the path to one of the files created abov
 
 When running a complete network of simulations, it is important to ensure that
 the file name for the result JSON and name of the working directory are
-different for each leg, otherwise you'll overwrite results. We recommend doing
+different for each leg and each repeat, otherwise you'll overwrite results. We recommend doing
 that with something like the following, which uses the fact that the JSON files
 in `network_setup/transformations/` have unique names, and creates directories
 and result JSON files based on those names. To run all legs sequentially (not
@@ -225,7 +232,10 @@ recommended) you could do something like:
 for file in network_setup/transformations/*.json; do
   relpath=${file:30}  # strip off "network_setup/transformations/"
   dirpath=${relpath%.*}  # strip off final ".json"
-  openfe quickrun $file -o results/$relpath -d results/$dirpath
+  # loop over three repeats
+  for repeat in {1..3}; do
+      openfe quickrun $file -o results/repeat${repeat}/$relpath -d results/repeat${repeat}/$dirpath
+  done
 done
 ```
 
@@ -241,10 +251,12 @@ and submit a job script for the simplest SLURM use case:
 for file in network_setup/transformations/*.json; do
   relpath=${file:30}  # strip off "network_setup/transformations/"
   dirpath=${relpath%.*}  # strip off final ".json"
-  jobpath="network_setup/transformations/${dirpath}.job"
-  cmd="openfe quickrun $file -o results/$relpath -d results/$dirpath"
-  echo -e "#!/usr/bin/env bash\n${cmd}" > $jobpath
-  sbatch $jobpath
+  for repeat in {1..3}; do
+      jobpath="network_setup/transformations/${dirpath}_${repeat}.job"
+      cmd="openfe quickrun $file -o results/repeat${repeat}/$relpath -d results/repeat${repeat}/$dirpath"
+      echo -e "#!/usr/bin/env bash\n${cmd}" > $jobpath
+      sbatch $jobpath
+  done
 done
 ```
 
@@ -273,29 +285,42 @@ openfe
 
 ```text
 results
-├── rbfe_lig_ejm_31_complex_lig_ejm_42_complex
-│   ├── shared_RelativeHybridTopologyProtocolUnit-3ea82011-75f0-4bb6-b415-e7d05bd012f6
-│   │   ├── checkpoint.nc
-│   │   └── simulation.nc
-│   ├── shared_RelativeHybridTopologyProtocolUnit-5262feb6-cb50-4bb2-90a2-359810c2bb9c
-│   │   ├── checkpoint.nc
-│   │   └── simulation.nc
-│   └── shared_RelativeHybridTopologyProtocolUnit-7a6def34-2967-4452-8d47-483bc7219c06
-│       ├── checkpoint.nc
-│       └── simulation.nc
-├── rbfe_lig_ejm_31_complex_lig_ejm_42_complex.json
-├── rbfe_lig_ejm_31_complex_lig_ejm_46_complex
-│   ├── shared_RelativeHybridTopologyProtocolUnit-ad113e55-5636-474e-9be3-ee77fe887e77
-│   │   ├── checkpoint.nc
-│   │   └── simulation.nc
-│   ├── shared_RelativeHybridTopologyProtocolUnit-ca74ad3c-2ac8-4961-be7c-fa802a1ec76b
-│   │   ├── checkpoint.nc
-│   │   └── simulation.nc
-│   └── shared_RelativeHybridTopologyProtocolUnit-f848e671-fdd3-4b8d-8bd2-6eb5140e3ed3
-│       ├── checkpoint.nc
-│       └── simulation.nc
-├── rbfe_lig_ejm_31_complex_lig_ejm_46_complex.json
-[continues]
+├── replicate_0
+│   ├── rbfe_lig_ejm_31_complex_lig_ejm_42_complex
+│   │   ├── shared_RelativeHybridTopologyProtocolUnit-79c279f04ec84218b7935bc0447539a9_attempt_0
+│   │   │   ├── checkpoint.nc
+│   │   │   ├── db.json
+│   │   │   ├── simulation_real_time_analysis.yaml
+│   │   │   └── simulation.nc
+│   │   ├── shared_RelativeHybridTopologyProtocolUnit-a3cef34132aa4e9cbb824fcbcd043b0e_attempt_0
+│   │   │   ├── checkpoint.nc
+│   │   │   ├── db.json
+│   │   │   ├── simulation_real_time_analysis.yaml
+│   │   │   └── simulation.nc
+│   │   └── shared_RelativeHybridTopologyProtocolUnit-abb2b104151c45fc8b0993fa0a7ee0af_attempt_0
+│   │       ├── checkpoint.nc
+│   │       ├── db.json
+│   │       ├── simulation_real_time_analysis.yaml
+│   │       └── simulation.nc
+│   ├── rbfe_lig_ejm_31_complex_lig_ejm_42_complex.json
+│   ├── rbfe_lig_ejm_31_complex_lig_ejm_46_complex
+│   │   ├── shared_RelativeHybridTopologyProtocolUnit-361500fe831c431aa830efd207db0955_attempt_0
+│   │   │   ├── checkpoint.nc
+│   │   │   ├── db.json
+│   │   │   ├── simulation_real_time_analysis.yaml
+│   │   │   └── simulation.nc
+│   │   ├── shared_RelativeHybridTopologyProtocolUnit-5a6176cfbf074f92bc76caac91b1c1bf_attempt_0
+│   │   │   ├── checkpoint.nc
+│   │   │   ├── db.json
+│   │   │   ├── simulation_real_time_analysis.yaml
+│   │   │   └── simulation.nc
+│   │   └── shared_RelativeHybridTopologyProtocolUnit-e16de73f07964e9096f34611e0c874ca_attempt_0
+│   │       ├── checkpoint.nc
+│   │       ├── db.json
+│   │       ├── simulation_real_time_analysis.yaml
+│   │       └── simulation.nc
+│   ├── rbfe_lig_ejm_31_complex_lig_ejm_46_complex.json
+...
 ```
 
 The JSON results file contains not only the calculated $\Delta G$, and