💡 Update comments based on default preconfig

Author: ChildMindInstituteCNL

CPAC/resources/configs/pipeline_config_anat-only.yml

@@ -98,7 +98,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [Off]
 
     func_registration_to_template:

CPAC/resources/configs/pipeline_config_benchmark-ANTS.yml

@@ -109,7 +109,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [On]
 
     func_registration_to_template:

CPAC/resources/configs/pipeline_config_benchmark-FNIRT.yml

@@ -126,7 +126,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [On]
 
     func_registration_to_template:

CPAC/resources/configs/pipeline_config_blank.yml

@@ -522,14 +522,28 @@ segmentation:
       WM_label: [2, 41]
 
 registration_workflows:
+
+  # Runtime quality checks
   guardrails:
+
+    # Minimum QC values to allow a run to complete post-registration
+    # Set any metric empty (like "Dice:") or to None to disable that guardrail
+    # Default thresholds adopted from XCP-Engine
+    # (https://github.com/PennLINC/xcpEngine/blob/397ab6cf/designs/cbf_all.dsn#L66)
     thresholds:
       Dice:
       Jaccard:
       CrossCorr:
       Coverage:
+
+    # If this option is turned on and best_of is set to 1, any registration step that falls below the specified thresholds will retry with an incremented seed
     retry_on_first_failure: Off
+
+    # If this number is > 1, C-PAC will run that many iterations of each registration calculation and choose the registration with the smallest difference from 1 across all specified thresholds
+    # If this number ≠ 1, the retry_on_first_failure option will have no effect
+    # Must be at least 1
     best_of: 1
+
   anatomical_registration:
     run: Off
     registration:
@@ -695,7 +709,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [Off]
 
         # reference for boundary based registration
@@ -1199,8 +1214,7 @@ functional_preproc:
     # this is a fork point
     #   run: [On, Off] - this will run both and fork the pipeline
     run: [Off]
-
-    space: 'native'
+    space: native
 
 nuisance_corrections:
   2-nuisance_regression:

CPAC/resources/configs/pipeline_config_ccs-options.yml

@@ -126,7 +126,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [On]
 
     func_registration_to_template:

CPAC/resources/configs/pipeline_config_fmriprep-options.yml

@@ -264,7 +264,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [On]
 
         # reference for boundary based registration

CPAC/resources/configs/pipeline_config_ndmg.yml

@@ -74,7 +74,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [On]
 
     func_registration_to_template:

CPAC/resources/configs/pipeline_config_rbc-options.yml

@@ -31,13 +31,23 @@ pipeline_setup:
     random_seed: 77742777
 
 registration_workflows:
+
+  # Runtime quality checks
   guardrails:
+
+    # Minimum QC values to allow a run to complete post-registration
+    # Set any metric empty (like "Dice:") or to None to disable that guardrail
+    # Default thresholds adopted from XCP-Engine
+    # (https://github.com/PennLINC/xcpEngine/blob/397ab6cf/designs/cbf_all.dsn#L66)
     thresholds:
       Dice: 0.8
       Jaccard: 0.9
       CrossCorr: 0.7
       Coverage: 0.8
+
+    # If this option is turned on and best_of is set to 1, any registration step that falls below the specified thresholds will retry with an incremented seed
     retry_on_first_failure: On
+
   anatomical_registration:
 
     # Template to be used during registration.
@@ -55,7 +65,12 @@ registration_workflows:
   functional_registration:
     coregistration:
       boundary_based_registration:
+
+        # this is a fork point
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [fallback]
+
     func_registration_to_template:
       output_resolution:
 
@@ -120,7 +135,7 @@ functional_preproc:
     # this is a fork point
     #   run: [On, Off] - this will run both and fork the pipeline
     run: [On]
-    space: 'template'
+    space: template
 
 nuisance_corrections:
   2-nuisance_regression:

CPAC/resources/configs/pipeline_config_regtest-1.yml

@@ -109,7 +109,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [On]
 
     func_registration_to_template:

CPAC/resources/configs/pipeline_config_regtest-2.yml

@@ -130,7 +130,8 @@ registration_workflows:
       boundary_based_registration:
 
         # this is a fork point
-        #   run: [On, Off] - this will run both and fork the pipeline
+        #   run: [On, Off, fallback] - this will run both and fork the pipeline
+        #   if 'fallback' is one of the selected options, BBR will run and, if its output fails quality_thresholds, the pipeline will fallback to BBR's input image
         run: [On]
 
     func_registration_to_template: