Apply transforms to raw data when MNI6 derivatives aren't available (#58

)

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,86 @@
+name: Bug Report
+description: File a report of a problem you encountered.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        # Thanks for taking the time to fill out this bug report!
+        ### The following information will help us in getting your issue resolved.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: A short description of what went wrong.
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: What command did you use?
+      description: |
+        If you're using `fmriprep-docker`, please include the `RUNNING: ...` line that is printed first.
+        This helps us replicate the problem. This will be automatically formatted into code, so no need for backticks.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: What version of fMRIPost-AROMA are you running?
+    validations:
+      required: true
+  - type: dropdown
+    id: environment
+    attributes:
+      label: How are you running fMRIPost-AROMA?
+      options:
+        - Docker
+        - Singularity
+        - Local installation ("bare-metal")
+        - Other
+    validations:
+      required: true
+  - type: dropdown
+    id: bids-valid
+    attributes:
+      label: Is your data BIDS valid?
+      description: |
+        The BIDS validator can be found at: https://bids-standard.github.io/bids-validator/
+        Errors should not be present, but warnings are acceptable.
+      options:
+        - "Yes"
+        - "No"
+    validations:
+      required: true
+  - type: dropdown
+    id: reuse
+    attributes:
+      label: Are you reusing any previously computed results?
+      description: |
+        You can select multiple options.
+        We recommend using a fresh working directory when upgrading to a new fMRIPost-AROMA minor series.
+      multiple: true
+      options:
+        - FreeSurfer
+        - Anatomical derivatives
+        - Work directory
+        - "No"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Please copy and paste any relevant log output.
+      description: |
+        Can you find some traces of the error reported in the visual report (at the bottom) or in *crashfiles*?
+        This will be automatically formatted into code, so no need for backticks.
+      render: shell
+  - type: textarea
+    id: addinfo
+    attributes:
+      label: Additional information / screenshots
+      description: |
+        If you would like to include any further information, such as any visual reports, please include them below.
+        Alternatively, you can privately share with us at <[email protected]>.
+        Reports do not contain data usable with personal identification or other research purposes.

.github/ISSUE_TEMPLATE/documentation.md

