Metadata extractor for FEAT analysis output

[mih]

Would be fairly simple to capture the essence of a 1st-level analysis:

• N significant blobs, plus blob properties (N voxels, MNI coordinate, ...)
• design matrix params
• time series length
• N contrasts, plus names

Higher-level analysis might be more complicated to identify meaningful props, but the basics would be pretty much just as simple.

[mih]

Here is a first draft. Clearly needs some exposure to real results and real variability. But so far this is what one can expect:

Relevant snippet of a 6 EV, 1 contrast, 1st-level analysis

    "fslfeat": {
      "@context": {
        "fslfeat": {
          "@id": "https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FEAT/",
          "description": "non-vocabulary for FSL FEAT variables",
          "type": "http://purl.org/dc/dcam/VocabularyEncodingScheme"
        }
      },
      "analysis": [
        {
          "alternateReference": 0,
          "analysis": "full",
          "bet": 1,
          "brain_thresh": 10,
          "con_mode": "orig",
          "con_mode_old": "orig",
          "confoundevs": 0,
          "conmask1_1": 0,
          "conmask_zerothresh": 0,
          "contrasts": [
            {
              "clusters": [
                {
                  "-log10(P)": 8.71,
                  "COPE-MAX": 666.0,
                  "COPE-MAX X (vox)": 25.0,
                  "COPE-MAX Y (vox)": 20.0,
                  "COPE-MAX Z (vox)": 7.0,
                  "COPE-MEAN": 171.0,
                  "Cluster Index": 7.0,
                  "P": 1.9699999999999996e-09,
                  "Voxels": 347.0,
                  "Z-COG X (vox)": 23.9,
                  "Z-COG Y (vox)": 18.6,
                  "Z-COG Z (vox)": 8.69,
                  "Z-MAX": 11.9,
                  "Z-MAX X (vox)": 26.0,
                  "Z-MAX Y (vox)": 19.0,
                  "Z-MAX Z (vox)": 7.0
                },
                {
                  "-log10(P)": 4.39,
                  "COPE-MAX": 284.0,
                  "COPE-MAX X (vox)": 55.0,
                  "COPE-MAX Y (vox)": 15.0,
                  "COPE-MAX Z (vox)": 22.0,
                  "COPE-MEAN": 98.2,
                  "Cluster Index": 6.0,
                  "P": 4.05e-05,
                  "Voxels": 164.0,
                  "Z-COG X (vox)": 53.5,
                  "Z-COG Y (vox)": 14.2,
                  "Z-COG Z (vox)": 22.8,
                  "Z-MAX": 4.91,
                  "Z-MAX X (vox)": 55.0,
                  "Z-MAX Y (vox)": 16.0,
                  "Z-MAX Z (vox)": 24.0
                },
                {
                  "-log10(P)": 2.03,
                  "COPE-MAX": 143.0,
                  "COPE-MAX X (vox)": 35.0,
                  "COPE-MAX Y (vox)": 48.0,
                  "COPE-MAX Z (vox)": 18.0,
                  "COPE-MEAN": 71.6,
                  "Cluster Index": 5.0,
                  "P": 0.00926,
                  "Voxels": 85.0,
                  "Z-COG X (vox)": 32.0,
                  "Z-COG Y (vox)": 49.3,
                  "Z-COG Z (vox)": 19.8,
                  "Z-MAX": 4.89,
                  "Z-MAX X (vox)": 30.0,
                  "Z-MAX Y (vox)": 49.0,
                  "Z-MAX Z (vox)": 21.0
                },
                {
                  "-log10(P)": 1.69,
                  "COPE-MAX": 170.0,
                  "COPE-MAX X (vox)": 21.0,
                  "COPE-MAX Y (vox)": 17.0,
                  "COPE-MAX Z (vox)": 20.0,
                  "COPE-MEAN": 74.4,
                  "Cluster Index": 4.0,
                  "P": 0.0203,
                  "Voxels": 75.0,
                  "Z-COG X (vox)": 21.3,
                  "Z-COG Y (vox)": 19.3,
                  "Z-COG Z (vox)": 22.5,
                  "Z-MAX": 4.0,
                  "Z-MAX X (vox)": 27.0,
                  "Z-MAX Y (vox)": 13.0,
                  "Z-MAX Z (vox)": 23.0
                },
                {
                  "-log10(P)": 1.34,
                  "COPE-MAX": 248.0,
                  "COPE-MAX X (vox)": 22.0,
                  "COPE-MAX Y (vox)": 42.0,
                  "COPE-MAX Z (vox)": 24.0,
                  "COPE-MEAN": 82.3,
                  "Cluster Index": 3.0,
                  "P": 0.0459,
                  "Voxels": 65.0,
                  "Z-COG X (vox)": 19.3,
                  "Z-COG Y (vox)": 43.9,
                  "Z-COG Z (vox)": 20.9,
                  "Z-MAX": 4.8,
                  "Z-MAX X (vox)": 22.0,
                  "Z-MAX Y (vox)": 42.0,
                  "Z-MAX Z (vox)": 24.0
                },
                {
                  "-log10(P)": 1.3,
                  "COPE-MAX": 529.0,
                  "COPE-MAX X (vox)": 51.0,
                  "COPE-MAX Y (vox)": 20.0,
                  "COPE-MAX Z (vox)": 6.0,
                  "COPE-MEAN": 191.0,
                  "Cluster Index": 2.0,
                  "P": 0.0499,
                  "Voxels": 64.0,
                  "Z-COG X (vox)": 51.4,
                  "Z-COG Y (vox)": 18.5,
                  "Z-COG Z (vox)": 5.31,
                  "Z-MAX": 9.85,
                  "Z-MAX X (vox)": 51.0,
                  "Z-MAX Y (vox)": 19.0,
                  "Z-MAX Z (vox)": 5.0
                },
                {
                  "-log10(P)": 1.3,
                  "COPE-MAX": 427.0,
                  "COPE-MAX X (vox)": 39.0,
                  "COPE-MAX Y (vox)": 5.0,
                  "COPE-MAX Z (vox)": 7.0,
                  "COPE-MEAN": 162.0,
                  "Cluster Index": 1.0,
                  "P": 0.0499,
                  "Voxels": 64.0,
                  "Z-COG X (vox)": 38.8,
                  "Z-COG Y (vox)": 6.26,
                  "Z-COG Z (vox)": 9.36,
                  "Z-MAX": 6.2,
                  "Z-MAX X (vox)": 39.0,
                  "Z-MAX Y (vox)": 5.0,
                  "Z-MAX Z (vox)": 7.0
                }
              ],
              "con_orig": [
                2.0,
                -1.0,
                0.0,
                0.0,
                -1.0,
                0
              ],
              "con_real": [
                2.0,
                0,
                -1.0,
                0,
                0.0,
                0,
                0.0,
                0,
                -1.0,
                0,
                0,
                0
              ],
              "name": "FFA"
            }
          ],
          "critical_z": 5.3,
          "dwell": 0.7,
          "ev": [
            {
              "convolve": 3,
              "convolve_phase": 0,
              "custom": "sub-02/onsets/run-1/face.txt",
              "deriv": 1,
              "evtitle": "face",
              "shape": "custom_ev3",
              "tempfilt": true
            },
            {
              "convolve": 3,
              "convolve_phase": 0,
              "custom": "sub-02/onsets/run-1/house.txt",
              "deriv": 1,
              "evtitle": "house",
              "shape": "custom_ev3",
              "tempfilt": true
            },
            {
              "convolve": 3,
              "convolve_phase": 0,
              "custom": "sub-02/onsets/run-1/body.txt",
              "deriv": 1,
              "evtitle": "body",
              "shape": "custom_ev3",
              "tempfilt": true
            },
            {
              "convolve": 2,
              "convolve_phase": 0,
              "custom": "sub-02/onsets/run-1/object.txt",
              "deriv": 1,
              "evtitle": "object",
              "gammadelay": 6,
              "gammasigma": 3,
              "shape": "custom_ev3",
              "tempfilt": true
            },
            {
              "convolve": 3,
              "convolve_phase": 0,
              "custom": "sub-02/onsets/run-1/scene.txt",
              "deriv": 1,
              "evtitle": "scene",
              "shape": "custom_ev3",
              "tempfilt": true
            },
            {
              "convolve": 3,
              "convolve_phase": 0,
              "custom": "sub-02/onsets/run-1/scramble.txt",
              "deriv": 1,
              "evtitle": "scramble",
              "shape": "custom_ev3",
              "tempfilt": true
            }
          ],
          "evs_orig": 6,
          "evs_real": 12,
          "evs_vox": 0,
          "inmelodic": 0,
          "inputtype": "cope",
          "level": "first",
          "mc": "mcflirt",
          "mixed": "me_flame1",
          "motionevs": true,
          "multiple": 1,
          "ncon_orig": 1,
          "ncon_real": 1,
          "ncopeinputs": 0,
          "ndelete": 0,
          "nftests_orig": 0,
          "nftests_real": 0,
          "noise": 0.66,
          "noisear": 0.34,
          "norm": 0,
          "npts": 156,
          "outputdir": "1stlvl_glm",
          "overwrite": 0,
          "paradigm_hp": 80.0,
          "path": "1stlvl_glm.feat",
          "perfsub": 0,
          "prewhiten": 1,
          "prob_thresh": 0.05,
          "reghighres": 0,
          "reghighres_dof": "BBR",
          "reghighres_search": 90,
          "reginitial_highres": 0,
          "reginitial_highres_dof": 3,
          "reginitial_highres_search": 90,
          "regstandard": "/usr/share/fsl/5.0/data/standard/MNI152_T1_2mm_brain",
          "regstandard_dof": 12,
          "regstandard_nonlinear_warpres": 10,
          "regstandard_search": 90,
          "regunwarp": 0,
          "robust": 0,
          "sh": 0,
          "signallossthresh": 10,
          "smooth": 5,
          "st": "regularup",
          "steps_disabled": [
            "melodic",
            "regstandard_nonlinear",
            "regstandard"
          ],
          "tagfirst": 1,
          "te": 35,
          "temphp": 1,
          "templp": 0,
          "thresh": "cluster",
          "totalVoxels": 34944000,
          "tr": 2.000001,
          "unwarp_dir": "y-",
          "version": 6.0,
          "z_thresh": 2.3
        }
      ]
    },

