Add custom censoring options

[tsalo]

Closes #724 and closes #723.

To do:

• Expand testing of both argument parsing and actual censoring
• Plot DVARS in CensorPlot
• Make sure the new method is documented thoroughly
• Cover the new arguments in integration tests

Changes proposed in this pull request

• Add new parameters to support more customized censoring:
  • --fd-thresh can accept a second value, which applies additional FD-based censoring after interpolation+filtering+denoising+recensoring.
  • --dvars-thresh, which accepts one or two values, to apply a DVARS-based threshold when identifying outliers.
  • --censor-before and --censor-after, which both accept one or two values to censor volumes before/after outlier volumes identified by --fd-thresh and --dvars-thresh.
  • --censor-between, which accepts one or two values to censor contiguous sequences of non-loutlier volumes between flagged outlier volumes, as long as the sequence is shorter than or equal to the censor-between value.
• Expand the outliers TSV file to have 6 columns:
  • framewise_displacement: Volumes with FD greater than the first value of --fd-thresh
  • dvars: Volumes with DVARS greater than the first value of --dvars-thresh
  • denoising: Volumes flagged by the framewise_displacement or dvars columns, expanded using the first values of --censor-before, --censor-after, and --censor-between
  • framewise_displacement_interpolation: Volumes with FD greater than the second value of --fd-thresh
  • dvars_interpolation: Volumes with DVARS greater than the second value of --dvars-thresh
  • interpolation: Volumes flagged by any of the previous columns, expanded using the second values of --censor-before, --censor-after, and --censor-between.
• Split up the GenerateConfounds interface into ModifyConfounds (motion filtering and FD recalculation), GenerateTemporalMask (outlier detection using FD and/or DVARS confounds), and GenerateDesignMatrix (select confounds, combine with custom confounds, and orthogonalize noise regressors w.r.t. signal regressors).

Documentation that should be reviewed

[codecov]

Codecov Report

Attention: Patch coverage is 81.19403% with 63 lines in your changes are missing coverage. Please review.

Project coverage is 83.00%. Comparing base (b539de9) to head (97126d4).

❗ Current head 97126d4 differs from pull request most recent head 4ae43ee

Please upload reports for the commit 4ae43ee to get more accurate results.

Files	Patch %	Lines
xcp_d/cli/parser_utils.py	23.80%	29 Missing and 3 partials ⚠️
xcp_d/utils/boilerplate.py	37.50%	4 Missing and 6 partials ⚠️
xcp_d/interfaces/censoring.py	95.19%	1 Missing and 4 partials ⚠️
xcp_d/interfaces/plotting.py	81.48%	3 Missing and 2 partials ⚠️
xcp_d/workflows/concatenation.py	20.00%	0 Missing and 4 partials ⚠️
xcp_d/interfaces/nilearn.py	71.42%	0 Missing and 2 partials ⚠️
xcp_d/utils/confounds.py	96.55%	1 Missing and 1 partial ⚠️
xcp_d/utils/plotting.py	50.00%	2 Missing ⚠️
xcp_d/utils/qcmetrics.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1159      +/-   ##
==========================================
- Coverage   83.53%   83.00%   -0.54%     
==========================================
  Files          54       54              
  Lines        6892     6877      -15     
  Branches      987      972      -15     
==========================================
- Hits         5757     5708      -49     
- Misses        873      911      +38     
+ Partials      262      258       -4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.