🐛 Notch filters vs. framewise-displacement-Jenkinson

[shnizzedy]

Describe the bug

Notch filters aren't being applied to FD-J.

discovered by @pab2163

Custom pipeline configuration

functional_preproc: 
  motion_estimates_and_correction: 
    motion_estimates:
      calculate_motion_first: On
    motion_estimate_filter:
      run: [On, Off]
      filters:
        - filter_type: notch
          filter_order: 4
          center_frequency: 0.31
          filter_bandwidth: 0.12
        - filter_type: notch
          filter_order: 4
          center_frequency: 0.25
          filter_bandwidth: 0.12

Expected behavior

motion estimate filters applied to FD-J and FD-P

Acceptance criteria

• [x] motion estimate filters applied to FD-J
• [x] motion estimate filters applied to FD-P

C-PAC version

v1.8.5-dev

Container platform

Docker, Singularity

Additional context

• motion_estimate_filter node block takes movement-parameters as an input, modifies it, and passes it along as an output https://github.com/FCP-INDI/C-PAC/blob/960305c38f611502fd7610dffd770d171a5e4b82/CPAC/func_preproc/func_preproc.py#L1293-L1306
• FD-P takes movement_parameters as input https://github.com/FCP-INDI/C-PAC/blob/960305c38f611502fd7610dffd770d171a5e4b82/CPAC/generate_motion_statistics/generate_motion_statistics.py#L211-L219
• FD-J takes transformations or rels_displacement as input https://github.com/FCP-INDI/C-PAC/blob/960305c38f611502fd7610dffd770d171a5e4b82/CPAC/generate_motion_statistics/generate_motion_statistics.py#L221-L233
• rels-displacement and coordinate-transformation are generated alongside movement-parameters by motion_correction https://github.com/FCP-INDI/C-PAC/blob/960305c38f611502fd7610dffd770d171a5e4b82/CPAC/func_preproc/func_preproc.py#L1207-L1223 but not modified by motion_estimate_filter (see above)

I think we can either

1. move the creation of rels-displacement and coordinate-transformation to a separate function after motion_estimate_filter or not or
2. regenerate rels-displacement and coordinate-transformation in or after motion_estimate_filter

[shnizzedy]

In https://github.com/FCP-INDI/C-PAC/blob/960305c38f611502fd7610dffd770d171a5e4b82/CPAC/func_preproc/func_preproc.py#L1207-L1229, how are the outputs "max-displacement", "rels-displacement", "movement-parameters" and "coordinate-transformation" interrelated?

― @shnizzedy

In the code snippet you provided, the outputs "max-displacement", "rels-displacement", "movement-parameters", and "coordinate-transformation" are all derived from the same set of motion parameters.

The "movement-parameters" are calculated from the motion correction step using either FSL's MCFLIRT or AFNI's 3dvolreg. These parameters represent the rigid-body transformation that aligns each volume to a reference volume.

The "max-displacement" and "rels-displacement" are both measures of the amount of motion in the time series. "max-displacement" is the maximum Euclidean distance between the motion-corrected volumes and the reference volume, while "rels-displacement" is the relative displacement between each pair of adjacent motion-corrected volumes. These metrics provide an estimate of the amount of head motion in the time series, which can be useful for quality control purposes.

The "coordinate-transformation" is calculated by concatenating the motion parameters for each volume, which results in a transformation matrix that maps each volume to the reference volume. This transformation can be used to align the functional time series to a common space, such as standard anatomical or functional templates.

In summary, all of these outputs are derived from the motion parameters calculated during motion correction, but they serve different purposes. "movement-parameters" describe the actual motion correction transformation, "max-displacement" and "rels-displacement" quantify the amount of motion in the time series, and "coordinate-transformation" can be used to align the functional time series to a common space.

― https://chat.openai.com/chat/75964636-a6b1-433d-8c4f-c9bb5cdcc2b2

[shnizzedy]

Motion params:

                roll  = rotation about the I-S axis }
                pitch = rotation about the R-L axis } degrees CCW
                yaw   = rotation about the A-P axis }
                  dS  = displacement in the Superior direction  }
                  dL  = displacement in the Left direction      } mm
                  dP  = displacement in the Posterior direction }

― https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dvolreg.html

[shnizzedy]

MCFLIRT seems comparably confusing: What’s the relation between FSL’s motion parameters and the affine transformation matrix (specifically the translation)

[shnizzedy]

Alex's idea: See if these different affines result in different FDJs. If not, we don't really need the affine-from-filtered-parameters besides as an intermediate between the filter and FDJ

[shnizzedy]

Looks like the difference in the translation vector doesn’t matter much and neither does one-pass vs. two-pass for FD-J.