This will expose general analysis parameters/properties to search, e.g.:

% datalad search --mode autofield fslfeat.analysis.version:6.0          
[INFO   ] Query completed in 0.0004303749883547425 sec. Reporting up to 20 top matches. 
search(ok): . (dataset)

but nothing about result clusters will be visible in a structured way, because the nesting is too deep.

Check the diff for TODOs.

[codecov-io]

Codecov Report

Merging #14 into master will increase coverage by 2.11%.
The diff coverage is 99.34%.

@@            Coverage Diff             @@
##           master      #14      +/-   ##
==========================================
+ Coverage   85.69%   87.81%   +2.11%     
==========================================
  Files          18       20       +2     
  Lines         839      993     +154     
==========================================
+ Hits          719      872     +153     
- Misses        120      121       +1

Impacted Files	Coverage Δ
...alad_neuroimaging/extractors/tests/test_fslfeat.py	100% <100%> (ø)
datalad_neuroimaging/extractors/fslfeat.py	99.17% <99.17%> (ø)
datalad_neuroimaging/extractors/nifti1.py	89.09% <0%> (+0.2%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update cf341f4...8401b07. Read the comment docs.

[mih]

@yarikoptic any immediate thoughts?

[yarikoptic]

have you tried https://github.com/incf-nidash/nidmresults-fsl , may be we could follow/try "the standard"?

[yarikoptic]

Just a cursory review, with minor comments. The only concern is values casting which imho should be less magical

[yarikoptic]

not for a change here, just sharing that I started to like/use more a convention import os.path as op and then accessing them all from op. -- makes it still short and clear, while later we might even come up with our "extended" datalad.support.path and change all the imports in one shot

[yarikoptic]

if that expected not to have it, I would raise ValueError to catch a moment of 'enlightenment' when we run into such case

[mih]

;-) If you point me to the docs on what is to be expected and what not, I'll do that....

