PerfusionQuantify (ASLtbx-style)
================================

**Purpose.** Compute CBF and related perfusion metrics from ASL data following an ASLtbx-inspired implementation.

What it does
------------

- Pairs **label** and **control** volumes from ``ASLContext`` and computes perfusion-weighted images.
- Supports PASL and (P)CASL quantification.
- Optional generation of BOLD and PERF time series and **mean** maps.
- Writes global signal summaries per volume.

Inputs
------

- ``derivatives/<sub>/perf/srr{asl}.nii`` (realigned + resliced 4D ASL)
- ``{asl}_mask_perf_cbf.nii`` (from :doc:`createmask`)
- M0 handling:
  - ``M0Type == "Separate"`` → ``perf/sr{M0}.nii``
  - ``M0Type == "Included"`` → extracted from ASL where ``ASLContext == "m0scan"``

Outputs & filenames
-------------------

- ``{asl}_CBF.nii`` (4D), and optionally:
  - ``{asl}_BOLD.nii`` (4D), ``{asl}_PERF.nii`` (4D)
  - mean maps: ``{asl}_mCBF.nii`` (+ ``_mBOLD.nii``, ``_mPERF.nii`` if enabled)
- ``{asl}_globalsg.txt`` (CSV header: ``Perf_outliercleaned,CBF_outliercleaned,Perf_whole,CBF_whole``)

Configuration
-------------

====================  ===================  ==============================================
Key                   Type / Default       Meaning
====================  ===================  ==============================================
``QuantFlag``         int / ``1``          Quantification mode (0 → relative via M0/mean BOLD; 1/2 → unique M0 with CSF/WM ratio)
``M0wmcsf``           float / *required if QuantFlag!=0*   WM/CSF M0 value for unique quantification
``MaskFlag``          bool / ``True``      Multiply by mask when computing metrics
``MeanFlag``          bool / ``True``      Save mean maps
``BOLDFlag``          bool / ``False``     Save BOLD 4D
``PerfFlag``          bool / ``False``     Save PERF 4D
``SubtractionType``   int / ``0``          0: pairwise, 1: surround average, 2: sinc interpolation
``SubtrationOrder``   int / ``1``          1: control - label, 0: label - control
``Timeshift``         float / ``0.5``      For sinc subtraction, fractional time shift
====================  ===================  ==============================================

Assumes available in ``data_descrip``:
- ``MagneticFieldStrength``, ``LabelingEfficiency``, ``LabelControl`` (bool order), ``PLDList``,
  ``SliceDuration`` (optional), ``LabelingDuration`` (for PCASL), and ``M0`` metadata.

YAML example
------------

.. code-block:: yaml

    modules:
      - name: PerfusionQuantify
        config:
          QuantFlag: 1
          M0wmcsf: 1.0
          MaskFlag: true
          MeanFlag: true
          BOLDFlag: false
          PerfFlag: false
          SubtractionType: 0
          SubtrationOrder: 1
          Timeshift: 0.5