🔀 Merge source into doc/xcpqc

shnizzedy · shnizzedy · commit 382484582fe9 · 2022-01-24T16:23:21.000-05:00
diff --git a/docs/_sources/developer/index.rst b/docs/_sources/developer/index.rst
@@ -18,6 +18,7 @@ Contents:
    installation
    pipeline
    nodes
+   random_state
    workflow_documentation
    workflows/index
    xcpqc
diff --git a/docs/_sources/developer/nodes.rst b/docs/_sources/developer/nodes.rst
@@ -1,7 +1,6 @@
 *****
 Nodes
 *****
-
 .. _mem_gb:
 
 .. _n_procs:
@@ -23,8 +22,10 @@ When a developer creates or modifies a Node in C-PAC, a ``mem_gb`` and ``n_procs
 
 For nodes that will use a varying amount of memory depending on the node's input data, the optional parameter ``mem_x`` takes a tuple of ``(memory multiplier, input file, multiplier mode)`` where ``memory multiplier`` is a number and ``input file`` is the string name of the Node input to multiply such that the memory estimate returned by the ``mem_gb`` attribute is the ``mem_gb`` argument plus ``memory multiplier`` times the dimensions of the ``input file`` as specified in the ``multiplier mode`` (``xyzt`` (spatial × temporal; default), ``xyz`` (spatial), or just ``t`` (temporal)).
 
-.. note::
-   ``mem_x`` is a new parameter in C-PAC v1.8.1 and subject to change in future releases as we continue to `develop methods for setting data- and operation-dependent memory estimates <https://github.com/FCP-INDI/C-PAC/issues/1509>`_.
+
+   .. note::
+      ``mem_x`` is a new parameter in C-PAC v1.8.1 and subject to change in future releases as we continue to `develop methods for setting data- and operation-dependent memory estimates <https://github.com/FCP-INDI/C-PAC/issues/1509>`_.
+
 
 .. autoclass:: CPAC.pipeline.nipype_pipeline_engine.Node
    :special-members: __init__
@@ -36,17 +37,33 @@ For nodes that will use a varying amount of memory depending on the node's input
    :members:
    :inherited-members:
 
+.. autoclass:: nipype.interfaces.base.core.Interface
+   :special-members: __init__
+   :members:
+   :inherited-members:
+
+
+   .. seealso::
+      `Nipype: Interface Specifications <https://nipype.readthedocs.io/en/1.5.1/devel/interface_specs.html>`_
+
+
+.. autoclass:: CPAC.utils.interfaces.function.Function
+   :special-members: __init__
+   :members:
+   :inherited-members:
+
 .. autoclass:: CPAC.pipeline.nipype_pipeline_engine.Workflow
    :special-members: __init__
    :members:
    :inherited-members:
 
+
 The Nipype utility function :py:func:`~nipype.utils.draw_gantt_chart.log_to_dict` reads a log file generated by ``log_nodes_cb`` to a Python dictionary.
 
+
 .. autofunction:: CPAC.utils.monitoring.log_nodes_cb
 
-draw_gantt_chart
-================
+
 
 .. automodule:: CPAC.utils.monitoring.draw_gantt_chart
    :members: resource_report, log_to_dict, generate_gantt_chart, resource_overusage_report
diff --git a/docs/_sources/developer/random_state.rst b/docs/_sources/developer/random_state.rst
@@ -0,0 +1,13 @@
+Random State
+============
+
+When performing reproducibility/variability experiments, it is important to isolate sources of variability. One such source is random state.
+
+Users can fix the random state of C-PAC's execution by specifying a random seed. When adding a Node that should accept a user-specified random seed, add
+
+* the :py:class:`nipype.interfaces.base.core.Interface` and the corresponding flags to add/remove to set the random seed, or
+* in the case of a :py:class:`CPAC.utils.interfaces.function.Function` Node, the Function node's function and a function to apply to that function definition to set the random seed
+
+to :py:func:`CPAC.pipeline.random_state.seed.random_seed_flags`.
+
+.. autofunction:: CPAC.pipeline.random_state.seed.random_seed_flags
diff --git a/docs/_sources/user/pipelines/design_a_pipeline.rst b/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
 
diff --git a/docs/_sources/user/pipelines/pipeline_config.rst b/docs/_sources/user/pipelines/pipeline_config.rst
@@ -37,15 +37,10 @@ Definitions
     .. include:: /glossary/template.rst
         :start-line: 3
 
-.. rubric:: Reference
-
-.. bibliography:: /references/glossary.bib
-   :style: cpac_docs_style
-   :cited:
-   :keyprefix: glossary-
 
 .. include:: design_a_pipeline.rst
 
