📝 Add user docs for random state

Ref FCP-INDI/C-PAC#1496

Co-authored-by: Greg Kiar <[email protected]>

Author: shnizzedy

docs/_sources/user/pipelines/design_a_pipeline.rst

@@ -13,21 +13,21 @@ Design A Pipeline
 
 C-PAC offers a graphical interface you can use to quickly and easily modify the default pipeline or create your own from scratch: `https://fcp-indi.github.io/C-PAC_GUI/ <https://fcp-indi.github.io/C-PAC_GUI/>`_
 
-.. note::
+    .. note::
+
+    Currently the GUI creates a C-PAC v1.6.0 pipeline configuration file. This syntax persisted through v1.7.2 but is deprecated with the release of v1.8.0.
 
-   Currently the GUI creates a C-PAC v1.6.0 pipeline configuration file. This syntax persisted through v1.7.2 but is deprecated with the release of v1.8.0.
+    If given a pipeline file in the older syntax, C-PAC v1.8 will attempt to convert the pipeline configuration file to the new syntax, saving the converted file in your output directory.
 
-   If given a pipeline file in the older syntax, C-PAC v1.8 will attempt to convert the pipeline configuration file to the new syntax, saving the converted file in your output directory.
+    An update to the GUI to create v1.8.0 syntax configuration files is underway.
 
-   An update to the GUI to create v1.8.0 syntax configuration files is underway.
+    The newer (v1.8) syntax will not work with older versions of C-PAC.
 
-   The newer (v1.8) syntax will not work with older versions of C-PAC.
+    See :ref:`using_a_text_editor` for configuring a custom pipeline without the GUI.
+    
+.. seealso::
 
-   See :ref:`using_a_text_editor` for configuring a custom pipeline without the GUI.
-   
-   .. seealso::
-   
-      :doc:`Details about mapping the older syntax to the new. </user/pipelines/1.7-1.8-nesting-mappings>`
+    :doc:`Details about mapping the older syntax to the new. </user/pipelines/1.7-1.8-nesting-mappings>`
 
 .. figure:: /_images/gui_home1.png
 

docs/_sources/user/pipelines/pipeline_config.rst

@@ -39,13 +39,15 @@ Definitions
 
 .. rubric:: Reference
 
-.. bibliography:: /references/glossary.bib
-   :style: cpac_docs_style
-   :cited:
-   :keyprefix: glossary-
+    .. bibliography:: /references/glossary.bib
+       :style: cpac_docs_style
+       :cited:
+       :keyprefix: glossary-
+
 
 .. include:: design_a_pipeline.rst
 
+
 .. _using_a_text_editor:
 
 Using a Text Editor
@@ -109,6 +111,7 @@ Data Management and Environment Settings
 
 * :doc:`Computer Settings </user/compute_config>`
 * :doc:`Output Settings </user/output_config>`
+* :doc:`Random State </user/pipelines/random_state>`
 
 Pre- and post-processing
 '''''''''''''''''''''''''

docs/_sources/user/pipelines/random_state.rst

@@ -0,0 +1,34 @@
+Random State
+============
+
+When performing reproducibility/variability experiments, it is important to isolate sources of variability. One such source is random state.
+
+Random seed can be set in pipeline config
+
+.. literalinclude:: /references/default_pipeline.yml
+   :language: YAML
+   :start-at: pipeline_setup:
+   :lines: 1
+
+.. literalinclude:: /references/default_pipeline.yml
+   :language: YAML
+   :start-at: system_config:
+   :end-before: # Select Off if you intend to run CPAC on a single machine.
+
+or on the command line with ``--random_seed $SEED``.
+
+Valid options are positive integers up to 2,147,483,647 or the word 'random' (which will set an integer in that range). If not specified, a seed will not be set, and each relevant process will run with an undocumented random seed.
+
+When a seed is set, a ``random.log`` file, including the constant seed and each node the seed was applied to, will be generated in the logging directory.
+
+The following processes currently support this feature:
+
+.. exec::
+    from CPAC.pipeline.random_state.seed import random_seed_flags, \
+                                                set_up_random_state
+    set_up_random_state('random')
+    processes = random_seed_flags()
+    for interface in processes['interfaces'].keys():
+        print(interface._cmd)
+    for fxn in processes['functions'].keys():
+        print('.'.join([fxn.__module__, fxn.__name__]))