Merge pull request #345 from PennLINC/doc/purge_txt

Add specification to use relative path for files listed in scans.txt used in `cubids purge`

Author: tien-tong

cubids/cli.py

@@ -578,7 +578,12 @@ def _parse_purge():
         "scans",
         type=IsFile,
         action="store",
-        help="path to the txt file of scans whose associations should be purged.",
+        help=(
+            "path to the txt file of scans whose associations should be purged. "
+            "When specifying files in this txt file, "
+            "always use relative paths starting from your BIDS directory. "
+            "e.g., ``sub-01/ses-01/func/sub-01_ses-01_task-rest_bold.nii.gz``"
+        ),
     )
     parser.add_argument(
         "--use-datalad",

cubids/cubids.py

@@ -726,7 +726,7 @@ def purge(self, scans_txt):
         scans_txt : str
             path to the .txt file that lists the scans
             you want to be deleted from the dataset, along
-            with thier associations.
+            with their associations.
             example path: /Users/Covitz/CCNP/scans_to_delete.txt
         """
         self.scans_txt = scans_txt

docs/example.rst

@@ -211,13 +211,15 @@ To do this, we run the ``cubids purge`` command.
 ``cubids purge`` requires as input a list of files to cleanly "purge" from the dataset.
 You can create this file in any text editor,
 as long as it is saved as plain text ``.txt``.
+When specifying files in this text file, 
+always use relative paths starting from your BIDS directory.
 For this example, we created the following file:
 
 .. code-block:: console
 
     $ cat no_ped.txt
 
-    /AN/EXAMPLE/PATH/CuBIDS_Test/BIDS_Dataset_Datalad/sub-02/ses-phdiff/func/sub-02_ses-phdiff_task-rest_bold.nii.gz
+    sub-02/ses-phdiff/func/sub-02_ses-phdiff_task-rest_bold.nii.gz
 
 
 and saved it in our ``CuBIDS_Test directory``.