@@ -0,0 +1,14 @@
+---
+name: Documentation improvement
+about: Is the documentation of something missing, unclear, or lacking? This is the place.
+title: ''
+labels: 'documentation'
+assignees: ''
+
+---
+<!--
+For the Documentation request, please include the following:
+------------------------
+What would you like changed/added and why?
+Do you have any suggestions for the new documents?
+-->

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,39 @@
+name: Feature Request
+description: Suggest an idea for a new feature or a change to an existing one.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Thank you for your suggestion!
+
+        We welcome any ideas about how to make *fMRIPost-AROMA* better for the community.
+        Please keep in mind that features may not get implemented immediately.
+  - type: textarea
+    id: summary
+    attributes:
+      label: What would you like to see added in fMRIPost-AROMA?
+      description: |
+        What are you trying to achieve with fMRIPost-AROMA?
+        Is this a more convenient way to do something that is already possible, or is a workaround currently unfeasible?
+        Does this feature adhere to the [NiPreps driving principles](https://www.nipreps.org/community/CONTRIBUTING/#driving-principles)?
+    validations:
+      required: true
+  - type: dropdown
+    id: interest
+    attributes:
+      label: Do you have any interest in helping implement the feature?
+      description: |
+        We appreciate any help you can offer!
+        For information on how to contribute, please refer to our [contributing guidelines](https://www.nipreps.org/community/CONTRIBUTING/).
+      options:
+        - "Yes"
+        - Yes, but I would need guidance
+        - "No"
+    validations:
+      required: true
+  - type: textarea
+    id: addinfo
+    attributes:
+      label: Additional information / screenshots
+      description: Add any additional information or context about the feature request here.

pyproject.toml

@@ -21,6 +21,7 @@ dependencies = [
   "fmriprep @ git+https://github.com/nipreps/fmriprep.git@master",
   "nipype >= 1.8.5",
   "nireports @ git+https://github.com/nipreps/nireports.git@main",
+  "nitransforms == 23.0.1",
   "niworkflows @ git+https://github.com/nipreps/niworkflows.git@master",
   "pybids >= 0.15.6",
   "sdcflows @ git+https://github.com/nipreps/sdcflows.git@master",

src/fmripost_aroma/cli/parser.py

@@ -318,8 +318,8 @@ def _bids_filter(value, parser):
         required=False,
         action='store',
         nargs='+',
-        default=[],
-        choices=['fieldmaps', 'slicetiming', 'jacobian'],
+        default=['fieldmaps'],
+        choices=['fieldmaps', 'slicetiming', 'fmap-jacobian'],
         help=(
             'Ignore selected aspects of the input dataset to disable corresponding '
             'parts of the resampling workflow (a space delimited list)'

src/fmripost_aroma/config.py

@@ -546,10 +546,17 @@ class workflow(_Config):
     (positive = exact, negative = maximum)."""
     denoise_method = None
     """Denoising strategy to be used."""
+    ignore = None
+    """Ignore particular steps for *fMRIPost-AROMA*."""
     cifti_output = None
     """Generate HCP Grayordinates, accepts either ``'91k'`` (default) or ``'170k'``."""
     dummy_scans = None
     """Set a number of initial scans to be considered nonsteady states."""
+    slice_time_ref = 0.5
+    """The time of the reference slice to correct BOLD values to, as a fraction
+    acquisition time. 0 indicates the start, 0.5 the midpoint, and 1 the end
+    of acquisition. The alias `start` corresponds to 0, and `middle` to 0.5.
+    The default value is 0.5."""
 
 
 class loggers:

src/fmripost_aroma/data/io_spec.json

@@ -78,6 +78,20 @@
                 "extension": [
                     ".tsv"
                 ]
+            },
+            "anat_dseg": {
+                "datatype": "anat",
+                "task": null,
+                "run": null,
+                "space": null,
+                "res": null,
+                "den": null,
+                "desc": null,
+                "suffix": "dseg",
+                "extension": [
+                    ".nii.gz",
+                    ".nii"
+                ]
             }
         },
         "transforms": {

src/fmripost_aroma/data/reports-spec-func.yml

@@ -10,17 +10,15 @@ sections:
   reportlets:
   - bids: {datatype: figures, desc: summary, suffix: bold}
   - bids: {datatype: figures, desc: validation, suffix: bold}
-  - bids: {datatype: figures, desc: aroma, suffix: bold}
-  - bids: {datatype: figures, desc: metrics, suffix: bold}
-  - bids: {datatype: figures, desc: coreg, suffix: bold}
+  - bids: {datatype: figures, desc: normalization, suffix: bold}
     caption: This panel shows the alignment of the reference EPI (BOLD) image to the
-      anatomical (T1-weighted) image.
-      The reference EPI has been contrast enhanced and susceptibility-distortion
-      corrected (if applicable) for improved anatomical fidelity.
-      The anatomical image has been resampled into EPI space, as well as the
-      anatomical white matter mask, which appears as a red contour.
+      MNI152NLin6Asym template.
+      The anatomical white matter mask has been warped to MNI152NLin6Asym space
+      and appears as a red contour.
     static: false
-    subtitle: Alignment of functional and anatomical MRI data (coregistration)
+    subtitle: Alignment of functional and template MRI data (normalization)
+  - bids: {datatype: figures, desc: aroma, suffix: bold}
+  - bids: {datatype: figures, desc: metrics, suffix: bold}
   - bids: {datatype: figures, desc: preprocCarpetplot, suffix: bold}
     title: Preprocessed BOLD
   - bids: {datatype: figures, desc: nonaggrCarpetplot, suffix: bold}

src/fmripost_aroma/data/reports-spec.yml

@@ -10,17 +10,15 @@ sections:
   reportlets:
   - bids: {datatype: figures, desc: summary, suffix: bold}
   - bids: {datatype: figures, desc: validation, suffix: bold}
-  - bids: {datatype: figures, desc: aroma, suffix: bold}
-  - bids: {datatype: figures, desc: metrics, suffix: bold}
-  - bids: {datatype: figures, desc: coreg, suffix: bold}
+  - bids: {datatype: figures, desc: normalization, suffix: bold}
     caption: This panel shows the alignment of the reference EPI (BOLD) image to the
-      anatomical (T1-weighted) image.
-      The reference EPI has been contrast enhanced and susceptibility-distortion
-      corrected (if applicable) for improved anatomical fidelity.
-      The anatomical image has been resampled into EPI space, as well as the
-      anatomical white matter mask, which appears as a red contour.
+      MNI152NLin6Asym template.
+      The anatomical white matter mask has been warped to MNI152NLin6Asym space
+      and appears as a red contour.
     static: false
-    subtitle: Alignment of functional and anatomical MRI data (coregistration)
+    subtitle: Alignment of functional and template MRI data (normalization)
+  - bids: {datatype: figures, desc: aroma, suffix: bold}
+  - bids: {datatype: figures, desc: metrics, suffix: bold}
   - bids: {datatype: figures, desc: preprocCarpetplot, suffix: bold}
     title: Preprocessed BOLD
   - bids: {datatype: figures, desc: nonaggrCarpetplot, suffix: bold}

src/fmripost_aroma/interfaces/confounds.py

@@ -101,7 +101,6 @@ def _get_ica_confounds(mixing, aroma_features, skip_vols, newpath=None):
 
     # Regress the good components out of the bad time series to get "pure evil" regressors
     signal_mixing_arr = mixing_arr[signal_ics, :].T
-    orthaggr_mixing_arr = aggr_mixing_arr.copy()
     aggr_mixing_arr_z = stats.zscore(aggr_mixing_arr, axis=0)
     signal_mixing_arr_z = stats.zscore(signal_mixing_arr, axis=0)
     betas = np.linalg.lstsq(signal_mixing_arr_z, aggr_mixing_arr_z, rcond=None)[0]

src/fmripost_aroma/interfaces/nilearn.py

@@ -21,7 +21,7 @@ class _MeanImageInputSpec(BaseInterfaceInputSpec):
     )
     mask_file = File(
         exists=True,
-        mandatory=True,
+        mandatory=False,
         desc='A binary brain mask.',
     )
     out_file = File(
@@ -46,11 +46,19 @@ class MeanImage(NilearnBaseInterface, SimpleInterface):
     output_spec = _MeanImageOutputSpec
 
     def _run_interface(self, runtime):
+        import nibabel as nb
         from nilearn.masking import apply_mask, unmask
+        from nipype.interfaces.base import isdefined
+
+        if isdefined(self.inputs.mask_file):
+            data = apply_mask(self.inputs.bold_file, self.inputs.mask_file)
+            mean_data = data.mean(axis=0)
+            mean_img = unmask(mean_data, self.inputs.mask_file)
+        else:
+            in_img = nb.load(self.inputs.bold_file)
+            mean_data = in_img.get_fdata().mean(axis=3)
+            mean_img = nb.Nifti1Image(mean_data, in_img.affine, in_img.header)
 
-        data = apply_mask(self.inputs.bold_file, self.inputs.mask_file)
-        mean_data = data.mean(axis=0)
-        mean_img = unmask(mean_data, self.inputs.mask_file)
         self._results['out_file'] = os.path.join(runtime.cwd, self.inputs.out_file)
         mean_img.to_filename(self._results['out_file'])
 

src/fmripost_aroma/tests/test_base.py

@@ -20,6 +20,7 @@ def test_init_ica_aroma_wf(tmp_path_factory):
         wf = init_ica_aroma_wf(
             bold_file='sub-01_task-rest_bold.nii.gz',
             metadata={'RepetitionTime': 2.0},
+            mem_gb={'resampled': 1},
         )
         assert wf.name == 'aroma_task_rest_wf'
 

src/fmripost_aroma/workflows/aroma.py

@@ -35,6 +35,7 @@ def init_ica_aroma_wf(
     *,
     bold_file: str,
     metadata: dict,
+    mem_gb: dict,
     susan_fwhm: float = 6.0,
 ):
     """Build a workflow that runs `ICA-AROMA`_.
@@ -192,6 +193,7 @@ def init_ica_aroma_wf(
             output_type='NIFTI' if config.execution.low_mem else 'NIFTI_GZ',
         ),
         name='smooth',
+        mem_gb=mem_gb['resampled'],
     )
     workflow.connect([
         (rm_non_steady_state, smooth, [('bold_cut', 'in_file')]),
@@ -209,6 +211,7 @@ def init_ica_aroma_wf(
             dim=config.workflow.melodic_dim,
         ),
         name='melodic',
+        mem_gb=mem_gb['resampled'],
     )
     workflow.connect([
         (inputnode, melodic, [('bold_mask_std', 'mask')]),