📝 Document "👽 Update CLI to accept dashes and underscores where appropriate" (#303)

Author: shnizzedy

.circleci/config.yml

@@ -33,7 +33,7 @@ commands:
             cd /home/circleci/build
             python -m venv ~/simple
             source ~/simple/bin/activate
-            pip install git+https://github.com/FCP-INDI/cpac.git@cabac8b820075876cfc28966071306b9314c139e semver
+            pip install git+https://github.com/FCP-INDI/cpac.git@81c33b52d72478bef54ccfdce05577d52ebf714c semver
             deactivate
   
   run-cpac-commands:
@@ -53,6 +53,9 @@ commands:
             mkdir -p docs/_sources/user/utils
             printf "Usage: cpac utils\n\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\`\n.. code-block:: console\n\n   $ cpac utils --help\n\n" > docs/_sources/user/utils/help.rst
             cpac utils --help | sed -e "s/.*/   &/" >> docs/_sources/user/utils/help.rst
+            mkdir -p docs/_sources/user/group/feat/load-preset/unpaired-two
+            printf ".. code-block:: console\n\n   $ cpac group feat load-preset unpaired-two --help\n\n" > docs/_sources/user/group/feat/load-preset/unpaired-two/help.rst
+            cpac group feat load-preset unpaired-two --help | sed -e "s/.*/   &/" >> docs/_sources/user/group/feat/load-preset/unpaired-two/help.rst
             deactivate
   prep-deploy:
     steps:
@@ -115,7 +118,7 @@ jobs:
   build-nightly:
     working_directory: /home/circleci/build
     docker:
-      - image: cimg/python:3.7
+      - image: cimg/python:3.10
     steps:
       - checkout:
           path: /home/circleci/build
@@ -131,7 +134,7 @@ jobs:
   build-version:
     working_directory: /home/circleci/build
     docker:
-      - image: cimg/python:3.7
+      - image: cimg/python:3.10
     steps:
       - checkout:
           path: /home/circleci/build
@@ -148,7 +151,7 @@ jobs:
   deploy-nightly:
     working_directory: /home/circleci/
     docker:
-      - image: cimg/python:3.7
+      - image: cimg/python:3.10
     steps:
       - attach_workspace:
           at: /home/circleci/
@@ -157,7 +160,7 @@ jobs:
   deploy-version:
     working_directory: /home/circleci/
     docker:
-      - image: cimg/python:3.7
+      - image: cimg/python:3.10
     steps:
       - attach_workspace:
           at: /home/circleci/

docs/_sources/developer/nodes.rst

@@ -7,9 +7,9 @@ Nodes
 
 .. _n_cpus:
 
-A Nipype :py:class:`~nipype.pipeline.engine.nodes.Node` has an initialization parameter ``mem_gb`` that differs from the :doc:`commandline option </user/run/help>` ``--mem_gb``. While the commandline option is **a limit**, the Node initialization parameter is **an estimate** of the most memory that Node will consume when run. The Node parameter is not a limit; rather, this value is used to allocate system resources at runtime.
+A Nipype :py:class:`~nipype.pipeline.engine.nodes.Node` has an initialization parameter ``mem_gb`` that differs from the :doc:`commandline option </user/run/help>` ``--mem-gb``. While the commandline option is **a limit**, the Node initialization parameter is **an estimate** of the most memory that Node will consume when run. The Node parameter is not a limit; rather, this value is used to allocate system resources at runtime.
 
-Conversely, the commandline option ``--n_cpus`` is **a limit** and the Node initialization parameter ``n_procs`` is **also a limit** of the maximum number of threads a Node will be permmitted to consume.
+Conversely, the commandline option ``--n-cpus`` is **a limit** and the Node initialization parameter ``n_procs`` is **also a limit** of the maximum number of threads a Node will be permmitted to consume.
 
 C-PAC automatically creates a JSON-like file called ``callback.log`` (via the function :py:func:`~CPAC.utils.monitoring.log_nodes_cb`) when running. This file includes for each Node:
 
@@ -18,7 +18,7 @@ C-PAC automatically creates a JSON-like file called ``callback.log`` (via the fu
    * specified maximum number of threads per Node, and
    * threads used at runtime.
 
-A ``callback.log`` can be provided to the pipeline configuration file (see :doc:`/user/compute_config`) or with the commandline flag ``--runtime_usage``. If a callback log is provided in the pipeline configuration, nodes with names that match nodes recorded in that pipeline log will have their memory estimates overridden by the values in the callback log plus a buffer percent (provided with the ``--runtime_buffer`` flag or in the pipeline configuration file).
+A ``callback.log`` can be provided to the pipeline configuration file (see :doc:`/user/compute_config`) or with the commandline flag ``--runtime-usage``. If a callback log is provided in the pipeline configuration, nodes with names that match nodes recorded in that pipeline log will have their memory estimates overridden by the values in the callback log plus a buffer percent (provided with the ``--runtime-buffer`` flag or in the pipeline configuration file).
 
 When a developer creates or modifies a Node in C-PAC, a ``mem_gb`` and ``n_procs`` argument should be provided unless the respective defaults of 0.2 and None (number of available system cores) are expected to be sufficient. When testing, the ``mem_gb`` and ``n_procs`` arguments should be adjusted if the observed memory and/or thread usage of a Node exceeds the estimate.
 

docs/_sources/user/compute_config.rst

@@ -20,8 +20,8 @@ Computer Settings
 
         `Open image <../_static/flowcharts/observed-usage.svg>`_
 
-    #. **Callback log - [text]:** The path to a callback log file from a previous run, including any resource-management parameters that will be applied in this run, like ``n_cpus`` and ``num_ants_threads``. This file is used override memory estimates with previously observed memory usage. Can be overridden with the commandline flag ``--runtime_usage``.
-    #. **Buffer - [percent]:** A percent of the previously observed memory usage that is to be added to the memory estimate. Default: 10. Can be overridden with the commandline flag ``--runtime_buffer``.
+    #. **Callback log - [text]:** The path to a callback log file from a previous run, including any resource-management parameters that will be applied in this run, like ``n_cpus`` and ``num_ants_threads``. This file is used override memory estimates with previously observed memory usage. Can be overridden with the commandline flag ``--runtime-usage``.
+    #. **Buffer - [percent]:** A percent of the previously observed memory usage that is to be added to the memory estimate. Default: 10. Can be overridden with the commandline flag ``--runtime-buffer``.
 
 #. **Number of Participants to Run Simultaneously - [integer]:** This number depends on computing resources.
 

docs/_sources/user/cpac.rst

@@ -88,32 +88,33 @@ To run C-PAC with a pipeline configuration file other than one of the pre-config
 
 .. code-block:: console
 
-    cpac run /Users/You/local_bids_data /Users/You/some_folder_for_outputs participant --pipeline_file /Users/You/Documents/pipeline_config.yml
+    cpac run /Users/You/local_bids_data /Users/You/some_folder_for_outputs participant --pipeline-file /Users/You/Documents/pipeline_config.yml
 
 Finally, to run C-PAC with a specific data configuration file (instead of providing a BIDS data directory):
 
 .. code-block:: console
 
-    cpac run /Users/You/any_directory /Users/You/some_folder_for_outputs participant --data_config_file /Users/You/Documents/data_config.yml
+    cpac run /Users/You/any_directory /Users/You/some_folder_for_outputs participant --data-config-file /Users/You/Documents/data_config.yml
 
-Note: we are still providing the postionally-required ``bids_dir`` input parameter. However C-PAC will not look for data in this directory when you provide a data configuration YAML with the ``--data_config_file`` flag. Providing ``.`` or ``$PWD`` will simply pass the present working directory. In addition, if the dataset in your data configuration file is not in BIDS format, just make sure to add the ``--skip_bids_validator`` flag at the end of your command to bypass the BIDS validation process.
+Note: we are still providing the postionally-required ``bids_dir`` input parameter. However C-PAC will not look for data in this directory when you provide a data configuration YAML with the ``--data-config-file`` flag. Providing ``.`` or ``$PWD`` will simply pass the present working directory. In addition, if the dataset in your data configuration file is not in BIDS format, just make sure to add the ``--skip-bids-validator`` flag at the end of your command to bypass the BIDS validation process.
 
 The full list of parameters and options that can be passed to C-PAC are shown below:
 
 .. include:: /user/run/help.rst
 
 .. include:: /user/utils/help.rst
 
-Note that any of the optional arguments above will over-ride any pipeline settings in the default pipeline or in the pipeline configuration file you provide via the ``--pipeline_file`` parameter.
+Note that any of the optional arguments above will over-ride any pipeline settings in the default pipeline or in the pipeline configuration file you provide via the ``--pipeline-file`` parameter.
 
 **Further usage notes:**
 
-* You can run only anatomical preprocessing easily, without modifying your data or pipeline configuration files, by providing the ``--anat_only`` flag.
+* You can run only anatomical preprocessing easily, without modifying your data or pipeline configuration files, by providing the ``--anat-only`` flag.
 
-* As stated, the default behavior is to read data that is organized in the BIDS format. This includes data that is in Amazon AWS S3 by using the format ``s3://<bucket_name>/<bids_dir>`` for the ``bids_dir`` command line argument. Outputs can be written to S3 using the same format for the ``output_dir``. Credentials for accessing these buckets can be specified on the command line (using ``--aws_input_creds`` or ``--aws_output_creds``).
+* As stated, the default behavior is to read data that is organized in the BIDS format. This includes data that is in Amazon AWS S3 by using the format ``s3://<bucket_name>/<bids_dir>`` for the ``bids_dir`` command line argument. Outputs can be written to S3 using the same format for the ``output_dir``. Credentials for accessing these buckets can be specified on the command line (using ``--aws-input-creds`` or ``--aws-output-creds``).
 
-* When the app is run, a data configuration file is written to the working directory. This directory can be specified with ``--working_dir`` or the directory from which you run ``cpac`` will be used. This file can be passed into subsequent runs, which avoids the overhead of re-parsing the BIDS input directory on each run (i.e. for cluster or cloud runs). These files can be generated without executing the C-PAC pipeline using the ``test_run`` command line argument.
+* When the app is run, a data configuration file is written to the working directory. This directory can be specified with ``--working-dir`` or the directory from which you run ``cpac`` will be used. This file can be passed into subsequent runs, which avoids the overhead of re-parsing the BIDS input directory on each run (i.e. for cluster or cloud runs). These files can be generated without executing the C-PAC pipeline using ``test_config`` as the analysis level.
 
 * The ``participant_label`` and ``participant_ndx`` arguments allow the user to specify which of the many datasets should be processed, which is useful when parallelizing the run of multiple participants.
 
 * If you want to pass runtime options to your container plaform (Docker or Singularity), you can pass them with ``-o`` or ``--container_options``.
+.. TODO: Update cpac to handle `-`s and `_`s like C-PAC

docs/_sources/user/docker.rst

@@ -58,9 +58,9 @@ To run the C-PAC Docker container with a pipeline configuration file other than
             -v /tmp:/tmp \
             -v /Users/You/Documents:/configs \
             -v /Users/You/resources:/resources \
-            fcpindi/c-pac:latest /bids_dataset /outputs participant --pipeline_file /configs/pipeline_config.yml
+            fcpindi/c-pac:latest /bids_dataset /outputs participant --pipeline-file /configs/pipeline_config.yml
 
-In this case, we need to map the directory containing the pipeline configuration file ``/Users/You/Documents`` to a Docker image virtual directory ``/configs``. Note we are using this ``/configs`` directory in the ``--pipeline_file`` input flag. In addition, if there are any ROIs, masks, or input files listed in your pipeline configuration file, the directory these are in must be mapped as well- assuming ``/Users/You/resources`` is your directory of ROI and/or mask files, we map it with ``-v /Users/You/resources:/resources``. In the pipeline configuration file you are providing, these ROI and mask files must be listed as ``/resources/ROI.nii.gz`` (etc.) because we have mapped ``/Users/You/resources`` to ``/resources``.
+In this case, we need to map the directory containing the pipeline configuration file ``/Users/You/Documents`` to a Docker image virtual directory ``/configs``. Note we are using this ``/configs`` directory in the ``--pipeline-file`` input flag. In addition, if there are any ROIs, masks, or input files listed in your pipeline configuration file, the directory these are in must be mapped as well- assuming ``/Users/You/resources`` is your directory of ROI and/or mask files, we map it with ``-v /Users/You/resources:/resources``. In the pipeline configuration file you are providing, these ROI and mask files must be listed as ``/resources/ROI.nii.gz`` (etc.) because we have mapped ``/Users/You/resources`` to ``/resources``.
 
 Finally, to run the Docker container with a specific data configuration file (instead of providing a BIDS data directory):
 
@@ -71,22 +71,22 @@ Finally, to run the Docker container with a specific data configuration file (in
             -v /Users/You/some_folder:/outputs \
             -v /tmp:/tmp \
             -v /Users/You/Documents:/configs \
-            fcpindi/c-pac:latest /bids_dataset /outputs participant --data_config_file /configs/data_config.yml
+            fcpindi/c-pac:latest /bids_dataset /outputs participant --data-config-file /configs/data_config.yml
 
-Note: we are still providing ``/bids_dataset`` to the ``bids_dir`` input parameter. However, we have mapped this to any directory on your machine, as C-PAC will not look for data in this directory when you provide a data configuration YAML with the ``--data_config_file`` flag. In addition, if the dataset in your data configuration file is not in BIDS format, just make sure to add the ``--skip_bids_validator`` flag at the end of your command to bypass the BIDS validation process.
+Note: we are still providing ``/bids_dataset`` to the ``bids_dir`` input parameter. However, we have mapped this to any directory on your machine, as C-PAC will not look for data in this directory when you provide a data configuration YAML with the ``--data-config-file`` flag. In addition, if the dataset in your data configuration file is not in BIDS format, just make sure to add the ``--skip-bids-validator`` flag at the end of your command to bypass the BIDS validation process.
 
 The full list of parameters and options that can be passed to the Docker container are shown below:
 
 .. include:: /user/run/help.rst
 
-Note that any of the optional arguments above will over-ride any pipeline settings in the default pipeline or in the pipeline configuration file you provide via the ``--pipeline_file`` parameter.
+Note that any of the optional arguments above will over-ride any pipeline settings in the default pipeline or in the pipeline configuration file you provide via the ``--pipeline-file`` parameter.
 
 **Further usage notes:**
 
-* You can run only anatomical preprocessing easily, without modifying your data or pipeline configuration files, by providing the ``--anat_only`` flag.
+* You can run only anatomical preprocessing easily, without modifying your data or pipeline configuration files, by providing the ``--anat-only`` flag.
 
-* As stated, the default behavior is to read data that is organized in the BIDS format. This includes data that is in Amazon AWS S3 by using the format ``s3://<bucket_name>/<bids_dir>`` for the ``bids_dir`` command line argument. Outputs can be written to S3 using the same format for the ``output_dir``. Credentials for accessing these buckets can be specified on the command line (using ``--aws_input_creds`` or ``--aws_output_creds``).
+* As stated, the default behavior is to read data that is organized in the BIDS format. This includes data that is in Amazon AWS S3 by using the format ``s3://<bucket_name>/<bids_dir>`` for the ``bids_dir`` command line argument. Outputs can be written to S3 using the same format for the ``output_dir``. Credentials for accessing these buckets can be specified on the command line (using ``--aws-input-creds`` or ``--aws-output-creds``).
 
-* When the app is run, a data configuration file is written to the working directory. This file can be passed into subsequent runs, which avoids the overhead of re-parsing the BIDS input directory on each run (i.e. for cluster or cloud runs). These files can be generated without executing the C-PAC pipeline using the test_run command line argument.
+* When the app is run, a data configuration file is written to the working directory. This file can be passed into subsequent runs, which avoids the overhead of re-parsing the BIDS input directory on each run (i.e. for cluster or cloud runs). These files can be generated without executing the C-PAC pipeline using ``test_config`` as the analysis level.
 
 * The ``participant_label`` and ``participant_ndx`` arguments allow the user to specify which of the many datasets should be processed, which is useful when parallelizing the run of multiple participants.

docs/_sources/user/group_fsl_feat.rst

@@ -45,7 +45,7 @@ You can generate any of these presets using the C-PAC command-line interface (CL
 
 .. code-block:: console
 
-    cpac group feat load_preset <preset type>
+    cpac group feat load-preset <preset type>
 
 Enter any of the following in place of :file:`<preset type>` for the type of analysis you want to run:
 
@@ -59,26 +59,21 @@ You can get more information about the required inputs for each preset with the
 
 .. code-block:: console
 
-    cpac group feat load_preset unpaired_two --help
+    cpac group feat load-preset unpaired-two --help
 
 This will produce:
 
-.. code-block:: console
-
-    Usage: cpac group feat load_preset unpaired_two [OPTIONS] GROUP_PARTICIPANTS
-                                                    Z_THRESH P_THRESH PHENO_FILE
-                                                    PHENO_SUB COVARIATE MODEL_NAME
-    Options:
-      --output_dir TEXT
-      --help             Show this message and exit.
+.. literalinclude:: /user/group/feat/load-preset/unpaired-two/help.rst
+    :language: bash
+    :start-at: Usage:
 
 Following this, you could generate a ready-to-run two-sample unpaired t-test by running the following, assuming the phenotype CSV has a column of participant IDs named "subject_id" and a column named "diagnosis", which is the covariate you wish to test:
 
 .. code-block:: console
 
-    cpac group feat load_preset unpaired_two /path/to/group_participant_list.txt 2.3 0.05
+    cpac group feat load-preset unpaired-two /path/to/group_participant_list.txt 2.3 0.05
             /path/to/phenotypic_file.csv subject_id diagnosis grp_analysis1 
-            --output_dir /path/to/output_dir
+            --output-dir /path/to/output_dir
 
 You will receive a message like this shortly after:
 
@@ -133,7 +128,7 @@ From the terminal
 
 Similar to the pipeline configuration YAML file, the group configuration YAML file allows you to configure your runs with key-value combinations. From terminal, you can quickly generate a default group configuration YAML file template in the directory you are in: ::
 
-    cpac utils group_config new_template
+    cpac utils group-config new-template
 
 This will generate a group configuration file that you can then modify to make your selections. See below: ::
 

docs/_sources/user/group_pybasc.rst

@@ -20,7 +20,7 @@ From terminal
 
 Similar to the pipeline configuration YAML file, the group configuration YAML file allows you to configure your runs with key-value combinations. From terminal, you can quickly generate a default group configuration YAML file template in the directory you are in: ::
 
-    cpac utils group_config new_template
+    cpac utils group-config new-template
 
 This will generate a group configuration file that you can then modify to make your selections. See below: ::