Leaspy integration

[ghisvail]

Discuss what needs to be worked on to facilitate integration between leaspy and clinica.

[emaheux]

Following our discussion, it would nice to have these metadata for scans:

Champ MRI:

• MagneticFieldStrength

Modèle du scanner

• Manufacturer
• ManufacturersModelName
• SoftwareVersions

Séquence MRI:

• SequenceName
• PulseSequenceType
• ScanningSequence (?)
• SequenceVariant (?)
• MRAcquisitionType (?)

if PET:

• NonlinearGradientCorrection (?)

And of course, the acquisition date, which is not always present for AIBL MRI for instance (having the image ID could help to latter fetch additional metadata when missing in such cases).

[ghisvail]

Could you find all of them in the ADNI / AIBL XML files?

[emaheux]

Indeed, in ADNI xml metadata we find most of them.
We also find some additional info on image pre-processing (GradWarp, N3m, ... ?)

One example xml file (some files have additional data, cf. zip file sent in Mattermost)

 <projectIdentifier>ADNI</projectIdentifier>
 <siteKey>XXXX</siteKey>
 <subject>
  <subjectIdentifier>XXXX</subjectIdentifier>
  <researchGroup>MCI</researchGroup>
  <subjectSex>M</subjectSex>
  <subjectInfo item="APOE A1">3</subjectInfo>
  <subjectInfo item="APOE A2">3</subjectInfo>
  <visit>
   <visitIdentifier>ADNI2 Year 4 Visit</visitIdentifier>
   <assessment name="MMSE">
    <component name="MMSE Total Score">
     <assessmentScore attribute="MMSCORE">29.0</assessmentScore>
    </component>
   </assessment>
   <assessment name="CDR">
    <component name="CDR Total Score">
     <assessmentScore attribute="CDGLOBAL">0.5</assessmentScore>
    </component>
   </assessment>
  </visit>
  <study>
   <studyIdentifier>XXXX</studyIdentifier>
   <subjectAge>71.6904</subjectAge>
   <ageQualifier>Y</ageQualifier>
   <weightKg>XXX</weightKg>
   <postMortem>F</postMortem>
   <series>
    <seriesIdentifier>XXXX</seriesIdentifier>
    <modality>MRI</modality>
    <dateAcquired>2016-03-23</dateAcquired>
    <seriesLevelMeta>
     <annotation>
      <text>Grinder Pipeline</text>
     </annotation>
     <derivedProduct>
      <imageUID>XXXX</imageUID>
      <processedDataLabel>MT1; GradWarp; N3m</processedDataLabel>
      <imageType>image volume</imageType>
      <tissue>All</tissue>
      <hemisphere>Both</hemisphere>
      <anatomicStructure>Brain</anatomicStructure>
      <registration>native</registration>
      <relatedImage>
       <imageUID>XXXX</imageUID>
       <relation>derived from</relation>
      </relatedImage>
      <provenanceDetail>
       <step>1</step>
       <process>Gradient Unwarping</process>
       <package>Grinder Pipeline</package>
       <program>nifti_unwarp_resample</program>
       <programVersion>1.0</programVersion>
       <timestamp>2016-03-29T18:01:32</timestamp>
       <platform>Linux</platform>
       <operatingSystem>2.6.32-573.18.1.</operatingSystem>
      </provenanceDetail>
      <provenanceDetail>
       <step>2</step>
       <process>N3m</process>
       <package>Grinder Pipeline</package>
       <program>brain_extraction2</program>
       <programVersion>2.04</programVersion>
       <timestamp>2016-03-29T18:13:49</timestamp>
       <platform>Linux</platform>
       <operatingSystem>2.6.32-573.18.1.</operatingSystem>
      </provenanceDetail>
      <creationDate>0000-00-00</creationDate>
     </derivedProduct>
     <relatedImageDetail>
      <originalRelatedImage>
       <imageUID>XXXX</imageUID>
       <description>SAG 3D MPRAGE</description>
       <protocolTerm>
        <protocol term="Acquisition Type">3D</protocol>
        <protocol term="Weighting">T1</protocol>
        <protocol term="Pulse Sequence">GR/IR</protocol>
        <protocol term="Slice Thickness">1.2</protocol>
        <protocol term="TE">3.54</protocol>
        <protocol term="TR">2400.0</protocol>
        <protocol term="TI">1000.0</protocol>
        <protocol term="Coil">PA</protocol>
        <protocol term="Flip Angle">8.0</protocol>
        <protocol term="Acquisition Plane">SAGITTAL</protocol>
        <protocol term="Matrix X">192.0</protocol>
        <protocol term="Matrix Y">192.0</protocol>
        <protocol term="Matrix Z">160.0</protocol>
        <protocol term="Pixel Spacing X">1.25</protocol>
        <protocol term="Pixel Spacing Y">1.25</protocol>
        <protocol term="Manufacturer">SIEMENS</protocol>
        <protocol term="Mfg Model">Avanto</protocol>
        <protocol term="Field Strength">1.5</protocol>
       </protocolTerm>
      </originalRelatedImage>
     </relatedImageDetail>
    </seriesLevelMeta>
   </series>
  </study>
 </subject>