[yarikoptic]

Why not to rely on having "" around the value to immediately decide it to be a string, this way we would avoid converting some "degenerate" evtitle's (especially the ones with explicit leading 0s for some reason such as "001", or "inf" or "NaN" for floats) etc into numeric values, where they were intended to stay strings.

[mih]

Because an FSF file has strings that are not quoted.

[yarikoptic]

IMHO quite heavy of a dependency, but oh well I guess.

[mih]

FTR: pandas is a core dependency of pybids. Heavy, but we already carry it, hence there is no penalty.

[mih]

https://github.com/incf-nidash/nidmresults-fsl

uhhh, how could I have missed that?! I'll check that out. If it works, consider this PR never happened.

[mih]

No immediate success with nidmfsl: incf-nidash/nidmresults-fsl#125

But I'll keep exploring. It seems it also makes sense to rely on fslpy for actual IO with a FEAT dir would be superior then coding it up ourselves. https://users.fmrib.ox.ac.uk/~paulmc/fsleyes/fslpy/latest/

[mih]

Was thinking about going with NIDM results as a replacement:

Pros:

• (presumably) less work
• much higher quality of metadata (proper semantics), not adhoc pile of key/values, etc.

Cons:

• it is a graph, for natural reasons
• without a proper graph search application, the practical utility of this metadata will be limited

My personal conclusion:

• pursue both: implement support for NIDM results, but also for a plain and simple FEAT config extractor
• the latter should be kept simple and fast, knowing that the real deal would come with NIDM
• inclusion on info, and structure of info from the feat extractor should come will clear discovery scenarios in mind
• discard present code, reimplement with fslpy

[mih]

This is made obsolete by a solution based on https://github.com/incf-nidash/nidmresults-fsl