+
 .. _using_a_text_editor:
 
 Using a Text Editor
@@ -97,6 +92,39 @@ Why a list?
 '''''''''''
 You may notice as you learn about the settings for various outputs that many of the values for C-PAC's configurable settings are stored in lists (i.e., multiple values are separated by commas and surrounded by square brackets).  Such lists containing ``On``s and ``Off``s (for ``True`` and ``False`` respectively) allow you to toggle on multiple options at the same time, and branch a pipeline into two different analysis strategies. See the `developer documentation <http://fcp-indi.github.io/docs/developer/workflows/cpac_pipeline.html>`_ for more information about how lists are used in C-PAC.
 
+Configurable Settings
+------------------------------
+
+.. raw:: html
+
+    <div class="flowchart-container"><object data="../_static/flowcharts/pipeline-individual.svg" type="image/svg+xml"></object></div>
+
+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
+'''''''''''''''''''''''''
+
+* :doc:`Anatomical Preprocessing </user/anat>`
+* :doc:`Functional Preprocessing </user/func>`
+* :doc:`Nuisance Corrections </user/nuisance>`
+* :doc:`Time Series Extraction </user/tse>`
+* :doc:`After Warp Settings </user/after_warp>`
+
+Derivatives
+'''''''''''
+
+* :doc:`Seed-based Correlation Analysis (SCA) and Dual Regression </user/sca>` - Analyze the connectivity between brain regions.
+* :doc:`Voxel-mirrored Homotopic Connectivity (VMHC) </user/vmhc>` - Investigate connectivity between hemispheres.
+* :doc:`Amplitude of Low Frequency Fluctuations (ALFF) and fractional ALFF (fALFF) </user/alff>` - Measure the power of slow fluctuations in brain activity.
+* :doc:`Regional Homogeneity (ReHo) </user/reho>` - Measure the similarity of activity patterns across neighboring voxels.
+* :doc:`Network Centrality </user/centrality>` - Analyze the structure of functional networks.
+
+
 .. toctree::
    :maxdepth: 2
 
@@ -106,3 +134,12 @@ You may notice as you learn about the settings for various outputs that many of
    pre-and-post
    derivatives
    quality
+
+
+.. rubric:: Reference
+
+
+.. bibliography:: /references/glossary.bib
+    :style: cpac_docs_style
+    :cited:
+    :keyprefix: glossary-
diff --git a/docs/_sources/user/pipelines/preconfig.rst b/docs/_sources/user/pipelines/preconfig.rst
@@ -84,6 +84,11 @@ This pipeline is designed to increase reproducibility with the preprocessing res
 * `https://github.com/poldracklab/fmriprep <https://github.com/poldracklab/fmriprep>`_
 * `https://www.nature.com/articles/s41592-018-0235-4 <https://www.nature.com/articles/s41592-018-0235-4>`_
 
+rbc-options: ReproBrainChart Options Pipeline
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pipeline Configuration YAML: `https://github.com/FCP-INDI/C-PAC/blob/main/CPAC/resources/configs/pipeline_config_rbc-options.yml <https://github.com/FCP-INDI/C-PAC/blob/main/CPAC/resources/configs/pipeline_config_rbc-options.yml>`_
+
 benchmark-ANTS: C-PAC Benchmark with ANTs Registration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/docs/_sources/user/pipelines/random_state.rst b/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__]))
diff --git a/docs/_sources/user/singularity.rst b/docs/_sources/user/singularity.rst
@@ -3,13 +3,13 @@ Run on Singularity
 
 For those who wish to avoid the administrator rights requirements often associated with Docker usage (or the security hazards when used on a shared computing system), `Singularity <https://singularityhub.github.io/singularityhub-docs/>`_ is a good option. Singularity is a container solution just like Docker, except it is designed specifically to offer secure deployment on shared cluster environments.
 
-You can pull a Singularity container much like how you would pull a Docker container, except you are pulling from `Singularity Hub <https://singularityhub.github.io/singularityhub-docs/>`_:
+You can pull a Singularity container much like how you would pull a Docker container:
 
 .. code-block:: console
 
-    singularity pull shub://FCP-INDI/C-PAC
+    singularity pull docker://fcpindi/c-pac:latest
 
-This will produce a Singularity container image in your current directory, named something like ``FCP-INDI-C-PAC-master-latest.simg``.
+This will produce a Singularity container image in your current directory, named something like ``c-pac_latest.sif``. You can instead specify the local filename you want before the ``docker://`` URI.
 
 Running a Singularity image is similar to running a Docker image, except ``-B`` maps local directories to a location in the Singularity image instead of ``-v``:
 
