Merge branch 'main' into bids-atlas-update

Author: tsalo

docs/api.rst

@@ -18,10 +18,5 @@ Library API
 ***********
 
 .. toctree::
-   :glob:
 
-   api/xcp_d.cli
-   api/xcp_d.workflows
-   api/xcp_d.interfaces
-   api/xcp_d.utils
-   api/xcp_d.ingression
+   api/xcp_d

docs/workflows.rst

@@ -352,6 +352,7 @@ The ``--skip`` parameter accepts the following options:
       Historically, users could pass the legacy ``--skip-parcellation`` flag to
       achieve this behavior. That flag is now deprecated — use
       ``--skip parcellation`` instead.
+
    **Note that skipping parcellation will automatically skip connectivity as well,
    since connectivity requires parcellated data.**
 

xcp_d/config.py

@@ -31,7 +31,7 @@
 The module has a :py:func:`~xcp_d.config.to_filename` function to allow writing out
 the settings to hard disk in *ToML* format, which looks like:
 
-.. literalinclude:: ../xcp_d/data/tests/config.toml
+.. literalinclude:: ../../xcp_d/data/tests/config.toml
    :language: toml
    :name: xcp_d.toml
    :caption: **Example file representation of XCP-D settings**.
@@ -43,12 +43,16 @@
 ----------------------
 .. autoclass:: environment
    :members:
+   :no-index:
 .. autoclass:: execution
    :members:
+   :no-index:
 .. autoclass:: workflow
    :members:
+   :no-index:
 .. autoclass:: nipype
    :members:
+   :no-index:
 
 Usage
 -----
@@ -75,6 +79,7 @@
 -------
 .. autoclass:: loggers
    :members:
+   :no-index:
 
 Other responsibilities
 ----------------------

xcp_d/data/tests/config.toml

@@ -26,17 +26,15 @@ run_uuid = "20240205-123456"
 templateflow_home = "~/.cache/templateflow"
 work_dir = "work/"
 write_graph = false
+atlases = ["Gordon"]
 
 [workflow]
-cifti = false
+file_format = "nifti"
 dummy_scans = 0
 input_type = "fmriprep"
 despike = false
 smoothing = 6
 combine_runs = false
-motion_filter_type = false
-band_stop_min = false
-band_stop_max = false
 motion_filter_order = 4
 head_radius = 50
 fd_thresh = 0.3
@@ -45,7 +43,6 @@ bandpass_filter = true
 high_pass = 0.01
 low_pass = 0.1
 bpf_order = 2
-atlases = []
 min_coverage = 0.5
 correlation_lengths = []
 process_surfaces = false

xcp_d/interfaces/plotting.py

@@ -241,19 +241,24 @@ class QCPlots(SimpleInterface):
     Examples
     --------
     .. testsetup::
-    >>> from tempfile import TemporaryDirectory
-    >>> tmpdir = TemporaryDirectory()
-    >>> os.chdir(tmpdir.name)
+
+        >>> from tempfile import TemporaryDirectory
+        >>> tmpdir = TemporaryDirectory()
+        >>> os.chdir(tmpdir.name)
+
     .. doctest::
-    qcplots = QCPlots()
-    qcplots.inputs.cleaned_file = datafile
-    qcplots.inputs.bold_file = rawbold
-    qcplots.inputs.TR = TR
-    qcplots.inputs.temporal_mask = temporalmask
-    qcplots.inputs.mask_file = mask
-    qcplots.run()
+
+        qcplots = QCPlots()
+        qcplots.inputs.cleaned_file = datafile
+        qcplots.inputs.bold_file = rawbold
+        qcplots.inputs.TR = TR
+        qcplots.inputs.temporal_mask = temporalmask
+        qcplots.inputs.mask_file = mask
+        qcplots.run()
+
     .. testcleanup::
-    >>> tmpdir.cleanup()
+
+        >>> tmpdir.cleanup()
     """
 
     input_spec = _QCPlotsInputSpec
@@ -525,8 +530,9 @@ class _SlicesDirInputSpec(FSLCommandInputSpec):
         desc='output every second axial slice rather than just 9 ortho slices',
     )
 
+    # Copy in_files from the original location to the runtime.cwd
     in_files = InputMultiPath(
-        File(exists=True),
+        File(exists=True, copyfile=False),
         argstr='%s',
         mandatory=True,
         position=-1,
@@ -551,17 +557,70 @@ class SlicesDir(FSLCommand):
 
     Notes
     -----
-    Usage: slicesdir [-o] [-p <image>] [-e <thr>] [-S] <filelist>
-    -o         :  filelist is pairs ( <underlying> <red-outline> ) of images
-    -p <image> :  use <image> as red-outline image on top of all images in <filelist>
-    -e <thr>   :  use the specified threshold for edges (if >0 use this proportion of max-min,
-                  if <0, use the absolute value)
-    -S         :  output every second axial slice rather than just 9 ortho slices
+    Usage: ``slicesdir [-o] [-p <image>] [-e <thr>] [-S] <filelist>``
+
+    - ``-o`` :  filelist is pairs ( <underlying> <red-outline> ) of images
+    - ``-p <image>`` :  use <image> as red-outline image on top of all images in <filelist>
+    - ``-e <thr>`` :  use the specified threshold for edges (if >0 use this proportion of
+      max-min, if <0, use the absolute value)
+    - ``-S`` :  output every second axial slice rather than just 9 ortho slices
     """
 
     _cmd = 'slicesdir'
     input_spec = _SlicesDirInputSpec
     output_spec = _SlicesDirOutputSpec
