[ENH] [Derivatives] Add MImap suffix for molecular imaging maps

[melanieganz]

In order to enable the addition of PET examples to the current atlas BEP proposal, we need to define what a PET derivative will be called. The PET derivatives are still under development (see here), but we have a pretty good idea how they should look like.

Hence we added a MImap suffix with details on units and descriptions to the schema.

Derived with help of @mnoergaard @CPernet

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.83%. Comparing base (373da35) to head (79d520c).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #2262   +/-   ##
=======================================
  Coverage   82.83%   82.83%           
=======================================
  Files          20       20           
  Lines        1672     1672           
=======================================
  Hits         1385     1385           
  Misses        287      287           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[bendhouseart]

Approval pending latin check fix.

[CPernet]

I thought we settled on petmap? Not mimap .. but fine by me

[effigies]

We need to add file rules to the schema and text to the spec. This could go on derivatives/imaging_data or derivatives/pet, or similar

Are there required metadata for these files?

[effigies]

To expand on the file rules, here is the current rule for derivative PET data (rules.files.deriv.imaging.pet_pet_volumetric in https://bids-specification.readthedocs.io/en/latest/schema.json):

          "pet_pet_volumetric": {
            "entities": {
              "task": "optional",
              "tracer": "optional",
              "reconstruction": "optional",
              "run": "optional",
              "subject": "optional",
              "session": "optional",
              "resolution": "optional",
              "space": "optional",
              "description": "optional"
            },
            "suffixes": [
              "pet"
            ],
            "extensions": [
              ".nii.gz",
              ".nii",
              ".json"
            ],
            "datatypes": [
              "pet"
            ],
            "selectors": [
              "dataset.dataset_description.DatasetType == 'derivative'"
            ]
          },

It's defined at

bids-specification/src/schema/rules/files/deriv/imaging.yaml

Lines 223 to 230 in 373da35

	pet_pet_volumetric:
	$ref:
	- meta.templates.deriv.volumetric
	- rules.files.raw.pet.pet
	entities:
	$ref:
	- meta.templates.deriv.volumetric.entities
	- rules.files.raw.pet.pet.entities

It references

bids-specification/src/schema/meta/templates.yaml

Lines 85 to 94 in 373da35

	# Imaging derivatives
	volumetric:
	$ref: meta.templates.deriv.spatial
	extensions:
	- .nii.gz
	- .nii
	- .json
	entities:
	$ref: meta.templates.deriv.spatial.entities
	resolution: optional

and

bids-specification/src/schema/rules/files/raw/pet.yaml

Lines 2 to 12 in 373da35

	pet:
	suffixes:
	- pet
	extensions:
	- .nii.gz
	- .nii
	- .json
	datatypes:
	- pet
	entities:
	$ref: meta.templates.raw.pet.entities

which in turn reference other templates, to produce the above JSON. If you don't need any new entities and just need the same result with a MImap suffix, then you could use:

mimap:
  $ref: rules.files.deriv.imaging.pet_pet_volumetric
  suffixes:
    - MImap

This would expand to:

          "mimap": {
            "entities": {
              "task": "optional",
              "tracer": "optional",
              "reconstruction": "optional",
              "run": "optional",
              "subject": "optional",
              "session": "optional",
              "resolution": "optional",
              "space": "optional",
              "description": "optional"
            },
            "suffixes": [
              "MImap"
            ],
            "extensions": [
              ".nii.gz",
              ".nii",
              ".json"
            ],
            "datatypes": [
              "pet"
            ],
            "selectors": [
              "dataset.dataset_description.DatasetType == 'derivative'"
            ]
          },

---

To add sidecar metadata, if it's a new term, it should go in objects.metadata. If it has enumerated values, those should go in objects.enums. Then the rule itself would go in rules/sidecars/derivatives/molecular.yaml (or whatever you want to call it):

MImap:
  selectors:
    - dataset.dataset_description.DatasetType == 'derivative'
    - suffix == 'MImap'
    - match(extension, "^\\.nii(\\.gz)?$")'
  fields:
    Units: required
    # Anything else?

[melanieganz]

Thanks for the feedback, @effigies!
I am liasing with the PET derivatives leads @mnoergaard and @mathesong on the metadata. Regarding new entities, I think we are covered by the ones that were introduced with pet as you linked above.

And @CPernet MImap seems broader since the PET extensions covers SPECT and PET, so molecular imaging seemed more appropriate. And in principle autoradiography could be saved in something like this as well.

[mathesong]

I would suggest changing the phrasing a little bit, at least to clean up the structure (and avoid being about units, then what mimaps are and then units again); but also to open up the possibility of mimaps representing other quantities too (e.g. Kd maps as estimated by the Lassen plot filter)

[mathesong]

Suggested change

	MImaps can have different units, e.g. unitless, ml/ml or pmol/ml. See
	[Innis et al. 2007](https://journals.sagepub.com/doi/full/10.1038/sj.jcbfm.9600493) for unit descriptions.
	MImaps are derivatives of molecular imaging (PET or SPECT) raw data. They can
	either be unitless, e.g. a BP_ND or SUVR, or have the units ml/cm^3 for a V_T or pmol/ml
	for average density maps (see [Beliveau et al. 2017](https://pmc.ncbi.nlm.nih.gov/articles/PMC5214625/)).
	MImaps are derivatives of molecular imaging (PET or SPECT) raw data which
	can represent different quantities with different units. As defined by
	[Innis et al. 2007]
	(https://journals.sagepub.com/doi/full/10.1038/sj.jcbfm.9600493), these
	maps can be unitless (e.g. BP_ND or SUVR), or have units of ml/cm^3 (e.g.
	V_T) or pmol/ml (average density maps, e.g.
	[Beliveau et al. 2017](https://pmc.ncbi.nlm.nih.gov/articles/PMC5214625/)),
	among others.

[mathesong]

Regarding the metadata, is the idea that this is a definitive list, or just some things which might be specified?

For instance, in the PET Preprocessing Derivatives (BEP023), we propose entities for measure, model and pvc, which I could imagine might be useful for a MIMap? And then in the sidecar metadata, there could be quite a few things as they relate to the PET data used to generate the atlases: smoothing parameters, modelling parameters etc. These would be more covered by the PET Derivatives specification, but I suppose they might also be specified for a MIMap atlas.

I suppose my question is how exhaustive this list is supposed to be, and how much of this can just be added when the PET Derivatives BEP is complete?

[mnoergaard]

I would feel comfortable with the MImap suffix, and then for the metadata I would follow the same strategy as the quantitative MRI part (https://bids-specification.readthedocs.io/en/stable/appendices/qmri.html#metadata-requirements-for-qmri-maps), having the metadata 'Sources', 'Description' and 'Units', all being recommended (qMRI don't have the 'Description' field, but I think MImap should have it). Then we might add additional recommended fields later when the PET-BIDS derivatives specification is finished, keeping things backwards compatible.

@mathesong This would only lock us on the suffix 'MImap', however, file entities that will be introduced later in the PET-BIDS specification will then be allowed to be added (e.g. 'model', 'pvc', 'meas', etc).

@effigies WDYT?

[mathesong]

@mnoergaard That sounds like a good strategy to me!

[effigies]

@mnoergaard If the BEP23 consensus is that there will be no more required metadata for MImap files, then that's fine. I would just be sure you're not rushing to put in something you're going to feel constrained by. BEP38 should not be interpreted as an artificial deadline for BEP23; the principles in BEP38 are adequately covered by the current example set, IMO.