[omar-rifai]

For AIBL we were retrieving most of this information (modulo the "Séquence MRI" info) from the DCM metadata, but I don't know if they are more or less reliable than the xml files.
Also, for these later (Séquence MRI info), is the interrogation mark supposed to denote fields which you have not found?

[emaheux]

I'm not sure either. An hypothesis is that some of these xml metadata directly come from DICOM headers (somehow automatically extracted when images are uploaded into their repo?), especially in the <protocolTerm> tag? In any case, they may be complementary, but primary source should remain the DICOM headers when metadata is present there I guess?

For the (?) in my list: no it is just some metadata, part of BIDS specification, that we may need at some point but I'm less sure than the other items listed (not sure of content / quality of info).

[omar-rifai]

After writing the comment I realized that we have some images in the Nifti format for ADNI on the lustre. It would be more straightfoward in a first iteration to rely on the xml I suppose.

[Symcies]

Participant ages are stored in the BIDS.

They are not listed in the BIDS documentation as potential RECOMMENDED options, but I wonder to which extend it can be beneficial to have them in the CAPS metadata?

In Leaspy case, ages are mandatory so we will retrieve them in BIDS or CAPS anyway.
At this stage, we will get them in the BIDS. If there are any reason / interest to migrate them also in CAPS, let us know so we can use only one structure to retrieve all the interesting information.

[ghisvail]

Ages are stored in the modality agnostic files of BIDS, and is a recommended piece of metadata.

Besides, there is also the distinction between the age at registration for the study versus the age at scan. I guess leaspy cares more for the latter than the former?

[MKVatinyan]

yes leaspy needs the age at each session

[ghisvail]

Ok so we'd need to update the converters to output an age for each session.

[emaheux]

Personally I'd say that having the scan date (primary information, not derived information) would be great in any case, reconstructing age at session can be part of a downstream process that we can conduct.

[omar-rifai]

Both age (corrected) and examination date are in the sessions files in ADNI

[omar-rifai]

This is currently under development in PR431 but has been stalled by the lack of ideal solution for the location of the data.

[NicolasGensollen]

I'm far from a BIDS expert but here is my understanding of where these metadata should go according to the BIDS specs. Please feel free to give your opinion (especially @ghisvail who knows the specs way better than I do).

If we assume the following file structure for the output of the ADNI to BIDS convertor:

subjects/
└─ participants.tsv
└─ sub-<label>/
   └─ sub-<label>_sessions.tsv
   └─ ses-<label>/
      └─ anat
         └─ sub-<label>_ses-<label>_T1w.nii.gz
         └─ sub-<label>_ses-<label>_T1w.json
         └─ sub-<label>_ses-<label>_FLAIR.nii.gz
         └─ sub-<label>_ses-<label>_FLAIR.json
      └─ pet
         └─ sub-<label>_ses-<label>_task-<label>_acq-<label>_pet.nii.gz
         └─ sub-<label>_ses-<label>_task-<label>_acq-<label>_pet.json
      └─ dwi
         └─ ...
      └─ sub-<label>_ses-<label>_scans.tsv