+    _short_basenames = None
+    _short_outline = None
+
+    def _run_interface(self, runtime):
+        """Create symlinks with short names before running slicesdir.
+
+        ``slicesdir`` names its output files by replacing path separators in the input
+        file paths with underscores. When input paths are long (e.g., in deep working
+        directories), the derived output filenames can exceed the OS's 255-character
+        filename limit (see https://github.com/PennLINC/xcp_d/issues/1545).
+
+        We work around this by creating symlinks with short names in the working
+        directory, and passing those short names to ``slicesdir`` instead of the
+        original long paths.
+        """
+        self._short_basenames = []
+        for i, f in enumerate(self.inputs.in_files):
+            ext = '.nii.gz' if f.endswith('.nii.gz') else os.path.splitext(f)[1]
+            basename = f'img{i}{ext}'
+            symlink_path = os.path.join(runtime.cwd, basename)
+            if os.path.lexists(symlink_path):
+                os.unlink(symlink_path)
+
+            os.symlink(os.path.abspath(f), symlink_path)
+            self._short_basenames.append(basename)
+
+        if isdefined(self.inputs.outline_image):
+            f = self.inputs.outline_image
+            ext = '.nii.gz' if f.endswith('.nii.gz') else os.path.splitext(f)[1]
+            self._short_outline = f'outline{ext}'
+            symlink_path = os.path.join(runtime.cwd, self._short_outline)
+            if os.path.lexists(symlink_path):
+                os.unlink(symlink_path)
+
+            os.symlink(os.path.abspath(f), symlink_path)
+
+        runtime = super()._run_interface(runtime)
+        return runtime
+
+    def _format_arg(self, name, spec, value):
+        """Use short symlink basenames for in_files and outline_image.
+
+        This ensures the ``slicesdir`` command line uses short paths, producing
+        short output filenames that won't exceed the OS filename length limit.
+        """
+        if name == 'in_files' and self._short_basenames is not None:
+            return ' '.join(self._short_basenames)
+
+        if name == 'outline_image' and self._short_outline is not None:
+            return spec.argstr % self._short_outline
+
+        return super()._format_arg(name, spec, value)
 
     def _list_outputs(self):
         """Create a Bunch which contains all possible files generated by running the interface.
@@ -580,13 +639,21 @@ def _list_outputs(self):
 
         out_dir = os.path.abspath(os.path.join(os.getcwd(), 'slicesdir'))
         outputs['out_dir'] = out_dir
+
+        # Use short basenames if available (set by _run_interface),
+        # otherwise fall back to the original path-based naming.
+        if self._short_basenames is not None:
+            in_basenames = self._short_basenames
+        else:
+            in_basenames = [f.replace(os.sep, '_') for f in self.inputs.in_files]
+
         outputs['out_files'] = [
             self._gen_fname(
-                basename=f.replace(os.sep, '_'),
+                basename=name,
                 cwd=out_dir,
                 ext=self.inputs.out_extension,
             )
-            for f in self.inputs.in_files
+            for name in in_basenames
         ]
         temp_files = [
             'grota.png',
@@ -633,9 +700,10 @@ class PNGAppend(FSLCommand):
 
     Usage: pngappend <input 1> <+|-> [n] <input 2> [<+|-> [n] <input n>]  output>
 
-    + appends horizontally,
-    - appends vertically (i.e. works like a linebreak)
-    [n] number ofgap pixels
+    - ``+`` appends horizontally,
+    - ``-`` appends vertically (i.e. works like a linebreak)
+    - ``[n]`` number of gap pixels
+
     note that files with .gif extension will be input/output in GIF format
     """
 

xcp_d/interfaces/restingstate.py

@@ -48,16 +48,21 @@ class SurfaceReHo(SimpleInterface):
     Examples
     --------
     .. testsetup::
-    >>> from tempfile import TemporaryDirectory
-    >>> tmpdir = TemporaryDirectory()
-    >>> os.chdir(tmpdir.name)
+
+        >>> from tempfile import TemporaryDirectory
+        >>> tmpdir = TemporaryDirectory()
+        >>> os.chdir(tmpdir.name)
+
     .. doctest::
-    >>> surfacereho_wf = SurfaceReHo()
-    >>> surfacereho_wf.inputs.surf_bold = 'rhhemi.func.gii'
-    >>> surfacereho_wf.inputs.surf_hemi = 'R'
-    >>> surfacereho_wf.run()
+
+        >>> surfacereho_wf = SurfaceReHo()
+        >>> surfacereho_wf.inputs.surf_bold = 'rhhemi.func.gii'
+        >>> surfacereho_wf.inputs.surf_hemi = 'R'
+        >>> surfacereho_wf.run()
+
     .. testcleanup::
-    >>> tmpdir.cleanup()
+
+        >>> tmpdir.cleanup()
     """
 
     input_spec = _SurfaceReHoInputSpec

xcp_d/interfaces/workbench.py

@@ -813,61 +813,53 @@ class ShowScene(WBCommand):
 
     Notes
     -----
-    wb_command -show-scene
-        <scene-file> - scene file
-        <scene-name-or-number> - name or number (starting at one) of the scene in
-            the scene file
-        <image-file-name> - output image file name
-        <image-width> - width of output image(s), in pixels
-        <image-height> - height of output image(s), in pixels
-
-        [-use-window-size] - Override image size with window size
-
-        [-no-scene-colors] - Do not use background and foreground colors in scene
-
-        [-set-map-yoke] - Override selected map index for a map yoking group.
-            <Map Yoking Roman Numeral> - Roman numeral identifying the map yoking
-            group (I, II, III, IV, V, VI, VII, VIII, IX, X)
-            <Map Index> - Map index for yoking group.  Indices start at 1 (one)
-
-        [-conn-db-login] - Login for scenes with files in Connectome Database
-            <Username> - Connectome DB Username
-            <Password> - Connectome DB Password
-
-        Render content of browser windows displayed in a scene into image
-        file(s).  The image file name should be similar to "capture.png".  If
-        there is only one image to render, the image name will not change.  If
-        there is more than one image to render, an index will be inserted into
-        the image name: "capture_01.png", "capture_02.png" etc.
-
-        If the scene references files in the Connectome Database,
-        the "-conn-db-login" option is available for providing the
-        username and password.  If this options is not specified,
-        the username and password stored in the user's preferences
-        is used.
-
-        The image format is determined by the image file extension.
-        The available image formats may vary by operating system.
-        Image formats available on this system are:
-            bmp
-            jpeg
-            jpg
-            png
-            ppm
-            tif
-            tiff
-
-        The result of using the "-use-window-size" option
-        is dependent upon the version used to create the scene.
-            * Versions 1.2 and newer contain the width and
-            height of the graphics region.  The output image
-            will be the width and height from the scene and
-            the image width and height specified on the command
-            line is ignored.
-            * If the scene does not contain the width and height
-            of the graphics region, the width and height specified
-            on the command line is used for the size of the
-            output image.
+    ``wb_command -show-scene``
+
+    Positional arguments:
+
+    - ``<scene-file>`` - scene file
+    - ``<scene-name-or-number>`` - name or number (starting at one) of the scene in
+      the scene file
+    - ``<image-file-name>`` - output image file name
+    - ``<image-width>`` - width of output image(s), in pixels
+    - ``<image-height>`` - height of output image(s), in pixels
+
+    Optional arguments:
+
+    - ``[-use-window-size]`` - Override image size with window size
+    - ``[-no-scene-colors]`` - Do not use background and foreground colors in scene
+    - ``[-set-map-yoke]`` - Override selected map index for a map yoking group.
+    - ``[-conn-db-login]`` - Login for scenes with files in Connectome Database
+
+    Render content of browser windows displayed in a scene into image
+    file(s).  The image file name should be similar to "capture.png".  If
+    there is only one image to render, the image name will not change.  If
+    there is more than one image to render, an index will be inserted into
+    the image name: "capture_01.png", "capture_02.png" etc.
+
+    If the scene references files in the Connectome Database,
+    the ``-conn-db-login`` option is available for providing the
+    username and password.  If this option is not specified,
+    the username and password stored in the user's preferences
+    is used.
+
+    The image format is determined by the image file extension.
+    The available image formats may vary by operating system.
+    Image formats available on this system are:
+    bmp, jpeg, jpg, png, ppm, tif, tiff.
+
+    The result of using the ``-use-window-size`` option
+    is dependent upon the version used to create the scene.
+
+    * Versions 1.2 and newer contain the width and
+      height of the graphics region.  The output image
+      will be the width and height from the scene and
+      the image width and height specified on the command
+      line is ignored.
+    * If the scene does not contain the width and height
+      of the graphics region, the width and height specified
+      on the command line is used for the size of the
+      output image.
     """
 
     input_spec = _ShowSceneInputSpec