Then:

• Age of participants -> participants.tsv under column age (see specs).
• Scan acquisition date -> sub-<label>_ses-<label>_scans.tsv under column acq_time
  The age of subject at the scan time can then be reconstructed.

example:

filename    acq_time    scan_id    mri_field
anat/sub-<label>_ses-<label>_T1w.nii.gz   2011-06-15T13:45:30    scan_id    3.0
anat/sub-<label>_ses-<label>_FLAIR.nii.gz   2011-06-15T13:55:33    scan_id    3.0
pet/sub-<label>_ses-<label>_task-<label>_acq-<label>_pet.nii.gz 2011-06-15T12:15:27    scan_id    3.0
dwi/...

• Notes:

  • Should we remove the column mri_field and have this information stored in the scan json files under MagneticFieldStrength ?
  • Should we add a file sub-<label>_ses-<label>_scans.json describing the columns different from filename and acq_time? (This is what I understand from here)

• MagneticFieldStrength, Manufacturer, ManufacturersModelName, SoftwareVersions, ScanningSequence, SequenceVariant, MRAquisitionType, PulseSequenceType, SequenceName, NonLinearGradientCorrection -> Scan json files (here is another example).

example sub-<label>_ses-<label>_FLAIR.json:

{
        "Modality": "MR",
        "MagneticFieldStrength": 3,
        "Manufacturer": "GE",
        "ManufacturersModelName": "Signa_HDxt",
        "SoftwareVersions": "15_LX_MR_Software_release:15.0_M4A_0947.a",
        "MRAcquisitionType": "2D",
        "SeriesDescription": "Axial_FLAIR",
        "ProtocolName": "Axial_FLAIR",
        "ScanningSequence": "SE_IR",
        "SequenceVariant": "SK",
        "ScanOptions": "FAST_GEMS_SAT_GEMS_EDR_GEMS_SP",
        "ImageType": ["ORIGINAL", "PRIMARY", "OTHER"],
        "SeriesNumber": 6,
        ...
}

[NicolasGensollen]

Thanks for your reply @ghisvail !

I belive acq_time is supposed to be the timestamp at which each scan was acquired.

This is also what I understand, but I thought this is one of the metadata @emaheux wanted in his first message.

What you are probably after is the age at session (which should be common to all scans belonging to an imaging session).

I agree we can also export the age at session in sub-<label>_sessions.tsv, but I think that the column name cannot be age because this will conflict with the age column of participants.tsv and violate this requirements: "Column names in sessions.tsv files MUST be different from group level participant key column names in the participants.tsv file" (see here).

[ghisvail]

Indeed, what about age_at_session then? (I have seen it used before can't remember where)

[ghisvail]

I have solicited guidance upstream: bids-standard/bids-specification#1020

If there are established and sensible practices, we might as well pick one of those.

[emaheux]

I belive acq_time is supposed to be the timestamp at which each scan was acquired.

This is also what I understand, but I thought this is one of the metadata @emaheux wanted in his first message.

I'm not sure to get all the possible implications but on our side we would be fine having either:

• age_at_baseline for individual and delays_since_baseline for each scan
• or age_at_baseline for individual and age_at_session/scan per scan (even if this latter option seems a bit more redundant compared to first option?)

[ghisvail]

Both have been mentioned in the issue actually. Each have their pros and cons, which I have summarized.

In a nustshell, one of:

1. Only store age at the session level (because inheritance is forbidden for tabular metadata).
2. Store age_at_session as a separate attribute in the session level. Keep age for subject level.
3. Store age at subject level and delay_since_first_session at session level. age_at_session is computed indirectly.